cx.ath.matthew.cgi

Class CGI

java.lang.Object

cx.ath.matthew.cgi.CGI

Direct Known Subclasses:

testcgi

public abstract class CGI
extends Object

This is the main class you have to extend with your CGI program. You should implement the cgi() method.

Author:

Matthew Johnson <src@matthew.ath.cx>

Field Summary

Fields

Modifier and Type	Field and Description
private Vector	cookies
private CGIErrorHandler	errorhandler
private HashMap	headers
private boolean	headers_sent
private LinkedList	pagedata
private LinkedList	rawdata

Constructor Summary

Constructors

Constructor and Description
CGI()

Method Summary

Methods

Modifier and Type	Method and Description
protected abstract void	cgi(Map POST, Map GET, Map ENV, Map COOKIES, String[] params) Override this method in your CGI program.
void	doCGI(String[] args) This method sets up all the CGI variables and calls the cgi() method, then writes out the page data.
void	flush() Flushes the output.
private Map	getCOOKIE() Sets up the COOKIEs
private Map	getENV() Sets up the ENV variables
private String	getenv(String var)
private Object[]	getfullenv(Class c) MUST pass String.class and ALWAYS returns a String[]
private Map	getGET() Sets up the GET variables
OutputStream	getOutputStream() This will return an OutputStream that you can write data directly to.
private String[]	getParams(String args) Sets up the param variables
private Map	getPOST() Sets up the POST variables
void	header(String variable, String value) Called by CGIs to send a header to the output
void	out(byte[] data) Called by CGIs to send byte data to the output.
void	out(String data) Called by CGIs to send a string to the output.
private Object	readVariables(String s, char seperator, boolean values) Reads variables from a String like a=b&c=d to a Map {a => b, c => d}.
void	setcookie(String variable, String value) Sets a Cookie in the web browser.
void	setcookie(String variable, String value, String path, String domain, Date expires, boolean secure) Sets a Cookie in the web browser, with extended attributes.
private void	setenv(String var, String value)
protected void	setErrorHandler(CGIErrorHandler handler) Sets a custom exception handler.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

errorhandler

private CGIErrorHandler errorhandler

headers_sent

private boolean headers_sent

headers

private HashMap headers

cookies

private Vector cookies

pagedata

private LinkedList pagedata

rawdata

private LinkedList rawdata

Constructor Detail

CGI

public CGI()

Method Detail

getenv

private String getenv(String var)

getfullenv

private Object[] getfullenv(Class c)

MUST pass String.class and ALWAYS returns a String[]

setenv

private void setenv(String var,
          String value)

header

public final void header(String variable,
          String value)
                  throws CGIHeaderSentException

Called by CGIs to send a header to the output

Parameters:

variable - The header variable to set.

value - The value of the variable.

Throws:

CGIHeaderSentException - if the headers have already been sent.

See Also:

flush()

setcookie

public final void setcookie(String variable,
             String value,
             String path,
             String domain,
             Date expires,
             boolean secure)
                     throws CGIHeaderSentException

Sets a Cookie in the web browser, with extended attributes. Calls header() so must be called before sending any output. A parameter will not be sent if it is null.

Parameters:

variable - The cookie variable to set.

value - The value of the variable.

path - The path that the cookie will be returned for.

domain - The domain that the cookie will be returned for.

expires - The expiry date of the cookie.

secure - Will only send the cookie over HTTPS if this is true.

Throws:

CGIHeaderSentException - if the headers have already been sent.

See Also:

flush(), header(java.lang.String, java.lang.String)

setcookie

public final void setcookie(String variable,
             String value)
                     throws CGIHeaderSentException

Sets a Cookie in the web browser. Calls header() so must be called before sending any output.

Parameters:

variable - The cookie variable to set.

value - The value of the variable.

Throws:

CGIHeaderSentException - if the headers have already been sent.

See Also:

flush(), header(java.lang.String, java.lang.String)

out

public final void out(byte[] data)
               throws CGIInvalidContentFormatException

Called by CGIs to send byte data to the output. The data is buffered until the CGI exits, or a call of flush.

Parameters:

data - The page data.

Throws:

CGIInvalidContentFormatException - if text data has already been sent.

See Also:

flush()

out

public final void out(String data)
               throws CGIInvalidContentFormatException

Called by CGIs to send a string to the output. The data is buffered until the CGI exits, or a call of flush.

Parameters:

data - The page data.

Throws:

CGIInvalidContentFormatException - if raw data has already been sent.

See Also:

flush()

getOutputStream

public final OutputStream getOutputStream()
                                   throws IOException

This will return an OutputStream that you can write data directly to. Calling this method will cause the output to be flushed and the Headers sent. At the moment this is not buffered and will be sent directly to the client. Subsequent calls to out() will appear after data written to the output stream.

Returns:

an OutputStream

Throws:

IOException

See Also:

out(byte[])

flush

public final void flush()
                 throws IOException

Flushes the output. Note that you cannot send a header after a flush. If you want to send both text and binary data in a page you may do so either side of a flush.

Throws:

IOException

See Also:

header(java.lang.String, java.lang.String)

setErrorHandler

protected final void setErrorHandler(CGIErrorHandler handler)

Sets a custom exception handler. Gets called when an exception is thrown. The default error handler prints the error nicely in HTML and then exits gracefully.

Parameters:

handler - The new exception handler

cgi

protected abstract void cgi(Map POST,
       Map GET,
       Map ENV,
       Map COOKIES,
       String[] params)
                     throws Exception

Override this method in your CGI program.

Parameters:

POST - A Map of variable =$gt; value for the POST variables.

GET - A Map of variable =$gt; value for the GET variables.

ENV - A Map of variable =$gt; value for the Webserver environment variables.

COOKIES - A Map of variable =$gt; value for the browser-sent cookies.

params - An array of parameters passed to the CGI (GET with no variable assignments)

Throws:

Exception - You can throw anything, it will be caught by the error handler.

readVariables

private Object readVariables(String s,
                   char seperator,
                   boolean values)

Reads variables from a String like a=b&c=d to a Map {a => b, c => d}.

Parameters:

s - String to read from.

seperator - seperator character between variables (eg &)

values - whether or not this string has values for variables

Returns:

a Map with values, a Vector without

getPOST

private Map getPOST()

Sets up the POST variables

getCOOKIE

private Map getCOOKIE()

Sets up the COOKIEs

getGET

private Map getGET()

Sets up the GET variables

getENV

private Map getENV()

Sets up the ENV variables

getParams

private String[] getParams(String args)

Sets up the param variables

doCGI

public final void doCGI(String[] args)

This method sets up all the CGI variables and calls the cgi() method, then writes out the page data.