ThreadContext (Apache Log4j API 2.3.2 API)

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. A child thread automatically inherits a copy of the mapped diagnostic context of its parent.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static interface ThreadContext.ContextStack
The ThreadContext Stack interface.

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

Field Summary

Fields
Modifier and Type Field and Description

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

static ThreadContextStack EMPTY_STACK
Empty, immutable ContextStack.

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

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and 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 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`	`remove(String key)` Removes the context value identified by the `key` 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 Detail
  - 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 Detail
  - 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.
  - 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.
  - 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.
  - 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:
    
    trim(int)
  - 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:
    
    getDepth()

Copyright © 1999-2021 Apache Software Foundation. All Rights Reserved.
Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, the Apache Logging project logo, and the Apache Log4j logo are trademarks of The Apache Software Foundation.

Class ThreadContext

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EMPTY_MAP

EMPTY_STACK

Method Detail

put

get

remove

clearMap

clearAll

containsKey

getContext

getImmutableContext

isEmpty

clearStack

cloneStack

getImmutableStack

setStack

getDepth

pop

peek

push

push

removeStack

trim