QueryParams (filter-service-metrics 1.13 1.13 API)

public interface QueryParams

Immutable HTTP query parameters.

Building a new `QueryParams`

You can use the QueryParams.of() factory methods or the QueryParamsBuilder to build a new QueryParams from scratch:


 // Using of()
 QueryParams paramsWithOf = QueryParams.of("the_string", "fourty-two",
                                           "the_number", 42);

 // Using builder()
 QueryParams paramsWithBuilder =
     QueryParams.builder()
                .add("the_string", "forty-two")
                .add("the_number", 42)
                .build();

 assert paramsWithOf.equals(paramsWithBuilder);

Building a new `QueryParams` from an existing one

You can use toBuilder() or withMutations(Consumer) to build a new QueryParams derived from an existing one:


 QueryParams params = QueryParams.of("name1", "value0");

 // Using toBuilder()
 QueryParams paramsWithToBuilder = params.toBuilder()
                                         .set("name1", "value1")
                                         .add("name2", "value2")
                                         .build();
 // Using withMutations()
 QueryParams paramsWithMutations = params.withMutations(builder -> {
     builder.set("name1", "value1");
     builder.add("name2", "value2");
 });

 assert paramsWithToBuilder.equals(paramsWithMutations);

 // Note that the original parameters remain unmodified.
 assert !params.equals(paramsWithToBuilder);
 assert !params.equals(paramsWithMutations);

Specifying a non-`String` parameter value

Certain parameter values are better represented as a Java object, such as Integer, MediaType, Instant or Date, than as a String. Armeria's query parameters API allows you to specify a Java object of well-known type as a parameter value by converting it into an HTTP-friendly String representation:

Number, CharSequence and MediaType
- Converted via toString()
- e.g. "42", "string", "text/plain; charset=utf-8"
CacheControl
- Converted via asHeaderValue()
- e.g. "no-cache, no-store, must-revalidate"
Instant, TemporalAccessor, Date and Calendar
- Converted into a time and date string as specified in RFC1123
- e.g. Sun, 27 Nov 2016 19:37:15 UTC
All other types
- Converted via toString()

Using `QueryParams.of()` factory methods


 QueryParams params = QueryParams.of("the-number", 42,
                                     "the-media-type", MediaType.JSON_UTF_8,
                                     "the-date", Instant.now());

Using `QueryParamsBuilder`


 QueryParams params =
     QueryParams.builder()
                .setObject("the-number", 42)
                .setObject("the-media-type", MediaType.JSON_UTF_8)
                .setObject("the-date", Instant.now())
                .build();

Specifying value type explicitly

