Package io.servicetalk.context.api

Interface ContextMap

All Known Implementing Classes:
DefaultContextMap
public interface ContextMap
The key-value entry map for different types of the value, defined by the ContextMap.Key.

  • Method Details

    • size

      int size()
      Determine the number of ContextMap.Key-value pairs in this ContextMap.
      Returns:
      the number of ContextMap.Key-value pairs in this ContextMap.

    • isEmpty

      default boolean isEmpty()
      Determine if there are no entries in this ContextMap.
      Returns:
      true if there are no entries in this ContextMap.

    • containsKey

      boolean containsKey(ContextMap.Key<?> key)
      Determine if this ContextMap contains an entry corresponding to the key.
      Parameters:
      key - The ContextMap.Key to lookup.
      Returns:
      true if this ContextMap contains an entry corresponding to the key, false otherwise.
      Throws:
      NullPointerException - (optional behavior) if key is null and the implementation doesn't support null keys.

    • containsValue

      boolean containsValue(@Nullable Object value)
      Determine if this ContextMap contains an entry with the specified value.
      Parameters:
      value - The value to lookup.
      Returns:
      true if this ContextMap contains one or more entries with the specified value, false otherwise.
      Throws:
      NullPointerException - (optional behavior) if value is null and the implementation doesn't support null values.

    • contains

      default <T> boolean contains(ContextMap.Key<T> key, @Nullable T value)
      Determine if this ContextMap contains an entry matching the passed key and value.
      Type Parameters:
      T - The anticipated type of object associated with the key.
      Parameters:
      key - The ContextMap.Key to lookup.
      value - The value to match.
      Returns:
      true if this ContextMap contains an entry matching the passed key and value, false otherwise.
      Throws:
      NullPointerException - (optional behavior) if key or value is null and the implementation doesn't support null keys or values.

    • get

      @Nullable <T> T get(ContextMap.Key<T> key)
      Get the value associated with the key, or null if no value is associated.
      Type Parameters:
      T - The anticipated type of object associated with the key.
      Parameters:
      key - The ContextMap.Key to lookup.
      Returns:
      The value associated with the key, or null if no value is associated. null can also indicate the value associated with the key is null (if null values are supported by the implementation).
      Throws:
      NullPointerException - (optional behavior) if key is null and the implementation doesn't support null keys.

    • getOrDefault

      @Nullable default <T> T getOrDefault(ContextMap.Key<T> key, T defaultValue)
      Get the value associated with the key, or defaultValue if no value is associated.
      Type Parameters:
      T - The anticipated type of object associated with the key.
      Parameters:
      key - The ContextMap.Key to lookup.
      defaultValue - The value to return if no value is associated with the key.
      Returns:
      The value associated with the key (can return null if null values are supported by the implementation), or defaultValue if no value is associated.
      Throws:
      NullPointerException - (optional behavior) if key is null and the implementation doesn't support null keys.

    • put

      @Nullable <T> T put(ContextMap.Key<T> key, @Nullable T value)
      Put a new entry into this ContextMap.
      Type Parameters:
      T - The type of object associated with the key.
      Parameters:
      key - The ContextMap.Key used to index the value.
      value - The value to put.
      Returns:
      The previous value associated with the key, or null if there was none. null can also indicate the value associated with the key was null (if null values are supported by the implementation).
      Throws:
      NullPointerException - (optional behavior) if key or value is null and the implementation doesn't support null keys or values.
      UnsupportedOperationException - if this method is not supported.

    • putIfAbsent

      @Nullable default <T> T putIfAbsent(ContextMap.Key<T> key, @Nullable T value)
      Put a new entry into this ContextMap if this map does not already contain this key or is mapped to null.
      Type Parameters:
      T - The type of object associated with the key.
      Parameters:
      key - The ContextMap.Key used to index the value.
      value - The value to put.
      Returns:
      The previous value associated with the key, or null if there was none. null can also indicate the value associated with the key was null (if null values are supported by the implementation).
      Throws:
      NullPointerException - (optional behavior) if key or value is null and the implementation doesn't support null keys or values.
      UnsupportedOperationException - if this method is not supported.

    • computeIfAbsent

      @Nullable default <T> T computeIfAbsent(ContextMap.Key<T> key, Function<ContextMap.Key<T>,T> computeFunction)
      Computes a new entry for this ContextMap if this map does not already contain this key or is mapped to null.
      Type Parameters:
      T - The type of object associated with the key.
      Parameters:
      key - The ContextMap.Key used to index a new value.
      computeFunction - The function to compute a new value. Implementation may invoke this function multiple times if concurrent threads attempt modifying this context map, result is expected to be idempotent.
      Returns:
      The current (existing or computed) value associated with the key, or null if the computed value is null.
      Throws:
      NullPointerException - (optional behavior) if key or computed value is null and the implementation doesn't support null keys or values.
      UnsupportedOperationException - if this method is not supported.

    • putAll

      default void putAll(ContextMap map)
      Put all the entries into this ContextMap.
      Parameters:
      map - The entries to insert into this ContextMap.
      Throws:
      IllegalArgumentException - if any value type does not match with its corresponding ContextMap.Key.type().
      NullPointerException - (optional behavior) if any of the map entries has a null key or value and the implementation doesn't support null keys or values.
      ConcurrentModificationException - done on a best effort basis if the passed map is detected to be modified while attempting to put all entries.
      UnsupportedOperationException - if this method is not supported.

    • putAll

      default void putAll(Map<ContextMap.Key<?>,Object> map)
      Put all the entries into this ContextMap.
      Parameters:
      map - The entries to insert into this ContextMap.
      Throws:
      IllegalArgumentException - if any value type does not match with its corresponding ContextMap.Key.type().
      NullPointerException - (optional behavior) if any of the map entries has a null key or value and the implementation doesn't support null keys or values.
      ConcurrentModificationException - done on a best effort basis if the passed map is detected to be modified while attempting to put all entries.
      UnsupportedOperationException - if this method is not supported.

    • remove

      @Nullable <T> T remove(ContextMap.Key<T> key)
      Remove an entry from this ContextMap, and get the previous value (if one exists).
      Type Parameters:
      T - The type of object associated with the key.
      Parameters:
      key - The ContextMap.Key which identifies an entry for removal.
      Returns:
      The previous value associated with the key, or null if there was none. null can also indicate the value associated with the key was null (if null values are supported by the implementation). If the ContextMap implementation is immutable this may be a new object.
      Throws:
      NullPointerException - (optional behavior) if key is null and the implementation doesn't support null keys.
      UnsupportedOperationException - if this method is not supported.

    • removeAll

      default boolean removeAll(Iterable<ContextMap.Key<?>> keys)
      Remove all entries from this ContextMap associated with the keys from the passed Iterable.
      Parameters:
      keys - The ContextMap.Keys that identify entries for removal.
      Returns:
      true if this map has changed as a result of this operation.
      Throws:
      NullPointerException - (optional behavior) if any of the keys is null and the implementation doesn't support null keys.
      ConcurrentModificationException - Done on a best effort basis if entries is detected to be modified while attempting to remove all entries.
      UnsupportedOperationException - if this method is not supported.

    • clear

      void clear()
      Clear the contents of this ContextMap.
      Throws:
      UnsupportedOperationException - if this method is not supported.

    • forEach

      @Nullable ContextMap.Key<?> forEach(BiPredicate<ContextMap.Key<?>,Object> consumer)
      Iterate over the entries contained in this ContextMap.
      Parameters:
      consumer - Each entry will be passed as key and value arguments to this BiPredicate. A consumer predicate should return true if it wants to keep iterating or false to stop iteration at the current entry.
      Returns:
      null if consumer iterated through all entries or the ContextMap.Key at which the iteration stopped.
      Throws:
      NullPointerException - if consumer is null.

    • copy

      ContextMap copy()
      Create an isolated copy of the current map. The return value contents are the same as this ContextMap but modifications to this ContextMap are not visible in the return value, and visa-versa.
      Returns:
      an isolated copy of the current map. The contents are the same as this ContextMap but modifications to this ContextMap are not visible in the return value, and visa-versa.

    • equals

      boolean equals(Object o)
      Determines if the specified object is equal to this ContextMap.
      Overrides:
      equals in class Object
      Parameters:
      o - object to be compared for equality with this ContextMap.
      Returns:
      true if the passed object is a ContextMap and has the same key-value mapping entries.
      See Also:

    • hashCode

      int hashCode()
      Returns the hash code value for this ContextMap.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code value for this ContextMap, taking into account the hash codes of each key-value mapping entries this ContextMap contains.
      See Also: