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

The MDC is managed on a per thread basis. A child thread automatically inherits a copy of the mapped diagnostic context of its parent.

Method Summary

static void	clear() Clear the context.
static void	clearStack() Clear the stack for this thread.
static Stack<String>	cloneStack() Return 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 identified by the key parameter.
static Map<String,String>	getContext() Get the current thread's MDC as a hashtable.
static int	getDepth() Get the current nesting depth of this thread's stack.
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	put(String key, String value) Put a context value (the o parameter) as identified with the key parameter into the current thread's context map.
static void	remove(String key) Remove the the context identified by the key parameter.
static void	removeStack() Remove the diagnostic context for this thread.
static void	setMaxDepth(int maxDepth) Set maximum depth of this diagnostic context.
static void	setStack(Stack<String> stack) Set this thread's stack.

Methods inherited from class java.lang.Object

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

Method Detail

put

public static void put(String key,
                       String value)

Put a context value (the o 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 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 the context 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()

Get the current thread's MDC as a hashtable. This method is intended to be used internally.

Returns:

a copy of the context.

clearStack

public static void clearStack()

Clear the stack for this thread.

cloneStack

public static Stack<String> cloneStack()

Return a copy of this thread's stack.

Returns:

A copy of this thread's stack.

setStack

public static void setStack(Stack<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:

setMaxDepth(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.

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.

setMaxDepth

public static void setMaxDepth(int maxDepth)

Set maximum depth of this diagnostic context. If the current depth is smaller or equal to maxDepth, then no action is taken.

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 NDC is unpredictable. The setMaxDepth method circumvents this problem.

For example, the combination

 void foo() {
    int depth = NDC.getDepth();
 

    ... complex sequence of calls
 

    NDC.setMaxDepth(depth);
 }
 

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

Parameters:

maxDepth - The maximum depth of the stack.

See Also:

getDepth()