Add Scope as interface for NonThrowingCloseables that work with current context.

This interface allows users to write a shorter, more descriptive type name when
using scoped tags or spans.

9 files changed, 49 insertions, 29 deletions

diff --git a/api/src/main/java/io/opencensus/common/Scope.java b/api/src/main/java/io/opencensus/common/Scope.java
new file mode 100644
index 00000000..929fbd23
--- /dev/null
+++ b/api/src/main/java/io/opencensus/common/Scope.java
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2017, Google Inc.
+ * 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.opencensus.common;
+
+/**
+ * A {@link NonThrowingCloseable} that represents a change to the current context over a scope of
+ * code.
+ */
+public interface Scope extends NonThrowingCloseable {}
diff --git a/api/src/main/java/io/opencensus/trace/CurrentSpanUtils.java b/api/src/main/java/io/opencensus/trace/CurrentSpanUtils.java
index 884fd636..57909f37 100644
--- a/api/src/main/java/io/opencensus/trace/CurrentSpanUtils.java
+++ b/api/src/main/java/io/opencensus/trace/CurrentSpanUtils.java
@@ -14,7 +14,7 @@
 package io.opencensus.trace;
 
 import io.grpc.Context;
-import io.opencensus.common.NonThrowingCloseable;
+import io.opencensus.common.Scope;
 import io.opencensus.trace.unsafe.ContextUtils;
 
 /**
@@ -43,12 +43,12 @@ final class CurrentSpanUtils {
    * @return An object that defines a scope where the given {@code Span} is set to the current
    *     context.
    */
