com.oreilly.servlet
Class ParameterParser

java.lang.Object
  com.oreilly.servlet.ParameterParser

public class ParameterParser
extends java.lang.Object

A class to simplify parameter handling. It can return parameters of any primitive type (no casting or parsing required), can throw an exception when a parameter is not found (simplifying error handling), and can accept default values (eliminating error handling).

It is used like this:

 ParameterParser parser = new ParameterParser(req);
  
 float ratio = parser.getFloatParameter("ratio", 1.0);
  
 int count = 0;
 try {
   count = parser.getIntParameter("count");
 }
 catch (NumberFormatException e) {
   handleMalformedCount();
 }
 catch (ParameterNotFoundException e) {
   handleNoCount();
 }
 

There's also a capability to find out if any required parameters are missing from a request:

 ParameterParser parser = new ParameterParser(req);
 String[] required = { "fname", "lname", "account" };
 String[] missing = parser.getMissingParameters(required);
 

The default charset for input parameters is ISO-8859-1 (Latin-1). If the parameter values are encoded in another format, specify that using setCharacterEncoding() before parsing. The parameter names currently have to be in the Latin-1 character set:

 ParameterParser parser = new ParameterParser(req);
 parser.setCharacterEncoding("Shift_JIS");
 String japaneseValue = parser.getStringParameter("latinName");
 

Version:

1.4, 2000/12/14, better checking the selected encoding is valid in setCharacterEncoding() thanks to Dewayne McNair, 1.3, 2000/05/17, added setCharacterEncoding(), 1.2, 2000/05/17, getBooleanParameter() now recognizes "on" and "yes", 1.1, 1999/12/20, added getMissingParameters() method, 1.0, 1998/09/18

Author:

Jason Hunter, Copyright © 1998, 1999

See Also:

ParameterNotFoundException

Constructor Summary

ParameterParser(ServletRequest req)
Constructs a new ParameterParser to handle the parameters of the given request.

Method Summary

boolean	getBooleanParameter(java.lang.String name) Gets the named parameter value as a boolean, with true indicated by "true", "on", or "yes" in any letter case, false indicated by "false", "off", or "no" in any letter case.
boolean	getBooleanParameter(java.lang.String name, boolean def) Gets the named parameter value as a boolean, with a default.
byte	getByteParameter(java.lang.String name) Gets the named parameter value as a byte
byte	getByteParameter(java.lang.String name, byte def) Gets the named parameter value as a byte, with a default.
char	getCharParameter(java.lang.String name) Gets the named parameter value as a char
char	getCharParameter(java.lang.String name, char def) Gets the named parameter value as a char, with a default.
double	getDoubleParameter(java.lang.String name) Gets the named parameter value as a double
double	getDoubleParameter(java.lang.String name, double def) Gets the named parameter value as a double, with a default.
float	getFloatParameter(java.lang.String name) Gets the named parameter value as a float
float	getFloatParameter(java.lang.String name, float def) Gets the named parameter value as a float, with a default.
int	getIntParameter(java.lang.String name) Gets the named parameter value as a int
int	getIntParameter(java.lang.String name, int def) Gets the named parameter value as a int, with a default.
long	getLongParameter(java.lang.String name) Gets the named parameter value as a long
long	getLongParameter(java.lang.String name, long def) Gets the named parameter value as a long, with a default.
java.lang.String[]	getMissingParameters(java.lang.String[] required) Determines which of the required parameters were missing from the request.
short	getShortParameter(java.lang.String name) Gets the named parameter value as a short
short	getShortParameter(java.lang.String name, short def) Gets the named parameter value as a short, with a default.
java.lang.String	getStringParameter(java.lang.String name) Gets the named parameter value as a String
java.lang.String	getStringParameter(java.lang.String name, java.lang.String def) Gets the named parameter value as a String, with a default.
void	setCharacterEncoding(java.lang.String encoding) Sets the character encoding (charset) of the request to help the parser properly decode parameter values.

Methods inherited from class java.lang.Object

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

Constructor Detail

ParameterParser

public ParameterParser(ServletRequest req)

Constructs a new ParameterParser to handle the parameters of the given request.

Parameters:

req - the servlet request

Method Detail

setCharacterEncoding

public void setCharacterEncoding(java.lang.String encoding)
                          throws java.io.UnsupportedEncodingException

Sets the character encoding (charset) of the request to help the parser properly decode parameter values. The default is to return undecoded values, the same as would be returned by getParameter().

Parameters:

encoding - the charset of the request

Throws:

java.io.UnsupportedEncodingException - if the charset is not supported on this sytem

getStringParameter

public java.lang.String getStringParameter(java.lang.String name)
                                    throws ParameterNotFoundException

Gets the named parameter value as a String

Parameters:

name - the parameter name

Returns:

the parameter value as a String

Throws:

ParameterNotFoundException - if the parameter was not found or was the empty string

getStringParameter

public java.lang.String getStringParameter(java.lang.String name,
                                           java.lang.String def)

Gets the named parameter value as a String, with a default. Returns the default value if the parameter is not found or is the empty string.

Parameters:

name - the parameter name

def - the default parameter value

Returns:

the parameter value as a String, or the default

getBooleanParameter

public boolean getBooleanParameter(java.lang.String name)
                            throws ParameterNotFoundException,
                                   java.lang.NumberFormatException

