You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by rp...@apache.org on 2016/08/30 15:11:24 UTC
logging-log4j2 git commit: LOG4J2-1010 added javadoc example
implementation for 3rd party implementors
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 <rp...@apache.org>
Authored: Wed Aug 31 00:11:20 2016 +0900
Committer: rpopma <rp...@apache.org>
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.