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

      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:

    • get

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

    • getLast

      @Nullable @Nullable String getLast(String name)
      Returns the value of a parameter with the specified name. If there are more than one value for the specified name, the last value in insertion order is returned.
      Parameters:
      name - the parameter name
      Returns:
      the last parameter value if found, or null if there is no such parameter

    • getLast

      String getLast(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 last value in insertion order is returned.
      Parameters:
      name - the parameter name
      defaultValue - the default value
      Returns:
      the last 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.

    • getBoolean

      @Nullable @Nullable Boolean getBoolean(String name)
      Returns the boolean 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:
      true if the first value in insertion order is one of "true", "TRUE", "1". false if the first value in insertion order is one of "false", "FALSE", "0". null if there is no such parameter or it can't be converted to boolean.

    • getBoolean

      boolean getBoolean(String name, boolean defaultValue)
      Returns the boolean 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:
      true if the first value in insertion order is one of "true", "TRUE", "1". false if the first value in insertion order is one of "false", "FALSE", "0". defaultValue if there is no such parameter or it can't be converted to boolean.

    • getLastBoolean

      @Nullable @Nullable Boolean getLastBoolean(String name)
      Returns the boolean value of a parameter with the specified name. If there are more than one value for the specified name, the last value in insertion order is returned.
      Parameters:
      name - the parameter name
      Returns:
      true if the last value in insertion order is one of "true", "TRUE", "1". false if the last value in insertion order is one of "false", "FALSE", "0". null if there is no such parameter or it can't be converted to boolean.

    • getLastBoolean

      boolean getLastBoolean(String name, boolean defaultValue)
      Returns the boolean value of a parameter with the specified name. If there are more than one value for the specified name, the last value in insertion order is returned.
      Parameters:
      name - the parameter name
      defaultValue - the default value
      Returns:
      true if the last value in insertion order is one of "true", "TRUE", "1". false if the last value in insertion order is one of "false", "FALSE", "0". defaultValue if there is no such parameter or it can't be converted to boolean.

    • getInt

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

    • getLastInt

      @Nullable @Nullable Integer getLastInt(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 last value in insertion order is returned.
      Parameters:
      name - the parameter name
      Returns:
      the int value of the last value in insertion order or null if there is no such parameter or it can't be converted to int.

    • getLastInt

      int getLastInt(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 last value in insertion order is returned.
      Parameters:
      name - the parameter name
      defaultValue - the default value
      Returns:
      the int value of the last value in insertion order or defaultValue if there is no such parameter or it can't be converted to int.

    • getLong

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

    • getLastLong

      @Nullable @Nullable Long getLastLong(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 last value in insertion order is returned.
      Parameters:
      name - the parameter name
      Returns:
      the long value of the last value in insertion order or null if there is no such parameter or it can't be converted to long.

    • getLastLong

      long getLastLong(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 last value in insertion order is returned.
      Parameters:
      name - the parameter name
      defaultValue - the default value
      Returns:
      the long value of the last value in insertion order or defaultValue if there is no such parameter or it can't be converted to long.

    • getFloat

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

    • getLastFloat

      @Nullable @Nullable Float getLastFloat(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 last value in insertion order is returned.
      Parameters:
      name - the parameter name
      Returns:
      the float value of the last value in insertion order or null if there is no such parameter or it can't be converted to float.

    • getLastFloat

      float getLastFloat(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 last value in insertion order is returned.
      Parameters:
      name - the parameter name
      defaultValue - the default value
      Returns:
      the float value of the last value in insertion order or defaultValue if there is no such parameter or it can't be converted to float.

    • getDouble

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

    • getLastDouble

      @Nullable @Nullable Double getLastDouble(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 last value in insertion order is returned.
      Parameters:
      name - the parameter name
      Returns:
      the double value of the last value in insertion order or null if there is no such parameter or it can't be converted to double.

    • getLastDouble

      double getLastDouble(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 last value in insertion order is returned.
      Parameters:
      name - the parameter name
      defaultValue - the default value
      Returns:
      the double value of the last value in insertion order or defaultValue if there is no such parameter or it can't be converted to double.

    • getTimeMillis

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

    • getLastTimeMillis

      @Nullable @Nullable Long getLastTimeMillis(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 last value in insertion order is returned.
      Parameters:
      name - the parameter name
      Returns:
      the milliseconds value of the last value in insertion order or null if there is no such parameter or it can't be converted to milliseconds.

    • getLastTimeMillis

      long getLastTimeMillis(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 last value in insertion order is returned.
      Parameters:
      name - the parameter name
      defaultValue - the default value
      Returns:
      the milliseconds value of the last 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

    • containsBoolean

      boolean containsBoolean(String name, boolean 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 with the name exist and value is true and parameter contains value that one of "true", "TRUE", "1" or value is false and parameter contains value that one of "false", "FALSE", "0". 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.