Holger's Java API

## com.antelmann.net
Class CGI

    java.lang.Object
      com.antelmann.net.CGI

    public class CGI

extends Object

The class CGI provides a convenient way to post parameters to a web-based CGI (Common Gateway Interface) script.

Here is a complete code example that assumes that the script specified with the given URL takes two input values: 'name' and 'text':

     try {
         URL url = new URL("http://myserver/cgi-bin/myscript.cgi");
         CGI cgi = new CGI(url);
         cgi.addHeader("cookie", "my cookie value");
         HashMap params = new HashMap();
         params.put("name", "Me");
         params.put("text", "first line\nsecond line\n<mailto:me@there>");
         int response = cgi.post(params);
         if (response != 200) {
             System.out.println("something went wrong");
         }
         // see the complete response the script sent back
         System.out.println(cgi.getResponseAsString());
     } catch (IOException e) { e.printStackTrace(); }

Note that you do not need to 'escape' the values, as this is done by the `post(Map)` method.

Since:
  5/5/2002
Author:
  Holger Antelmann

Nested Class Summary
`static class` `CGI.MultipartHandler`

Constructor Summary
`CGI(String cgiURLString)`
`CGI(String cgiURLString, String charset)`
`CGI(URL cgiUrl)` requires a URL based on the HTTP protocol specifying the script you are posting to
`CGI(URL cgiURL, String charset)`

Method Summary
`void` `addHeader(String key, String value)` allows to add additional header information to the request.
`void` `clearAuthorization()`
`void` `clearHeaders()`
`String` `decode(String str)`
`String` `encode(Object str)`
`String` `encodeAsURLParameter(Map<?,?> parameters)`
`String` `encodeAsURLParameter(String[][] parameterValues)`
`int` `get()`
`int` `get(Map<?,?> parameters)`
`int` `get(String content)`
`int` `get(String[][] parameterValues)`
`int` `get(String parameter, String value)`
`String` `getAuthorizationUser()`
`String` `getCharset()` returns the character set used for encoding (defaults to 'UTF-8')
`int` `getConnectTimeout()`
`String` `getErrorAsString()`
`List<SimpleEntry<String,String>>` `getHeaders()`
`byte[]` `getLastError()`
`Map<String,List<String>>` `getLastHeader()`
`byte[]` `getLastResponse()`
`int` `getReadTimeout()`
`String` `getResponseAsString()` convenience method: returns the last response as a String using the current character set encoding
`SSLHelper` `getSslHelper()`
`boolean` `isSendContentLength()`
`int` `post()`
`int` `post(Handler<HttpURLConnection,IOException> handler)`
`int` `post(InputStream stream)`
`int` `post(Map<?,?> parameters)` posts the given parameters to the instance's URL via POST.
`int` `post(String content)`
`int` `post(String[][] parameterValues)` posts the given parameter/value pairs to the embedded URL in the exact specified order.
`int` `post(String parameter, String value)` convenience method to post a single parameter/value pair
`void` `removeHeader(String key)`
`void` `setAuthorization(String user, char[] password)`
`void` `setCharset(String charset)` allows to change the character set used for encoding
`void` `setConnectTimeout(int connectTimeout)`
`void` `setHeader(String key, String value)`
`void` `setReadTimeout(int readTimeout)`
`void` `setSendContentLength(boolean sendContentLength)`
`void` `setSslHelper(SSLHelper sslHelper)`
`int` `submit(String method, Handler<HttpURLConnection,IOException> handler)` allows to provide a custom way to handle the streaming to the output by callback.
`int` `submit(String method, InputStream content)` streams the content to the URL per HTTP: POST, GET or HEADER.
`int` `submit(String method, String content)` posts the encoded string directly to the URL per HTTP: POST, GET or HEADER.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### CGI

    public CGI(String cgiURLString)
        throws MalformedURLException,
               UnsupportedOperationException

Throws:
  `MalformedURLException`
  `UnsupportedOperationException`

### CGI

    public CGI(URL cgiUrl)
        throws UnsupportedOperationException

  requires a URL based on the HTTP protocol specifying the script you are posting to

  Throws:
    `UnsupportedOperationException` - if the protocol is not HTTP

### CGI

    public CGI(String cgiURLString,
               String charset)
        throws MalformedURLException

Throws:
  `MalformedURLException`

### CGI

    public CGI(URL cgiURL,
               String charset)

Method Detail

### getCharset

    public String getCharset()

  returns the character set used for encoding (defaults to 'UTF-8')

### setCharset

    public void setCharset(String charset)

  allows to change the character set used for encoding

### getSslHelper

    public SSLHelper getSslHelper()

