wcs.api

Class URL

java.lang.Object

wcs.api.URL

public class URL
extends java.lang.Object

Represents a www-form-urlencoded query string containing an (ordered) list of parameters. It also stores the path and return a string tokenizer to read path elements.

An instance of this class represents a query string encoded using the www-form-urlencoded encoding scheme, as defined by HTML 4.01 Specification: application/x-www-form-urlencoded, and HTML 4.01 Specification: Ampersands in URI attribute values. This is a common encoding scheme of the query component of a URI, though the RFC 2396 URI specification itself does not define a specific format for the query component.

This class provides static methods for creating UrlEncodedQueryString instances by parsing URI and string forms. It can then be used to create, retrieve, update and delete parameters, and to re-apply the query string back to an existing URI.

Encoding and decoding

UrlEncodedQueryString automatically encodes and decodes parameter names and values to and from www-form-urlencoded encoding by using java.net.URLEncoder and java.net.URLDecoder, which follow the HTML 4.01 Specification: Non-ASCII characters in URI attribute values recommendation.

Multivalued parameters

Often, parameter names are unique across the name/value pairs of a www-form-urlencoded query string. However, it is permitted for the same parameter name to appear in multiple name/value pairs, denoting that a single parameter has multiple values. This less common use case can lead to ambiguity when adding parameters - is the 'add' a 'replace' (of an existing parameter, if one with the same name already exists) or an 'append' (potentially creating a multivalued parameter, if one with the same name already exists)?

This requirement significantly shapes the UrlEncodedQueryString API. In particular there are:

• set methods for setting a parameter, potentially replacing an existing value
• append methods for adding a parameter, potentially creating a multivalued parameter
• get methods for returning a single value, even if the parameter has multiple values
• getValues methods for returning multiple values

Retrieving parameters

UrlEncodedQueryString can be used to parse and retrieve parameters from a query string by passing either a URI or a query string:

URI uri = new URI("http://java.sun.com?forum=2");
UrlEncodedQueryString queryString = UrlEncodedQueryString.parse(uri);
System.out.println(queryString.get("forum"));


Modifying parameters

UrlEncodedQueryString can be used to set, append or remove parameters from a query string:

URI uri = new URI("/forum/article.jsp?id=2&para=4");
UrlEncodedQueryString queryString = UrlEncodedQueryString.parse(uri);
queryString.set("id", 3);
queryString.remove("para");
System.out.println(queryString);


When modifying parameters, the ordering of existing parameters is maintained. Parameters are set and removed in-place, while appended parameters are added to the end of the query string.

Applying the Query

UrlEncodedQueryString can be used to apply a modified query string back to a URI, creating a new URI:

URI uri = new URI("/forum/article.jsp?id=2");
UrlEncodedQueryString queryString = UrlEncodedQueryString.parse(uri);
queryString.set("id", 3);
uri = queryString.apply(uri);


When reconstructing query strings, there are two valid separator parameters defined by the W3C (ampersand "&" and semicolon ";"), with ampersand being the most common. The apply and toString methods both default to using an ampersand, with overloaded forms for using a semicolon.

Thread Safety

This implementation is not synchronized. If multiple threads access a query string concurrently, and at least one of the threads modifies the query string, it must be synchronized externally. This is typically accomplished by synchronizing on some object that naturally encapsulates the query string.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	URL.Separator Enumeration of recommended www-form-urlencoded separators.

Method Summary

Methods

Modifier and Type	Method and Description
URL	append(java.lang.String query) Appends query parameters from a www-form-urlencoded string.
URL	append(java.lang.String name, java.lang.Number value) Appends a query parameter.
URL	append(java.lang.String name, java.lang.String value) Appends a query parameter.
java.net.URI	apply(java.net.URI uri) Applies the query string to the given URI.
java.net.URI	apply(java.net.URI uri, URL.Separator separator) Applies the query string to the given URI, using the given separator between parameters.
boolean	contains(java.lang.String name) Returns whether the named parameter exists.
static URL	create() Creates an empty UrlEncodedQueryString.
static URL	create(java.lang.String path, java.util.Map<java.lang.String,java.util.List<java.lang.String>> parameterMap) Creates a UrlEncodedQueryString from the given Map.
boolean	equals(java.lang.Object obj) Compares the specified object with this UrlEncodedQueryString for equality.
java.lang.String	get(java.lang.String name) Returns the value of the named parameter as a String.
java.util.Map<java.lang.String,java.util.List<java.lang.String>>	getMap() Returns a mutable Map of the query parameters.
java.util.Iterator<java.lang.String>	getNames() Returns an Iterator of String objects containing the names of the parameters.
java.lang.String	getPath()
java.util.StringTokenizer	getPathTokens() Return a string tokenizer for path elements
java.util.List<java.lang.String>	getValues(java.lang.String name) Returns a List of String objects containing all of the values the named parameter has, or null if the parameter does not exist.
int	hashCode() Returns a hash code value for the UrlEncodedQueryString.
boolean	isEmpty() Returns whether the query string is empty.
static URL	parse(java.lang.String path, java.lang.String query)
static URL	parse(java.net.URI uri) Creates a UrlEncodedQueryString by extracting and parsing the query component from the given URI.
URL	remove(java.lang.String name) Removes the named query parameter.
URL	set(java.lang.String query) Sets query parameters from a www-form-urlencoded string.
URL	set(java.lang.String name, java.lang.Number value) Sets a query parameter.
URL	set(java.lang.String name, java.lang.String value) Sets a query parameter.
java.lang.String	toString() Returns a www-form-urlencoded string of the query parameters.
java.lang.String	toString(URL.Separator separator) Returns a www-form-urlencoded string of the query parameters, using the given separator between parameters.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static URL create()

