Mark ContextUtils as public (but deprecated) (#2072)

* Mark ContextUtils as public (but deprecated) to fix bincompat issues with 0.17.x->0.18.x
* Add an access mechanism for grpc context and update deprecation denotation.

Author: jsuereth

api/src/main/java/io/opencensus/trace/unsafe/ContextHandleUtils.java

@@ -16,6 +16,7 @@
 
 package io.opencensus.trace.unsafe;
 
+import io.grpc.Context;
 import io.opencensus.internal.Provider;
 import io.opencensus.trace.ContextHandle;
 import io.opencensus.trace.ContextManager;
@@ -76,4 +77,18 @@ public static ContextHandle withValue(
   public static Span getValue(ContextHandle context) {
     return CONTEXT_MANAGER.getValue(context);
   }
+
+  /**
+   * Attempts to pull the {@link io.grpc.Context} out of an OpenCensus {@code ContextHandle}.
+   *
+   * @return The context, or null if not a GRPC backed context handle.
+   */
+  @Nullable
+  public static Context tryExtractGrpcContext(ContextHandle handle) {
+    if (handle instanceof ContextHandleImpl) {
+      return ((ContextHandleImpl) handle).getContext();
+    }
+    // TODO: see if we can do something for the OpenTelemetry shim.
+    return null;
+  }
 }

api/src/main/java/io/opencensus/trace/unsafe/ContextManagerImpl.java

@@ -31,11 +31,13 @@ public ContextHandle currentContext() {
   }
 
   @Override
+  @SuppressWarnings({"deprecation"})
   public ContextHandle withValue(ContextHandle contextHandle, @Nullable Span span) {
     return wrapContext(ContextUtils.withValue(unwrapContext(contextHandle), span));
   }
 
   @Override
+  @SuppressWarnings({"deprecation"})
   public Span getValue(ContextHandle contextHandle) {
     return ContextUtils.getValue(unwrapContext(contextHandle));
   }

api/src/main/java/io/opencensus/trace/unsafe/ContextUtils.java

@@ -26,14 +26,16 @@
 */
 
 /**
- * Util methods/functionality to interact with the {@link io.grpc.Context}.
- *
- * <p>Users must interact with the current Context via the public APIs in {@link
- * io.opencensus.trace.Tracer} and avoid usages of the {@link #CONTEXT_SPAN_KEY} directly.
+ * Utilities for grabbing manipulating current context and grabbing current span.
  *
+ * @deprecated Please use {@link io.opencensus.trace.unsafe.ContextHandleUtils} Util
+ *     methods/functionality to interact with the {@link io.grpc.Context}. Users must interact with
+ *     the current Context via the public APIs in {@link io.opencensus.trace.Tracer} and avoid
+ *     usages of the {@link #CONTEXT_SPAN_KEY} directly.
  * @since 0.5
  */
-final class ContextUtils {
+@Deprecated()
+public final class ContextUtils {
   // No instance of this class.
   private ContextUtils() {}
 

api/src/test/java/io/opencensus/trace/unsafe/ContextUtilsTest.java

@@ -47,4 +47,10 @@ public void testGetCurrentSpan_ContextSetToNull() {
       ContextHandleUtils.currentContext().detach(orig);
     }
   }
+
+  @Test
+  public void testTryExtractGrpcContext_WillNotThrow() {
+    assertThat(ContextHandleUtils.tryExtractGrpcContext(ContextHandleUtils.currentContext()))
+        .isNotNull();
+  }
 }