LOG4J2-1010 improved ContextDataInjector documentation
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/07162bea Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/07162bea Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/07162bea Branch: refs/heads/LOG4J2-1010&LOG4J2-1447-injectable-contextdata&better-datastructure Commit: 07162bea686913a21f0b7688d1c8ad50f9b7b691 Parents: 947d9d6 Author: rpopma <rpo...@apache.org> Authored: Sun Aug 28 22:24:13 2016 +0900 Committer: rpopma <rpo...@apache.org> Committed: Sun Aug 28 22:24:13 2016 +0900 ---------------------------------------------------------------------- .../logging/log4j/core/impl/ContextDataInjector.java | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/07162bea/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 5b74968..c1bd4b4 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 @@ -28,8 +28,13 @@ import org.apache.logging.log4j.core.config.Property; * </p><p> * 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 {@code ThreadLocal} variables is not convenient or desirable. - * By specifying a custom {@code ContextDataInjectorFactory}, users can initialize log events with context data from - * any arbitrary context. + * Users can configure the {@code ContextDataInjectorFactory} to provide custom {@code ContextDataInjector} objects, + * 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. + * 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> * * @see ContextDataInjectorFactory @@ -43,7 +48,8 @@ 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. * - * @param properties Properties from the log4j configuration to be added to the resulting ContextData + * @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.
