com.google.gdata.util.common.net

Class UriParameterMap

java.lang.Object

com.google.common.collect.ForwardingObject

com.google.common.collect.ForwardingMultimap<java.lang.String,java.lang.String>

com.google.gdata.util.common.net.UriParameterMap

All Implemented Interfaces:

com.google.common.collect.ListMultimap<java.lang.String,java.lang.String>, com.google.common.collect.Multimap<java.lang.String,java.lang.String>, java.io.Serializable, java.lang.Cloneable

public final class UriParameterMap
extends com.google.common.collect.ForwardingMultimap<java.lang.String,java.lang.String>
implements com.google.common.collect.ListMultimap<java.lang.String,java.lang.String>, java.lang.Cloneable, java.io.Serializable

Represents a sequence of name-value pairs encoded using the application/x-www-form-urlencoded content type, typically as the query part of a URI, as defined by section 17.13.4 of the W3C's HTML 4.01 Specification.

This class stores keys and values in unicode (decoded) form, allowing clients to get and set parameters safely using normal strings. Encoding is performed when toString(Charset) is called. See the UriEncoder class comments for an important discussion regarding encoding.

Parameter maps may not contain null values. Both keys and values are allowed to be the empty string, though in most cases only values are the empty string. Parsing a query string may be a "lossy" operation in the trivial sense, in that the original string cannot be exactly reconstructed; for example, the query string "foo=&bar" is considered equivalent to "foo&bar". Also note that parsing the empty string will not return an empty map but will return a map with a single entry of the empty string as both key and value. The empty map (see EMPTY_MAP) represents an undefined query.

In addition to the ListMultimap API, this class provides a convenient getFirst(java.lang.String) method for retrieving the first value of a parameter, for when you expect only a single parameter of the specified name.

Parameter maps are typically constructed either by Uri or UriBuilder. However, you may also construct a parameter map from scratch using the constructor, or by calling parse(String).

See Also:

UriBuilder#getQueryParameters(), Uri#getQueryParameters(), Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static UriParameterMap	EMPTY_MAP The immutable empty map.

Constructor Summary

Constructors

Constructor and Description
UriParameterMap() Constructs a new empty parameter map.

Method Summary

Methods

Modifier and Type	Method and Description
void	appendTo(java.lang.Appendable out, java.nio.charset.Charset encoding) Appends the string representation of these parameters to the specified Appendable using the specified encoding.
void	appendTo(java.lang.StringBuilder out, java.nio.charset.Charset encoding) Appends the string representation of these parameters to the specified string builder using the specified encoding.
UriParameterMap	clone()
java.util.Map<java.lang.String,java.lang.String[]>	copyToArrayMap() Returns an immutable copy of this parameter map as a Map from strings to string arrays.
protected com.google.common.collect.ListMultimap<java.lang.String,java.lang.String>	delegate()
java.util.List<java.lang.String>	get(java.lang.String key)
java.lang.String	getFirst(java.lang.String key) Returns the first parameter value for the specified key (parameter name) or null if no parameters are defined for that key.
static UriParameterMap	parse(java.lang.String query) Constructs a new parameter map populated with parameters parsed from the specified query string using the UriEncoder.DEFAULT_ENCODING, UTF-8.
static UriParameterMap	parse(java.lang.String query, java.nio.charset.Charset encoding) Constructs a new parameter map populated with parameters parsed from the specified query string using the specified encoding.
java.util.List<java.lang.String>	removeAll(java.lang.Object key)
java.util.List<java.lang.String>	replaceValues(java.lang.String key, java.lang.Iterable<? extends java.lang.String> values)
java.lang.String	toString() Returns the string representation of these parameters using the UriEncoder.DEFAULT_ENCODING, UTF-8, e.g., "q=flowers&n=20".
java.lang.String	toString(java.nio.charset.Charset encoding) Returns the string representation of these parameters using the specified encoding, e.g., "q=flowers&n=20".
static UriParameterMap	unmodifiableMap(UriParameterMap map) Returns an unmodifiable view of the specified parameter map.

Methods inherited from class com.google.common.collect.ForwardingMultimap

asMap, clear, containsEntry, containsKey, containsValue, entries, equals, hashCode, isEmpty, keys, keySet, put, putAll, putAll, remove, size, values

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.google.common.collect.ListMultimap

asMap, equals

Methods inherited from interface com.google.common.collect.Multimap

clear, containsEntry, containsKey, containsValue, entries, hashCode, isEmpty, keys, keySet, put, putAll, putAll, remove, size, values

Field Detail

EMPTY_MAP

public static final UriParameterMap EMPTY_MAP

The immutable empty map.

Constructor Detail

UriParameterMap

public UriParameterMap()

