Package io.servicetalk.concurrent.api

Class AsyncContext

  • public final class AsyncContext
extends java.lang.Object
    Presents a static interface to retain state in an asynchronous environment.

    This should not be used as a "catch all" to avoid designing APIs which accommodate for your needs. This should be used as a last resort (e.g. for low level framework or infrastructure like tasks) because there maybe non-trivial overhead required to maintain this context.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void clear()
      Convenience method to clear all the key/value pairs from the current context.
      static boolean containsKey​(AsyncContextMap.Key<?> key)
      Convenience method to determine if the current context contains a key/value entry corresponding to key.
      static AsyncContextMap current()
      Get the current AsyncContextMap.
      static void disable()
      Disable AsyncContext.
      static AsyncContextMap.Key<?> forEach​(java.util.function.BiPredicate<AsyncContextMap.Key<?>,​java.lang.Object> consumer)
      Convenience method to iterate over the key/value pairs contained in the current context.
      static <T> T get​(AsyncContextMap.Key<T> key)
      Convenience method to get the value associated with key from the current context.
      static boolean isDisabled()
      Determine if disable() has been previously called.
      static boolean isEmpty()
      Convenience method to determine if there are no key/value pairs in the current context.
      static <T> void put​(AsyncContextMap.Key<T> key, T value)
      Convenience method for adding a value to the current context.
      static void putAll​(java.util.Map<AsyncContextMap.Key<?>,​java.lang.Object> map)
      Convenience method for to put all the key/value pairs into the current context.
      static void remove​(AsyncContextMap.Key<?> key)
      Convenience method to remove a key/value pair from the current context.
      static void removeAll​(java.lang.Iterable<AsyncContextMap.Key<?>> entries)
      Convenience method to remove all the key/value pairs from the current context.
      static <T,​U>
      java.util.function.BiConsumer<T,​U>      		 wrapBiConsume​(java.util.function.BiConsumer<T,​U> consumer)
      Wrap a BiFunction to ensure it is able to track AsyncContext correctly.
      static <T,​U,​V>
      java.util.function.BiFunction<T,​U,​V>      		 wrapBiFunction​(java.util.function.BiFunction<T,​U,​V> func)
      Wrap a BiFunction to ensure it is able to track AsyncContext correctly.
      static <T> java.util.function.Consumer<T> wrapConsumer​(java.util.function.Consumer<T> consumer)
      Wrap a Consumer to ensure it is able to track AsyncContext correctly.
      static Executor wrapExecutor​(Executor executor)
      Wrap an Executor to ensure it is able to track AsyncContext correctly.
      static <T,​U>
      java.util.function.Function<T,​U>      		 wrapFunction​(java.util.function.Function<T,​U> func)
      Wrap a Function to ensure it is able to track AsyncContext correctly.
      static java.util.concurrent.Executor wrapJdkExecutor​(java.util.concurrent.Executor executor)
      Wrap an Executor to ensure it is able to track AsyncContext correctly.
      static java.util.concurrent.ExecutorService wrapJdkExecutorService​(java.util.concurrent.ExecutorService executor)
      Wrap an ExecutorService to ensure it is able to track AsyncContext correctly.
      static java.util.concurrent.ScheduledExecutorService wrapJdkScheduledExecutorService​(java.util.concurrent.ScheduledExecutorService executor)
      Wrap a ScheduledExecutorService to ensure it is able to track AsyncContext correctly.
      static java.lang.Runnable wrapRunnable​(java.lang.Runnable runnable)
      Wrap a Runnable to ensure it is able to track AsyncContext correctly.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • put

        public static <T> void put​(AsyncContextMap.Key<T> key,
                           @Nullable
                           T value)
        Convenience method for adding a value to the current context.
        Type Parameters:
        T - The type of object associated with key.
        Parameters:
        key - the key used to index value. Cannot be null.
        value - the value to put.
        Throws:
        java.lang.NullPointerException - if key or value is null and the underlying AsyncContextMap implementation doesn't support null keys or values.
        java.lang.UnsupportedOperationException - if this method is not supported by the underlying AsyncContextMap implementation.
        See Also:
        AsyncContextMap.put(AsyncContextMap.Key, Object)

      • putAll

        public static void putAll​(java.util.Map<AsyncContextMap.Key<?>,​java.lang.Object> map)
        Convenience method for to put all the key/value pairs into the current context.
        Parameters:
        map - contains the key/value pairs that will be added.
        Throws:
        java.util.ConcurrentModificationException - done on a best effort basis if entries is detected to be modified while attempting to put all entries.
        java.lang.NullPointerException - if key or value is null and the underlying AsyncContextMap implementation doesn't support null keys or values.
        java.lang.UnsupportedOperationException - if this method is not supported by the underlying AsyncContextMap implementation.
        See Also:
        AsyncContextMap.putAll(Map)

      • removeAll

        public static void removeAll​(java.lang.Iterable<AsyncContextMap.Key<?>> entries)
        Convenience method to remove all the key/value pairs from the current context.
        Parameters:
        entries - A Iterable which contains all the keys to remove.
        Throws:
        java.lang.UnsupportedOperationException - if this method is not supported by the underlying AsyncContextMap implementation.
        See Also:
        AsyncContextMap.removeAll(Iterable)

      • clear

        public static void clear()
        Convenience method to clear all the key/value pairs from the current context.
        Throws:
        java.lang.UnsupportedOperationException - if this method is not supported by the underlying AsyncContextMap implementation.
        See Also:
        AsyncContextMap.clear()

      • get

        @Nullable
