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

java.lang.Object
  extended by com.google.common.collect.ForwardingObject
      extended by com.google.common.collect.ForwardingMultimap<java.lang.String,java.lang.String>
          extended by 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
static UriParameterMap EMPTY_MAP
          The immutable empty map.
 
Constructor Summary
UriParameterMap()
          Constructs a new empty parameter map.
 
Method Summary
 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>