Javadoc fixes

.mvn/javadoc/log4j-api/package-list

@@ -0,0 +1,10 @@
+org.apache.logging.log4j
+org.apache.logging.log4j.internal
+org.apache.logging.log4j.internal.map
+org.apache.logging.log4j.message
+org.apache.logging.log4j.simple
+org.apache.logging.log4j.simple.internal
+org.apache.logging.log4j.spi
+org.apache.logging.log4j.status
+org.apache.logging.log4j.util
+org.apache.logging.log4j.util.internal

.mvn/javadoc/metrics-core/package-list

@@ -0,0 +1 @@
+com.codahale.metrics

.mvn/javadoc/opentelemetry-api/package-list

@@ -0,0 +1,10 @@
+io.opentelemetry.api
+io.opentelemetry.api.baggage
+io.opentelemetry.api.baggage.propagation
+io.opentelemetry.api.common
+io.opentelemetry.api.internal
+io.opentelemetry.api.logs
+io.opentelemetry.api.metrics
+io.opentelemetry.api.trace
+io.opentelemetry.api.trace.propagation
+io.opentelemetry.api.trace.propagation.internal

.mvn/javadoc/opentelemetry-context/package-list

@@ -0,0 +1,3 @@
+io.opentelemetry.context
+io.opentelemetry.context.internal.shaded
+io.opentelemetry.context.propagation

.mvn/javadoc/package-list

@@ -1,17 +1,17 @@
-nl.talsmasoftware.context
-nl.talsmasoftware.context.clearable
-nl.talsmasoftware.context.delegation
-nl.talsmasoftware.context.executors
-nl.talsmasoftware.context.observer
-nl.talsmasoftware.context.threadlocal
-nl.talsmasoftware.context.timing
-nl.talsmasoftware.context.functions
-nl.talsmasoftware.context.futures
-nl.talsmasoftware.context.metrics
-nl.talsmasoftware.context.locale
-nl.talsmasoftware.context.mdc
-nl.talsmasoftware.context.slf4j.mdc
-nl.talsmasoftware.context.log4j2.threadcontext
-nl.talsmasoftware.context.opentracing
-nl.talsmasoftware.context.servletrequest
-nl.talsmasoftware.context.springsecurity
+nl.talsmasoftware.context.api
+nl.talsmasoftware.context.core
+nl.talsmasoftware.context.core.concurrent
+nl.talsmasoftware.context.core.delegation
+nl.talsmasoftware.context.core.function
+nl.talsmasoftware.context.core.threadlocal
+nl.talsmasoftware.context.managers.locale
+nl.talsmasoftware.context.managers.log4j2.threadcontext
+nl.talsmasoftware.context.managers.opentelemetry
+nl.talsmasoftware.context.managers.opentracing
+nl.talsmasoftware.context.managers.servletrequest
+nl.talsmasoftware.context.managers.slf4j.mdc
+nl.talsmasoftware.context.managers.spring.security
+nl.talsmasoftware.context.timers.metrics
+nl.talsmasoftware.context.timers.micrometer
+nl.talsmasoftware.context.timers.opentelemetry
+nl.talsmasoftware.context.timers.opentracing

.mvn/javadoc/slf4j-api/package-list

@@ -0,0 +1,4 @@
+org.slf4j
+org.slf4j.event
+org.slf4j.helpers
+org.slf4j.spi

context-propagation-api/pom.xml

@@ -34,7 +34,6 @@
     <properties>
         <project.moduleName>${project.groupId}.api</project.moduleName>
         <root.basedir>${project.parent.basedir}</root.basedir>
-        <project.javadoc.version>8</project.javadoc.version>
 
         <javax.annotation-api.version>1.3.2</javax.annotation-api.version>
     </properties>

context-propagation-api/src/main/java/nl/talsmasoftware/context/api/ContextManager.java

@@ -16,10 +16,10 @@
 package nl.talsmasoftware.context.api;
 
 /**
- * The service definition a {@linkplain Context} manager.
+ * {@linkplain Context} manager service.
  *
  * <p>
- * Implementations must be made available as <em>service provider</em>.<br>
+ * Implementations must be made available through the {@linkplain java.util.ServiceLoader ServiceLoader}.<br>
  * For details how to make your implementation available, please see the documentation of {@link java.util.ServiceLoader}.
  *
  * @param <T> type of the context value

context-propagation-api/src/main/java/nl/talsmasoftware/context/api/package-info.java

@@ -14,18 +14,15 @@
  * limitations under the License.
  */
 /**
- * Main API concepts used throughout the {@code context-propagation} library.
+ * API concepts used throughout the {@code context-propagation} library.
  *
  * <h2>{@linkplain nl.talsmasoftware.context.api.Context}</h2>
  * <p>
  * A {@linkplain nl.talsmasoftware.context.api.Context context} contains
  * a {@linkplain nl.talsmasoftware.context.api.Context#getValue() value}.<br>
  * There can be one active context per thread. A context remains active until it is closed or another context
- * is activated in that thread.
- *
- * <p>
- * An {@code AbstractThreadLocalContext} base class is provided in the core module that supports
- * nested contexts and provides predictable behaviour for out-of-order closing.
+ * is activated in the same thread. Normally, a context is backed by a {@linkplain java.lang.ThreadLocal ThreadLocal}
+ * variable.
  *
  * <h2>{@linkplain nl.talsmasoftware.context.api.ContextManager}</h2>
  * <p>
@@ -35,17 +32,19 @@
  * the {@linkplain nl.talsmasoftware.context.api.ContextManager#getActiveContextValue() active context value}.
  *
  * <p>
- * For most application code it should not be necessary to interact with context managers directly.
- * Instead, using the various context-aware utility classes will automatically propagate context values.
+ * For normal application code it should not be necessary to interact with context managers directly.
+ * Instead, using the various context-aware utility classes from the core module will automatically propagate
+ * any supported context types to background threads for you.
  *
  * <h2>{@linkplain nl.talsmasoftware.context.api.ContextSnapshot}</h2>
  * <p>
- * A snapshot contains the current value from all known context managers.<br>
- * These values can be reactivated in another thread.<br>
- * Reactivated snapshots must be closed to avoid leaking context.
+ * A snapshot contains the active context value from all known context managers.<br>
+ * These values can be reactivated all together in another thread
+ * by {@linkplain nl.talsmasoftware.context.api.ContextSnapshot#reactivate() reactivating} the snapshot.<br>
+ * Reactivated snapshots <strong>must</strong> be closed to avoid leaking context.
  *
  * <p>
- * All context aware utility classes in this library are tested
+ * All context aware utility classes in this the core module of this library are tested
  * to make sure they reactivate and close snapshots in a safe way.
  *
  * @author Sjoerd Talsma

context-propagation-core/src/main/java/nl/talsmasoftware/context/core/concurrent/ContextAwareCompletableFuture.java

@@ -36,10 +36,15 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- * This class extends the standard {@link CompletableFuture} that was introduced in java version 8.
+ * {@linkplain CompletableFuture} that makes every successive call with a reactivated
+ * {@linkplain ContextSnapshot context snapshot} taken from the submitting thread.
+ *
+ * <p>
+ * Snapshots are properly closed after running the function body.
+ *
  * <p>
- * The class is a 'normal' Completable Future, but every successive call made on the result will be made within the
- * {@link ContextSnapshot context during creation} of this {@link ContextAwareCompletableFuture}.
+ * The implementation allows the creator to {@linkplain #takeNewSnapshot() take a new snapshot} to propagate
+ * after each completion stage. Please be aware that this may cause relatively high overhead.
  *
  * @author Sjoerd Talsma
  */

context-propagation-core/src/main/java/nl/talsmasoftware/context/core/concurrent/ContextAwareExecutorService.java

@@ -18,44 +18,50 @@
 import nl.talsmasoftware.context.api.ContextSnapshot;
 import nl.talsmasoftware.context.api.ContextSnapshot.Reactivation;
 import nl.talsmasoftware.context.core.ContextManagers;
-import nl.talsmasoftware.context.core.delegation.CallMappingExecutorService;
+import nl.talsmasoftware.context.core.delegation.DelegatingExecutorService;
 
 import java.util.concurrent.Callable;
 import java.util.concurrent.ExecutorService;
 
 /**
- * Executor service that wraps another executor service, making sure background tasks operates 'within'
- * a context snapshot taken from the submitting thread.
+ * Executor service that wraps another {@linkplain ExecutorService}, making sure background tasks operate 'within'
+ * a {@linkplain ContextSnapshot context snapshot} taken from the submitting thread.
  *
  * <p>
- * The executor service will make sure to close the reactivated snapshot again after the code in the task is finished,
+ * Any existing {@linkplain ExecutorService} can be used as a delegate, including those from
+ * the {@linkplain java.util.concurrent.Executors Executors} utility class.
+ *
+ * <p>
+ * The executor service will make sure to close each reactivated snapshot again after the code in the task is finished,
  * even if it throws an exception.
  *
  * <p>
- * Both {@link Callable} and {@link Runnable} tasks are mapped.
+ * Both {@link Callable} and {@link Runnable} tasks are wrapped.
  *
  * @author Sjoerd Talsma
  */
-public class ContextAwareExecutorService extends CallMappingExecutorService {
+public class ContextAwareExecutorService extends DelegatingExecutorService implements ExecutorService{
     public ContextAwareExecutorService(ExecutorService delegate) {
         super(delegate);
     }
 
-    /**
-     * This method maps any callable (before scheduling it) by taking a snapshot of the context in the scheduling thread
-     * and propagating this context into the executed callable by snapshot reactivation.
-     *
-     * @param callable The callable to be mapped.
-     * @param <V>      the actual return type of the callable object being scheduled.
-     * @return A callable that will reactivate the scheduling thread context snapshot before executing.
-     */
     @Override
-    protected <V> Callable<V> map(final Callable<V> callable) {
+    protected <T> Callable<T> wrap(final Callable<T> callable) {
         final ContextSnapshot snapshot = ContextManagers.createContextSnapshot();
         return () -> {
             try (Reactivation reactivation = snapshot.reactivate()) {
                 return callable.call();
             }
         };
     }
+
+    @Override
+    protected Runnable wrap(final Runnable runnable) {
+        final ContextSnapshot snapshot = ContextManagers.createContextSnapshot();
+        return () -> {
+            try (Reactivation reactivation = snapshot.reactivate()) {
+                runnable.run();
+            }
+        };
+    }
 }

context-propagation-core/src/main/java/nl/talsmasoftware/context/core/concurrent/ContextSnapshotHolder.java

@@ -44,24 +44,24 @@ final class ContextSnapshotHolder implements Consumer<ContextSnapshot>, Supplier
     }
 
     /**
-     * Accept a new snapshot (i.e. after a single stage is completed) to be propagated
-     * into another completion stage.
+     * Returns the current snapshot, normally to activate when beginning a new completion stage.
      *
-     * @param snapshot The snapshot to hold (required, must not be {@code null})
+     * @return The held snapshot (must never be {@code null})
      */
     @Override
-    public void accept(ContextSnapshot snapshot) {
-        this.snapshot = requireNonNull(snapshot, "Context snapshot is <null>.");
+    public ContextSnapshot get() {
+        return snapshot;
     }
 
     /**
-     * Returns the current snapshot, normally to activate when beginning a new completion stage.
+     * Accept a new snapshot (i.e. after a single stage is completed) to be propagated
+     * into another completion stage.
      *
-     * @return The held snapshot (should never be {@code null})
+     * @param snapshot The snapshot to hold (required, must not be {@code null})
      */
     @Override
-    public ContextSnapshot get() {
-        return snapshot;
+    public void accept(ContextSnapshot snapshot) {
+        this.snapshot = requireNonNull(snapshot, "Context snapshot is <null>.");
     }
 
 }

context-propagation-core/src/main/java/nl/talsmasoftware/context/core/concurrent/package-info.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2016-2024 Talsma ICT
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Context management for ThreadLocal values in concurrent applications.
+ *
+ * <h2>{@linkplain nl.talsmasoftware.context.core.concurrent.ContextAwareExecutorService ContextAwareExecutorService}</h2>
+ * <p>
+ * Executor service that wraps another {@linkplain java.util.concurrent.ExecutorService ExecutorService},
+ * making sure background tasks operate 'within'
+ * a {@linkplain nl.talsmasoftware.context.api.ContextSnapshot context snapshot} taken from the submitting thread.
+ *
+ * <h2>{@linkplain nl.talsmasoftware.context.core.concurrent.ContextAwareCompletableFuture ContextAwareCompletableFuture}</h2>
+ * <p>
+ * {@linkplain java.util.concurrent.CompletableFuture CompletableFuture} that runs every successive call with a reactivated
+ * {@linkplain nl.talsmasoftware.context.api.ContextSnapshot context snapshot} taken from the submitting thread.
+ */
+package nl.talsmasoftware.context.core.concurrent;