You might prefer type-safe setters for more efficiency and less ambiguity:


 QueryParams params =
     QueryParams.builder()
                .setInt("the-number", 42)
                .set("the-media-type", MediaType.JSON_UTF_8.toString())
                .setTimeMillis("the-date", System.currentTimeMillis())
                .build();

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default StringBuilder`	`appendQueryString(StringBuilder buf)` Encodes all parameter entries into a query string, as defined in 4.10.22.6, HTML5 W3C Recommendation, and appends it into the specified `StringBuilder`.
`static QueryParamsBuilder`	`builder()` Returns a new empty builder.
`boolean`	`contains(String name)` Returns `true` if a parameter with the `name` exists, `false` otherwise.
`boolean`	`contains(String name, String value)` Returns `true` if a parameter with the `name` and `value` exists.
`boolean`	`containsDouble(String name, double value)` Returns `true` if a parameter with the `name` and `value` exists.
`boolean`	`containsFloat(String name, float value)` Returns `true` if a parameter with the `name` and `value` exists.
`boolean`	`containsInt(String name, int value)` Returns `true` if a parameter with the `name` and `value` exists.
`boolean`	`containsLong(String name, long value)` Returns `true` if a parameter with the `name` and `value` exists.
`boolean`	`containsObject(String name, Object value)` Returns `true` if a parameter with the `name` and `value` exists.
`boolean`	`containsTimeMillis(String name, long value)` Returns `true` if a parameter with the `name` and `value` exists.
`void`	`forEach(BiConsumer<String,String> action)` Invokes the specified `action` for all parameter entries.
`void`	`forEachValue(String name, Consumer<String> action)` Invokes the specified `action` for all values of the parameters with the specified `name`.
`static QueryParams`	`fromQueryString(String queryString)` Decodes the specified query string into a `QueryParams`, as defined in 4.10.22.6, HTML5 W3C Recommendation.
`static QueryParams`	`fromQueryString(String queryString, boolean semicolonAsSeparator)` Decodes the specified query string into a `QueryParams`, as defined in 4.10.22.6, HTML5 W3C Recommendation.
`static QueryParams`	`fromQueryString(String queryString, int maxParams)` Decodes the specified query string into a `QueryParams`, as defined in 4.10.22.6, HTML5 W3C Recommendation.
`static QueryParams`	`fromQueryString(String queryString, int maxParams, boolean semicolonAsSeparator)` Decodes the specified query string into a `QueryParams`, as defined in 4.10.22.6, HTML5 W3C Recommendation.
`String`	`get(String name)` Returns the value of a parameter with the specified `name`.
`String`	`get(String name, String defaultValue)` Returns the value of a parameter with the specified `name`.
`List<String>`	`getAll(String name)` Returns all values for the parameter with the specified name.
`Double`	`getDouble(String name)` Returns the `double` value of a parameter with the specified `name`.
`double`	`getDouble(String name, double defaultValue)` Returns the `double` value of a parameter with the specified `name`.
`Float`	`getFloat(String name)` Returns the `float` value of a parameter with the specified `name`.
`float`	`getFloat(String name, float defaultValue)` Returns the `float` value of a parameter with the specified `name`.
`Integer`	`getInt(String name)` Returns the `int` value of a parameter with the specified `name`.
`int`	`getInt(String name, int defaultValue)` Returns the `int` value of a parameter with the specified `name`.
`Long`	`getLong(String name)` Returns the `long` value of a parameter with the specified `name`.
`long`	`getLong(String name, long defaultValue)` Returns the `long` value of a parameter with the specified `name`.
`Long`	`getTimeMillis(String name)` Returns the value of a parameter with the specified `name` in milliseconds.
`long`	`getTimeMillis(String name, long defaultValue)` Returns the value of a parameter with the specified `name` in milliseconds.
`boolean`	`isEmpty()` Returns `true` if this parameters does not contain any entries.
`Iterator<Map.Entry<String,String>>`	`iterator()` Returns an `Iterator` that yields all parameter entries.
`Set<String>`	`names()` Returns a `Set` of all parameter names.
`static QueryParams`	`of()` Returns an empty `QueryParams`.
`static QueryParams`	`of(String name, Object value)` Returns a new `QueryParams` with the specified parameter.
`static QueryParams`	`of(String name1, Object value1, String name2, Object value2)` Returns a new `QueryParams` with the specified parameters.
`static QueryParams`	`of(String name1, Object value1, String name2, Object value2, String name3, Object value3)` Returns a new `QueryParams` with the specified parameters.
`static QueryParams`	`of(String name1, Object value1, String name2, Object value2, String name3, Object value3, String name4, Object value4)` Returns a new `QueryParams` with the specified parameters.
`static QueryParams`	`of(String name, String value)` Returns a new `QueryParams` with the specified parameter.
`static QueryParams`	`of(String name1, String value1, String name2, String value2)` Returns a new `QueryParams` with the specified parameters.
`static QueryParams`	`of(String name1, String value1, String name2, String value2, String name3, String value3)` Returns a new `QueryParams` with the specified parameters.
`static QueryParams`	`of(String name1, String value1, String name2, String value2, String name3, String value3, String name4, String value4)` Returns a new `QueryParams` with the specified parameters.
`int`	`size()` Returns the number of parameters.
`default Stream<Map.Entry<String,String>>`	`stream()` Returns a `Stream` that yields all parameter entries.
`QueryParamsBuilder`	`toBuilder()` Returns a new builder created from the entries of this parameters.
`default String`	`toQueryString()` Encodes all parameter entries into a query string, as defined in 4.10.22.6, HTML5 W3C Recommendation.
`Iterator<String>`	`valueIterator(String name)` Returns an `Iterator` that yields all values of the parameters with the specified `name`.
`default Stream<String>`	`valueStream(String name)` Returns a `Stream` that yields all values of the parameters with the specified `name`.
`default QueryParams`	`withMutations(Consumer<QueryParamsBuilder> mutator)` Returns a new parameters which is the result from the mutation by the specified `Consumer`.

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Method Detail
  - builder
```
static QueryParamsBuilder builder()
```
    Returns a new empty builder.
  - of
```
static QueryParams of()
```
    Returns an empty QueryParams.
  - of
```
static QueryParams of(String name,
                      String value)