Gets the named parameter value as a boolean, with true indicated by "true", "on", or "yes" in any letter case, false indicated by "false", "off", or "no" in any letter case.

Parameters:

name - the parameter name

Returns:

the parameter value as a boolean

Throws:

ParameterNotFoundException - if the parameter was not found

java.lang.NumberFormatException - if the parameter could not be converted to a boolean

getBooleanParameter

public boolean getBooleanParameter(java.lang.String name,
                                   boolean def)

Gets the named parameter value as a boolean, with a default. Returns the default value if the parameter is not found.

Parameters:

name - the parameter name

def - the default parameter value

Returns:

the parameter value as a boolean, or the default

getByteParameter

public byte getByteParameter(java.lang.String name)
                      throws ParameterNotFoundException,
                             java.lang.NumberFormatException

Gets the named parameter value as a byte

Parameters:

name - the parameter name

Returns:

the parameter value as a byte

Throws:

ParameterNotFoundException - if the parameter was not found

java.lang.NumberFormatException - if the parameter value could not be converted to a byte

getByteParameter

public byte getByteParameter(java.lang.String name,
                             byte def)

Gets the named parameter value as a byte, with a default. Returns the default value if the parameter is not found or cannot be converted to a byte.

Parameters:

name - the parameter name

def - the default parameter value

Returns:

the parameter value as a byte, or the default

getCharParameter

public char getCharParameter(java.lang.String name)
                      throws ParameterNotFoundException

Gets the named parameter value as a char

Parameters:

name - the parameter name

Returns:

the parameter value as a char

Throws:

ParameterNotFoundException - if the parameter was not found or was the empty string

getCharParameter

public char getCharParameter(java.lang.String name,
                             char def)

Gets the named parameter value as a char, with a default. Returns the default value if the parameter is not found.

Parameters:

name - the parameter name

def - the default parameter value

Returns:

the parameter value as a char, or the default

getDoubleParameter

public double getDoubleParameter(java.lang.String name)
                          throws ParameterNotFoundException,
                                 java.lang.NumberFormatException

Gets the named parameter value as a double

Parameters:

name - the parameter name

Returns:

the parameter value as a double

Throws:

ParameterNotFoundException - if the parameter was not found

java.lang.NumberFormatException - if the parameter could not be converted to a double

getDoubleParameter

public double getDoubleParameter(java.lang.String name,
                                 double def)

Gets the named parameter value as a double, with a default. Returns the default value if the parameter is not found.

Parameters:

name - the parameter name

def - the default parameter value

Returns:

the parameter value as a double, or the default

getFloatParameter

public float getFloatParameter(java.lang.String name)
                        throws ParameterNotFoundException,
                               java.lang.NumberFormatException

Gets the named parameter value as a float

Parameters:

name - the parameter name

Returns:

the parameter value as a float

Throws:

ParameterNotFoundException - if the parameter was not found

java.lang.NumberFormatException - if the parameter could not be converted to a float

getFloatParameter

public float getFloatParameter(java.lang.String name,
                               float def)

Gets the named parameter value as a float, with a default. Returns the default value if the parameter is not found.

Parameters:

name - the parameter name

def - the default parameter value

Returns:

the parameter value as a float, or the default

getIntParameter

public int getIntParameter(java.lang.String name)
                    throws ParameterNotFoundException,
                           java.lang.NumberFormatException

Gets the named parameter value as a int

Parameters:

name - the parameter name

Returns:

the parameter value as a int

Throws:

ParameterNotFoundException - if the parameter was not found

java.lang.NumberFormatException - if the parameter could not be converted to a int

getIntParameter

public int getIntParameter(java.lang.String name,
                           int def)

Gets the named parameter value as a int, with a default. Returns the default value if the parameter is not found.

Parameters:

name - the parameter name

def - the default parameter value

Returns:

the parameter value as a int, or the default

getLongParameter

public long getLongParameter(java.lang.String name)
                      throws ParameterNotFoundException,
                             java.lang.NumberFormatException

Gets the named parameter value as a long

Parameters:

name - the parameter name

Returns:

the parameter value as a long

Throws:

ParameterNotFoundException - if the parameter was not found

java.lang.NumberFormatException - if the parameter could not be converted to a long

getLongParameter

public long getLongParameter(java.lang.String name,
                             long def)

Gets the named parameter value as a long, with a default. Returns the default value if the parameter is not found.

Parameters:

name - the parameter name

def - the default parameter value

Returns:

the parameter value as a long, or the default

getShortParameter

public short getShortParameter(java.lang.String name)
                        throws ParameterNotFoundException,
                               java.lang.NumberFormatException

Gets the named parameter value as a short

Parameters:

name - the parameter name

Returns:

the parameter value as a short

Throws:

ParameterNotFoundException - if the parameter was not found

java.lang.NumberFormatException - if the parameter could not be converted to a short

getShortParameter

public short getShortParameter(java.lang.String name,
                               short def)

Gets the named parameter value as a short, with a default. Returns the default value if the parameter is not found.

Parameters:

name - the parameter name

def - the default parameter value

Returns:

the parameter value as a short, or the default

getMissingParameters

public java.lang.String[] getMissingParameters(java.lang.String[] required)

Determines which of the required parameters were missing from the request. Returns null if all the parameters are present.

Parameters:

an - array of required parameters

Returns:

an array of missing parameters, or null if none are missing