Cleanup deprecations to develop next major version (v2)

context-propagation/pom.xml → context-propagation-api/pom.xml

@@ -22,22 +22,18 @@
     <modelVersion>4.0.0</modelVersion>
     <parent>
         <groupId>nl.talsmasoftware.context</groupId>
-        <artifactId>context-propagation-root</artifactId>
-        <version>1.1.1-SNAPSHOT</version>
+        <artifactId>context-propagation</artifactId>
+        <version>2.0.0-SNAPSHOT</version>
     </parent>
 
     <!-- Artifact identification -->
-    <artifactId>context-propagation</artifactId>
-    <name>Context propagation (core)</name>
+    <artifactId>context-propagation-api</artifactId>
+    <name>Context propagation (api)</name>
     <packaging>jar</packaging>
 
     <properties>
-        <project.moduleName>${project.groupId}</project.moduleName>
+        <project.moduleName>${project.groupId}.api</project.moduleName>
         <root.basedir>${project.parent.basedir}</root.basedir>
-        <maven.compiler.source>1.5</maven.compiler.source>
-        <maven.compiler.target>1.5</maven.compiler.target>
-        <!-- Suppress java version deprecation warnings -->
-        <project.compiler.argument>-Xlint:-options</project.compiler.argument>
         <project.javadoc.version>8</project.javadoc.version>
 
         <javax.annotation-api.version>1.3.2</javax.annotation-api.version>

context-propagation/src/main/java/nl/talsmasoftware/context/api/Context.java → context-propagation-api/src/main/java/nl/talsmasoftware/context/api/Context.java

@@ -15,8 +15,6 @@
  */
 package nl.talsmasoftware.context.api;
 
-import nl.talsmasoftware.context.ContextManager;
-
 import java.io.Closeable;
 
 /**
@@ -44,9 +42,9 @@
  *
  * @param <T> Type of the context value.
  * @author Sjoerd Talsma
- * @since 1.1.0
+ * @since 2.0.0
  */
