public final class

UriParameterMap

extends ForwardingMultimap<K, V>
implements ListMultimap<K, V> Serializable Cloneable
java.lang.Object
   ↳ com.google.common.collect.ForwardingObject
     ↳ com.google.common.collect.ForwardingMultimap<K, V>
       ↳ com.google.gdata.util.common.net.UriParameterMap

Class Overview

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(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()

Summary

Constants
long serialVersionUID
Fields
public static final UriParameterMap EMPTY_MAP The immutable empty map.
private final ListMultimap<String, String> delegate
Public Constructors
UriParameterMap()
Constructs a new empty parameter map.
Public Methods
void appendTo(StringBuilder out, Charset encoding)
Appends the string representation of these parameters to the specified string builder using the specified encoding.
void appendTo(Appendable out, Charset encoding)
Appends the string representation of these parameters to the specified Appendable using the specified encoding.
UriParameterMap clone()
Map<String, String[]> copyToArrayMap()
Returns an immutable copy of this parameter map as a Map from strings to string arrays.
List<String> get(String key)
String getFirst(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(String query)
Constructs a new parameter map populated with parameters parsed from the specified query string using the DEFAULT_ENCODING, UTF-8.
static UriParameterMap parse(String query, Charset encoding)
Constructs a new parameter map populated with parameters parsed from the specified query string using the specified encoding.
List<String> removeAll(Object key)
List<String> replaceValues(String key, Iterable<? extends String> values)
String toString()
Returns the string representation of these parameters using the DEFAULT_ENCODING, UTF-8, e.g., "q=flowers&n=20".
String toString(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.
Protected Methods
ListMultimap<String, String> delegate()
[Expand]
Inherited Methods
From class com.google.common.collect.ForwardingMultimap
From class com.google.common.collect.ForwardingObject
From class java.lang.Object
From interface com.google.common.collect.ListMultimap
From interface com.google.common.collect.Multimap

Constants

private static final long serialVersionUID

Constant Value: -3053773769157973706 (0xd59ed0efc0eee936)

Fields

public static final UriParameterMap EMPTY_MAP

The immutable empty map.

private final ListMultimap<String, String> delegate

Public Constructors

public UriParameterMap ()

Constructs a new empty parameter map.

Public Methods

public void appendTo (StringBuilder out, 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
NullPointerException if any argument is null

public void appendTo (Appendable out, Charset encoding)

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
NullPointerException if any argument is null
IOException if the Appendable encounters an error

public UriParameterMap clone ()

public Map<String, String[]> copyToArrayMap ()

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

public List<String> get (String key)

Parameters
key

public String getFirst (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)

public static UriParameterMap parse (String query)

Constructs a new parameter map populated with parameters parsed from the specified query string using the 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
NullPointerException if query is null

public static UriParameterMap parse (String query, 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
NullPointerException if any argument is null

public List<String> removeAll (Object key)

Parameters
key

public List<String> replaceValues (String key, Iterable<? extends String> values)

Parameters
key
values

public String toString ()

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

public String toString (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
NullPointerException if encoding is null

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
NullPointerException if map is null

Protected Methods

protected ListMultimap<String, String> delegate ()