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");
     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()