cx.ath.matthew.cgi

Class CGI

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>

Method Summary
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.
OutputStream	getOutputStream() This will return an OutputStream that you can write data directly to.
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.
void	setcookie(String variable, String value, String path, String domain, Date expires, boolean secure) Sets a Cookie in the web browser, with extended attributes.
void	setcookie(String variable, String value) Sets a Cookie in the web browser.
protected void	setErrorHandler(CGIErrorHandler handler) Sets a custom exception handler.

Method Detail

cgi

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

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.

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.

flush

public final void flush()

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.

See Also: CGI

getOutputStream

public final OutputStream getOutputStream()

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

See Also: CGI

header

public final void header(String variable, String value)

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: CGI

out

public final void out(byte[] data)

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: CGI

out

public final void out(String data)

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: CGI

setcookie

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

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.

setcookie

public final void setcookie(String variable, String value)

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.

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