Rc1 add async examples

opentracing-api/src/main/java/io/opentracing/Scope.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2016-2017 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;
+
+import java.io.Closeable;
+
+/**
+ * A {@link Scope} formalizes the activation and deactivation of a {@link Span}, usually from a CPU standpoint.
+ *
+ * <p>
+ * Many times a {@link Span} will be extant (in that {@link Span#finish()} has not been called) despite being in a
+ * non-runnable state from a CPU/scheduler standpoint. For instance, a {@link Span} representing the client side of an
+ * RPC will be unfinished but blocked on IO while the RPC is still outstanding. A {@link Scope} defines when a given
+ * {@link Span} <em>is</em> scheduled and on the path.
+ */
+public interface Scope extends Closeable {
+    /**
+     * Mark the end of the active period for the current thread and {@link Scope},
+     * updating the {@link ScopeManager#active()} in the process.
+     *
+     * <p>
+     * NOTE: Calling {@link #close} more than once on a single {@link Scope} instance leads to undefined
+     * behavior.
+     */
+    @Override
+    void close();
+
+    /**
+     * @return the {@link Span} that's been scoped by this {@link Scope}
+     */
+    Span span();
+}

opentracing-api/src/main/java/io/opentracing/ScopeManager.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2016-2017 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;
+
+/**
+ * The {@link ScopeManager} interface abstracts both the activation of {@link Span} instances (via
+ * {@link ScopeManager#activate(Span)}) and access to an active {@link Span}/{@link Scope}
+ * (via {@link ScopeManager#active()}).
+ *
+ * @see Scope
+ * @see Tracer#scopeManager()
+ */
+public interface ScopeManager {
+    /**
+     * Make a {@link Span} instance active.
+     *
+     * @param span the {@link Span} that should become the {@link #active()}
+     * @return a {@link Scope} instance to control the end of the active period for the {@link Span}. It is a
+     * programming error to neglect to call {@link Scope#close()} on the returned instance.
+     */
+    Scope activate(Span span);
+    Scope activate(Span span, boolean finishOnClose);
+
+    /**
+     * Return the currently active {@link Scope} which can be used to access the currently active
+     * {@link Scope#span()}.
+     *
+     * <p>
+     * If there is an {@link Scope non-null scope}, its wrapped {@link Span} becomes an implicit parent of any
+     * newly-created {@link Span} at {@link Tracer.SpanBuilder#startActive()} time (rather than at
+     * {@link Tracer#buildSpan(String)} time).
+     *
+     * @return the {@link Scope active scope}, or null if none could be found.
+     */
+    Scope active();
+}