public static <T> T get​(AsyncContextMap.Key<T> key)
        Convenience method to get the value associated with key from the current context.
        Type Parameters:
        T - The anticipated type of object associated with key.
        Parameters:
        key - the key to lookup.
        Returns:
        the value associated with key, or null if no value is associated. null can also indicate the value associated with key is null (if null values are supported by the underlying AsyncContextMap implementation).
        Throws:
        java.lang.NullPointerException - (optional behavior) if key is null and the underlying AsyncContextMap implementation doesn't support null keys or values.
        See Also:
        AsyncContextMap.get(AsyncContextMap.Key)

      • containsKey

        public static boolean containsKey​(AsyncContextMap.Key<?> key)
        Convenience method to determine if the current context contains a key/value entry corresponding to key.
        Parameters:
        key - the key to lookup.
        Returns:
        true if the current context contains a key/value entry corresponding to key. false otherwise.
        Throws:
        java.lang.NullPointerException - (optional behavior) if key is null and the underlying AsyncContextMap implementation doesn't support null keys or values.
        See Also:
        AsyncContextMap.containsKey(AsyncContextMap.Key)

      • isEmpty

        public static boolean isEmpty()
        Convenience method to determine if there are no key/value pairs in the current context.
        Returns:
        true if there are no key/value pairs in the current context.
        See Also:
        AsyncContextMap.isEmpty()

      • forEach

        @Nullable
public static AsyncContextMap.Key<?> forEach​(java.util.function.BiPredicate<AsyncContextMap.Key<?>,​java.lang.Object> consumer)
        Convenience method to iterate over the key/value pairs contained in the current context.
        Parameters:
        consumer - Each key/value pair will be passed as arguments to this BiPredicate. Returns true if the consumer wants to keep iterating or false to stop iteration at the current key/value pair.
        Returns:
        null if consumer iterated through all key/value pairs or the AsyncContextMap.Key at which the iteration stopped.
        Throws:
        java.lang.NullPointerException - if consumer is null.
        See Also:
        AsyncContextMap.forEach(BiPredicate)

      • wrapJdkExecutor

        public static java.util.concurrent.Executor wrapJdkExecutor​(java.util.concurrent.Executor executor)
        Wrap an Executor to ensure it is able to track AsyncContext correctly.
        Parameters:
        executor - The executor to wrap.
        Returns:
        The wrapped executor.

      • wrapExecutor

        public static Executor wrapExecutor​(Executor executor)
        Wrap an Executor to ensure it is able to track AsyncContext correctly.
        Parameters:
        executor - The executor to wrap.
        Returns:
        The wrapped executor.

      • wrapJdkExecutorService

        public static java.util.concurrent.ExecutorService wrapJdkExecutorService​(java.util.concurrent.ExecutorService executor)
        Wrap an ExecutorService to ensure it is able to track AsyncContext correctly.
        Parameters:
        executor - The executor to wrap.
        Returns:
        The wrapped executor.

      • wrapJdkScheduledExecutorService

        public static java.util.concurrent.ScheduledExecutorService wrapJdkScheduledExecutorService​(java.util.concurrent.ScheduledExecutorService executor)
        Wrap a ScheduledExecutorService to ensure it is able to track AsyncContext correctly.
        Parameters:
        executor - The executor to wrap.
        Returns:
        The wrapped executor.

      • wrapRunnable

        public static java.lang.Runnable wrapRunnable​(java.lang.Runnable runnable)
        Wrap a Runnable to ensure it is able to track AsyncContext correctly.
        Parameters:
        runnable - The runnable to wrap.
        Returns:
        The wrapped Runnable.

      • wrapConsumer

        public static <T> java.util.function.Consumer<T> wrapConsumer​(java.util.function.Consumer<T> consumer)
        Wrap a Consumer to ensure it is able to track AsyncContext correctly.
        Type Parameters:
        T - The type of data consumed by consumer.
        Parameters:
        consumer - The consumer to wrap.
        Returns:
        The wrapped Consumer.

      • wrapFunction

        public static <T,​U> java.util.function.Function<T,​U> wrapFunction​(java.util.function.Function<T,​U> func)
        Wrap a Function to ensure it is able to track AsyncContext correctly.
        Type Parameters:
        T - The type of data consumed by func.
        U - The type of data returned by func.
        Parameters:
        func - The function to wrap.
        Returns:
        The wrapped Function.

      • wrapBiConsume

        public static <T,​U> java.util.function.BiConsumer<T,​U> wrapBiConsume​(java.util.function.BiConsumer<T,​U> consumer)
        Wrap a BiFunction to ensure it is able to track AsyncContext correctly.
        Type Parameters:
        T - The type of data consumed by func.
        U - The type of data consumed by func.
        Parameters:
        consumer - The consumer to wrap.
        Returns:
        The wrapped BiConsumer.

      • wrapBiFunction

        public static <T,​U,​V> java.util.function.BiFunction<T,​U,​V> wrapBiFunction​(java.util.function.BiFunction<T,​U,​V> func)
        Wrap a BiFunction to ensure it is able to track AsyncContext correctly.
        Type Parameters:
        T - The type of data consumed by func.
        U - The type of data consumed by func.
        V - The type of data returned by func.
        Parameters:
        func - The function to wrap.
        Returns:
        The wrapped BiFunction.

      • disable

        public static void disable()
        Disable AsyncContext. It is assumed the application will call this in a well orchestrated fashion. For example the behavior of in flight AsyncContext is undefined, objects that are already initialized with AsyncContext enabled may continue to preserve AsyncContext in an unreliable fashion. and also how this behaves relative to concurrent invocation is undefined. External synchronization should be used to ensure this change is visible to other threads.

      • isDisabled

        public static boolean isDisabled()
        Determine if disable() has been previously called.
        Returns:
        true if disable() has been previously called.