```
    Returns a new QueryParams with the specified parameter.
  - of
```
static QueryParams of(String name,
                      Object value)
```
    Returns a new QueryParams with the specified parameter. The value is converted into a String as explained in Specifying a non-String parameter value.
  - of
```
static QueryParams of(String name1,
                      String value1,
                      String name2,
                      String value2)
```
    Returns a new QueryParams with the specified parameters.
  - of
```
static QueryParams of(String name1,
                      Object value1,
                      String name2,
                      Object value2)
```
    Returns a new QueryParams with the specified parameters. The values are converted into Strings as explained in Specifying a non-String parameter value.
  - of
```
static QueryParams of(String name1,
                      String value1,
                      String name2,
                      String value2,
                      String name3,
                      String value3)
```
    Returns a new QueryParams with the specified parameters.
  - of
```
static QueryParams of(String name1,
                      Object value1,
                      String name2,
                      Object value2,
                      String name3,
                      Object value3)
```
    Returns a new QueryParams with the specified parameters. The values are converted into Strings as explained in Specifying a non-String parameter value.
  - of
```
static QueryParams of(String name1,
                      String value1,
                      String name2,
                      String value2,
                      String name3,
                      String value3,
                      String name4,
                      String value4)
```
    Returns a new QueryParams with the specified parameters.
  - of
```
static QueryParams of(String name1,
                      Object value1,
                      String name2,
                      Object value2,
                      String name3,
                      Object value3,
                      String name4,
                      Object value4)
```
    Returns a new QueryParams with the specified parameters. The values are converted into Strings as explained in Specifying a non-String parameter value.
  - fromQueryString
```
static QueryParams fromQueryString(String queryString)
```
    Decodes the specified query string into a QueryParams, as defined in 4.10.22.6, HTML5 W3C Recommendation.
    
    Parameters:
    
    queryString - the query string with or without leading question mark ('?').
    
    Returns:
    
    the decoded QueryParams. An empty QueryParams is returned if queryString is null.
  - fromQueryString
```
static QueryParams fromQueryString(String queryString,
                                   int maxParams)
```
    Decodes the specified query string into a QueryParams, as defined in 4.10.22.6, HTML5 W3C Recommendation.
    
    Parameters:
    
    queryString - the query string with or without leading question mark ('?').
    
    maxParams - the max number of parameters to decode. If the queryString contains more parameters than this value, the extra parameters will not be decoded.
    
    Returns:
    
    the decoded QueryParams. An empty QueryParams is returned if queryString is null.
  - fromQueryString
```
static QueryParams fromQueryString(String queryString,
                                   boolean semicolonAsSeparator)
```
    Decodes the specified query string into a QueryParams, as defined in 4.10.22.6, HTML5 W3C Recommendation.
    
    Parameters:
    
    queryString - the query string with or without leading question mark ('?').
    
    semicolonAsSeparator - whether to treat a semicolon (';') as a separator as well as an ampersand ('&'). Note that HTML5 expects you to use only ampersand as a separator. Enable this flag only when you need to interop with a legacy system.
    
    Returns:
    
    the decoded QueryParams. An empty QueryParams is returned if queryString is null.
  - fromQueryString
```
static QueryParams fromQueryString(String queryString,
                                   int maxParams,
                                   boolean semicolonAsSeparator)
