Module io.helidon.common.http
Package io.helidon.common.http

Interface Parameters

All Superinterfaces:
Iterable<Map.Entry<String,List<String>>>
All Known Subinterfaces:
BodyPartHeaders, FormParams, Headers, RequestHeaders, ResponseHeaders, WebClientRequestHeaders, WebClientResponseHeaders
All Known Implementing Classes:
HashHeaders, HashParameters, ReadableBodyPartHeaders, ReadOnlyHeaders, ReadOnlyParameters, WriteableBodyPartHeaders
public interface Parameters extends Iterable<Map.Entry<String,List<String>>>
Parameters represents key : value pairs where key is a String with potentially multiple values.

This structure represents query parameters, headers and path parameters in e.g. HttpRequest.

Interface focus on most convenient use cases in HTTP Request and Response processing, like 

 
 // Get and map with default
 .first("count").map(Integer::new).orElse(0);
 // Find max in multiple values
 .all("counts").stream().mapToInt(Integer::valueOf).max().orElse(0);

Mutable operations are defined in two forms:

  • put... create or replace association.
  • add... create association or add values to existing association.

It is possible to use toMap() method to get immutable map view of data.

Various static factory methods can be used to create common implementations.

  • Method Details

    • toUnmodifiableParameters

      static Parameters toUnmodifiableParameters(Parameters parameters)
      Returns an unmodifiable view.
      Parameters:
      parameters - a parameters for unmodifiable view.
      Returns:
      An unmodifiable view.
      Throws:
      NullPointerException - if parameter parameters is null.

    • first

      Optional<String> first(String name)
      Returns an Optional containing the first value of the given parameter (and possibly multi-valued) parameter. If the parameter is not present, then the returned Optional is empty.
      Parameters:
      name - the parameter name
      Returns:
      an Optional<V> for the first named value
      Throws:
      NullPointerException - if name is null

    • all

      List<String> all(String name)
      Returns an unmodifiable List of all of the values of the given named parameter. Always returns a List, which may be empty if the parameter is not present.
      Parameters:
      name - the parameter name
      Returns:
      a List of values with zero or greater size
      Throws:
      NullPointerException - if name is null

    • put

      List<String> put(String key, String... values)
      Associates specified values with the specified key (optional operation). If parameters previously contained a mapping for the key, the old values fully replaced.
      Parameters:
      key - key with which the specified value is to be associated
      values - value to be associated with the specified key
      Returns:
      the previous values associated with key, or empty List if there was no mapping for key.
      Throws:
      NullPointerException - if the specified key is null.
      UnsupportedOperationException - if put operation is not supported (unmodifiable Parameters).

    • put

      List<String> put(String key, Iterable<String> values)
      Associates specified values with the specified key (optional operation). If parameters previously contained a mapping for the key, the old values fully replaced.
      Parameters:
      key - key with which the specified value is to be associated
      values - value to be associated with the specified key. If null then association will be removed.
      Returns:
      the previous values associated with key, or empty List if there was no mapping for key.
      Throws:
      NullPointerException - if the specified key is null.
      UnsupportedOperationException - if put operation is not supported (unmodifiable Parameters).

    • putIfAbsent

      List<String> putIfAbsent(String key, String... values)
      If the specified key is not already associated with a value associates it with the given value and returns empty List, else returns the current value (optional operation).
      Parameters:
      key - key with which the specified value is to be associated
      values - value to be associated with the specified key
      Returns:
      the previous values associated with key, or empty List if there was no mapping for key.
      Throws:
      NullPointerException - if the specified key is null.
      UnsupportedOperationException - if put operation is not supported (unmodifiable Parameters).

    • putIfAbsent

      List<String> putIfAbsent(String key, Iterable<String> values)
      If the specified key is not already associated with a value associates it with the given value and returns empty List, else returns the current value (optional operation).
      Parameters:
      key - key with which the specified value is to be associated
      values - value to be associated with the specified key
      Returns:
      the previous values associated with key, or empty List if there was no mapping for key.
      Throws:
      NullPointerException - if the specified key is null.
      UnsupportedOperationException - if put operation is not supported (unmodifiable Parameters).

    • computeIfAbsent

      List<String> computeIfAbsent(String key, Function<String,Iterable<String>> values)
      If the specified key is not already associated with a value computes new association using the given function and returns empty List, else returns the current value (optional operation).
      Parameters:
      key - key with which the specified value is to be associated
      values - value to be associated with the specified key
      Returns:
      the current (potentially computed) values associated with key, or empty List if function returns null
      Throws:
      NullPointerException - if the specified key is null
      UnsupportedOperationException - if put operation is not supported (unmodifiable Parameters)
      IllegalStateException - if the computation detectably attempts a recursive update to this map that would otherwise never complete
      RuntimeException - or Error if the mappingFunction does so, in which case the mapping is left unestablished

    • computeSingleIfAbsent

      List<String> computeSingleIfAbsent(String key, Function<String,String> value)
      If the specified key is not already associated with a value computes new association using the given function and returns empty List, else returns the current value (optional operation).
      Parameters:
      key - a key with which the specified value is to be associated
      value - a single value to be associated with the specified key
      Returns:
      the current (potentially computed) values associated with key, or empty List if function returns null
      Throws:
      NullPointerException - if the specified key is null.
      UnsupportedOperationException - if put operation is not supported (unmodifiable Parameters).
      IllegalStateException - if the computation detectably attempts a recursive update to this map that would otherwise never complete
      RuntimeException - or Error if the mappingFunction does so, in which case the mapping is left unestablished

    • putAll

      Parameters putAll(Parameters parameters)
      Copies all of the mappings from the specified parameters to this instance replacing values of existing associations (optional operation).
      Parameters:
      parameters - to copy.
      Returns:
      this instance of Parameters
      Throws:
      NullPointerException - if the specified parameters are null.
      UnsupportedOperationException - if put operation is not supported (unmodifiable Parameters).

    • add

      Parameters add(String key, String... values)
      Adds specified values to association with the specified key (optional operation). If parameters doesn't contains mapping, new mapping is created.
      Parameters:
      key - key with which the specified value is to be associated
      values - value to be add to association with the specified key
      Returns:
      this instance of Parameters
      Throws:
      NullPointerException - if the specified key is null.
      UnsupportedOperationException - if put operation is not supported (unmodifiable Parameters).

    • add

      Parameters add(String key, Iterable<String> values)
      Adds specified values to association with the specified key (optional operation). If parameters doesn't contains mapping, new mapping is created.
      Parameters:
      key - key with which the specified value is to be associated
      values - value to be add to association with the specified key. If null then noting will be add.
      Returns:
      this instance of Parameters
      Throws:
      NullPointerException - if the specified key is null.
      UnsupportedOperationException - if put operation is not supported (unmodifiable Parameters).

    • addAll

      Parameters addAll(Parameters parameters)
      Copies all of the mappings from the specified parameters to this instance adding values to existing associations (optional operation).
      Parameters:
      parameters - to copy.
      Returns:
      this instance of Parameters
      Throws:
      NullPointerException - if the specified parameters are null.
      UnsupportedOperationException - if put operation is not supported (unmodifiable Parameters).

    • remove

      List<String> remove(String key)
      Removes the mapping for a key if it is present (optional operation).
      Parameters:
      key - key whose mapping is to be removed.
      Returns:
      the previous value associated with key, or empty List.

    • toMap

      Map<String,List<String>> toMap()
      Returns a copy of parameters as a Map. This interface should only be used when it is required to iterate over the entire set of parameters.
      Returns:
      the Map

    • iterator

      default Iterator<Map.Entry<String,List<String>>> iterator()

      Implementations should override this default with a more efficient implementation.

      Specified by:
      iterator in interface Iterable<Map.Entry<String,List<String>>>
      Returns:
      Iterator over the entries in the data