Constructs a new empty parameter map.

Method Detail

parse

public static UriParameterMap parse(java.lang.String query)

Constructs a new parameter map populated with parameters parsed from the specified query string using the UriEncoder.DEFAULT_ENCODING, UTF-8.

Parameters:

query - the query string, e.g., "q=flowers&n=20"

Returns:

a mutable parameter map representing the query string

Throws:

java.lang.NullPointerException - if query is null

parse

public static UriParameterMap parse(java.lang.String query,
                    java.nio.charset.Charset encoding)

Constructs a new parameter map populated with parameters parsed from the specified query string using the specified encoding.

Parameters:

query - the query string, e.g., "q=flowers&n=20"

encoding - the character encoding to use

Returns:

a mutable parameter map representing the query string

Throws:

java.lang.NullPointerException - if any argument is null

unmodifiableMap

public static UriParameterMap unmodifiableMap(UriParameterMap map)

Returns an unmodifiable view of the specified parameter map. This method allows modules to provide users with "read-only" access to internal parameter maps. Query operations on the returned map "read through" to the specified map, and attempts to modify the returned map, whether direct or via its iterator or collection views, result in an UnsupportedOperationException.

Parameters:

map - the parameter map for which to return an unmodifiable view

Returns:

an unmodifiable view of the specified parameter map

Throws:

java.lang.NullPointerException - if map is null

delegate

protected com.google.common.collect.ListMultimap<java.lang.String,java.lang.String> delegate()

Overrides:

delegate in class com.google.common.collect.ForwardingMultimap<java.lang.String,java.lang.String>

getFirst

public java.lang.String getFirst(java.lang.String key)

Returns the first parameter value for the specified key (parameter name) or null if no parameters are defined for that key. If the parameter is defined, equivalent to get(key).get(0).

Parameters:

key - the name of the parameter

Returns:

the value of the parameter if present, or null

See Also:

javax.servlet.ServletRequest#getParameter(String)

appendTo

public void appendTo(java.lang.StringBuilder out,
            java.nio.charset.Charset encoding)

Appends the string representation of these parameters to the specified string builder using the specified encoding.

Parameters:

out - the string builder to append to

encoding - the character encoding to use

Throws:

java.lang.NullPointerException - if any argument is null

appendTo

public void appendTo(java.lang.Appendable out,
            java.nio.charset.Charset encoding)
              throws java.io.IOException

Appends the string representation of these parameters to the specified Appendable using the specified encoding.

Parameters:

out - the appendable to append to

encoding - the character encoding to use

Throws:

java.lang.NullPointerException - if any argument is null

java.io.IOException - if the Appendable encounters an error

clone

public UriParameterMap clone()

Overrides:

clone in class java.lang.Object

toString

public java.lang.String toString(java.nio.charset.Charset encoding)

Returns the string representation of these parameters using the specified encoding, e.g., "q=flowers&n=20".

Parameters:

encoding - the character encoding to use

Throws:

java.lang.NullPointerException - if encoding is null

copyToArrayMap

public java.util.Map<java.lang.String,java.lang.String[]> copyToArrayMap()

Returns an immutable copy of this parameter map as a Map from strings to string arrays.

toString

public java.lang.String toString()

Returns the string representation of these parameters using the UriEncoder.DEFAULT_ENCODING, UTF-8, e.g., "q=flowers&n=20".

Overrides:

toString in class com.google.common.collect.ForwardingObject

get

public java.util.List<java.lang.String> get(java.lang.String key)

Specified by:

get in interface com.google.common.collect.ListMultimap<java.lang.String,java.lang.String>

Specified by:

get in interface com.google.common.collect.Multimap<java.lang.String,java.lang.String>

Overrides:

get in class com.google.common.collect.ForwardingMultimap<java.lang.String,java.lang.String>

removeAll

public java.util.List<java.lang.String> removeAll(java.lang.Object key)

Specified by:

removeAll in interface com.google.common.collect.ListMultimap<java.lang.String,java.lang.String>

Specified by:

removeAll in interface com.google.common.collect.Multimap<java.lang.String,java.lang.String>

Overrides:

removeAll in class com.google.common.collect.ForwardingMultimap<java.lang.String,java.lang.String>

replaceValues

public java.util.List<java.lang.String> replaceValues(java.lang.String key,
                                             java.lang.Iterable<? extends java.lang.String> values)

Specified by:

replaceValues in interface com.google.common.collect.ListMultimap<java.lang.String,java.lang.String>

Specified by:

replaceValues in interface com.google.common.collect.Multimap<java.lang.String,java.lang.String>

Overrides:

replaceValues in class com.google.common.collect.ForwardingMultimap<java.lang.String,java.lang.String>