```
    Decodes the specified query string into a QueryParams, as defined in 4.10.22.6, HTML5 W3C Recommendation.
    
    Parameters:
    
    queryString - the query string with or without leading question mark ('?').
    
    maxParams - the max number of parameters to decode. If the queryString contains more parameters than this value, the extra parameters will not be decoded.
    
    semicolonAsSeparator - whether to treat a semicolon (';') as a separator as well as an ampersand ('&'). Note that HTML5 expects you to use only ampersand as a separator. Enable this flag only when you need to interop with a legacy system.
    
    Returns:
    
    the decoded QueryParams. An empty QueryParams is returned if queryString is null.
  - toBuilder
```
QueryParamsBuilder toBuilder()
```
    Returns a new builder created from the entries of this parameters.
    
    See Also:
    
    withMutations(Consumer)
  - withMutations
```
default QueryParams withMutations(Consumer<QueryParamsBuilder> mutator)
```
    Returns a new parameters which is the result from the mutation by the specified Consumer. This method is a shortcut for:
```
 builder = toBuilder();
 mutator.accept(builder);
 return builder.build();
 
```
    See Also:
    
    toBuilder()
  - get
```
String get(String name)
```
    Returns the value of a parameter with the specified name. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    Returns:
    
    the first parameter value if found, or null if there is no such parameter
  - get
```
String get(String name,
           String defaultValue)
```
    Returns the value of a parameter with the specified name. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    defaultValue - the default value
    
    Returns:
    
    the first parameter value, or defaultValue if there is no such parameter
  - getAll
```
List<String> getAll(String name)
```
    Returns all values for the parameter with the specified name. The returned List can't be modified.
    
    Parameters:
    
    name - the parameter name
    
    Returns:
    
    a List of parameter values or an empty List if there is no such parameter.
  - getInt
```
Integer getInt(String name)
```
    Returns the int value of a parameter with the specified name. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    Returns:
    
    the int value of the first value in insertion order or null if there is no such parameter or it can't be converted to int.
  - getInt
```
int getInt(String name,
           int defaultValue)
```
    Returns the int value of a parameter with the specified name. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    defaultValue - the default value
    
    Returns:
    
    the int value of the first value in insertion order or defaultValue if there is no such parameter or it can't be converted to int.
  - getLong
```
Long getLong(String name)
```
    Returns the long value of a parameter with the specified name. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    Returns:
    
    the long value of the first value in insertion order or null if there is no such parameter or it can't be converted to long.
  - getLong
```
long getLong(String name,
             long defaultValue)
```
    Returns the long value of a parameter with the specified name. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    defaultValue - the default value
    
    Returns:
    
    the long value of the first value in insertion order or defaultValue if there is no such parameter or it can't be converted to long.
  - getFloat
```
Float getFloat(String name)
```
    Returns the float value of a parameter with the specified name. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    Returns:
    
    the float value of the first value in insertion order or null if there is no such parameter or it can't be converted to float.
  - getFloat
```
float getFloat(String name,
               float defaultValue)
```
    Returns the float value of a parameter with the specified name. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    defaultValue - the default value
    
    Returns:
    
    the float value of the first value in insertion order or defaultValue if there is no such parameter or it can't be converted to float.
  - getDouble
```
Double getDouble(String name)
```
    Returns the double value of a parameter with the specified name. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    Returns:
    
    the double value of the first value in insertion order or null if there is no such parameter or it can't be converted to double.
  - getDouble
```
double getDouble(String name,
                 double defaultValue)
```
    Returns the double value of a parameter with the specified name. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    defaultValue - the default value
    
    Returns:
    
    the double value of the first value in insertion order or defaultValue if there is no such parameter or it can't be converted to double.
  - getTimeMillis
```
Long getTimeMillis(String name)
```
    Returns the value of a parameter with the specified name in milliseconds. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    Returns:
    
    the milliseconds value of the first value in insertion order or null if there is no such parameter or it can't be converted to milliseconds.
  - getTimeMillis
```
long getTimeMillis(String name,
                   long defaultValue)
```
    Returns the value of a parameter with the specified name in milliseconds. If there are more than one value for the specified name, the first value in insertion order is returned.
    
    Parameters:
    
    name - the parameter name
    
    defaultValue - the default value
    
    Returns:
    
    the milliseconds value of the first value in insertion order or defaultValue if there is no such parameter or it can't be converted to milliseconds.
  - contains
```
boolean contains(String name)
```
    Returns true if a parameter with the name exists, false otherwise.
    
    Parameters:
    
    name - the parameter name
  - contains
```
boolean contains(String name,
                 String value)
```
    Returns true if a parameter with the name and value exists.
    
    Parameters:
    
    name - the parameter name
    
    value - the parameter value to find
  - containsObject
```
boolean containsObject(String name,
                       Object value)
