Module org.elasticsearch.server
Package org.elasticsearch.common.util.concurrent

Class ThreadContext

java.lang.Object
org.elasticsearch.common.util.concurrent.ThreadContext
All Implemented Interfaces:
Writeable, TraceContext
public final class ThreadContext extends Object implements Writeable, TraceContext
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 except for headers involved in task tracing. The removed context can be restored by closing the returned ThreadContext.StoredContext.
      Returns:
      a stored context that will restore the current context to its state at the point this method was called

    • stashContextPreservingRequestHeaders

      public ThreadContext.StoredContext stashContextPreservingRequestHeaders(Set<String> requestHeaders)
      Just like stashContext() but preserves request headers specified via requestHeaders, if these exist in the context before stashing.

    • stashContextPreservingRequestHeaders

      public ThreadContext.StoredContext stashContextPreservingRequestHeaders(String... requestHeaders)

    • newEmptyContext

      public ThreadContext.StoredContext newEmptyContext()
      Removes the current context and replaces it with a completely empty default context, detaching execution entirely from the calling context. The calling context can be restored by closing the returned ThreadContext.StoredContext. Similar to stashContext() except that this method does not even preserve tracing-related headers.

    • newEmptySystemContext

      public ThreadContext.StoredContext newEmptySystemContext()
      Removes the current context and replaces it with a completely empty system context, detaching execution entirely from the calling context. The calling context can be restored by closing the returned ThreadContext.StoredContext. Similar to stashContext() except that this method does not even preserve tracing-related headers.

    • newTraceContext

      public ThreadContext.StoredContext newTraceContext()
      When using a Tracer to capture activity in Elasticsearch, when a parent span is already in progress, it is necessary to start a new context before beginning a child span. This method creates a context, moving tracing-related fields to different names so that a new child span can be started. This child span will pick up the moved fields and use them to establish the parent-child relationship.
      Returns:
      a stored context, which can be restored when this context is no longer needed.

    • hasTraceContext

      public boolean hasTraceContext()

    • clearTraceContext

      public ThreadContext.StoredContext clearTraceContext()
      When using a Tracer, sometimes you need to start a span completely unrelated to any current span. In order to avoid any parent/child relationship being created, this method creates a new context that clears all the tracing fields.
      Returns:
      a stored context, which can be restored when this context is no longer needed.

    • 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.

    • newStoredContextPreservingResponseHeaders

      public ThreadContext.StoredContext newStoredContextPreservingResponseHeaders()
      Just like stashContext() but no default context is set and the response headers of the restore thread will be preserved.

    • restoreExistingContext

      public ThreadContext.StoredContext restoreExistingContext(ThreadContext.StoredContext existingContext)
      Capture the current context and then restore the given context, returning a ThreadContext.StoredContext that reverts back to the current context again. Equivalent to using newStoredContext() and then calling existingContext.restore().

    • newStoredContext

      public ThreadContext.StoredContext newStoredContext()
      Just like stashContext() but no default context is set.

    • newStoredContext

      public ThreadContext.StoredContext newStoredContext(Collection<String> transientHeadersToClear, Collection<String> requestHeadersToClear)
      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 and requestHeadersToClear can be used to clear specific request headers. All original headers (without the responseHeaders) are restored by closing the returned ThreadContext.StoredContext.

    • newStoredContextPreservingResponseHeaders

      public ThreadContext.StoredContext newStoredContextPreservingResponseHeaders(Collection<String> transientHeadersToClear, Collection<String> requestHeadersToClear)
      Just like newStoredContext(Collection, Collection) but all headers are restored to original, except of responseHeaders which will be preserved from the restore thread.

    • newRestorableContext

      public Supplier<ThreadContext.StoredContext> newRestorableContext(boolean preserveResponseHeaders)
      Returns a supplier that gathers a newStoredContextPreservingResponseHeaders() 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
      Specified by:
      getHeader in interface TraceContext

    • getHeaderOrDefault

      public String getHeaderOrDefault(String key, String defaultValue)
      Returns the header for the given key or defaultValue 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
      Specified by:
      putHeader in interface TraceContext

    • putHeader

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

    • setErrorTraceTransportHeader

      public void setErrorTraceTransportHeader(RestRequest r)

    • putTransient

      public void putTransient(String key, Object value)
      Puts a transient header object into this context
      Specified by:
      putTransient in interface TraceContext

    • getTransient

      public <T> T getTransient(String key)
      Returns a transient header object or null if there is no header for the given key
      Specified by:
      getTransient in interface TraceContext

    • getTransientHeaders

      public Map<String,Object> getTransientHeaders()
      Returns unmodifiable copy of all transient headers.

    • 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.

    • preserveContextWithTracing

      public Runnable preserveContextWithTracing(Runnable command)
      Saves the current thread context and wraps command in a Runnable that restores that context before running command. Also starts a new tracing context durin executing. If command has already been wrapped then it is returned unaltered.

    • unwrap

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

    • isDefaultContext

      public boolean isDefaultContext()
      Returns true if the current context is the default context.

    • 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

    • sanitizeHeaders

      public void sanitizeHeaders()
      Remove unwanted and unneeded headers from the thread context. Does not store prior context.

    • buildDefaultHeaders

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