org.jboss.dna.common.util
Class LogContext

java.lang.Object
  extended by org.jboss.dna.common.util.LogContext

@Immutable
public class LogContext
extends Object

Provides a "mapped diagnostic context" (MDC) for use in capturing extra context information to be included in logs of multithreaded applications. Not all logging implementations support MDC, although a few do (including Log4J and Logback). Note that if the logging implementation does not support MDC, this information is ignored.

It can be difficult to understand what is going on within a multithreaded application. When multiple threads are working simultaneously, their log messages are mixed together. Thus, it's difficult to follow the log messages of a single thread. Log contexts provide a way to associate additional information with "the current context", and log messages can include that additional information in the messages.

Log contexts are managed for you, and so using them is very straightforward. Typically, log contexts are used within well-defined activities, and additional information is recorded in the context at the beginning of the activity and cleared at the end of the activity.

The following example shows how to set and clear this additional information:

   LogContext.set("username","jsmith");
   LogContext.set("operation","process");
   ...
   // do work here
   ...
   LogContext.clear();
 
Note that the actually values would not be hardcoded but would be retrieved from other objects available at the time.

If the logging system doesn't support MDC, then the additional information provided via LogContext is ignored. However, if the logging system is able to use MDC and it is set up with patterns that reference the keys, then those log messages will contain the values for those keys.


Constructor Summary
LogContext()
           
 
Method Summary
static void clear()
          Clear all entries in the MDC of the underlying implementation.
static String get(String key)
          Get the context identified by the key parameter.
static void remove(String key)
          Remove the the context identified by the key parameter using the underlying system's MDC implementation.
static void set(String key, String value)
          Put a context value (the val parameter) as identified with the key parameter into the current thread's context map.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LogContext

public LogContext()
Method Detail

set

public static void set(String key,
                       String value)
Put a context value (the val parameter) as identified with the key parameter into the current thread's context map. The key parameter cannot be null. The code>val parameter can be null only if the underlying implementation supports it.

This method delegates all work to the MDC of the underlying logging system.

Parameters:
key - the key
value - the value
Throws:
IllegalArgumentException - in case the "key" parameter is null

get

public static String get(String key)
Get the context identified by the key parameter. The key parameter cannot be null.

This method delegates all work to the MDC of the underlying logging system.

Parameters:
key - the key
Returns:
the string value identified by the key parameter.
Throws:
IllegalArgumentException - in case the "key" parameter is null

remove

public static void remove(String key)
Remove the the context identified by the key parameter using the underlying system's MDC implementation. The key parameter cannot be null. This method does nothing if there is no previous value associated with key.

Parameters:
key - the key
Throws:
IllegalArgumentException - in case the "key" parameter is null

clear

public static void clear()
Clear all entries in the MDC of the underlying implementation.



Copyright © 2008-2009 JBoss, a division of Red Hat. All Rights Reserved.