simple.util.parse
Class ParameterParser

java.lang.Object
  extended by simple.util.parse.Parser
      extended by simple.util.parse.MapParser
          extended by simple.util.parse.ParameterParser
All Implemented Interfaces:
java.io.Serializable, java.util.Map, Parameters

public class ParameterParser
extends MapParser
implements Parameters

The ParameterParser is used to parse data encoded in the application/x-www-form-urlencoded MIME type. It is also used to parse a query string from a HTTP URL, see RFC 2616. The parsed parameters are available through the various methods of the simple.http.net.Parameters interface. The syntax of the parsed parameters is described below in BNF.


    params  = *(pair [ "&" params])
    pair    = name "=" value
    name    = *(text | escaped)
    value   = *(text | escaped)
    escaped = % HEX HEX

 
This will consume all data found as a name or value, if the data is a "+" character then it is replaced with a space character. This regards only "=", "&", and "%" as having special values. The "=" character delimits the name from the value and the "&" delimits the name value pair. The "%" character represents the start of an escaped sequence, which consists of two hex digits. All escaped sequences are converted to its character value.

Author:
Niall Gallagher
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from interface java.util.Map
java.util.Map.Entry<K,V>
 
Field Summary
 
Fields inherited from class simple.util.parse.MapParser
map
 
Fields inherited from class simple.util.parse.Parser
buf, count, off
 
Constructor Summary
ParameterParser()
          Constructor for the ParameterParser.
ParameterParser(java.lang.String text)
          Constructor for the ParameterParser.
 
Method Summary
 boolean getBoolean(java.lang.Object name)
          This extracts a boolean parameter for the named value.
 float getFloat(java.lang.Object name)
          This extracts a float parameter for the named value.
 int getInteger(java.lang.Object name)
          This extracts an integer parameter for the named value.
 java.lang.String getParameter(java.lang.Object name)
          This extracts a value for the given name.
 java.util.Enumeration getParameterNames()
          This enumerates the names of every parameter.
protected  void init()
          This initializes the parser so that it can be used several times.
protected  void parse()
          This performs the actual parsing of the parameter text.
 java.lang.String toString()
          This toString method is used to compose an string in the application/x-www-form-urlencoded MIME type.
 java.lang.String toString(java.util.Set set)
          This toString method is used to compose an string in the application/x-www-form-urlencoded MIME type.
 
Methods inherited from class simple.util.parse.MapParser
clear, containsKey, containsValue, entrySet, get, isEmpty, keySet, put, putAll, remove, size, token, values
 
Methods inherited from class simple.util.parse.Parser
digit, ensureCapacity, parse, skip, space, toLower
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values
 

Constructor Detail

ParameterParser

public ParameterParser()
Constructor for the ParameterParser. This creates an instance that can be use to parse HTML form data and URL query strings encoded as application/x-www-form-urlencoded. The parsed parameters are made available through the interface simple.util.net.Parameters.


ParameterParser

public ParameterParser(java.lang.String text)
Constructor for the ParameterParser. This creates an instance that can be use to parse HTML form data and URL query strings encoded as application/x-www-form-urlencoded. The parsed parameters are made available through the interface simple.util.net.Parameters.

Parameters:
text - this is the text to parse for the parameters
Method Detail

getParameterNames

public java.util.Enumeration getParameterNames()
This enumerates the names of every parameter. This enables the parameter values to be extracted by providing the name to the getParameter method. The resulting Enumeration contains string objects.

Specified by:
getParameterNames in interface Parameters
Returns:
this returns an Enumeration of names

getParameter

public java.lang.String getParameter(java.lang.Object name)
This extracts a value for the given name. The name issued to this method must be from the Enumeration issued. If there is no parameter of this name this will return a null value. If there are multiple values this will return the first value.

Specified by:
getParameter in interface Parameters
Parameters:
name - the name of the parameter value to retrieve
Returns:
this returns the first value for the given name

getInteger

public int getInteger(java.lang.Object name)
This extracts an integer parameter for the named value. If the named parameter does not exist this will return a zero value. If however the parameter exists but is not in the format of a decimal integer value then this will throw a NumberFormatException.

Specified by:
getInteger in interface Parameters
Parameters:
name - the name of the parameter value to retrieve
Returns:
this returns the parameter value as an integer
Throws:
java.lang.NumberFormatException - if the value is not valid

getFloat

public float getFloat(java.lang.Object name)
This extracts a float parameter for the named value. If the named parameter does not exist this will return a zero value. If however the parameter exists but is not in the format of a floating point number then this will throw a NumberFormatException.

Specified by:
getFloat in interface Parameters
Parameters:
name - the name of the parameter value to retrieve
Returns:
this returns the parameter value as a float
Throws:
java.lang.NumberFormatException - if the value is not valid

getBoolean

public boolean getBoolean(java.lang.Object name)
This extracts a boolean parameter for the named value. If the named parameter does not exist this will return false otherwize the value is evaluated. If it is either true or false then those boolean values are returned, otherwize it is false.

Specified by:
getBoolean in interface Parameters
Parameters:
name - the name of the parameter value to retrieve
Returns:
this returns the parameter value as an float

init

protected void init()
This initializes the parser so that it can be used several times. This clears any previous parameters extracted. This ensures that when the next parse(String) is invoked the status of the Parameters is empty.

Specified by:
init in class Parser

parse

protected void parse()
This performs the actual parsing of the parameter text. The parameters parsed from this are taken as "name=value" pairs. Multiple pairs within the text are separated by an "&". This will parse and insert all parameters into a hashtable.

Specified by:
parse in class Parser

toString

public java.lang.String toString(java.util.Set set)
This toString method is used to compose an string in the application/x-www-form-urlencoded MIME type. This will encode the tokens specified in the Set. Each name=value pair acquired is converted into a UTF-8 escape sequence so that the parameters can be sent in the IS0-8859-1 format required via the HTTP/1.1 specification RFC 2616.

Parameters:
set - this is the set of parameters to be encoded
Returns:
returns a HTTP parameter encoding for the pairs

toString

public java.lang.String toString()
This toString method is used to compose an string in the application/x-www-form-urlencoded MIME type. This will iterate over all tokens that have been added to this object, either during parsing, or during use of the instance. Each name=value pair acquired is converted into a UTF-8 escape sequence so that the parameters can be sent in the IS0-8859-1 format required via the HTTP/1.1 specification RFC 2616.

Specified by:
toString in interface Parameters
Overrides:
toString in class java.lang.Object
Returns:
returns a HTTP parameter encoding for the pairs