IBM WebSphere Application ServerTM
Release 8

com.ibm.websphere.logging.hpel
Class LogRecordContext

java.lang.Object
  extended by com.ibm.websphere.logging.hpel.LogRecordContext

public class LogRecordContext
extends java.lang.Object

Provides a means to add key-value pairs to log and trace records. This class is particularly useful when the key-value pair that you need to add to log and trace output is already managed as a ThreadLocal.

Code that needs to add key-value pairs to log and trace records can register a key, and a corresponding LogRecordContext.Extension callback via the registerExtension method.

Log handlers can then use these key-value pairs in log and trace output by calling the getExtensions method, which in turn calls back to any registered LogRecordContext.Extension callbacks to populate the key-value pairs into a Map.

As an example, the following code could be used to add a LogRecordContext.Extension that provides the ThreadId of the current thread.


 import com.ibm.websphere.logging.hpel.LogRecordContext;
 
 public class ThreadIdExtension {
 
        // a strong reference to the LogRecordContext.Extension to make
        // sure it is not garbage collected
        private final static LogRecordContext.Extension extension = new LogRecordContext.Extension() {
                public String getValue() {
                        return Long.toString(Thread.currentThread().getId());
                }
        };
        
        public static void init() {
                LogRecordContext.registerExtension("ThreadId", extension);
        }
        
        public static void destroy() {
                LogRecordContext.unregisterExtension("ThreadId");
        }
        
 }
 
 
A log handler could then make use of this information as follows:
 import java.io.PrintWriter;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.logging.Handler;
 import java.util.logging.LogRecord;
 
 import com.ibm.websphere.logging.hpel.LogRecordContext;
 
 public class MyHandler extends Handler {
 
        private PrintWriter printWriter;
        
        MyHandler(PrintWriter printWriter) {
                this.printWriter = printWriter; 
        }
        
        public void close() { printWriter.close(); }
        public void flush() { printWriter.flush(); }
        
        public void publish(LogRecord record) {
                Map context = new HashMap();
                
                // get the extension keys/values
                LogRecordContext.getExtensions(context);
                
                String threadId = context.get("ThreadId");
                printWriter.println("[" + threadId + "] " + record.getMessage());
        }
 
 }
 
Note that the HPEL handlers call LogRecordContext.getExtensions and store the resultant key-value pairs in the log and trace data repositories. This information can then be accessed via the com.ibm.websphere.logging.hpel.reader.RepositoryLogRecord getExtensions method. Extension information can also be used for filtering log and trace records via the LogViewer command line tool's -includeExtensions option.


Nested Class Summary
static interface LogRecordContext.Extension
          Call back interface to retrieve current extension value.
 
Constructor Summary
LogRecordContext()
           
 
Method Summary
static void getExtensions(java.util.Map<java.lang.String,java.lang.String> map)
          Retrieves values for all registered context extensions.
static void registerExtension(java.lang.String key, LogRecordContext.Extension extension)
          Registers new context extension.
static boolean unregisterExtension(java.lang.String key)
          Removes context extension registration.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LogRecordContext

public LogRecordContext()
Method Detail

registerExtension

public static void registerExtension(java.lang.String key,
                                     LogRecordContext.Extension extension)
Registers new context extension. To avoid memory leaks Extensions are stored as weak references. It means that caller need to keep strong reference (a static field for example) to keep that extension in the registration map.

Parameters:
key - String key to associate with the registered extension
extension - LogRecordContext.Extension implementation returning extension runtime values
Throws:
java.lang.IllegalArgumentException - if parameter key or extension are null; or if key already has extension associated with it.

unregisterExtension

public static boolean unregisterExtension(java.lang.String key)
Removes context extension registration.

Parameters:
key - String key associated with the registered extension.
Returns:
true if key had extension associated with it.
Throws:
java.lang.IllegalArgumentException - if parameter key is null.

getExtensions

public static void getExtensions(java.util.Map<java.lang.String,java.lang.String> map)
                          throws java.lang.IllegalArgumentException
Retrieves values for all registered context extensions.

Parameters:
map - Map instance to populate with key-value pairs of the context extensions.
Throws:
java.lang.IllegalArgumentException - if parameter map is null

IBM WebSphere Application ServerTM
Release 8