-public interface Context<T> extends Closeable, nl.talsmasoftware.context.Context<T> {
+public interface Context<T> extends Closeable {
 
     /**
      * The value associated with this context.

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

@@ -15,8 +15,6 @@
  */
 package nl.talsmasoftware.context.api;
 
-import nl.talsmasoftware.context.clearable.Clearable;
-
 /**
  * The service definition a {@linkplain Context} manager.
  *
@@ -26,8 +24,9 @@
  *
  * @param <T> type of the context value
  * @author Sjoerd Talsma
+ * @since 2.0.0
  */
-public interface ContextManager<T> extends nl.talsmasoftware.context.ContextManager<T>, Clearable {
+public interface ContextManager<T> {
 
     /**
      * Initialize a new context containing the specified <code>value</code>.
@@ -41,20 +40,12 @@ public interface ContextManager<T> extends nl.talsmasoftware.context.ContextMana
      */
     Context<T> initializeNewContext(T value);
 
-    /**
-     * The currently active context, or <code>null</code> if no context is active.
-     *
-     * @return The active context or <code>null</code> if there is none.
-     * @deprecated In favour of {@link #getActiveContextValue}
-     */
-    @Deprecated
-    Context<T> getActiveContext();
-
     /**
      * The value of the currently active context, or {@code null} if no context is active.
      *
      * @return The value of the active context, or {@code null} if no context is active.
      * @see Context#getValue()
+     * @since 2.0.0
      */
     T getActiveContextValue();
 
@@ -72,6 +63,8 @@ public interface ContextManager<T> extends nl.talsmasoftware.context.ContextMana
      *
      * <p>
      * This method normally should only get called by {@code ContextManagers.clearActiveContexts()}.
+     *
+     * @since 2.0.0
      */
     void clear();
 

context-propagation/src/main/java/nl/talsmasoftware/context/api/ContextSnapshot.java → context-propagation-api/src/main/java/nl/talsmasoftware/context/api/ContextSnapshot.java

@@ -15,9 +15,6 @@
  */
 package nl.talsmasoftware.context.api;
 
-import nl.talsmasoftware.context.Context;
-import nl.talsmasoftware.context.ContextManager;
-
 import java.io.Closeable;
 
 /**
@@ -41,9 +38,9 @@
  * {@link Reactivation#close()}.
  *
  * @author Sjoerd Talsma
- * @since 1.1.0
+ * @since 2.0.0
  */
-public interface ContextSnapshot extends nl.talsmasoftware.context.ContextSnapshot {
+public interface ContextSnapshot {
 
     /**
      * Temporarily reactivates all captured context values that are in the snapshot.
@@ -69,8 +66,10 @@ public interface ContextSnapshot extends nl.talsmasoftware.context.ContextSnapsh
      *
      * <p>
      * It is <strong>strongly advised</strong> to only use reactivation with try-with-resources code blocks.
+     *
+     * @since 2.0.0
      */
-    interface Reactivation extends Closeable, Context<Void> {
+    interface Reactivation extends Closeable {
         /**
          * Ends the contexts from the reactivated context snapshot.
          *
@@ -79,15 +78,6 @@ interface Reactivation extends Closeable, Context<Void> {
          * before the snapshot was activated.
          */
         void close();
-
-        /**
-         * A reactivation contains no value.
-         *
-         * @return Always {@code null}.
-         * @deprecated From the next major version, Reactivation will no longer extend Context.
-         */
-        @Deprecated
-        Void getValue();
     }
 
 }

context-propagation/src/main/java/nl/talsmasoftware/context/api/ContextTimer.java → context-propagation-api/src/main/java/nl/talsmasoftware/context/api/ContextTimer.java

@@ -20,29 +20,30 @@
 /**
  * Minimal Service Provider Interface for services that wish to get informed of context switching metrics.
  * <p>
- * Currently the following timed operations are updated:
+ * Currently, the following timed operations are updated:
  * <ul>
  * <li>{@code ContextManagers.createContextSnapshot}</li>
- * <li>{@code ContextSnapshot.reactivate}</li>
- * <li>{@code ContextManager.initializeNewContext}(*)</li>
- * <li>{@code ContextManager.getActiveContext}(*)</li>
+ * <li>{@linkplain ContextSnapshot#reactivate()}</li>
+ * <li>{@linkplain ContextManager#getActiveContextValue()} (*)</li>
+ * <li>{@linkplain ContextManager#initializeNewContext(Object)} (*)</li>
  * </ul>
  * <p>
  * (*) <em>Timing is updated for each concrete {@code ContextManager} implementation class</em>
  *
  * @author Sjoerd Talsma
- * @since 1.1.0
+ * @since 2.0.0
  */
 public interface ContextTimer {
 
     /**
      * Provides a new update for the context timer.
      *
-     * @param type     The class being called
-     * @param method   The method being called
-     * @param duration The duration of the method
-     * @param unit     The unit of the duration
+     * @param type     Class that was called
+     * @param method   Method that was called
+     * @param duration Duration of the call
+     * @param unit     Unit of the duration
+     * @param error    Error that was thrown in the call (optional, normally {@code null})
      */
-    void update(Class<?> type, String method, long duration, TimeUnit unit);
+    void update(Class<?> type, String method, long duration, TimeUnit unit, Throwable error);
 
 }

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

@@ -0,0 +1,53 @@
+/*
+ * 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.
+ */
+/**
+ * Main 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.
+ *
+ * <h2>{@linkplain nl.talsmasoftware.context.api.ContextManager}</h2>
+ * <p>
+ * Manages the active context.
+ * Can {@linkplain nl.talsmasoftware.context.api.ContextManager#initializeNewContext(java.lang.Object) initialize a new context}
+ * and provides access to
+ * 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.
+ *
+ * <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.
+ *
+ * <p>
+ * All context aware utility classes in this library are tested
+ * to make sure they reactivate and close snapshots in a safe way.
+ *
+ * @author Sjoerd Talsma
+ */
+package nl.talsmasoftware.context.api;