Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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` | `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()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 1999-2015 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.