Creates an empty UrlEncodedQueryString.

Calling toString() on the created instance will return an empty String.

create

public static URL create(java.lang.String path,
         java.util.Map<java.lang.String,java.util.List<java.lang.String>> parameterMap)

Creates a UrlEncodedQueryString from the given Map.

The order the parameters are created in corresponds to the iteration order of the Map.

Parameters:

parameterMap - Map containing parameter names and values.

parse

public static URL parse(java.lang.String path,
        java.lang.String query)

parse

public static URL parse(java.net.URI uri)

Creates a UrlEncodedQueryString by extracting and parsing the query component from the given URI.

This method assumes the query component is www-form-urlencoded. When parsing, all separators from the Separators enum are recognised.

The result of calling this method with a query component that is not www-form-urlencoded will likely be mismatched parameter names.

Parameters:

uri - URI to be parsed

getPath

public java.lang.String getPath()

get

public java.lang.String get(java.lang.String name)

Returns the value of the named parameter as a String. Returns null if the parameter does not exist, or exists but has a null value (see contains).

You should only use this method when you are sure the parameter has only one value. If the parameter might have more than one value, use getValues.

If you use this method with a multivalued parameter, the value returned is equal to the first value in the List returned by getValues.

Parameters:

name - String specifying the name of the parameter

Returns:

String representing the single value of the parameter, or null if the parameter does not exist or exists but with a null value (see contains).

contains

public boolean contains(java.lang.String name)

Returns whether the named parameter exists.

This can be useful to distinguish between a parameter not existing, and a parameter existing but with a null value (eg. foo=1&bar). This is distinct from a parameter existing with a value of the empty String (eg. foo=1&bar=).

getNames

public java.util.Iterator<java.lang.String> getNames()

Returns an Iterator of String objects containing the names of the parameters. If there are no parameters, the method returns an empty Iterator. For names with multiple values, only one copy of the name is returned.

Returns:

an Iterator of String objects, each String containing the name of a parameter; or an empty Iterator if there are no parameters

getValues

public java.util.List<java.lang.String> getValues(java.lang.String name)

Returns a List of String objects containing all of the values the named parameter has, or null if the parameter does not exist.

If the parameter has a single value, the List has a size of 1.

Parameters:

name - name of the parameter to retrieve

Returns:

a List of String objects containing the parameter's values, or null if the paramater does not exist

getMap

public java.util.Map<java.lang.String,java.util.List<java.lang.String>> getMap()

Returns a mutable Map of the query parameters.

Returns:

Map containing parameter names as keys and parameter values as map values. The keys in the parameter map are of type String. The values in the parameter map are Lists of type String, and their ordering is consistent with their ordering in the query string. Will never return null.

getPathTokens

public java.util.StringTokenizer getPathTokens()

Return a string tokenizer for path elements

Returns:

set

public URL set(java.lang.String name,
      java.lang.String value)

Sets a query parameter.

If one or more parameters with this name already exist, they will be replaced with a single parameter with the given value. If no such parameters exist, one will be added.

Parameters:

name - name of the query parameter

value - value of the query parameter. If null, the parameter is removed

Returns:

a reference to this object

set

public URL set(java.lang.String name,
      java.lang.Number value)

Sets a query parameter.

If one or more parameters with this name already exist, they will be replaced with a single parameter with the given value. If no such parameters exist, one will be added.

This version of set accepts a Number suitable for auto-boxing. For example:

queryString.set( "id", 3 );


Parameters:

name - name of the query parameter

value - value of the query parameter. If null, the parameter is removed

Returns:

a reference to this object

set

public URL set(java.lang.String query)

Sets query parameters from a www-form-urlencoded string.

The given string is assumed to be in www-form-urlencoded format. The result of passing a string not in www-form-urlencoded format (eg. passing an entire URI, not just its query string) will likely be mismatched parameter names.

