Change API to remove the "Option" logic and keep only Builder. (#380)

4 files changed, 69 insertions, 278 deletions

diff --git a/api/src/main/java/io/opencensus/trace/SpanBuilder.java b/api/src/main/java/io/opencensus/trace/SpanBuilder.java
index 782248ba..f573d9a6 100644
--- a/api/src/main/java/io/opencensus/trace/SpanBuilder.java
+++ b/api/src/main/java/io/opencensus/trace/SpanBuilder.java
@@ -13,11 +13,11 @@
 
 package io.opencensus.trace;
 
+import static com.google.common.base.Preconditions.checkNotNull;
+
 import io.opencensus.common.NonThrowingCloseable;
 import io.opencensus.trace.base.EndSpanOptions;
 import io.opencensus.trace.base.Sampler;
-import io.opencensus.trace.base.StartSpanOptions;
-import io.opencensus.trace.internal.SpanFactory;
 import java.util.List;
 import javax.annotation.Nullable;
 
@@ -102,34 +102,15 @@ import javax.annotation.Nullable;
  * <p>If your Java version is less than Java SE 7, see {@link SpanBuilder#startSpan} and {@link
  * SpanBuilder#startScopedSpan} for usage examples.
  */
-public final class SpanBuilder {
-  private final SpanFactory spanFactory;
-  private final String name;
-  private final StartSpanOptions.Builder startSpanOptionsBuilder = StartSpanOptions.builder();
-  private Span parentSpan;
-  private SpanContext parentSpanContext;
-  private boolean remoteParent;
-
-  static SpanBuilder builder(SpanFactory spanFactory, Span parentSpan, String name) {
-    return new SpanBuilder(spanFactory, parentSpan, null, false, name);
-  }
-
-  static SpanBuilder builderWithRemoteParent(
-      SpanFactory spanFactory, SpanContext parentSpanContext, String name) {
-    return new SpanBuilder(spanFactory, null, parentSpanContext, true, name);
-  }
+public abstract class SpanBuilder {
 
   /**
-   * Sets the {@link Sampler} to use. If a {@code null} value is passed, the implementation will
-   * provide a default.
+   * Sets the {@link Sampler} to use. If not set, the implementation will provide a default.
    *
    * @param sampler The {@code Sampler} to use when determining sampling for a {@code Span}.
    * @return this.
    */
-  public SpanBuilder setSampler(@Nullable Sampler sampler) {
-    startSpanOptionsBuilder.setSampler(sampler);
-    return this;
-  }
+  public abstract SpanBuilder setSampler(Sampler sampler);
 
   /**
    * Sets the {@code List} of parent links. Links are used to link {@link Span}s in different
@@ -138,11 +119,9 @@ public final class SpanBuilder {
    *
    * @param parentLinks New links to be added.
    * @return this.
+   * @throws NullPointerException if {@code parentLinks} is {@code null}.
    */
-  public SpanBuilder setParentLinks(@Nullable List<Span> parentLinks) {
-    startSpanOptionsBuilder.setParentLinks(parentLinks);
-    return this;
-  }
+  public abstract SpanBuilder setParentLinks(List<Span> parentLinks);
 
   /**
    * Sets the option {@link Span.Options#RECORD_EVENTS} for the newly created {@code Span}. If not
@@ -151,27 +130,7 @@ public final class SpanBuilder {
    * @param recordEvents New value determining if this {@code Span} should have events recorded.
    * @return this.
    */
-  public SpanBuilder setRecordEvents(boolean recordEvents) {
-    startSpanOptionsBuilder.setRecordEvents(recordEvents);
-    return this;
-  }
-
-  /**
-   * If called this will force the newly created {@code Span} to be a root span. As a consequence,
-   * any parent specified (or inherited from the Context) will be ignored (N.B. does not apply to
-   * linked parents set through {@link #setParentLinks}).
-   *
-   * <p>This is useful when {@link Tracer#spanBuilder(String)} is used and the newly created {@code
-   * Span} needs to be decoupled from the parent {@code Span}.
-   *
-   * @return this.
-   */
-  public SpanBuilder becomeRoot() {
-    parentSpan = null;
-    parentSpanContext = null;
-    remoteParent = false;
-    return this;
-  }
+  public abstract SpanBuilder setRecordEvents(boolean recordEvents);
 
   /**
    * Starts a new {@link Span}.
@@ -201,9 +160,7 @@ public final class SpanBuilder {
    *
    * @return the newly created {@code Span}.
    */
-  public Span startSpan() {
-    return start();
-  }
+  public abstract Span startSpan();
 
   // TODO(bdrutu): Add error_prone annotation @MustBeClosed when the 2.0.16 jar is fixed.
   /**
@@ -260,28 +217,38 @@ public final class SpanBuilder {
    * @return an object that defines a scope where the newly created {@code Span} will be set to the
    *     current Context.
    */
-  public NonThrowingCloseable startScopedSpan() {
-    return new ScopedSpanHandle(start());
+  public final NonThrowingCloseable startScopedSpan() {
+    return new ScopedSpanHandle(startSpan());
   }
 
-  private SpanBuilder(
-      SpanFactory spanFactory,
-      @Nullable Span parentSpan,
-      @Nullable SpanContext parentSpanContext,
-      boolean remoteParent,
-      String name) {
-    this.parentSpan = parentSpan;
-    this.parentSpanContext = parentSpanContext;
-    this.remoteParent = remoteParent;
-    this.name = name;
-    this.spanFactory = spanFactory;
-  }
+  static final class NoopSpanBuilder extends SpanBuilder {
+    NoopSpanBuilder(@Nullable Span parentSpan, String name) {
+      checkNotNull(name, "name");
+    }
+
+    NoopSpanBuilder(SpanContext remoteParentSpanContext, String name) {
+      checkNotNull(remoteParentSpanContext, "remoteParentSpanContext");
+      checkNotNull(name, "name");
+    }
+
+    @Override
+    public Span startSpan() {
+      return BlankSpan.INSTANCE;
+    }
+
+    @Override
+    public SpanBuilder setSampler(@Nullable Sampler sampler) {
+      return this;
+    }
+
+    @Override
+    public SpanBuilder setParentLinks(List<Span> parentLinks) {
+      return this;
+    }
 
-  // Utility method to start a Span.
-  private Span start() {
-    return remoteParent
-        ? spanFactory.startSpanWithRemoteParent(
-            parentSpanContext, name, startSpanOptionsBuilder.build())
-        : spanFactory.startSpan(parentSpan, name, startSpanOptionsBuilder.build());
+    @Override
+    public SpanBuilder setRecordEvents(boolean recordEvents) {
+      return this;
+    }
   }
 }
diff --git a/api/src/main/java/io/opencensus/trace/Tracer.java b/api/src/main/java/io/opencensus/trace/Tracer.java
index e6172bed..ef5616a9 100644
--- a/api/src/main/java/io/opencensus/trace/Tracer.java
+++ b/api/src/main/java/io/opencensus/trace/Tracer.java
@@ -16,8 +16,6 @@ package io.opencensus.trace;
 import static com.google.common.base.Preconditions.checkNotNull;
 
 import io.opencensus.common.NonThrowingCloseable;
-import io.opencensus.trace.base.StartSpanOptions;
-import io.opencensus.trace.internal.SpanFactory;
 import javax.annotation.Nullable;
 
 /**
@@ -67,7 +65,6 @@ import javax.annotation.Nullable;
  */
 public abstract class Tracer {
   private static final NoopTracer noopTracer = new NoopTracer();
-  private final SpanFactory spanFactory;
 
   /**
    * Returns the no-op implementation of the {@code Tracer}.
@@ -142,7 +139,7 @@ public abstract class Tracer {
    * @param span The {@link Span} to be set to the current Context.
    * @return an object that defines a scope where the given {@link Span} will be set to the current
    *     Context.
-   * @throws NullPointerException if span is null.
+   * @throws NullPointerException if {@code span} is null.
    */
   public final NonThrowingCloseable withSpan(Span span) {
     return ContextUtils.withSpan(checkNotNull(span, "span"));
@@ -150,7 +147,7 @@ public abstract class Tracer {
 
   /**
    * Returns a {@link SpanBuilder} to create and start a new child {@link Span} as a child of to the
-   * current {@code Span} if any, otherwise create a root Span with the default options.
+   * current {@code Span} if any, otherwise creates a root {@code Span}.
    *
    * <p>See {@link SpanBuilder} for usage examples.
    *
@@ -159,7 +156,7 @@ public abstract class Tracer {
    *
    * @param name The name of the returned Span.
    * @return a {@code SpanBuilder} to create and start a new {@code Span}.
-   * @throws NullPointerException if name is null.
+   * @throws NullPointerException if {@code name} is null.
    */
   public final SpanBuilder spanBuilder(String name) {
     return spanBuilder(ContextUtils.getCurrentSpan(), name);
@@ -167,64 +164,60 @@ public abstract class Tracer {
 
   /**
    * Returns a {@link SpanBuilder} to create and start a new child {@link Span} (or root if parent
-   * is null), with parent being the designated {@code Span}.
+   * is {@code null} or has an invalid {@link SpanContext}), with parent being the designated {@code
+   * Span}.
    *
    * <p>See {@link SpanBuilder} for usage examples.
    *
-   * <p>This <b>must</b> be used to create a {@code Span} when manual Context propagation is used.
+   * <p>This <b>must</b> be used to create a {@code Span} when manual Context propagation is used
+   * OR when creating a root {@code Span} with a {@code null} parent.
    *
    * @param parent The parent of the returned Span. If null the {@code SpanBuilder} will build a
    *     root {@code Span}.
    * @param name The name of the returned Span.
    * @return a {@code SpanBuilder} to create and start a new {@code Span}.
-   * @throws NullPointerException if name is null.
+   * @throws NullPointerException if {@code name} is null.
    */
-  public final SpanBuilder spanBuilder(@Nullable Span parent, String name) {
-    return SpanBuilder.builder(spanFactory, parent, checkNotNull(name, "name"));
-  }
+  public abstract SpanBuilder spanBuilder(@Nullable Span parent, String name);
 
   /**
    * Returns a {@link SpanBuilder} to create and start a new child {@link Span} (or root if parent
-   * is null), with parent being the {@link Span} designated by the {@link SpanContext}.
+   * is an invalid {@link SpanContext}), with parent being the {@link Span} designated by the {@link
+   * SpanContext}.
    *
    * <p>See {@link SpanBuilder} for usage examples.
    *
    * <p>This <b>must</b> be used to create a {@code Span} when the parent is in a different process.
    * This is only intended for use by RPC systems or similar.
    *
-   * @param remoteParent The remote parent of the returned Span.
+   * <p>If no {@link SpanContext} OR fail to parse the {@link SpanContext} on the server side,
+   * users must call this method with an {@link SpanContext#INVALID} remote parent {@code
+   * SpanContext}.
+   *
+   * @param remoteParentSpanContext The remote parent of the returned Span.
    * @param name The name of the returned Span.
    * @return a {@code SpanBuilder} to create and start a new {@code Span}.
-   * @throws NullPointerException if name is null.
+   * @throws NullPointerException if {@code name} or {@code remoteParentSpanContext} are null.
    */
-  public final SpanBuilder spanBuilderWithRemoteParent(
-      @Nullable SpanContext remoteParent, String name) {
-    return SpanBuilder.builderWithRemoteParent(
-        spanFactory, remoteParent, checkNotNull(name, "name"));
-  }
+  public abstract SpanBuilder spanBuilderWithRemoteParent(
+      SpanContext remoteParentSpanContext, String name);
 
   // No-Op implementation of the Tracer.
   private static final class NoopTracer extends Tracer {
-    private NoopTracer() {
-      super(new NoopSpanFactory());
-    }
 
-    // No-op implementation of the SpanFactory
-    private static final class NoopSpanFactory extends SpanFactory {
-      @Override
-      public Span startSpan(@Nullable Span parent, String name, StartSpanOptions options) {
-        return BlankSpan.INSTANCE;
-      }
+    @Override
+    public SpanBuilder spanBuilder(@Nullable Span parent, String name) {
+      return new SpanBuilder.NoopSpanBuilder(parent, name);
+    }
 
-      @Override
-      public Span startSpanWithRemoteParent(
-          @Nullable SpanContext remoteParent, String name, StartSpanOptions options) {
-        return BlankSpan.INSTANCE;
-      }
+    @Override
+    public SpanBuilder spanBuilderWithRemoteParent(
+        SpanContext remoteParentSpanContext, String name) {
+      return new SpanBuilder.NoopSpanBuilder(remoteParentSpanContext, name);
     }
-  }
 
-  protected Tracer(SpanFactory spanFactory) {
-    this.spanFactory = checkNotNull(spanFactory, "spanFactory");
+    private NoopTracer() {}
   }
+
+  protected Tracer() {}
 }
diff --git a/api/src/main/java/io/opencensus/trace/base/StartSpanOptions.java b/api/src/main/java/io/opencensus/trace/base/StartSpanOptions.java
deleted file mode 100644
index 518f1e60..00000000
--- a/api/src/main/java/io/opencensus/trace/base/StartSpanOptions.java
+++ /dev/null
@@ -1,122 +0,0 @@
-/*
- * Copyright 2016, 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.trace.base;
-
-import com.google.auto.value.AutoValue;
-import com.google.common.annotations.VisibleForTesting;
-import io.opencensus.trace.Span;
-import io.opencensus.trace.config.TraceConfig;
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.List;
-import javax.annotation.Nullable;
-import javax.annotation.concurrent.Immutable;
-
-/**
- * A class that enables overriding the default values used when starting a {@link Span}. Allows
- * overriding the {@link Sampler sampler}, the parent links, and option to record all the events
- * even if the {@code Span} is not sampled.
- */
-@AutoValue
-@Immutable
-public abstract class StartSpanOptions {
-  private static final List<Span> EMPTY_PARENT_LINKS_LIST = Collections.emptyList();
-
-  /** The default {@code StartSpanOptions}. */
-  @VisibleForTesting public static final StartSpanOptions DEFAULT = builder().build();
-
-  /**
-   * Returns the {@link Sampler} to be used, or {@code null} if default.
-   *
-   * @return the {@code Sampler} to be used, or {@code null} if default.
-   */
-  @Nullable
-  public abstract Sampler getSampler();
-
-  /**
-   * Returns the parent links to be set for the {@link Span}.
-   *
-   * @return the parent links to be set for the {@code Span}.
-   */
-  public abstract List<Span> getParentLinks();
-
-  /**
-   * Returns the record events option, or {@code null} if default.
-   *
-   * <p>See {@link Span.Options#RECORD_EVENTS} for more details.
-   *
-   * @return the record events option, or {@code null} if default.
-   */
-  @Nullable
-  public abstract Boolean getRecordEvents();
-
-  /**
-   * Returns a new {@link Builder} with default options.
-   *
-   * @return a new {@code Builder} with default options.
-   */
-  public static Builder builder() {
-    return new AutoValue_StartSpanOptions.Builder().setParentLinks(EMPTY_PARENT_LINKS_LIST);
-  }
-
-  /** Builder class for {@link StartSpanOptions}. */
-  @AutoValue.Builder
-  public abstract static class Builder {
-
-    /**
-     * Sets the {@link Sampler} to be used. If {@code null} the default {@code Sampler} from the
-     * {@link TraceConfig#getActiveTraceParams()} will be used.
-     *
-     * @param sampler the {@link Sampler} to be used.
-     * @return this.
-     */
-    public abstract Builder setSampler(@Nullable Sampler sampler);
-
-    /**
-     * Sets the parent links to be set for the {@link Span}.
-     *
-     * @param parentLinks the parent links to be set for the {@link Span}.
-     * @return this.
-     * @throws NullPointerException if {@code parentLinks} is {@code null}.
-     */
-    public abstract Builder setParentLinks(List<Span> parentLinks);
-
-    /**
-     * Sets the record events option. If {@code null} the default value from the {@link
-     * TraceConfig#getActiveTraceParams()} will be used.
-     *
-     * <p>See {@link Span.Options#RECORD_EVENTS} for more details.
-     *
-     * @param recordEvents the record events option.
-     * @return this.
-     */
-    public abstract Builder setRecordEvents(@Nullable Boolean recordEvents);
-
-    abstract List<Span> getParentLinks(); // not public
-
-    abstract StartSpanOptions autoBuild(); // not public
-
-    /**
-     * Builds and returns a {@code StartSpanOptions} with the desired settings.
-     *
-     * @return a {@code StartSpanOptions} with the desired settings.
-     */
-    public StartSpanOptions build() {
-      setParentLinks(Collections.unmodifiableList(new ArrayList<Span>(getParentLinks())));
-      return autoBuild();
-    }
-  }
-
-  StartSpanOptions() {}
-}
diff --git a/api/src/main/java/io/opencensus/trace/internal/SpanFactory.java b/api/src/main/java/io/opencensus/trace/internal/SpanFactory.java
deleted file mode 100644
index a0306152..00000000
--- a/api/src/main/java/io/opencensus/trace/internal/SpanFactory.java
+++ /dev/null
@@ -1,47 +0,0 @@
-/*
- * 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.trace.internal;
-
-import io.opencensus.trace.Span;
-import io.opencensus.trace.SpanContext;
-import io.opencensus.trace.base.StartSpanOptions;
-import javax.annotation.Nullable;
-
-/** Factory class to create and start a {@link Span}. */
-public abstract class SpanFactory {
-  /**
-   * Creates and starts a new child {@link Span} (or root if parent is {@code null}), with parent
-   * being the designated {@code Span} and the given options.
-   *
-   * @param parent The parent of the returned {@code Span}.
-   * @param name The name of the returned {@code Span}.
-   * @param options The options for the start of the {@code Span}.
-   * @return A child {@code Span} that will have the name provided.
-   */
-  public abstract Span startSpan(@Nullable Span parent, String name, StartSpanOptions options);
-
-  /**
-   * Creates and starts a new child {@link Span} (or root if parent is {@code null}), with parent
-   * being the {@code Span} designated by the {@link SpanContext} and the given options.
-   *
-   * <p>This must be used to create a {@code Span} when the parent is on a different process.
-   *
-   * @param remoteParent The remote parent of the returned {@code Span}.
-   * @param name The name of the returned {@code Span}.
-   * @param options The options for the start of the {@code Span}.
-   * @return A child {@code Span} that will have the name provided.
-   */
-  public abstract Span startSpanWithRemoteParent(
-      @Nullable SpanContext remoteParent, String name, StartSpanOptions options);
-}