-  static NonThrowingCloseable withSpan(Span span) {
+  static Scope withSpan(Span span) {
     return new WithSpan(span, ContextUtils.CONTEXT_SPAN_KEY);
   }
 
   // Defines an arbitrary scope of code as a traceable operation. Supports try-with-resources idiom.
-  private static final class WithSpan implements NonThrowingCloseable {
+  private static final class WithSpan implements Scope {
     private final Context origContext;
 
     /**
diff --git a/api/src/main/java/io/opencensus/trace/ScopedSpanHandle.java b/api/src/main/java/io/opencensus/trace/ScopedSpanHandle.java
index e2cf1710..81493a2e 100644
--- a/api/src/main/java/io/opencensus/trace/ScopedSpanHandle.java
+++ b/api/src/main/java/io/opencensus/trace/ScopedSpanHandle.java
@@ -13,7 +13,7 @@
 
 package io.opencensus.trace;
 
-import io.opencensus.common.NonThrowingCloseable;
+import io.opencensus.common.Scope;
 
 /**
  * Defines a scope of code where the given {@link Span} is in the current context. The scope is
@@ -22,9 +22,9 @@ import io.opencensus.common.NonThrowingCloseable;
  *
  * <p>Supports try-with-resource idiom.
  */
-final class ScopedSpanHandle implements NonThrowingCloseable {
+final class ScopedSpanHandle implements Scope {
   private final Span span;
-  private final NonThrowingCloseable withSpan;
+  private final Scope withSpan;
 
   /**
    * Creates a {@code ScopedSpanHandle}
diff --git a/api/src/main/java/io/opencensus/trace/SpanBuilder.java b/api/src/main/java/io/opencensus/trace/SpanBuilder.java
index e61318ea..1d427b9c 100644
--- a/api/src/main/java/io/opencensus/trace/SpanBuilder.java
+++ b/api/src/main/java/io/opencensus/trace/SpanBuilder.java
@@ -15,7 +15,7 @@ package io.opencensus.trace;
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
-import io.opencensus.common.NonThrowingCloseable;
+import io.opencensus.common.Scope;
 import java.util.List;
 import javax.annotation.Nullable;
 
@@ -31,7 +31,7 @@ import javax.annotation.Nullable;
  *   private static final Tracer tracer = Tracing.getTracer();
  *   void doWork {
  *     // Create a Span as a child of the current Span.
- *     try (NonThrowingCloseable ss = tracer.spanBuilder("MyChildSpan").startScopedSpan()) {
+ *     try (Scope ss = tracer.spanBuilder("MyChildSpan").startScopedSpan()) {
  *       tracer.getCurrentSpan().addAnnotation("my annotation");
  *       doSomeWork();  // Here the new span is in the current Context, so it can be used
  *                      // implicitly anywhere down the stack.
@@ -57,7 +57,7 @@ import javax.annotation.Nullable;
  *   }
  *
  *   public void onExecuteHandler(ServerCallHandler serverCallHandler) {
- *     try (NonThrowingCloseable ws = tracer.withSpan(mySpan)) {
+ *     try (Scope ws = tracer.withSpan(mySpan)) {
  *       tracer.getCurrentSpan().addAnnotation("Start rpc execution.");
  *       serverCallHandler.run();  // Here the new span is in the current Context, so it can be
  *                                 // used implicitly anywhere down the stack.
@@ -178,7 +178,7 @@ public abstract class SpanBuilder {
    *   private static final Tracer tracer = Tracing.getTracer();
    *   void doWork {
    *     // Create a Span as a child of the current Span.
-   *     try (NonThrowingCloseable ss = tracer.spanBuilder("MyChildSpan").startScopedSpan()) {
+   *     try (Scope ss = tracer.spanBuilder("MyChildSpan").startScopedSpan()) {
    *       tracer.getCurrentSpan().addAnnotation("my annotation");
    *       doSomeWork();  // Here the new span is in the current Context, so it can be used
    *                      // implicitly anywhere down the stack. Anytime in this closure the span
@@ -199,7 +199,7 @@ public abstract class SpanBuilder {
    *   private static Tracer tracer = Tracing.getTracer();
    *   void doWork {
    *     // Create a Span as a child of the current Span.
-   *     NonThrowingCloseable ss = tracer.spanBuilder("MyChildSpan").startScopedSpan();
+   *     Scope ss = tracer.spanBuilder("MyChildSpan").startScopedSpan();
    *     try {
    *       tracer.getCurrentSpan().addAnnotation("my annotation");
    *       doSomeWork();  // Here the new span is in the current Context, so it can be used
@@ -215,7 +215,7 @@ public abstract class SpanBuilder {
    * @return an object that defines a scope where the newly created {@code Span} will be set to the
    *     current Context.
    */
-  public final NonThrowingCloseable startScopedSpan() {
+  public final Scope startScopedSpan() {
     return new ScopedSpanHandle(startSpan());
   }
 
diff --git a/api/src/main/java/io/opencensus/trace/Tracer.java b/api/src/main/java/io/opencensus/trace/Tracer.java
index b9f7b67b..55a48aa0 100644
--- a/api/src/main/java/io/opencensus/trace/Tracer.java
+++ b/api/src/main/java/io/opencensus/trace/Tracer.java
@@ -15,7 +15,7 @@ package io.opencensus.trace;
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
-import io.opencensus.common.NonThrowingCloseable;
+import io.opencensus.common.Scope;
 import io.opencensus.trace.SpanBuilder.NoopSpanBuilder;
 import javax.annotation.Nullable;
 
@@ -36,7 +36,7 @@ import javax.annotation.Nullable;
  * class MyClass {
  *   private static final Tracer tracer = Tracing.getTracer();
  *   void doWork() {
- *     try(NonThrowingCloseable ss = tracer.spanBuilder("MyClass.DoWork").startScopedSpan) {
+ *     try(Scope ss = tracer.spanBuilder("MyClass.DoWork").startScopedSpan) {
  *       tracer.getCurrentSpan().addAnnotation("Starting the work.");
  *       doWorkInternal();
  *       tracer.getCurrentSpan().addAnnotation("Finished working.");
@@ -107,7 +107,7 @@ public abstract class Tracer {
    * void doWork() {
    *   // Create a Span as a child of the current Span.
    *   Span span = tracer.spanBuilder("my span").startSpan();
-   *   try (NonThrowingCloseable ws = tracer.withSpan(span)) {
+   *   try (Scope ws = tracer.withSpan(span)) {
    *     tracer.getCurrentSpan().addAnnotation("my annotation");
    *     doSomeOtherWork();  // Here "span" is the current Span.
    *   }
@@ -125,7 +125,7 @@ public abstract class Tracer {
    * void doWork() {
    *   // Create a Span as a child of the current Span.
    *   Span span = tracer.spanBuilder("my span").startSpan();
-   *   NonThrowingCloseable ws = tracer.withSpan(span);
+   *   Scope ws = tracer.withSpan(span);
    *   try {
    *     tracer.getCurrentSpan().addAnnotation("my annotation");
    *     doSomeOtherWork();  // Here "span" is the current Span.
@@ -141,7 +141,7 @@ public abstract class Tracer {
    *     Context.
    * @throws NullPointerException if {@code span} is {@code null}.
    */
-  public final NonThrowingCloseable withSpan(Span span) {
+  public final Scope withSpan(Span span) {
     return CurrentSpanUtils.withSpan(checkNotNull(span, "span"));
   }
 
diff --git a/api/src/main/java/io/opencensus/trace/propagation/BinaryFormat.java b/api/src/main/java/io/opencensus/trace/propagation/BinaryFormat.java
index 284576ec..ab3ad5f2 100644
--- a/api/src/main/java/io/opencensus/trace/propagation/BinaryFormat.java
+++ b/api/src/main/java/io/opencensus/trace/propagation/BinaryFormat.java
@@ -28,7 +28,7 @@ import java.text.ParseException;
  * private static final BinaryFormat binaryFormat =
  *     Tracing.getPropagationComponent().getBinaryFormat();
  * void onSendRequest() {
- *   try (NonThrowingCloseable ss = tracer.spanBuilder("Sent.MyRequest").startScopedSpan()) {
+ *   try (Scope ss = tracer.spanBuilder("Sent.MyRequest").startScopedSpan()) {
  *     byte[] binaryValue = binaryFormat.toBinaryValue(tracer.getCurrentContext().context());
  *     // Send the request including the binaryValue and wait for the response.
  *   }
@@ -51,7 +51,7 @@ import java.text.ParseException;
  *   } catch (ParseException e) {
  *     // Maybe log the exception.
  *   }
- *   try (NonThrowingCloseable ss =
+ *   try (Scope ss =
  *            tracer.spanBuilderWithRemoteParent("Recv.MyRequest", spanContext).startScopedSpan()) {
  *     // Handle request and send response back.
  *   }
diff --git a/api/src/test/java/io/opencensus/trace/CurrentSpanUtilsTest.java b/api/src/test/java/io/opencensus/trace/CurrentSpanUtilsTest.java
index 9d82bd2c..9b8f6328 100644
--- a/api/src/test/java/io/opencensus/trace/CurrentSpanUtilsTest.java
+++ b/api/src/test/java/io/opencensus/trace/CurrentSpanUtilsTest.java
@@ -16,7 +16,7 @@ package io.opencensus.trace;
 import static com.google.common.truth.Truth.assertThat;
 
 import io.grpc.Context;
-import io.opencensus.common.NonThrowingCloseable;
+import io.opencensus.common.Scope;
 import io.opencensus.trace.unsafe.ContextUtils;
 import org.junit.Before;
 import org.junit.Test;
@@ -56,7 +56,7 @@ public class CurrentSpanUtilsTest {
   @Test
   public void withSpan() {
     assertThat(CurrentSpanUtils.getCurrentSpan()).isNull();
-    NonThrowingCloseable ws = CurrentSpanUtils.withSpan(span);
+    Scope ws = CurrentSpanUtils.withSpan(span);
     try {
       assertThat(CurrentSpanUtils.getCurrentSpan()).isSameAs(span);
     } finally {
@@ -68,7 +68,7 @@ public class CurrentSpanUtilsTest {
   @Test
   public void propagationViaRunnable() {
     Runnable runnable = null;
-    NonThrowingCloseable ws = CurrentSpanUtils.withSpan(span);
+    Scope ws = CurrentSpanUtils.withSpan(span);
     try {
       assertThat(CurrentSpanUtils.getCurrentSpan()).isSameAs(span);
       runnable =
diff --git a/api/src/test/java/io/opencensus/trace/ScopedSpanHandleTest.java b/api/src/test/java/io/opencensus/trace/ScopedSpanHandleTest.java
index 8922f4c2..72999115 100644
--- a/api/src/test/java/io/opencensus/trace/ScopedSpanHandleTest.java
+++ b/api/src/test/java/io/opencensus/trace/ScopedSpanHandleTest.java
@@ -17,7 +17,7 @@ import static com.google.common.truth.Truth.assertThat;
 import static org.mockito.Matchers.same;
 import static org.mockito.Mockito.verify;
 
-import io.opencensus.common.NonThrowingCloseable;
+import io.opencensus.common.Scope;
 import org.junit.Before;
 import org.junit.Test;
 import org.junit.runner.RunWith;
@@ -39,7 +39,7 @@ public class ScopedSpanHandleTest {
   @Test
   public void initAttachesSpan_CloseDetachesAndEndsSpan() {
     assertThat(tracer.getCurrentSpan()).isSameAs(BlankSpan.INSTANCE);
-    NonThrowingCloseable ss = new ScopedSpanHandle(span);
+    Scope ss = new ScopedSpanHandle(span);
     try {
       assertThat(tracer.getCurrentSpan()).isSameAs(span);
     } finally {
diff --git a/api/src/test/java/io/opencensus/trace/TracerTest.java b/api/src/test/java/io/opencensus/trace/TracerTest.java
index a0830428..96116bc2 100644
--- a/api/src/test/java/io/opencensus/trace/TracerTest.java
+++ b/api/src/test/java/io/opencensus/trace/TracerTest.java
@@ -18,7 +18,7 @@ import static org.mockito.Matchers.same;
 import static org.mockito.Mockito.when;
 
 import io.grpc.Context;
-import io.opencensus.common.NonThrowingCloseable;
+import io.opencensus.common.Scope;
 import org.junit.Before;
 import org.junit.Rule;
 import org.junit.Test;
@@ -56,7 +56,7 @@ public class TracerTest {
   @Test
   public void getCurrentSpan_WithSpan() {
     assertThat(noopTracer.getCurrentSpan()).isSameAs(BlankSpan.INSTANCE);
-    NonThrowingCloseable ws = noopTracer.withSpan(span);
+    Scope ws = noopTracer.withSpan(span);
     try {
       assertThat(noopTracer.getCurrentSpan()).isSameAs(span);
     } finally {
@@ -68,7 +68,7 @@ public class TracerTest {
   @Test
   public void propagationViaRunnable() {
     Runnable runnable;
-    NonThrowingCloseable ws = noopTracer.withSpan(span);
+    Scope ws = noopTracer.withSpan(span);
     try {
       assertThat(noopTracer.getCurrentSpan()).isSameAs(span);
       runnable =
@@ -129,7 +129,7 @@ public class TracerTest {
 
   @Test
   public void startSpanWithParentFromContext() {
-    NonThrowingCloseable ws = tracer.withSpan(span);
+    Scope ws = tracer.withSpan(span);
     try {
       assertThat(tracer.getCurrentSpan()).isSameAs(span);
       when(tracer.spanBuilderWithExplicitParent(same(SPAN_NAME), same(span)))
@@ -142,7 +142,7 @@ public class TracerTest {
 
   @Test
   public void startSpanWithInvalidParentFromContext() {
-    NonThrowingCloseable ws = tracer.withSpan(BlankSpan.INSTANCE);
+    Scope ws = tracer.withSpan(BlankSpan.INSTANCE);
     try {
       assertThat(tracer.getCurrentSpan()).isSameAs(BlankSpan.INSTANCE);
       when(tracer.spanBuilderWithExplicitParent(same(SPAN_NAME), same(BlankSpan.INSTANCE)))