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
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)
.
UriBuilder#getQueryParameters()
,
Uri#getQueryParameters()
,
Serialized FormModifier and Type | Field and Description |
---|---|
static UriParameterMap |
EMPTY_MAP
The immutable empty map.
|
Constructor and Description |
---|
UriParameterMap()
Constructs a new empty parameter map.
|
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. |
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.
|
public static final UriParameterMap EMPTY_MAP
public static UriParameterMap parse(java.lang.String query)
UriEncoder.DEFAULT_ENCODING
,
UTF-8.query
- the query string, e.g., "q=flowers&n=20"java.lang.NullPointerException
- if query
is nullpublic static UriParameterMap parse(java.lang.String query, java.nio.charset.Charset encoding)
query
- the query string, e.g., "q=flowers&n=20"encoding
- the character encoding to usejava.lang.NullPointerException
- if any argument is nullpublic static UriParameterMap unmodifiableMap(UriParameterMap map)
UnsupportedOperationException
.map
- the parameter map for which to return an unmodifiable viewjava.lang.NullPointerException
- if map
is nullpublic java.lang.String getFirst(java.lang.String key)
key
(parameter
name) or null
if no parameters are defined for that key. If the
parameter is defined, equivalent to get(key).get(0)
.key
- the name of the parameterjavax.servlet.ServletRequest#getParameter(String)
public void appendTo(java.lang.StringBuilder out, java.nio.charset.Charset encoding)
out
- the string builder to append toencoding
- the character encoding to usejava.lang.NullPointerException
- if any argument is nullpublic void appendTo(java.lang.Appendable out, java.nio.charset.Charset encoding) throws java.io.IOException
Appendable
using the specified encoding.out
- the appendable to append toencoding
- the character encoding to usejava.lang.NullPointerException
- if any argument is nulljava.io.IOException
- if the Appendable
encounters an errorpublic UriParameterMap clone()
clone
in class java.lang.Object
public java.lang.String toString(java.nio.charset.Charset encoding)
encoding
- the character encoding to usejava.lang.NullPointerException
- if encoding
is nullpublic java.util.Map<java.lang.String,java.lang.String[]> copyToArrayMap()
Map
from
strings to string arrays.public java.lang.String toString()
UriEncoder.DEFAULT_ENCODING
, UTF-8, e.g., "q=flowers&n=20".toString
in class com.google.common.collect.ForwardingObject
public java.util.List<java.lang.String> get(java.lang.String key)
get
in interface com.google.common.collect.ListMultimap<java.lang.String,java.lang.String>
get
in interface com.google.common.collect.Multimap<java.lang.String,java.lang.String>
get
in class com.google.common.collect.ForwardingMultimap<java.lang.String,java.lang.String>
public java.util.List<java.lang.String> removeAll(java.lang.Object key)
removeAll
in interface com.google.common.collect.ListMultimap<java.lang.String,java.lang.String>
removeAll
in interface com.google.common.collect.Multimap<java.lang.String,java.lang.String>
removeAll
in class com.google.common.collect.ForwardingMultimap<java.lang.String,java.lang.String>
public java.util.List<java.lang.String> replaceValues(java.lang.String key, java.lang.Iterable<? extends java.lang.String> values)
replaceValues
in interface com.google.common.collect.ListMultimap<java.lang.String,java.lang.String>
replaceValues
in interface com.google.common.collect.Multimap<java.lang.String,java.lang.String>
replaceValues
in class com.google.common.collect.ForwardingMultimap<java.lang.String,java.lang.String>