UrlEncodedQueryString now Open Sourced

I just Open Sourced my UrlEncodedQueryString implementation over at java.net.

This is a project I worked on with Sun in response to this RFE, but that ultimately never made it into the JDK. I still use it extensively in my own projects, however, and find it very useful.

A recent posting in the RFE's comments section prompted me to dust it off and give it a good home. Enjoy!

Overview: Represents a www-form-urlencoded query string

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. Methods for creating, retrieving, updating and deleting the parameters on a query string, and methods for applying 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 to its constructor:

URI uri = new URI("http://java.sun.com?forum=2");
UrlEncodedQueryString queryString = new UrlEncodedQueryString(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 = new UrlEncodedQueryString(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 = new UrlEncodedQueryString(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.

JavaDoc

For more information, see the JavaDoc.