Package org.apache.logging.log4j

Class ThreadContext

java.lang.Object
org.apache.logging.log4j.ThreadContext
public final class ThreadContext extends Object
The ThreadContext allows applications to store information either in a Map or a Stack.

The MDC is managed on a per thread basis. To enable automatic inheritance of copies of the MDC to newly created threads, enable the "isThreadContextMapInheritable" Log4j system property.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    ThreadContext.ContextStack
    The ThreadContext Stack interface.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Map<String,String>
    EMPTY_MAP
    Empty, immutable Map.
    static final ThreadContextStack
    EMPTY_STACK
    Empty, immutable ContextStack.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    clearAll()
    Clears the context map and stack.
    static void
    clearMap()
    Clears the context map.
    static void
    clearStack()
    Clears the stack for this thread.
    static ThreadContext.ContextStack
    cloneStack()
    Returns a copy of this thread's stack.
    static boolean
    containsKey(String key)
    Determines if the key is in the context.
    static String
    get(String key)
    Gets the context value identified by the key parameter.
    static Map<String,String>
    getContext()
    Returns a mutable copy of current thread's context Map.
    static int
    getDepth()
    Gets the current nesting depth of this thread's stack.
    static Map<String,String>
    getImmutableContext()
    Returns an immutable view of the current thread's context Map.
    static ThreadContext.ContextStack
    getImmutableStack()
    Gets an immutable copy of this current thread's context stack.
    static ReadOnlyThreadContextMap
    getThreadContextMap()
    Returns a read-only view of the internal data structure used to store thread context key-value pairs, or null if the internal data structure does not implement the ReadOnlyThreadContextMap interface.
    static void
    init()
    Consider private, used for testing.
    static boolean
    isEmpty()
    Returns true if the Map is empty.
    static String
    peek()
    Looks at the last diagnostic context at the top of this NDC without removing it.
    static String
    pop()
    Returns the value of the last item placed on the stack.
    static void
    push(String message)
    Pushes new diagnostic context information for the current thread.
    static void
    push(String message, Object... args)
    Pushes new diagnostic context information for the current thread.
    static void
    put(String key, String value)
    Puts a context value (the value parameter) as identified with the key parameter into the current thread's context map.
    static void
    putAll(Map<String,String> m)
    Puts all given context map entries into the current thread's context map.
    static void
    putIfNull(String key, String value)
    Puts a context value (the value parameter) as identified with the key parameter into the current thread's context map if the key does not exist.
    static void
    remove(String key)
    Removes the context value identified by the key parameter.
    static void
    removeAll(Iterable<String> keys)
    Removes the context values identified by the keys parameter.
    static void
    removeStack()
    Removes the diagnostic context for this thread.
    static void
    setStack(Collection<String> stack)
    Sets this thread's stack.
    static void
    trim(int depth)
    Trims elements from this diagnostic context.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • EMPTY_MAP

      public static final Map<String,String> EMPTY_MAP
      Empty, immutable Map.

    • EMPTY_STACK

      public static final ThreadContextStack EMPTY_STACK
      Empty, immutable ContextStack.

  • Method Details

    • init

      public static void init()
      Consider private, used for testing.
      Since:
      2.20.0

    • put

      public static void put(String key, String value)
      Puts a context value (the value parameter) as identified with the key parameter into the current thread's context map.

      If the current thread does not have a context map it is created as a side effect.

      Parameters:
      key - The key name.
      value - The key value.

    • putIfNull

      public static void putIfNull(String key, String value)
      Puts a context value (the value parameter) as identified with the key parameter into the current thread's context map if the key does not exist.

      If the current thread does not have a context map it is created as a side effect.

      Parameters:
      key - The key name.
      value - The key value.
      Since:
      2.13.0

    • putAll

      public static void putAll(Map<String,String> m)
      Puts all given context map entries into the current thread's context map.

      If the current thread does not have a context map it is created as a side effect.

      Parameters:
      m - The map.
      Since:
      2.7

    • get

      public static String get(String key)
      Gets the context value identified by the key parameter.

      This method has no side effects.

      Parameters:
      key - The key to locate.
      Returns:
      The value associated with the key or null.

    • remove

      public static void remove(String key)
      Removes the context value identified by the key parameter.
      Parameters:
      key - The key to remove.

    • removeAll

      public static void removeAll(Iterable<String> keys)
      Removes the context values identified by the keys parameter.
      Parameters:
      keys - The keys to remove.
      Since:
      2.8

    • clearMap

      public static void clearMap()
      Clears the context map.

    • clearAll

      public static void clearAll()
      Clears the context map and stack.

    • containsKey

      public static boolean containsKey(String key)
      Determines if the key is in the context.
      Parameters:
      key - The key to locate.
      Returns:
      True if the key is in the context, false otherwise.

    • getContext

      public static Map<String,String> getContext()
      Returns a mutable copy of current thread's context Map.
      Returns:
      a mutable copy of the context.

    • getImmutableContext

      public static Map<String,String> getImmutableContext()
      Returns an immutable view of the current thread's context Map.
      Returns:
      An immutable view of the ThreadContext Map.

    • getThreadContextMap

      public static ReadOnlyThreadContextMap getThreadContextMap()
      Returns a read-only view of the internal data structure used to store thread context key-value pairs, or null if the internal data structure does not implement the ReadOnlyThreadContextMap interface.

      The DefaultThreadContextMap implementation does not implement ReadOnlyThreadContextMap, so by default this method returns null.

      Returns:
      the internal data structure used to store thread context key-value pairs or null
      Since:
      2.8
      See Also:

    • isEmpty

      public static boolean isEmpty()
      Returns true if the Map is empty.
      Returns:
      true if the Map is empty, false otherwise.

    • clearStack

      public static void clearStack()
      Clears the stack for this thread.

    • cloneStack

      public static ThreadContext.ContextStack cloneStack()
      Returns a copy of this thread's stack.
      Returns:
      A copy of this thread's stack.

    • getImmutableStack

      public static ThreadContext.ContextStack getImmutableStack()
      Gets an immutable copy of this current thread's context stack.
      Returns:
      an immutable copy of the ThreadContext stack.

    • setStack

      public static void setStack(Collection<String> stack)
      Sets this thread's stack.
      Parameters:
      stack - The stack to use.

    • getDepth

      public static int getDepth()
      Gets the current nesting depth of this thread's stack.
      Returns:
      the number of items in the stack.
      See Also:

    • pop

      public static String pop()
      Returns the value of the last item placed on the stack.

      The returned value is the value that was pushed last. If no context is available, then the empty string "" is returned.

      Returns:
      String The innermost diagnostic context.

    • peek

      public static String peek()
      Looks at the last diagnostic context at the top of this NDC without removing it.

      The returned value is the value that was pushed last. If no context is available, then the empty string "" is returned.

      Returns:
      String The innermost diagnostic context.

    • push

      public static void push(String message)
      Pushes new diagnostic context information for the current thread.

      The contents of the message parameter is determined solely by the client.

      Parameters:
      message - The new diagnostic context information.

    • push

      public static void push(String message, Object... args)
      Pushes new diagnostic context information for the current thread.

      The contents of the message and args parameters are determined solely by the client. The message will be treated as a format String and tokens will be replaced with the String value of the arguments in accordance with ParameterizedMessage.

      Parameters:
      message - The new diagnostic context information.
      args - Parameters for the message.

    • removeStack

      public static void removeStack()
      Removes the diagnostic context for this thread.

      Each thread that created a diagnostic context by calling push(java.lang.String) should call this method before exiting. Otherwise, the memory used by the thread cannot be reclaimed by the VM.

      As this is such an important problem in heavy duty systems and because it is difficult to always guarantee that the remove method is called before exiting a thread, this method has been augmented to lazily remove references to dead threads. In practice, this means that you can be a little sloppy and occasionally forget to call remove(java.lang.String) before exiting a thread. However, you must call remove sometime. If you never call it, then your application is sure to run out of memory.

    • trim

      public static void trim(int depth)
      Trims elements from this diagnostic context. If the current depth is smaller or equal to maxDepth, then no action is taken. If the current depth is larger than newDepth then all elements at maxDepth or higher are discarded.

      This method is a convenient alternative to multiple pop() calls. Moreover, it is often the case that at the end of complex call sequences, the depth of the ThreadContext is unpredictable. The trim method circumvents this problem.

      For example, the combination 

       void foo() {
     final int depth = ThreadContext.getDepth();

     // ... complex sequence of calls

     ThreadContext.trim(depth);
 }

      ensures that between the entry and exit of foo the depth of the diagnostic stack is conserved.

      Parameters:
      depth - The number of elements to keep.
      See Also: