Document new Slf4j propagation functionality.

This closes #590

Signed-off-by: Sjoerd Talsma <sjoerdtalsma@users.noreply.github.com>

Author: sjoerdtalsma

managers/context-manager-slf4j/README.md renamed to managers/context-manager-slf4j/readme.md

@@ -1,6 +1,6 @@
 [![Maven Version][maven-img]][maven] 
 
-# SLF4J MDC propagation library
+# Slf4j MDC propagation library
 
 Adding the `slf4j-propagation` jar to your classpath
 is all that is needed to let the [Mapped Diagnostic Context (MDC)][mdc] 
@@ -20,11 +20,15 @@ Add it to your classpath.
 
 Done!
 
-Now the `MDC.getCopyOfContextMap()` is copied into each snapshot 
-from the `ContextSnapshot.capture()` method
-to be reactivated by the `Contextsnapshot.reactivate()` call.
-The `ContextAwareExecutorService` automatically propagates the full [MDC] content
-into all executed tasks this way.
+## What does it do?
+
+The current `MDC` map values are included in each `ContextSnapshot` when it is captured.  
+Upon reactivation, these captured values (and _only_ these captured values) are reactivated in the MDC.
+- MDC keys that exist in the target MDC which are _not_ part of the snapshot are left unchanged.
+- MDC keys with the case-insensitive substring `"thread"`, are _not_ captured in the ContextSnashot,
+  since they most-likely contain a thread-specific value.
+- When a reactivation is _closed_, the _previous_ MDC values _for the captured keys_ are restored.
+  All other keys that are _not_ part of the context snapshot will be left unchanged.
 
 
   [maven-img]: https://img.shields.io/maven-central/v/nl.talsmasoftware.context.managers/context-manager-slf4j

managers/context-manager-slf4j/src/main/java/nl/talsmasoftware/context/managers/slf4j/mdc/Slf4jMdcManager.java

@@ -17,6 +17,7 @@
 
 import nl.talsmasoftware.context.api.Context;
 import nl.talsmasoftware.context.api.ContextManager;
+import nl.talsmasoftware.context.api.ContextSnapshot;
 import org.slf4j.MDC;
 
 import java.util.Collections;
@@ -30,18 +31,28 @@
  * getting the active context is fully delegated to the MDC.
  *
  * <p>
+ * Upon {@linkplain ContextSnapshot#reactivate() reactivation},
+ * these captured values (and <em>only</em> these captured values) are reactivated in the MDC.
+ * <ul>
+ *  <li>MDC keys that exist in the target MDC which are <em>not</em> part of the snapshot are left unchanged.
+ *  <li>MDC keys with the case-insensitive substring {@code "thread"}, are <em>not</em> captured
+ *      in the {@linkplain ContextSnapshot},
+ *      since they most-likely contain a thread-specific value.
+ *  <li>When a reactivation is <em>closed</em>, the <em>previous</em> MDC values <em>for the captured keys</em> are restored.
+ *      All other keys that are not part of the context snapshot will be left unchanged.
+ * </ul>
+ *
+ * <p>
  * Closing a context returned form {@link #activate(Map)} restores the MDC
  * to the values it had before the context was created.<br>
  * This means that closing nested contexts out-of-order will probably result in an undesirable state.<br>
  * It is therefore strongly advised to use Java's {@code try-with-resources} mechanism to ensure proper
  * closing of nested MDC contexts.
  *
- * <p>
- * This manager does not implement the optional {@link #clear()} method.
+ * @author Sjoerd Talsma
+ * @implNote This manager does not implement the optional {@link #clear()} method.
  * {@linkplain ContextManager#clearAll()} will therefore <strong>not</strong> clear the {@linkplain MDC}.
  * Please use {@linkplain MDC#clear()} explicitly to do that.
- *
- * @author Sjoerd Talsma
  */
 public class Slf4jMdcManager implements ContextManager<Map<String, String>> {
     /**

managers/context-manager-slf4j/src/main/java/nl/talsmasoftware/context/managers/slf4j/mdc/package-info.java

@@ -18,11 +18,19 @@
  *
  * <p>
  * This context manager maintains no ThreadLocal state of its own,
- * instead it propagates the
- * existing {@linkplain org.slf4j.MDC#getCopyOfContextMap() MDC context map}
- * into each {@linkplain nl.talsmasoftware.context.api.ContextSnapshot context snapshot}
- * to be applied again when the snapshot
- * is {@linkplain nl.talsmasoftware.context.api.ContextSnapshot#reactivate() reactivated}
- * in another thread.
+ * instead it propagates the current {@linkplain org.slf4j.MDC MDC} values
+ * into each {@linkplain nl.talsmasoftware.context.api.ContextSnapshot context snapshot} that is captured.
+ *
+ * <p>
+ * Upon {@linkplain nl.talsmasoftware.context.api.ContextSnapshot#reactivate() reactivation},
+ * these captured values (and <em>only</em> these captured values) are reactivated in the MDC.
+ * <ul>
+ *  <li>MDC keys that exist in the target MDC which are <em>not</em> part of the snapshot are left unchanged.
+ *  <li>MDC keys with the case-insensitive substring {@code "thread"}, are <em>not</em> captured
+ *      in the {@linkplain nl.talsmasoftware.context.api.ContextSnapshot},
+ *      since they most-likely contain a thread-specific value.
+ *  <li>When a reactivation is <em>closed</em>, the <em>previous</em> MDC values <em>for the captured keys</em> are restored.
+ *      All other keys that are not part of the context snapshot will be left unchanged.
+ * </ul>
  */
 package nl.talsmasoftware.context.managers.slf4j.mdc;