Package nl.colorize.util.http

Class PostData

java.lang.Object

nl.colorize.util.http.PostData

public class PostData
extends Object

Represents data that has been sent as part of an HTTP request and is encoded using the application/x-www-form-urlencoded content type. This is commonly used in URL query strings, and in "classic" HTML forms as documented in sections 4.10.21.7 and 4.10.21.8 of the HTML specification.

Post data parameters consist of name/value pairs. This class provides two ways to retrieve parameter values: getRequiredParameter(String) (which will throw an exception if the parameter is not present), and getOptionalParameter(String, String) (which will return a default value for missing parameters). Note that the parameter is considered "missing" if it is either not present at all, or if the parameter name is specified but its value is empty.

Method Summary

Modifier and Type	Method	Description
boolean	contains(String name)	Returns true if this PostData contains at least one parameter with the specified name.
static PostData	create(String key, String value, String... rest)	Creates a PostData instance from a number of key/value pairs.
static PostData	create(Map<String,?> data)	Creates a PostData instance from existing key/value pairs.
static PostData	empty()	Utility method that returns a PostData instance that indicates no parameters have been specified.
String	encode()	Encodes this PostData into a string that follows the application/x-www-form-urlencoded notation, using the UTF-8 character encoding.
String	encode(Charset charset)	Encodes this PostData into a string that follows the application/x-www-form-urlencoded notation.
boolean	equals(Object o)
String	getOptionalParameter(String name, String defaultValue)	Returns either the value of the parameter with the specified name, or defaultValue if no parameter with that name exists.
List<String>	getParameterValues(String name)	Returns all values for the parameter with the specified name.
String	getRequiredParameter(String name)	Returns the value of the parameter with the specified name.
int	hashCode()
boolean	isEmpty()
PostData	merge(PostData other)	Creates a new PostData instance by merging all parameters from this instance with another one.
static PostData	parse(String encoded)	Parses PostData from the specified string using the UTF-8 character encoding.
static PostData	parse(String encoded, Charset charset)	Parses PostData from the specified string.
Map<String,String>	toMap()	Deprecated. Using a map does not allow for an explicit iteration order, and it also does not allow multiple parameters to use the same name.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Details

getRequiredParameter

public String getRequiredParameter(String name)

Returns the value of the parameter with the specified name. If multiple parameters match the requested name, the first occurrence will be returned. Use getParameterValues(String) if you want to retrieve all matching parameters.

Throws:

IllegalStateException - if no parameter with that name exists.

getOptionalParameter

public String getOptionalParameter(String name,
 String defaultValue)

Returns either the value of the parameter with the specified name, or defaultValue if no parameter with that name exists.

getParameterValues

public List<String> getParameterValues(String name)

Returns all values for the parameter with the specified name. Returns an empty list if no matching parameters exist. This can also return multiple values, as it is allowed for multiple parameters to have the same name.

contains

public boolean contains(String name)

Returns true if this PostData contains at least one parameter with the specified name.

isEmpty

public boolean isEmpty()

toMap

@Deprecated
public Map<String,String> toMap()

Deprecated.

Using a map does not allow for an explicit iteration order, and it also does not allow multiple parameters to use the same name.

Creates a map that includes all parameters in this PostData. If multiple parameters share the same name, the map will include the first occurrence.

merge

public PostData merge(PostData other)

Creates a new PostData instance by merging all parameters from this instance with another one.

Throws:

IllegalArgumentException - if both instances contain a parameter with the same name.

encode

public String encode(Charset charset)

Encodes this PostData into a string that follows the application/x-www-form-urlencoded notation. An example of such a string is a=2&b=3. If this PostData contains no parameters this will return an empty string.

encode

public String encode()

Encodes this PostData into a string that follows the application/x-www-form-urlencoded notation, using the UTF-8 character encoding. An example of such a string is a=2&b=3. If this PostData contains no parameters this will return an empty string.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

create

public static PostData create(String key,
 String value,
 String... rest)

Creates a PostData instance from a number of key/value pairs. When specifying multiple key/value pairs, the rest parameter expects the order key1, value1, key2, value2, ....

Throws:

IllegalArgumentException - if the number of parameters is not a multiple of two.

create

public static PostData create(Map<String,?> data)

Creates a PostData instance from existing key/value pairs. The parameter order will be based on the map's iteration order.

parse

public static PostData parse(String encoded,
 Charset charset)

Parses PostData from the specified string. The input is expected to follow the application/x-www-form-urlencoded notation, for example b=2&c=3. If the encoded input string is empty, this will return empty().

parse

public static PostData parse(String encoded)

Parses PostData from the specified string using the UTF-8 character encoding. The input is expected to follow the application/x-www-form-urlencoded notation, for example b=2&c=3. If the encoded input string is empty, this will return empty().

empty

public static PostData empty()

Utility method that returns a PostData instance that indicates no parameters have been specified. Encoding this instance will produce an empty string.