Package org.elasticsearch.common.util.concurrent

Class ThreadContext

java.lang.Object
org.elasticsearch.common.util.concurrent.ThreadContext
All Implemented Interfaces:
Writeable
public final class ThreadContext extends Object implements Writeable
A ThreadContext is a map of string headers and a transient map of keyed objects that are associated with a thread. It allows to store and retrieve header information across method calls, network calls as well as threads spawned from a thread that has a ThreadContext associated with. Threads spawned from a ThreadPool have out of the box support for ThreadContext and all threads spawned will inherit the ThreadContext from the thread that it is forking from.". Network calls will also preserve the senders headers automatically.

Consumers of ThreadContext usually don't need to interact with adding or stashing contexts. Every elasticsearch thread is managed by a thread pool or executor being responsible for stashing and restoring the threads context. For instance if a network request is received, all headers are deserialized from the network and directly added as the headers of the threads ThreadContext (see readHeaders(StreamInput). In order to not modify the context that is currently active on this thread the network code uses a try/with pattern to stash it's current context, read headers into a fresh one and once the request is handled or a handler thread is forked (which in turn inherits the context) it restores the previous context. For instance: 

     // current context is stashed and replaced with a default context
     try (StoredContext context = threadContext.stashContext()) {
         threadContext.readHeaders(in); // read headers into current context
         if (fork) {
             threadPool.execute(() -> request.handle()); // inherits context
         } else {
             request.handle();
         }
     }
     // previous context is restored on StoredContext#close()

  • Field Details

  • Constructor Details

    • ThreadContext

      public ThreadContext(Settings settings)
      Creates a new ThreadContext instance
      Parameters:
      settings - the settings to read the default request headers from

  • Method Details

    • stashContext

      public ThreadContext.StoredContext stashContext()
      Removes the current context and resets a default context. The removed context can be restored by closing the returned ThreadContext.StoredContext.

    • captureAsWriteable

      public Writeable captureAsWriteable()
      Captures the current thread context as writeable, allowing it to be serialized out later

    • stashWithOrigin

      public ThreadContext.StoredContext stashWithOrigin(String origin)
      Removes the current context and resets a default context marked with as originating from the supplied string. The removed context can be restored by closing the returned ThreadContext.StoredContext. Callers should be careful to save the current context before calling this method and restore it any listeners, likely with ContextPreservingActionListener. Use OriginSettingClient which can be used to do this automatically.

      Without security the origin is ignored, but security uses it to authorize actions that are made up of many sub-actions. These actions call stashWithOrigin(java.lang.String) before performing on behalf of a user that should be allowed even if the user doesn't have permission to perform those actions on their own.

      For example, a user might not have permission to GET from the tasks index but the tasks API will perform a get on their behalf using this method if it can't find the task in memory.

    • stashAndMergeHeaders

      public ThreadContext.StoredContext stashAndMergeHeaders(Map<String,String> headers)
      Removes the current context and resets a new context that contains a merge of the current headers and the given headers. The removed context can be restored when closing the returned ThreadContext.StoredContext. The merge strategy is that headers that are already existing are preserved unless they are defaults.

    • newStoredContext

      public ThreadContext.StoredContext newStoredContext(boolean preserveResponseHeaders)
      Just like stashContext() but no default context is set.
      Parameters:
      preserveResponseHeaders - if set to true the response headers of the restore thread will be preserved.

    • newStoredContext

      public ThreadContext.StoredContext newStoredContext(boolean preserveResponseHeaders, Collection<String> transientHeadersToClear)
      Just like stashContext() but no default context is set. Instead, the transientHeadersToClear argument can be used to clear specific transient headers in the new context. All headers (with the possible exception of responseHeaders) are restored by closing the returned ThreadContext.StoredContext.
      Parameters:
      preserveResponseHeaders - if set to true the response headers of the restore thread will be preserved.

    • newRestorableContext

      public Supplier<ThreadContext.StoredContext> newRestorableContext(boolean preserveResponseHeaders)
      Returns a supplier that gathers a newStoredContext(boolean) and restores it once the returned supplier is invoked. The context returned from the supplier is a stored version of the suppliers callers context that should be restored once the originally gathered context is not needed anymore. For instance this method should be used like this: 
           Supplier<ThreadContext.StoredContext> restorable = context.newRestorableContext(true);
     new Thread() {
         public void run() {
             try (ThreadContext.StoredContext ctx = restorable.get()) {
                 // execute with the parents context and restore the threads context afterwards
             }
         }

     }.start();
      Parameters:
      preserveResponseHeaders - if set to true the response headers of the restore thread will be preserved.
      Returns:
      a restorable context supplier

    • wrapRestorable

      public Supplier<ThreadContext.StoredContext> wrapRestorable(ThreadContext.StoredContext storedContext)
      Same as newRestorableContext(boolean) but wraps an existing context to restore.
      Parameters:
      storedContext - the context to restore

    • writeTo

      public void writeTo(StreamOutput out) throws IOException
      Description copied from interface: Writeable
      Write this into the StreamOutput.
      Specified by:
      writeTo in interface Writeable
      Throws:
      IOException

    • readHeaders

      public void readHeaders(StreamInput in) throws IOException
      Reads the headers from the stream into the current context
      Throws:
      IOException

    • setHeaders

      public void setHeaders(Tuple<Map<String,String>,Map<String,Set<String>>> headerTuple)

    • readHeadersFromStream

      public static Tuple<Map<String,String>,Map<String,Set<String>>> readHeadersFromStream(StreamInput in) throws IOException
      Throws:
      IOException

    • getHeader

      public String getHeader(String key)
      Returns the header for the given key or null if not present

    • getHeaders

      public Map<String,String> getHeaders()
      Returns all of the request headers from the thread's context.
      Be advised, headers might contain credentials. In order to avoid storing, and erroneously exposing, such headers, it is recommended to instead store security headers that prove the credentials have been verified successfully, and which are internal to the system, in the sense that they cannot be sent by the clients.

    • getRequestHeadersOnly

      public Map<String,String> getRequestHeadersOnly()
      Returns the request headers, without the default headers

    • getResponseHeaders

      public Map<String,List<String>> getResponseHeaders()
      Get a copy of all response headers.
      Returns:
      Never null.

    • copyHeaders

      public void copyHeaders(Iterable<Map.Entry<String,String>> headers)
      Copies all header key, value pairs into the current context

    • putHeader

      public void putHeader(String key, String value)
      Puts a header into the context

    • putHeader

      public void putHeader(Map<String,String> header)
      Puts all of the given headers into this context

    • putTransient

      public void putTransient(String key, Object value)
      Puts a transient header object into this context

    • getTransient

      public <T> T getTransient(String key)
      Returns a transient header object or null if there is no header for the given key

    • addResponseHeader

      public void addResponseHeader(String key, String value)
      Add the value for the specified key Any duplicate value is ignored.
      Parameters:
      key - the header name
      value - the header value

    • addResponseHeader

      public void addResponseHeader(String key, String value, Function<String,String> uniqueValue)
      Add the value for the specified key with the specified uniqueValue used for de-duplication. Any duplicate value after applying uniqueValue is ignored.
      Parameters:
      key - the header name
      value - the header value
      uniqueValue - the function that produces de-duplication values

    • preserveContext

      public Runnable preserveContext(Runnable command)
      Saves the current thread context and wraps command in a Runnable that restores that context before running command. If command has already been passed through this method then it is returned unaltered rather than wrapped twice.

    • unwrap

      public Runnable unwrap(Runnable command)
      Unwraps a command that was previously wrapped by preserveContext(Runnable).

    • markAsSystemContext

      public void markAsSystemContext()
      Marks this thread context as an internal system context. This signals that actions in this context are issued by the system itself rather than by a user action.

    • isSystemContext

      public boolean isSystemContext()
      Returns true iff this context is a system context

    • buildDefaultHeaders

      public static Map<String,String> buildDefaultHeaders(Settings settings)