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.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 theContextDataInjectorFactory
to provide customContextDataInjector
objects, in order to initialize log events with context data from any arbitrary context.When providing a custom
ContextDataInjector
, be aware that theContextDataInjectorFactory
may be invoked multiple times and the various components in Log4j that need access to context data may each have their own instance ofContextDataInjector
. 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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description StringMap
injectContextData(List<Property> properties, StringMap reusable)
Returns aStringMap
object initialized with the specified properties and the appropriate context data.ReadOnlyStringMap
rawContextData()
Returns aReadOnlyStringMap
object reflecting the current state of the context.
-
-
-
Method Detail
-
injectContextData
StringMap injectContextData(List<Property> properties, StringMap reusable)
Returns aStringMap
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 benull
or emptyreusable
- aStringMap
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
ReadOnlyStringMap rawContextData()
Returns aReadOnlyStringMap
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 returnnull
-
-