Added ScopeListener interface to the ThreadLocalScopeManager

opentracing-util/src/main/java/io/opentracing/util/NoopScopeListener.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2016-2019 The OpenTracing Authors
+ *
+ * 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 io.opentracing.util;
+
+import io.opentracing.Span;
+
+public interface NoopScopeListener extends ScopeListener {
+    NoopScopeListener INSTANCE = new NoopScopeListenerImpl();
+}
+
+/**
+ * A noop (i.e., cheap-as-possible) implementation of a ScopeListener.
+ */
+class NoopScopeListenerImpl implements NoopScopeListener {
+
+    @Override
+    public void onActivated(Span span) {
+    }
+
+    @Override
+    public void onClosed() {
+    }
+}

opentracing-util/src/main/java/io/opentracing/util/ScopeListener.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2016-2019 The OpenTracing Authors
+ *
+ * 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 io.opentracing.util;
+
+import io.opentracing.Scope;
+import io.opentracing.ScopeManager;
+import io.opentracing.Span;
+
+/**
+ * Listener that can react on changes of currently active {@link Span}.
+ * <p>
+ * The {@link #onActivated} method will be called, whenever scope changes - that can be both
+ * as result of a {@link ScopeManager#activate(Span, boolean)} call or when {@link Scope#close()}
+ * is closed on a nested scope.
+ * <p>
+ * {@link #onClosed} is called when closing outermost scope - meaning no scope is currently active.
+ *
+ * @see ThreadLocalScopeManager
+ */
+public interface ScopeListener {
+
+    /**
+     * Called whenever a scope was activated (changed).
+     *
+     * @param span Activated span. Never null.
+     */
+    void onActivated(Span span);
+
+    /**
+     * Called when outermost scope was deactivated.
+     */
+    void onClosed();
+}

opentracing-util/src/main/java/io/opentracing/util/ThreadLocalScope.java

@@ -35,6 +35,7 @@ public class ThreadLocalScope implements Scope {
         this.finishOnClose = finishOnClose;
         this.toRestore = scopeManager.tlsScope.get();
         scopeManager.tlsScope.set(this);
+        scopeManager.listener.onActivated(wrapped);
     }
 
     @Override
@@ -48,7 +49,13 @@ public void close() {
             wrapped.finish();
         }
 
-        scopeManager.tlsScope.set(toRestore);
+        if (toRestore != null) {
+            scopeManager.tlsScope.set(toRestore);
+            scopeManager.listener.onActivated(toRestore.wrapped);
+        } else {
+            scopeManager.tlsScope.remove();
+            scopeManager.listener.onClosed();
+        }
     }
 
     @Override

opentracing-util/src/main/java/io/opentracing/util/ThreadLocalScopeManager.java

@@ -19,11 +19,33 @@
 
 /**
  * A simple {@link ScopeManager} implementation built on top of Java's thread-local storage primitive.
+ * <p>
+ * Optionally supports {@link ScopeListener}, to perform additional actions when scope is changed for given thread.
+ * Listener methods are always called synchronously on the same thread, right after activation (meaning {@link #active()}
+ * already returns new a scope).
  *
  * @see ThreadLocalScope
  */
 public class ThreadLocalScopeManager implements ScopeManager {
+
     final ThreadLocal<ThreadLocalScope> tlsScope = new ThreadLocal<ThreadLocalScope>();
+    final ScopeListener listener;
+
+    /**
+     * Default constructor for {@link ThreadLocalScopeManager}, without any listener.
+     */
+    public ThreadLocalScopeManager() {
+        this(null);
+    }
+
+    /**
+     * Constructs {@link ThreadLocalScopeManager} with custom {@link ScopeListener}.
+     *
+     * @param listener Listener to register. When null, noop listener will be used.
+     */
+    public ThreadLocalScopeManager(ScopeListener listener) {
+        this.listener = listener != null ? listener : NoopScopeListener.INSTANCE;
+    }
 
     @Override
     public Scope activate(Span span, boolean finishOnClose) {

opentracing-util/src/test/java/io/opentracing/util/ThreadLocalScopeTest.java

@@ -27,10 +27,12 @@
 
 public class ThreadLocalScopeTest {
     private ThreadLocalScopeManager scopeManager;
+    private ScopeListener scopeListener;
 
     @Before
     public void before() throws Exception {
-        scopeManager = new ThreadLocalScopeManager();
+        scopeListener = mock(ScopeListener.class);
+        scopeManager = new ThreadLocalScopeManager(scopeListener);
     }
 
     @Test
@@ -63,6 +65,11 @@ public void implicitSpanStack() throws Exception {
         verify(backgroundSpan, times(1)).finish();
         verify(foregroundSpan, times(1)).finish();
 
+        // Verify listener calls
+        verify(scopeListener, times(2)).onActivated(backgroundSpan);
+        verify(scopeListener, times(1)).onActivated(foregroundSpan);
+        verify(scopeListener, times(1)).onClosed();
+
         // And now nothing is active.
         Scope missingSpan = scopeManager.active();
         assertNull(missingSpan);
@@ -71,11 +78,16 @@ public void implicitSpanStack() throws Exception {
     @Test
     public void testDeactivateWhenDifferentSpanIsActive() {
         Span span = mock(Span.class);
+        Span nestedSpan = mock(Span.class);
 
         Scope active = scopeManager.activate(span, false);
-        scopeManager.activate(mock(Span.class), false);
+        scopeManager.activate(nestedSpan, false);
         active.close();
 
         verify(span, times(0)).finish();
+
+        verify(scopeListener, times(1)).onActivated(span);
+        verify(scopeListener, times(1)).onActivated(nestedSpan);
+        verify(scopeListener, times(0)).onClosed();
     }
 }