```
    Returns true if a parameter with the name and value exists.
    
    Parameters:
    
    name - the parameter name
    
    value - the parameter value
    
    Returns:
    
    true if the parameter exists. false otherwise
  - containsInt
```
boolean containsInt(String name,
                    int value)
```
    Returns true if a parameter with the name and value exists.
    
    Parameters:
    
    name - the parameter name
    
    value - the parameter value
    
    Returns:
    
    true if the parameter exists. false otherwise
  - containsLong
```
boolean containsLong(String name,
                     long value)
```
    Returns true if a parameter with the name and value exists.
    
    Parameters:
    
    name - the parameter name
    
    value - the parameter value
    
    Returns:
    
    true if the parameter exists. false otherwise
  - containsFloat
```
boolean containsFloat(String name,
                      float value)
```
    Returns true if a parameter with the name and value exists.
    
    Parameters:
    
    name - the parameter name
    
    value - the parameter value
    
    Returns:
    
    true if the parameter exists. false otherwise
  - containsDouble
```
boolean containsDouble(String name,
                       double value)
```
    Returns true if a parameter with the name and value exists.
    
    Parameters:
    
    name - the parameter name
    
    value - the parameter value
    
    Returns:
    
    true if the parameter exists. false otherwise
  - containsTimeMillis
```
boolean containsTimeMillis(String name,
                           long value)
```
    Returns true if a parameter with the name and value exists.
    
    Parameters:
    
    name - the parameter name
    
    value - the parameter value
    
    Returns:
    
    true if the parameter exists. false otherwise
  - size
```
int size()
```
    Returns the number of parameters.
  - isEmpty
```
boolean isEmpty()
```
    Returns true if this parameters does not contain any entries.
  - names
```
Set<String> names()
```
    Returns a Set of all parameter names. The returned Set cannot be modified.
  - iterator
```
Iterator<Map.Entry<String,String>> iterator()
```
    Returns an Iterator that yields all parameter entries.
  - valueIterator
```
Iterator<String> valueIterator(String name)
```
    Returns an Iterator that yields all values of the parameters with the specified name.
  - forEach
```
void forEach(BiConsumer<String,String> action)
```
    Invokes the specified action for all parameter entries.
  - forEachValue
```
void forEachValue(String name,
                  Consumer<String> action)
```
    Invokes the specified action for all values of the parameters with the specified name.
  - stream
```
default Stream<Map.Entry<String,String>> stream()
```
    Returns a Stream that yields all parameter entries.
  - valueStream
```
default Stream<String> valueStream(String name)
```
    Returns a Stream that yields all values of the parameters with the specified name.
  - toQueryString
```
default String toQueryString()
```
    Encodes all parameter entries into a query string, as defined in 4.10.22.6, HTML5 W3C Recommendation.
    
    Returns:
    
    the encoded query string.
  - appendQueryString
```
default StringBuilder appendQueryString(StringBuilder buf)
```
    Encodes all parameter entries into a query string, as defined in 4.10.22.6, HTML5 W3C Recommendation, and appends it into the specified StringBuilder.
    
    Returns:
    
    the specified StringBuilder for method chaining.

Interface QueryParams

Building a new QueryParams

Building a new QueryParams from an existing one

Specifying a non-String parameter value

Using QueryParams.of() factory methods

Using QueryParamsBuilder

Specifying value type explicitly

Method Summary

Methods inherited from interface java.lang.Iterable

Method Detail

builder

of

of

of

of

of

of

of

of

of

fromQueryString

fromQueryString

fromQueryString

fromQueryString

toBuilder

withMutations

get

get

getAll

getInt

getInt

getLong

getLong

getFloat

getFloat

getDouble

getDouble

getTimeMillis

getTimeMillis

contains

contains

containsObject

containsInt

containsLong

containsFloat

containsDouble

containsTimeMillis

size

isEmpty

names

iterator

valueIterator

forEach

forEachValue

stream

valueStream

toQueryString

appendQueryString

Building a new `QueryParams`

Building a new `QueryParams` from an existing one

Specifying a non-`String` parameter value

Using `QueryParams.of()` factory methods

Using `QueryParamsBuilder`