bb.net
Class HttpParameters

java.lang.Object
  extended by bb.net.HttpParameters

public class HttpParameters
extends Object

This class provides a convenient way to store all the parameters associated with an http request in a form that is properly encoded for submission.

Many programmers use a Properties instance to do the same functionality as this class. Unfortunately, the Properties class has a fundamental defect: each key is always mapped to exactly one value. In contrast, each http parameter key is allowed to be mapped to many values; this class supports this feature. Furthermore, since this class is dedicated to supporting http parameters, it is more convenient to use for this purpose than the Properties class (e.g. the toGetParameterString and toPostParameterString methods).

This class is not multithread safe.

Author:
Brent Boyer

Field Summary
protected  StringBuilder buffer
          Stores the parameters as they are added.
 
Constructor Summary
HttpParameters()
          Simply calls this(1).
HttpParameters(int initialNumberOfParameters)
          Constructs a new HttpParameters instance.
 
Method Summary
 void addParameter(String name, String value)
          Simply calls addParameter(name, value, "UTF-8").
 void addParameter(String name, String value, String encoding)
          Adds name and value as a new properly encoded parameter to buffer.
 void addProperties(Properties properties)
          Simply calls addProperties(properties, "UTF-8").
 void addProperties(Properties properties, String encoding)
          Adds all the name and value pairs in the properties arg as parameters to this instance.
 String toFormUrlencodedString()
          Returns the parameters that have been added so far as a single String of name/value pairs that is properly encoded for HTML form submission as MIME type application/x-www-form-urlencoded.
 String toGetParameterString()
          Returns the parameters that have been added so far as a single String of name/value pairs that is suitable for appending to a URL as part of an HTTP GET request.
 String toPostParameterString()
          Returns the parameters that have been added so far as a single String of name/value pairs that is suitable for writing on an OutputStream to a server as part of an HTTP POST request.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

buffer

protected StringBuilder buffer
Stores the parameters as they are added. Is initialized in a constructor.

Constructor Detail

HttpParameters

public HttpParameters()
Simply calls this(1).


HttpParameters

public HttpParameters(int initialNumberOfParameters)
Constructs a new HttpParameters instance.

Parameters:
initialNumberOfParameters -
Method Detail

addProperties

public void addProperties(Properties properties)
                   throws IllegalArgumentException,
                          UnsupportedEncodingException
Simply calls addProperties(properties, "UTF-8").

Throws:
IllegalArgumentException - if properties == null; any (name, value) pair of properties violates what addParameter requires
UnsupportedEncodingException - if "UTF-8" is not a supported encoding (this should never happen)

addProperties

public void addProperties(Properties properties,
                          String encoding)
                   throws IllegalArgumentException,
                          UnsupportedEncodingException
Adds all the name and value pairs in the properties arg as parameters to this instance. This method is mainly provided for the convenience of old code which used Properties instances. New code should only use instances of this class.

Throws:
IllegalArgumentException - if properties == null; any (name, value) pair of properties or encoding violates what addParameter requires
UnsupportedEncodingException - if encoding is not supported

addParameter

public void addParameter(String name,
                         String value)
                  throws IllegalArgumentException,
                         UnsupportedEncodingException
Simply calls addParameter(name, value, "UTF-8").

Throws:
IllegalArgumentException - if either name is blank; value == null
UnsupportedEncodingException - if "UTF-8" is not a supported encoding (this should never happen)

addParameter

public void addParameter(String name,
                         String value,
                         String encoding)
                  throws IllegalArgumentException,
                         UnsupportedEncodingException
Adds name and value as a new properly encoded parameter to buffer. Before adding them, an ampersand is added if buffer already has contents (i.e. previous parameters). Also, both name and value are first converted into application/x-www-form-urlencoded MIME format using URLEncoder before being added.

Throws:
IllegalArgumentException - if either name is blank; value == null; encoding is blank
UnsupportedEncodingException - if encoding is not supported

toFormUrlencodedString

public String toFormUrlencodedString()
Returns the parameters that have been added so far as a single String of name/value pairs that is properly encoded for HTML form submission as MIME type application/x-www-form-urlencoded.

Note: the charset for URLs (which includes HTML form encoding) is "US-ASCII". One consequence is that the high byte of each char in the result is unused.

Returns:
a properly encoded String of the name/value pairs, or an empty String (i.e. "") if there are no name/value pairs

toGetParameterString

public String toGetParameterString()
Returns the parameters that have been added so far as a single String of name/value pairs that is suitable for appending to a URL as part of an HTTP GET request.

Returns:
the result of "?" + toFormUrlencodedString()
See Also:
toFormUrlencodedString()

toPostParameterString

public String toPostParameterString()
Returns the parameters that have been added so far as a single String of name/value pairs that is suitable for writing on an OutputStream to a server as part of an HTTP POST request.

Returns:
the result of toFormUrlencodedString()
See Also:
toFormUrlencodedString()