Class CgiParser

www.samuelsiren.com

Class CgiParser

java.lang.Object
  |
  +--CgiParser

public class CgiParser
extends java.lang.Object

This small class "unpacks" the environment variables that are input to CGI scripts.

Please note that since environment variables aren't accessible from Java, the environment variables PATH_INFO, QUERY_STRING, and CONTENT_LENGTH always must be passed as parameters to the contructors of this class. This can be done by e.g. using a Unix Shell Script as wrapper.

Example, Unix Shell Script wrapper file:

#!/bin/sh
cd /YourDomain/cgi-bin
/usr/local/jdk/bin/java CgiParser "$PATH_INFO" "$QUERY_STRING" "$CONTENT_LENGTH"

Some Class features:

POST v.s. GET handled transparently, i.e. QUERY_STRING (passed in the URL at GET) and content (passed in the CONTENT_LENGTH number of bytes read from java.lang.System.in at POST) are treated exactly the same
Automatic URL-decoding of QUERY_STRING, content, and PATH_INFO
Possibility to handle PATH_INFO elements as parameter/value pairs, i.e. for URLs like e.g. http://a.com/cgi-bin/b.sh/x=1/y=2/z=3/t=4 the path elements can be treated exactly like corresponding QUERY_STRING or content parameter/value pair elements, i.e. "x=1&y=2&z=3&t=4"

Constructor Summary

CgiParser(java.lang.String pathInfo, java.lang.String queryString, java.lang.String contentLength)
          Construct a CGI Parser and parse the environment variables.

CgiParser(java.lang.String pathInfo, java.lang.String queryString, java.lang.String contentLength, boolean pathParams)
          Construct a CGI Parser and parse the environment variables.

Method Summary

java.util.Enumeration getParams()
          Returns Enumeration containing the QUERY_STRING or content (or PATH_INFO) parameter names.

java.lang.String getParamValue(java.lang.String param)
          Returns value of named parameter as posted in QUERY_STRING or content (or PATH_INFO).

boolean inPath(java.lang.String s)
          Returns true if PATH_INFO contains such an element.

static void main(java.lang.String[] args)
          Test program, printing a HTML page to java.lang.System.out (as "CGI output").

java.lang.String pathAt(int index)
          Returns the PATH_INFO element of the specified index.

int pathIndex(java.lang.String s)
          Returns the index of the PATH_INFO element, or -1 if element not in PATH_INFO.

int pathSize()
          Returns number of PATH_INFO elements.

Methods inherited from class java.lang.Object

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

Constructor Detail

CgiParser

public CgiParser(java.lang.String pathInfo,
                 java.lang.String queryString,
                 java.lang.String contentLength)

Construct a CGI Parser and parse the environment variables.

Parameters:: pathInfo - environment variable PATH_INFO; queryString - environment variable QUERY_STRING; contentLength - environment variable CONTENT_LENGTH

CgiParser

public CgiParser(java.lang.String pathInfo,
                 java.lang.String queryString,
                 java.lang.String contentLength,
                 boolean pathParams)

Construct a CGI Parser and parse the environment variables.