### setSslHelper

    public void setSslHelper(SSLHelper sslHelper)

### setAuthorization

    public void setAuthorization(String user,
                                 char[] password)

### getAuthorizationUser

    public String getAuthorizationUser()

### clearAuthorization

    public void clearAuthorization()

### getConnectTimeout

    public int getConnectTimeout()

### setConnectTimeout

    public void setConnectTimeout(int connectTimeout)

### getReadTimeout

    public int getReadTimeout()

### setReadTimeout

    public void setReadTimeout(int readTimeout)

### isSendContentLength

    public boolean isSendContentLength()

### setSendContentLength

    public void setSendContentLength(boolean sendContentLength)

### getResponseAsString

    public String getResponseAsString()

  convenience method: returns the last response as a String using the current character set encoding

  See Also:
    `setCharset(String)`

### getLastResponse

    public byte[] getLastResponse()

### getLastError

    public byte[] getLastError()

### getLastHeader

    public Map<String,List<String>> getLastHeader()

### getErrorAsString

    public String getErrorAsString()

### setHeader

    public void setHeader(String key,
                          String value)

### removeHeader

    public void removeHeader(String key)

### addHeader

    public void addHeader(String key,
                          String value)

  allows to add additional header information to the request. The order of how headers are added is kept.

  See Also:
    `URLConnection.setRequestProperty(String, String)`

### getHeaders

    public List<SimpleEntry<String,String>> getHeaders()

### clearHeaders

    public void clearHeaders()

### get

    public int get()
            throws IOException

  Throws:
    `IOException`

### post

    public int post()
             throws IOException

  Throws:
    `IOException`

### get

    public int get(String parameter,
                   String value)
            throws IOException

  Throws:
    `IOException`

### post

    public int post(String parameter,
                    String value)
             throws IOException

  convenience method to post a single parameter/value pair

  Throws:
    `IOException`

### post

    public int post(String[][] parameterValues)
             throws IOException

  posts the given parameter/value pairs to the embedded URL in the exact specified order.

  The value entries must not already be encoded; this is done within this method. To retrieve the full text returned by the server after you called this method, use `getResponse()`

  Returns:
    the response code from the server
  Throws:
    `IOException`
  See Also:
    `getResponseAsString()`

### get

    public int get(String[][] parameterValues)
            throws IOException

  Throws:
    `IOException`

### post

    public int post(InputStream stream)
             throws IOException

  Throws:
    `IOException`

### post

    public int post(Handler<HttpURLConnection,IOException> handler)
             throws IOException

  Throws:
    `IOException`
  See Also:
    `CGI.MultipartHandler`

### post

    public int post(Map<?,?> parameters)
             throws IOException

  posts the given parameters to the instance's URL via POST. The parameters map each input name to its value. Both, key and value, are used as strings; you must not 'escape' the strings (replacing spaces, \"&\"'s etc.) as this is automatically done within this method. The method takes an Object-to-Object Map, so that Properties may be passed as parameter. To retrieve the full text returned by the server after you called this method, use `getResponse()`

  Returns:
    the response code from the server
  Throws:
    `IOException`
  See Also:
    `getResponseAsString()`

### get

    public int get(Map<?,?> parameters)
            throws IOException

  Throws:
    `IOException`

### encodeAsURLParameter

    public String encodeAsURLParameter(String[][] parameterValues)

### encodeAsURLParameter

    public String encodeAsURLParameter(Map<?,?> parameters)

### encode

    public String encode(Object str)

### decode

    public String decode(String str)

### post

    public int post(String content)
             throws IOException

  Throws:
    `IOException`

### get

    public int get(String content)
            throws IOException

  Throws:
    `IOException`

### submit

    public int submit(String method,
                      String content)
               throws IOException

  posts the encoded string directly to the URL per HTTP: POST, GET or HEADER. To retrieve the full text returned by the server after you called this method, use `getResponse()`

  Returns:
    the response code from the server
  Throws:
    `IOException`
  See Also:
    `getLastResponse()`

### submit

    public int submit(String method,
                      InputStream content)
               throws IOException

  streams the content to the URL per HTTP: POST, GET or HEADER. To retrieve the full text returned by the server after you called this method, use `getResponse()`

  Returns:
    the response code from the server
  Throws:
    `IOException`
  See Also:
    `getLastResponse()`

### submit

    public int submit(String method,
                      Handler<HttpURLConnection,IOException> handler)
               throws IOException

  allows to provide a custom way to handle the streaming to the output by callback.

  Parameters:
    `handler` - the handler is called right before the connect happens
  Returns:
    the response code from the server
  Throws:
    `IOException`
  See Also:
    `getLastResponse()`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads