Introduce ContextObserver API (Merge #92)

Author: sjoerdtalsma

context-propagation-java5/src/main/java/nl/talsmasoftware/context/Context.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 Talsma ICT
+ * Copyright 2016-2019 Talsma ICT
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,6 +20,9 @@
 /**
  * A context can be anything that needs to be maintained on the 'current thread' level.
  * <p>
+ * It is the responsibility of the one activating a new context to
+ * also {@linkplain #close() close} it again <em>from the same thread</em>.
+ * <p>
  * Implementations are typically maintained within a static {@link ThreadLocal} variable.<br>
  * A context has a very simple life-cycle: they can be created and {@link #close() closed}.
  * A well-behaved <code>Context</code> implementation will make sure that thread-local state is restored
@@ -48,15 +51,17 @@ public interface Context<T> extends Closeable {
     T getValue();
 
     /**
-     * Closes this context and restores any context changes made by this object to the way things were before it
-     * got created.
+     * Closes this context.
+     * <p>
+     * It is the responsibility of the one activating a new context to also close it again <em>from the same thread</em>.
      * <p>
      * It must be possible to call this method multiple times.
      * It is the responsibility of the implementor of this context to make sure that closing an already-closed context
      * has no unwanted side-effects.
      * A simple way to achieve this is by using an {@link java.util.concurrent.atomic.AtomicBoolean} to make sure the
      * 'closing' transition is executed only once.
      * <p>
+     * Implementors should attempt to restore previous contextual state upon close.
      *
      * @throws RuntimeException if an error occurs while restoring the context.
      */

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 Talsma ICT
+ * Copyright 2016-2019 Talsma ICT
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,12 +18,20 @@
 /**
  * The contract for a ContextManager Service.
  * <p>
- * Concrete implementations can be registered by providing an implementation class with a default constructor,
- * along with a class declaration in a service file called:<br>
- * <code>"/META-INF/services/nl.talsmasoftware.context.ContextManager"</code>
- * <p>
+ * Implementations can be registered by providing a fully qualified class name in a service file called:<br>
+ * <code>"/META-INF/services/nl.talsmasoftware.context.ContextManager"</code><br>
  * That will take care of any active context being captured in {@link ContextSnapshot} instances
- * managed by the {@link ContextManagers} utility class.
+ * managed by the {@link ContextManagers} utility class.<br>
+ * <b>Note:</b> <em>Make sure your implementation has a default (no-argument) constructor.</em>
+ * <p>
+ * A context manager is required to notify
+ * registered {@linkplain nl.talsmasoftware.context.observer.ContextObserver ContextObserver}
+ * of context updates.
+ * Using the {@linkplain nl.talsmasoftware.context.threadlocal.AbstractThreadLocalContext AbstractThreadLocalContext}
+ * already fulfills this requirement.
+ * Other implementations can use the utility methods defined in
+ * {@linkplain nl.talsmasoftware.context.observer.ContextObservers} to locate the appropriate context observers
+ * to be notified.
  *
  * @author Sjoerd Talsma
  */

context-propagation-java5/src/main/java/nl/talsmasoftware/context/PriorityServiceLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 Talsma ICT
+ * Copyright 2016-2019 Talsma ICT
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -37,7 +37,7 @@
  * @param <SVC> The type of service to load.
  * @author Sjoerd Talsma
  */
-final class PriorityServiceLoader<SVC> implements Iterable<SVC> {
+public final class PriorityServiceLoader<SVC> implements Iterable<SVC> {
     private static final Logger LOGGER = Logger.getLogger(PriorityServiceLoader.class.getName());
     private static final String SYSTEMPROPERTY_CACHING = "talsmasoftware.context.caching";
     private static final String ENVIRONMENT_CACHING_VALUE = System.getenv(
@@ -46,7 +46,7 @@ final class PriorityServiceLoader<SVC> implements Iterable<SVC> {
     private final Class<SVC> serviceType;
     private final Map<ClassLoader, List<SVC>> cache = new WeakHashMap<ClassLoader, List<SVC>>();
 
-    PriorityServiceLoader(Class<SVC> serviceType) {
+    public PriorityServiceLoader(Class<SVC> serviceType) {
         if (serviceType == null) throw new NullPointerException("Service type is <null>.");
         this.serviceType = serviceType;
     }
@@ -62,18 +62,18 @@ public Iterator<SVC> iterator() {
         return services.iterator();
     }
 
-    private static boolean isCachingDisabled() {
-        final String cachingProperty = System.getProperty(SYSTEMPROPERTY_CACHING, ENVIRONMENT_CACHING_VALUE);
-        return "0".equals(cachingProperty) || "false".equalsIgnoreCase(cachingProperty);
-    }
-
     /**
      * Removes the cache so the next call to {@linkplain #iterator()} will attempt to load the objects again.
      */
-    void clearCache() {
+    public void clearCache() {
         cache.clear();
     }
 
+    private static boolean isCachingDisabled() {
+        final String cachingProperty = System.getProperty(SYSTEMPROPERTY_CACHING, ENVIRONMENT_CACHING_VALUE);
+        return "0".equals(cachingProperty) || "false".equalsIgnoreCase(cachingProperty);
+    }
+
     private List<SVC> findServices(ClassLoader classLoader) {
         ArrayList<SVC> found = new ArrayList<SVC>();
         for (Iterator<SVC> iterator = loadServices(serviceType, classLoader); iterator.hasNext(); ) {

context-propagation-java5/src/main/java/nl/talsmasoftware/context/observer/ContextObserver.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2016-2019 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.
+ */
+package nl.talsmasoftware.context.observer;
+
+import nl.talsmasoftware.context.ContextManager;
+
+/**
+ * Observe context updates for a particular class of {@linkplain ContextManager}.
+ * <p>
+ * Create your context observer by implementing this interface
+ * and registering your class to the {@code ServiceLoader}
+ * SPI by adding the fully qualified class name to the resource
+ * {@code /META-INF/services/nl.talsmasoftware.context.observer.ContextObserver}.
+ * <p>
+ * It is the responsibility of the context implementor to update observers of
+ * context updates. SPI lookup of appropriate observers is facilitated
+ * by the {@linkplain ContextObservers#onActivate(Class, Object, Object)}
+ * and {@linkplain ContextObservers#onDeactivate(Class, Object, Object)}
+ * utility methods.<br>
+ * All subclasses of {@code AbstractThreadLocalContext} are already observable.
+ *
+ * @author Sjoerd Talsma
+ */
+public interface ContextObserver<T> {
+
+    /**
+     * The observed context manager(s).
+     * <p>
+     * Context observers can indicate which type of context manager must be observed using this method.
+     * For instance, returning {@code LocaleContextManager.class} here, updates for the {@code LocaleContext} will
+     * be offered to this observer.
+     * <p>
+     * To observe <em>all</em> context updates, return the {@linkplain ContextManager} interface class itself,
+     * since all context managers must implement it.
+     * <p>
+     * Return {@code null} to disable the observer.
+     *
+     * @return The observed context manager class or {@code null} to disable this observer.
+     */
+    Class<? extends ContextManager<T>> getObservedContextManager();
+
+    /**
+     * Indicates that a context <em>was just activated</em>.
+     *
+     * @param activatedContextValue The now active context value.
+     * @param previousContextValue  The previous context value or {@code null} if unknown or unsupported.
+     */
+    void onActivate(T activatedContextValue, T previousContextValue);
+
+    /**
+     * Indicates that a context <em>was just deactivated</em>.
+     *
+     * @param deactivatedContextValue The deactivated context value.
+     * @param restoredContextValue    The now active restored context value or {@code null} if unknown or unsupported.
+     */
+    void onDeactivate(T deactivatedContextValue, T restoredContextValue);
+
+}

context-propagation-java5/src/main/java/nl/talsmasoftware/context/observer/ContextObservers.java

@@ -0,0 +1,106 @@
+/*
+ * Copyright 2016-2019 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.
+ */
+package nl.talsmasoftware.context.observer;
+
+import nl.talsmasoftware.context.ContextManager;
+import nl.talsmasoftware.context.PriorityServiceLoader;
+
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * Utility class to assist Context implementors.
+ * <p>
+ * It implements the SPI behaviour, locating appropriate {@linkplain ContextObserver}
+ * implementations to be notified of {@linkplain #onActivate(Class, Object, Object) activate}
+ * and {@linkplain #onDeactivate(Class, Object, Object) deactivate} occurrances.
+ *
+ * @author Sjoerd Talsma
+ */
+public final class ContextObservers {
+
+    /**
+     * The service loader that loads (and possibly caches) {@linkplain ContextManager} instances in prioritized order.
+     */
+    private static final PriorityServiceLoader<ContextObserver> CONTEXT_OBSERVERS =
+            new PriorityServiceLoader<ContextObserver>(ContextObserver.class);
+
+    /**
+     * Private constructor to avoid instantiation of this class.
+     */
+    private ContextObservers() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Notifies all {@linkplain ContextObserver context observers} for the specified {@code contextManager}
+     * about the activated context value.
+     *
+     * @param contextManager        The context manager type that activated the context (required to observe).
+     * @param activatedContextValue The activated context value or {@code null} if no value was activated.
+     * @param previousContextValue  The previous context value or {@code null} if unknown or unsupported.
+     * @param <T>                   The type managed by the context manager.
+     */
+    @SuppressWarnings("unchecked") // If the observer tells us it can observe the values, we trust it.
+    public static <T> void onActivate(Class<? extends ContextManager<? super T>> contextManager,
+                                      T activatedContextValue,
+                                      T previousContextValue) {
+        if (contextManager != null) for (ContextObserver observer : CONTEXT_OBSERVERS) {
+            try {
+                final Class observedContext = observer.getObservedContextManager();
+                if (observedContext != null && observedContext.isAssignableFrom(contextManager)) {
+                    observer.onActivate(activatedContextValue, previousContextValue);
+                }
+            } catch (RuntimeException observationException) {
+                Logger.getLogger(observer.getClass().getName()).log(Level.WARNING,
+                        "Exception in " + observer.getClass().getSimpleName()
+                                + ".onActivate(" + activatedContextValue + ", " + previousContextValue
+                                + ") for " + contextManager.getSimpleName() + ": " + observationException.getMessage(),
+                        observationException);
+            }
+        }
+    }
+
+    /**
+     * Notifies all {@linkplain ContextObserver context observers} for the specified {@code contextManager}
+     * about the deactivated context value.
+     *
+     * @param contextManager          The context manager type that deactivated the context (required to observe).
+     * @param deactivatedContextValue The deactivated context value
+     * @param restoredContextValue    The restored context value or {@code null} if unknown or unsupported.
+     * @param <T>                     The type managed by the context manager.
+     */
+    @SuppressWarnings("unchecked") // If the observer tells us it can observe the values, we trust it.
+    public static <T> void onDeactivate(Class<? extends ContextManager<? super T>> contextManager,
+                                        T deactivatedContextValue,
+                                        T restoredContextValue) {
+        if (contextManager != null) for (ContextObserver observer : CONTEXT_OBSERVERS) {
+            try {
+                final Class observedContext = observer.getObservedContextManager();
+                if (observedContext != null && observedContext.isAssignableFrom(contextManager)) {
+                    observer.onDeactivate(deactivatedContextValue, restoredContextValue);
+                }
+            } catch (RuntimeException observationException) {
+                Logger.getLogger(observer.getClass().getName()).log(Level.WARNING,
+                        "Exception in " + observer.getClass().getSimpleName()
+                                + ".onDeactivate(" + deactivatedContextValue + ", " + deactivatedContextValue
+                                + ") for " + contextManager.getSimpleName() + ": " + observationException.getMessage(),
+                        observationException);
+            }
+        }
+    }
+
+}

context-propagation-java5/src/main/java/nl/talsmasoftware/context/threadlocal/AbstractThreadLocalContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 Talsma ICT
+ * Copyright 2016-2019 Talsma ICT
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,8 @@
 package nl.talsmasoftware.context.threadlocal;
 
 import nl.talsmasoftware.context.Context;
+import nl.talsmasoftware.context.ContextManager;
+import nl.talsmasoftware.context.observer.ContextObservers;
 
 import java.lang.reflect.Modifier;
 import java.util.concurrent.ConcurrentHashMap;
@@ -32,6 +34,7 @@
  * @author Sjoerd Talsma
  */
 public abstract class AbstractThreadLocalContext<T> implements Context<T> {
+    private static final AtomicBoolean DEPRECATED_CONSTRUCTOR_WARNING = new AtomicBoolean(true);
     /**
      * The constant of ThreadLocal context instances per subclass name so different types don't get mixed.
      */
@@ -42,6 +45,7 @@ public abstract class AbstractThreadLocalContext<T> implements Context<T> {
     private final ThreadLocal<AbstractThreadLocalContext<T>> sharedThreadLocalContext = threadLocalInstanceOf((Class) getClass());
     private final Logger logger = Logger.getLogger(getClass().getName());
     private final AtomicBoolean closed = new AtomicBoolean(false);
+    private final Class<? extends ContextManager<? super T>> contextManagerType;
 
     /**
      * The parent context that was active at the time this context was created (if any)
@@ -64,14 +68,36 @@ public abstract class AbstractThreadLocalContext<T> implements Context<T> {
      *
      * @param newValue The new value to become active in this new context
      *                 (or <code>null</code> to register a new context with 'no value').
+     * @deprecated Using this constructor makes it impossible to register a {@code ContextObserver}!
      */
-    @SuppressWarnings("unchecked")
+    @Deprecated
     protected AbstractThreadLocalContext(T newValue) {
+        this(null, newValue);
+        logger.log(DEPRECATED_CONSTRUCTOR_WARNING.compareAndSet(true, false) ? Level.WARNING : Level.FINE,
+                "Initialized new {0} without context manager type. " +
+                        "This makes it impossible to register ContextObservers for it. " +
+                        "Please fix {1} by specifying a ContextManager type " +
+                        "in the AbstractThreadLocalContext constructor.",
+                new Object[]{this, getClass().getSimpleName()});
+    }
+
+    /**
+     * Instantiates a new context with the specified value.
+     * The new context will be made the active context for the current thread.
+     *
+     * @param contextManagerType The context manager type (required to notify appropriate observers)
+     * @param newValue           The new value to become active in this new context
+     *                           (or <code>null</code> to register a new context with 'no value').
+     */
+    @SuppressWarnings("unchecked")
+    protected AbstractThreadLocalContext(Class<? extends ContextManager<? super T>> contextManagerType, T newValue) {
         this.unwindIfNecessary(); // avoid unnecessary parentContexts
+        this.contextManagerType = contextManagerType;
         this.parentContext = sharedThreadLocalContext.get();
         this.value = newValue;
         this.sharedThreadLocalContext.set(this);
         logger.log(Level.FINEST, "Initialized new {0}.", this);
+        ContextObservers.onActivate(contextManagerType, value, parentContext == null ? null : parentContext.getValue());
     }
 
     /**
@@ -119,9 +145,12 @@ public T getValue() {
      * This method has no side-effects if the context was already closed (it is safe to call multiple times).
      */
     public void close() {
-        closed.set(true);
-        this.unwindIfNecessary(); // Remove this context created in the same thread.
+        final boolean observe = closed.compareAndSet(false, true);
+        final Context<T> restored = this.unwindIfNecessary(); // Remove this context created in the same thread.
         logger.log(Level.FINEST, "Closed {0}.", this);
+        if (observe) {
+            ContextObservers.onDeactivate(contextManagerType, this.value, restored == null ? null : restored.getValue());
+        }
     }
 
     /**

context-propagation-java5/src/test/java/nl/talsmasoftware/context/DummyContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2017 Talsma ICT
+ * Copyright 2016-2019 Talsma ICT
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,7 +25,7 @@ final class DummyContext extends AbstractThreadLocalContext<String> {
             AbstractThreadLocalContext.threadLocalInstanceOf(DummyContext.class);
 
     DummyContext(String newValue) {
-        super(newValue);
+        super(DummyContextManager.class, newValue);
     }
 
     // Public for testing!