org.apache.logging.log4j.core

Interface ContextDataInjector

All Known Implementing Classes:

ThreadContextDataInjector.ForCopyOnWriteThreadContextMap, ThreadContextDataInjector.ForDefaultThreadContextMap, ThreadContextDataInjector.ForGarbageFreeThreadContextMap

public interface ContextDataInjector

Responsible for initializing the context data of LogEvents. Context data is data that is set by the application to be included in all subsequent log events.

NOTE: It is no longer recommended that custom implementations of this interface be provided as it is difficult to do. Instead, provide a custom ContextDataProvider.

The source of the context data is implementation-specific. The default source for context data is the ThreadContext.

In some asynchronous models, work may be delegated to several threads, while conceptually this work shares the same context. In such models, storing context data in ThreadLocal variables is not convenient or desirable. Users can configure the ContextDataInjectorFactory to provide custom ContextDataInjector objects, in order to initialize log events with context data from any arbitrary context.

When providing a custom ContextDataInjector, be aware that the ContextDataInjectorFactory may be invoked multiple times and the various components in Log4j that need access to context data may each have their own instance of ContextDataInjector. This includes the object(s) that populate log events, but also various lookups and filters that look at context data to determine whether an event should be logged.

Implementors should take particular note of how the different methods in the interface have different thread-safety guarantees to enable optimal performance.

Since:

2.7

See Also:

StringMap, ReadOnlyStringMap, ContextDataInjectorFactory, ThreadContext, ThreadContextDataInjector

Method Summary

Modifier and Type	Method and Description
org.apache.logging.log4j.util.StringMap	injectContextData(List<Property> properties, org.apache.logging.log4j.util.StringMap reusable) Returns a StringMap object initialized with the specified properties and the appropriate context data.
org.apache.logging.log4j.util.ReadOnlyStringMap	rawContextData() Returns a ReadOnlyStringMap object reflecting the current state of the context.

Method Detail

injectContextData

org.apache.logging.log4j.util.StringMap injectContextData(List<Property> properties,
                                                          org.apache.logging.log4j.util.StringMap reusable)

Returns a StringMap object initialized with the specified properties and the appropriate context data. The returned value may be the specified parameter or a different object.

This method will be called for each log event to initialize its context data and implementors should take care to make this method as performant as possible while preserving at least the following thread-safety guarantee.

Thread-safety note: The returned object can safely be passed off to another thread: future changes in the underlying context data will not be reflected in the returned object.

Example implementation:

 public StringMap injectContextData(List properties, StringMap reusable) {
     if (properties == null || properties.isEmpty()) {
         // assume context data is stored in a copy-on-write data structure that is safe to pass to another thread
         return (StringMap) rawContextData();
     }
     // first copy configuration properties into the result
     ThreadContextDataInjector.copyProperties(properties, reusable);

     // then copy context data key-value pairs (may overwrite configuration properties)
     reusable.putAll(rawContextData());
     return reusable;
 }
 

Parameters:

properties - Properties from the log4j configuration to be added to the resulting ReadOnlyStringMap. May be null or empty

reusable - a StringMap instance that may be reused to avoid creating temporary objects

Returns:

a StringMap instance initialized with the specified properties and the appropriate context data. The returned value may be the specified parameter or a different object.

See Also:

ThreadContextDataInjector.copyProperties(List, StringMap)

rawContextData

org.apache.logging.log4j.util.ReadOnlyStringMap rawContextData()

Returns a ReadOnlyStringMap object reflecting the current state of the context. Configuration properties are not included in the result.

This method may be called multiple times for each log event by Filters and Lookups and implementors should take care to make this method as performant as possible while preserving at least the following thread-safety guarantee.

Thread-safety note: The returned object can only be safely used in the current thread. Changes in the underlying context may or may not be reflected in the returned object, depending on the context data source and the implementation of this method. It is not safe to pass the returned object to another thread.

Returns:

a ReadOnlyStringMap object reflecting the current state of the context, may not return null