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

Nested Class Summary

static interface

ThreadContext.ContextStack The ThreadContext Stack interface.

Field Summary

static Map<String,String>	EMPTY_MAP Empty, immutable Map.
static ThreadContextStack	EMPTY_STACK Empty, immutable ContextStack.

Method Summary

static void	clear() Clear the context.
static void	clearStack() Clear the stack for this thread.
static ThreadContext.ContextStack	cloneStack() Returns a copy of this thread's stack.
static boolean	containsKey(String key) Determine if the key is in the context.
static String	get(String key) Get 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() Get 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() Get 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) Push new diagnostic context information for the current thread.
static void	push(String message, Object... args) Push new diagnostic context information for the current thread.
static void	put(String key, String value) Put a context value (the value parameter) as identified with the key parameter into the current thread's context map.
static void	remove(String key) Remove the context value identified by the key parameter.
static void	removeStack() Remove the diagnostic context for this thread.
static void	setStack(Collection<String> stack) Set 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)

Put 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)

Get 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)

Remove the context value identified by the key parameter.

Parameters:

key - The key to remove.

clear

public static void clear()

Clear the context.

containsKey

public static boolean containsKey(String key)

Determine 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()

Clear 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()

Get 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)

Set this thread's stack.

Parameters:

stack - The stack to use.

getDepth

public static int getDepth()

Get 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)

Push 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)

Push 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()

Remove 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() {
    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()