Package com.linecorp.armeria.common

Interface QueryParams

All Superinterfaces:
Iterable<Map.Entry<String,​String>>
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:

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 Details

    • 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​(@Nullable 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 without leading question mark ('?').
      Returns:
      the decoded QueryParams. An empty QueryParams is returned if queryString is null.

    • fromQueryString

      static QueryParams fromQueryString​(@Nullable 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 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​(@Nullable 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 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​(@Nullable 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 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 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

      @Nullable 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

      @Nullable 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

      @Nullable 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

      @Nullable 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

      @Nullable 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

      @Nullable 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.
      Specified by:
      iterator in interface Iterable<Map.Entry<String,​String>>

    • 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.