The given string is parsed into named parameters, and each is added to the existing parameters. If a parameter with the same name already exists, it is replaced with a single parameter with the given value. If the same parameter name appears more than once in the given string, it is stored as a multivalued parameter. When parsing, all Separators are recognised.

Parameters:

query - www-form-urlencoded string. If null, does nothing

Returns:

a reference to this object

append

public URL append(java.lang.String name,
         java.lang.String value)

Appends a query parameter.

If one or more parameters with this name already exist, their value will be preserved and the given value will be stored as a multivalued parameter. If no such parameters exist, one will be added.

Parameters:

name - name of the query parameter

value - value of the query parameter. If null, does nothing

Returns:

a reference to this object

append

public URL append(java.lang.String name,
         java.lang.Number value)

Appends a query parameter.

If one or more parameters with this name already exist, their value will be preserved and the given value will be stored as a multivalued parameter. If no such parameters exist, one will be added.

This version of append accepts a Number suitable for auto-boxing. For example:

queryString.append( "id", 3 );


Parameters:

name - name of the query parameter

value - value of the query parameter. If null, does nothing

Returns:

a reference to this object

append

public URL append(java.lang.String query)

Appends query parameters from a www-form-urlencoded string.

The given string is assumed to be in www-form-urlencoded format. The result of passing a string not in www-form-urlencoded format (eg. passing an entire URI, not just its query string) will likely be mismatched parameter names.

The given string is parsed into named parameters, and appended to the existing parameters. If a parameter with the same name already exists, or if the same parameter name appears more than once in the given string, it is stored as a multivalued parameter. When parsing, all Separators are recognised.

Parameters:

query - www-form-urlencoded string. If null, does nothing

Returns:

a reference to this object

isEmpty

public boolean isEmpty()

Returns whether the query string is empty.

Returns:

true if the query string has no parameters

remove

public URL remove(java.lang.String name)

Removes the named query parameter.

If the parameter has multiple values, all its values are removed.

Parameters:

name - name of the parameter to remove

Returns:

a reference to this object

apply

public java.net.URI apply(java.net.URI uri)

Applies the query string to the given URI.

A copy of the given URI is taken and its existing query string, if there is one, is replaced. The query string parameters are separated by Separator.Ampersand.

Parameters:

uri - URI to copy and update

Returns:

a copy of the given URI, with an updated query string

apply

public java.net.URI apply(java.net.URI uri,
                 URL.Separator separator)

Applies the query string to the given URI, using the given separator between parameters.

A copy of the given URI is taken and its existing query string, if there is one, is replaced. The query string parameters are separated using the given Separator.

Parameters:

uri - URI to copy and update

separator - separator to use between parameters

Returns:

a copy of the given URI, with an updated query string

equals

public boolean equals(java.lang.Object obj)

Compares the specified object with this UrlEncodedQueryString for equality.

Returns true if the given object is also a UrlEncodedQueryString and the two UrlEncodedQueryStrings have the same parameters. More formally, two UrlEncodedQueryStrings t1 and t2 represent the same UrlEncodedQueryString if t1.toString().equals(t2.toString()). This ensures that the equals method checks the ordering, as well as the existence, of every parameter.

Clients interested only in the existence, not the ordering, of parameters are recommended to use getMap().equals.

This implementation first checks if the specified object is this UrlEncodedQueryString; if so it returns true. Then, it checks if the specified object is a UrlEncodedQueryString whose toString() is identical to the toString() of this UrlEncodedQueryString; if not, it returns false. Otherwise, it returns true

Overrides:

equals in class java.lang.Object

Parameters:

obj - object to be compared for equality with this UrlEncodedQueryString.

Returns:

true if the specified object is equal to this UrlEncodedQueryString.

hashCode

public int hashCode()

Returns a hash code value for the UrlEncodedQueryString.

The hash code of the UrlEncodedQueryString is defined to be the hash code of the String returned by toString(). This ensures the ordering, as well as the existence, of parameters is taken into account.

Clients interested only in the existence, not the ordering, of parameters are recommended to use getMap().hashCode.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this UrlEncodedQueryString.

toString

public java.lang.String toString()

Returns a www-form-urlencoded string of the query parameters.

The HTML specification recommends two parameter separators in HTML 4.01 Specification: application/x-www-form-urlencoded and HTML 4.01 Specification: Ampersands in URI attribute values. Of those, the ampersand is the more commonly used and this method defaults to that.

Overrides:

toString in class java.lang.Object

Returns:

www-form-urlencoded string, or null if there are no parameters.

toString

public java.lang.String toString(URL.Separator separator)

Returns a www-form-urlencoded string of the query parameters, using the given separator between parameters.

Parameters:

separator - separator to use between parameters

Returns:

www-form-urlencoded string, or an empty String if there are no parameters