Deprecate OpenTracing APIs that will be removed later through a break…

…ing-api release. (#1669) Motivation: We are going through an effort to re-visit the OpenTracing APIs and the implementations as part of a fix related to B3 sampling. Modifications: Deprecating APIs that will be removed or replaced where needed in a follow up breaking-api release. Result: Cleaner API, consistent & leaner state without duplication.
apple · Jul 15, 2021 · ac72f93 · ac72f93
1 parent 05a1cc5
commit ac72f93
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 2 deletions.
diff --git a/...cing-inmemory-api/src/main/java/io/servicetalk/opentracing/inmemory/api/InMemorySpan.java b/...cing-inmemory-api/src/main/java/io/servicetalk/opentracing/inmemory/api/InMemorySpan.java
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2018 Apple Inc. and the ServiceTalk project authors
+ * Copyright © 2018, 2021 Apple Inc. and the ServiceTalk project authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -48,7 +48,9 @@ public interface InMemorySpan extends Span, InMemoryTraceState {
      * Returns the low 64 bits of trace ID.
      *
      * @return low 64 bits of the trace ID
+     * @deprecated This method will be removed in a follow up release, to an effort to clean API.
      */
+    @Deprecated
     default long traceId() {
         String traceIdHex = traceIdHex();
         return longOfHexBytes(traceIdHex, traceIdHex.length() >= 32 ? 16 : 0);
@@ -58,7 +60,9 @@ default long traceId() {
      * Returns the high 64 bits for 128-bit trace IDs, or {@code 0L} for 64-bit trace IDs.
      *
      * @return high 64 bits of the trace ID
+     * @deprecated This method will be removed in a follow up release, to an effort to clean API.
      */
+    @Deprecated
     default long traceIdHigh() {
         String traceIdHex = traceIdHex();
         return traceIdHex.length() >= 32 ? longOfHexBytes(traceIdHex, 0) : 0;
@@ -68,7 +72,9 @@ default long traceIdHigh() {
      * Returns the span ID.
      *
      * @return span ID
+     * @deprecated This method will be removed in a follow up release, to an effort to clean API.
      */
+    @Deprecated
     default long spanId() {
         return longOfHexBytes(spanIdHex(), 0);
     }
@@ -77,8 +83,10 @@ default long spanId() {
      * Returns the parent span ID, could be null.
      *
      * @return parent span ID
+     * @deprecated This method will be removed in a follow up release, to an effort to clean API.
      */
     @Nullable
+    @Deprecated
     default Long parentSpanId() {
         String parentSpanIdHex = parentSpanIdHex();
         return parentSpanIdHex == null ? null : longOfHexBytes(parentSpanIdHex, 0);
@@ -88,7 +96,9 @@ default Long parentSpanId() {
      * Returns the parent span ID in hex. Returns {@code "null"} if the parent span ID is not present.
      *
      * @return parent span ID in hex
+     * @deprecated This method will be removed in a follow up release, to an effort to clean API.
      */
+    @Deprecated
     default String nonnullParentSpanIdHex() {
         String parentSpanIdHex = parentSpanIdHex();
         return parentSpanIdHex == null ? NO_PARENT_ID : parentSpanIdHex;

diff --git a/...memory-api/src/main/java/io/servicetalk/opentracing/inmemory/api/InMemorySpanContext.java b/...memory-api/src/main/java/io/servicetalk/opentracing/inmemory/api/InMemorySpanContext.java
@@ -24,7 +24,10 @@ public interface InMemorySpanContext extends SpanContext {
     /**
      * Get the {@link InMemoryTraceState} associated with this object.
      * @return the {@link InMemoryTraceState} associated with this object.
+     * @deprecated This method will be removed in a follow up release, to an effort to clean API. Alternative accessors
+     * will be offered through the {@link InMemorySpanContext} API.
      */
+    @Deprecated
     InMemoryTraceState traceState();
 
     /**
@@ -34,7 +37,9 @@ public interface InMemorySpanContext extends SpanContext {
      * based upon some sampling policy.
      *
      * @return whether the span should be sampled
+     * @deprecated This method will change in a follow up release, to hold an additional state of {@code null}.
      */
+    @Deprecated
     default boolean isSampled() {
         return traceState().isSampled();
     }

diff --git a/...nmemory-api/src/main/java/io/servicetalk/opentracing/inmemory/api/InMemoryTraceState.java b/...nmemory-api/src/main/java/io/servicetalk/opentracing/inmemory/api/InMemoryTraceState.java
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2018 Apple Inc. and the ServiceTalk project authors
+ * Copyright © 2018, 2021 Apple Inc. and the ServiceTalk project authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,7 +19,10 @@
 
 /**
  * Utility for representing a Ziplin-like trace state.
+ * @deprecated This class will be removed in a follow up release. Alternative accessors will be available through
+ * the {@link InMemorySpanContext} API.
  */
+@Deprecated
 public interface InMemoryTraceState {
     /**
      * The hex representation of the traceId.