Parameters:: pathInfo - environment variable PATH_INFO; queryString - environment variable QUERY_STRING; contentLength - environment variable CONTENT_LENGTH; pathParams - when true, if the PATH_INFO elements contain parameter/value pairs (e.g. http://a.com/cgi-bin/b.sh/x=1/y=2/ i.e. x = 1 and y = 2) those elements will be handled exactly as the parameter/value pairs in QUERY_STRING and content.

Method Detail

getParams

public java.util.Enumeration getParams()

Returns Enumeration containing the QUERY_STRING or content (or PATH_INFO) parameter names.

Example: The URL being http://a.com/cgi-bin/b.sh?x=1&y=2 or the content being "x=1&y=2", the resulting Enumeration will contain the strings "x" and "y".
Provided that the CgiParser was constructed with pathParams set to true, the URL http://a.com/cgi-bin/b.sh/x=1/y=2 will yield the same result. Also, in that case any PATH_INFO/QUERY_STRING/content parameter/value pair combination works perfectly Ok, e.g. for the URL http://a.com/cgi-bin/b.sh/x=1/y=2?z=3&t=4 with the content being "v=5&w=6", the resulting Enumeration will contain "x", "y", "z", "t", "v", and "w"; where "x" and "y" come from PATH_INFO, "z" and "t" come from QUERY_STRING, and "v" and "w" come from content.

The basic idea of usage is:

     for (Enumeration e = cgiParser.getParams(); e.hasMoreElements();) {
         String param = (String)e.nextElement();
         String value = cgiParser.getParamValue(param);
         // Do something with param and/or value
     }

Returns:: Enumeration containing the parameter names

getParamValue

public java.lang.String getParamValue(java.lang.String param)

Returns value of named parameter as posted in QUERY_STRING or content (or PATH_INFO).

Example: The URL being http://a.com/cgi-bin/b.sh?x=1&y=2 or the content being "x=1&y=2", getParamValue("x") will return "1" and getParamValue("y") will return "2" (always as a String, n.b.)
If the CgiParser was constructed with pathParams set to true, the URL http://a.com/cgi-bin/b.sh/x=1/y=2 will also yield getParamValue("x") returning "1" and getParamValue("y") returning "2".

Parameters:: param - parameter name
Returns:: value of named parameter (null if not found)

pathSize

public int pathSize()

Returns number of PATH_INFO elements.

Example: The URL being http://a.com/cgi-bin/b.sh/x/y/z/t, pathSize returns 4.

Returns:: number of PATH_INFO elements

pathAt

public java.lang.String pathAt(int index)

Returns the PATH_INFO element of the specified index.

Example: The URL being http://a.com/cgi-bin/b.sh/x/y/z/t, pathAt(2) returns "z".

Parameters:: index - index, from 0 to pathSize()-1
Returns:: PATH_INFO element of the specified index

pathIndex

public int pathIndex(java.lang.String s)

Returns the index of the PATH_INFO element, or -1 if element not in PATH_INFO.

Example: The URL being http://a.com/cgi-bin/b.sh/x/y/z/t, pathIndex("z") returns 2, and pathIndex("q") returns -1.

Parameters:: s - element id
Returns:: index of the PATH_INFO element, or -1 if element not found in PATH_INFO

inPath

public boolean inPath(java.lang.String s)

Returns true if PATH_INFO contains such an element.

Example: The URL being http://a.com/cgi-bin/b.sh/x/y/z/t, inPath("z") returns true, and inPath("q") returns false.

Parameters:: s - element id
Returns:: true if PATH_INFO contains such an element, false otherwise

main

public static void main(java.lang.String[] args)

Test program, printing a HTML page to java.lang.System.out (as "CGI output").

This program needs to be wrapped in e.g. a Unix Shell Script.

Parameters:: args[0] - environment variable PATH_INFO; args[1] - environment variable QUERY_STRING; args[2] - environment variable CONTENT_LENGTH

Constructor Summary
`CgiParser(java.lang.String pathInfo, java.lang.String queryString, java.lang.String contentLength)` Construct a CGI Parser and parse the environment variables.
`CgiParser(java.lang.String pathInfo, java.lang.String queryString, java.lang.String contentLength, boolean pathParams)` Construct a CGI Parser and parse the environment variables.

Method Summary
`java.util.Enumeration`	`getParams()` Returns Enumeration containing the QUERY_STRING or content (or PATH_INFO) parameter names.
`java.lang.String`	`getParamValue(java.lang.String param)` Returns value of named parameter as posted in QUERY_STRING or content (or PATH_INFO).
`boolean`	`inPath(java.lang.String s)` Returns true if PATH_INFO contains such an element.
`static void`	`main(java.lang.String[] args)` Test program, printing a HTML page to java.lang.System.out (as "CGI output").
`java.lang.String`	`pathAt(int index)` Returns the PATH_INFO element of the specified index.
`int`	`pathIndex(java.lang.String s)` Returns the index of the PATH_INFO element, or -1 if element not in PATH_INFO.
`int`	`pathSize()` Returns number of PATH_INFO elements.