com.ibm.websphere.logging.hpel

Class LogRecordContext

java.lang.Object

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.

There are two ways to add key-value pairs to the LogRecordContext. The one you should use depends on whether the value is fixed, or variable.

Fixed value extensions

When you want to add an extension with a fixed value use the addExtension method. As an example, the following code uses addExtension to register an extension.

 
 Logger myLogger = Logger.getLogger("myLogger");
 LogRecordContext.addExtension("someName", "someValue");
 // This message will have the someName=someValue extension added to it
 logger.info("some message");
 LogRecordContext.removeExtension("someName");
 // This message will not have the extension added to it
 logger.info("some other message");
 
 

Variable value extensions

When you want to add an extension with a callback method to compute the extension value use the registerExtension method. As an example, the following code uses registerExtension to add an 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");
        }
        
 }
 
 

Using the extensions

Log handlers can use the key-value pairs in log and trace output by calling the getExtensions(Map) method. The getExtensions method first calls the getValue method for each LogRecordContext.Extension, adding the resultant key-value pairs to the Map. getExtensions then copies the fixed key-value pairs into the Map. An example log handler could be written 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

Nested Classes

Modifier and Type	Class and Description
static interface	LogRecordContext.Extension Call back interface to retrieve current extension value.

Constructor Summary

Constructors

Constructor and Description
LogRecordContext()

Method Summary

Methods

Modifier and Type	Method and Description
static void	addExtension(java.lang.String extensionName, java.lang.String extensionValue) Adds an extension key/value to the context.
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	removeExtension(java.lang.String extensionName) Removes an extension key/value from the context
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

addExtension

public static void addExtension(java.lang.String extensionName,
                java.lang.String extensionValue)

Adds an extension key/value to the context.

Parameters:

extensionName - String extensionName key name for the new extension

extensionValue - String extensionValue key value for the new extension

Throws:

java.lang.IllegalArgumentException - if parameter extensionName or extensionValue are null

removeExtension

public static boolean removeExtension(java.lang.String extensionName)

Removes an extension key/value from the context

Parameters:

extensionName - String extensionName associated with the registered extension.

Throws:

java.lang.IllegalArgumentException - if parameter extensionName is null.

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