Repository: logging-log4j2 Updated Branches: refs/heads/LOG4J2-1010&LOG4J2-1447-injectable-contextdata&better-datastructure d3d3069a1 -> 2a976a990
LOG4J2-1010 added javadoc example implementation for 3rd party implementors Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/2a976a99 Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/2a976a99 Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/2a976a99 Branch: refs/heads/LOG4J2-1010&LOG4J2-1447-injectable-contextdata&better-datastructure Commit: 2a976a990f9002b49f5fabaa0858be9464e5aa99 Parents: d3d3069 Author: rpopma <[email protected]> Authored: Wed Aug 31 00:11:20 2016 +0900 Committer: rpopma <[email protected]> Committed: Wed Aug 31 00:11:20 2016 +0900 ---------------------------------------------------------------------- .../log4j/core/impl/ContextDataInjector.java | 34 ++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/2a976a99/log4j-core/src/main/java/org/apache/logging/log4j/core/impl/ContextDataInjector.java ---------------------------------------------------------------------- diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/impl/ContextDataInjector.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/impl/ContextDataInjector.java index 7fe4c53..058ffe1 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/impl/ContextDataInjector.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/impl/ContextDataInjector.java @@ -33,9 +33,13 @@ import org.apache.logging.log4j.core.config.Property; * in order to initialize log events with context data from any arbitrary context. * </p><p> * When providing a custom {@code ContextDataInjector}, be aware that the {@code ContextDataFactory} may be invoked - * multiple times by the various components in Log4j that need access to context data. + * multiple times and the various components in Log4j that need access to context data may each have their own instance + * of {@code 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. + * </p><p> + * Implementors should take particular note of how the different methods in the interface have different thread-safety + * guarantees to enable optimal performance. * </p> * * @see ContextDataInjectorFactory @@ -49,21 +53,47 @@ public interface ContextDataInjector { * Returns a {@code MutableContextData} object initialized with the specified properties and the appropriate * context data. The returned value may be the specified parameter or a different object. * <p> + * 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. + * </p><p> * 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. + * </p><p> + * Example implementation: * </p> + * <pre> + * public MutableContextData injectContextData(List<Property> properties, MutableContextData 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 (MutableContextData) rawContextData(); + * } + * // first copy configuration properties into the result + * ThreadContextDataInjector.copyProperties(properties, reusable); + * + * // then copy context data key-value pairs (may overwrite configuration properties) + * reusable.addAll(rawContextData()); + * return reusable; + * } + * </pre> * * @param properties Properties from the log4j configuration to be added to the resulting ContextData. May be * {@code null} or empty * @param reusable a {@code MutableContextData} instance that may be reused to avoid creating temporary objects * @return a {@code MutableContextData} instance initialized with the specified properties and the appropriate * context data. The returned value may be the specified parameter or a different object. + * @see ThreadContextDataInjector#copyProperties(List, MutableContextData) */ MutableContextData injectContextData(final List<Property> properties, final MutableContextData reusable); /** - * Returns a {@code ContextData} object reflecting the current state of the context. + * Returns a {@code ContextData} object reflecting the current state of the context. Configuration properties + * are not included in the result. * <p> + * 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. + * </p><p> * Thread-safety note: The returned object can only be safely used <em>in the current thread</em>. 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.
