Add a configuration class to help to create StackdriverTraceExporter. (closes #949) (#990)

5 files changed, 191 insertions, 58 deletions

diff --git a/exporters/trace/stackdriver/build.gradle b/exporters/trace/stackdriver/build.gradle
index b495b424..fa486561 100644
--- a/exporters/trace/stackdriver/build.gradle
+++ b/exporters/trace/stackdriver/build.gradle
@@ -6,6 +6,8 @@ description = 'OpenCensus Trace Stackdriver Exporter'
 }
 
 dependencies {
+    compileOnly libraries.auto_value
+
     compile project(':opencensus-api'),
             libraries.google_auth
 
@@ -23,4 +25,4 @@ dependencies {
     testCompile project(':opencensus-api')
 
     signature "org.codehaus.mojo.signature:java17:+@signature"
-}
\ No newline at end of file
+}
diff --git a/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverExporter.java b/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverExporter.java
index fb09d76a..8797cc77 100644
--- a/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverExporter.java
+++ b/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverExporter.java
@@ -54,7 +54,11 @@ public final class StackdriverExporter {
    */
   public static void createAndRegisterWithCredentialsAndProjectId(
       Credentials credentials, String projectId) throws IOException {
-    StackdriverTraceExporter.createAndRegisterWithCredentialsAndProjectId(credentials, projectId);
+    StackdriverTraceExporter.createAndRegister(
+        StackdriverTraceConfiguration.builder()
+            .setCredentials(credentials)
+            .setProjectId(projectId)
+            .build());
   }
 
   /**
@@ -76,7 +80,11 @@ public final class StackdriverExporter {
    * @since 0.6
    */
   public static void createAndRegisterWithProjectId(String projectId) throws IOException {
-    StackdriverTraceExporter.createAndRegisterWithProjectId(projectId);
+    StackdriverTraceExporter.createAndRegister(
+        StackdriverTraceConfiguration.builder()
+            .setCredentials(GoogleCredentials.getApplicationDefault())
+            .setProjectId(projectId)
+            .build());
   }
 
   /**
@@ -98,7 +106,11 @@ public final class StackdriverExporter {
    * @since 0.6
    */
   public static void createAndRegister() throws IOException {
-    StackdriverTraceExporter.createAndRegister();
+    StackdriverTraceExporter.createAndRegister(
+        StackdriverTraceConfiguration.builder()
+            .setCredentials(GoogleCredentials.getApplicationDefault())
+            .setProjectId(ServiceOptions.getDefaultProjectId())
+            .build());
   }
 
   /**
diff --git a/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverTraceConfiguration.java b/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverTraceConfiguration.java
new file mode 100644
index 00000000..88613724
--- /dev/null
+++ b/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverTraceConfiguration.java
@@ -0,0 +1,102 @@
+/*
+ * Copyright 2018, OpenCensus 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.opencensus.exporter.trace.stackdriver;
+
+import com.google.auth.Credentials;
+import com.google.auto.value.AutoValue;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * Configurations for {@link StackdriverTraceExporter}.
+ *
+ * @since 0.12
+ */
+@AutoValue
+@Immutable
+// Suppress Checker Framework warning about missing @Nullable in generated equals method.
+@AutoValue.CopyAnnotations
+@SuppressWarnings("nullness")
+public abstract class StackdriverTraceConfiguration {
+
+  StackdriverTraceConfiguration() {}
+
+  /**
+   * Returns the {@link Credentials}.
+   *
+   * @return the {@code Credentials}.
+   * @since 0.12
+   */
+  @Nullable
+  public abstract Credentials getCredentials();
+
+  /**
+   * Returns the cloud project id.
+   *
+   * @return the cloud project id.
+   * @since 0.12
+   */
+  @Nullable
+  public abstract String getProjectId();
+
+  /**
+   * Returns a new {@link Builder}.
+   *
+   * @return a {@code Builder}.
+   * @since 0.12
+   */
+  public static Builder builder() {
+    return new AutoValue_StackdriverTraceConfiguration.Builder();
+  }
+
+  /**
+   * Builder for {@link StackdriverTraceConfiguration}.
+   *
+   * @since 0.12
+   */
+  @AutoValue.Builder
+  public abstract static class Builder {
+
+    Builder() {}
+
+    /**
+     * Sets the {@link Credentials} used to authenticate API calls.
+     *
+     * @param credentials the {@code Credentials}.
+     * @return this.
+     * @since 0.12
+     */
+    public abstract Builder setCredentials(Credentials credentials);
+
+    /**
+     * Sets the cloud project id.
+     *
+     * @param projectId the cloud project id.
+     * @return this.
+     * @since 0.12
+     */
+    public abstract Builder setProjectId(String projectId);
+
+    /**
+     * Builds a {@link StackdriverTraceConfiguration}.
+     *
+     * @return a {@code StackdriverTraceConfiguration}.
+     * @since 0.12
+     */
+    public abstract StackdriverTraceConfiguration build();
+  }
+}
diff --git a/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverTraceExporter.java b/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverTraceExporter.java
index 303adee8..566bebc8 100644
--- a/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverTraceExporter.java
+++ b/exporters/trace/stackdriver/src/main/java/io/opencensus/exporter/trace/stackdriver/StackdriverTraceExporter.java
@@ -36,7 +36,10 @@ import javax.annotation.concurrent.GuardedBy;
  *
  * <pre>{@code
  * public static void main(String[] args) {
- *   StackdriverTraceExporter.createAndRegisterWithProjectId("MyStackdriverProjectId");
+ *   StackdriverTraceExporter.createAndRegister(
+ *       StackdriverTraceConfiguration.builder()
+ *           .setProjectId("MyStackdriverProjectId")
+ *           .build());
  *   ... // Do work.
  * }
  * }</pre>
@@ -53,70 +56,30 @@ public final class StackdriverTraceExporter {
   private static Handler handler = null;
 
   /**
-   * Creates and registers the Stackdriver Trace exporter to the OpenCensus library for an explicit
-   * project ID and using explicit credentials. Only one Stackdriver exporter can be registered at
-   * any point.
-   *
-   * @param credentials a credentials used to authenticate API calls.
-   * @param projectId the cloud project id.
-   * @throws IllegalStateException if a Stackdriver exporter is already registered.
-   * @since 0.12
-   */
-  public static void createAndRegisterWithCredentialsAndProjectId(
-      Credentials credentials, String projectId) throws IOException {
-    synchronized (monitor) {
-      checkState(handler == null, "Stackdriver exporter is already registered.");
-      registerInternal(StackdriverV2ExporterHandler.createWithCredentials(credentials, projectId));
-    }
-  }
-
-  /**
-   * Creates and registers the Stackdriver Trace exporter to the OpenCensus library for an explicit
-   * project ID. Only one Stackdriver exporter can be registered at any point.
-   *
-   * <p>This uses the default application credentials see {@link
-   * GoogleCredentials#getApplicationDefault}.
-   *
-   * <p>This is equivalent with:
-   *
-   * <pre>{@code
-   * StackdriverTraceExporter.createAndRegisterWithCredentialsAndProjectId(
-   *     GoogleCredentials.getApplicationDefault(), projectId);
-   * }</pre>
-   *
-   * @param projectId the cloud project id.
-   * @throws IllegalStateException if a Stackdriver exporter is already registered.
-   * @since 0.12
-   */
-  public static void createAndRegisterWithProjectId(String projectId) throws IOException {
-    synchronized (monitor) {
-      checkState(handler == null, "Stackdriver exporter is already registered.");
-      registerInternal(StackdriverV2ExporterHandler.create(projectId));
-    }
-  }
-
-  /**
    * Creates and registers the Stackdriver Trace exporter to the OpenCensus library. Only one
    * Stackdriver exporter can be registered at any point.
    *
-   * <p>This uses the default application credentials see {@link
+   * <p>If the {@code credentials} in the provided {@link StackdriverTraceConfiguration} is not set,
+   * the exporter will use the default application credentials. See {@link
    * GoogleCredentials#getApplicationDefault}.
    *
-   * <p>This uses the default project ID configured see {@link ServiceOptions#getDefaultProjectId}.
-   *
-   * <p>This is equivalent with:
-   *
-   * <pre>{@code
-   * StackdriverTraceExporter.createAndRegisterWithProjectId(ServiceOptions.getDefaultProjectId());
-   * }</pre>
+   * <p>If the {@code projectId} in the provided {@link StackdriverTraceConfiguration} is not set,
+   * the exporter will use the default project ID. See {@link ServiceOptions#getDefaultProjectId}.
    *
+   * @param configuration the {@code StackdriverTraceConfiguration} used to create the exporter.
    * @throws IllegalStateException if a Stackdriver exporter is already registered.
    * @since 0.12
    */
-  public static void createAndRegister() throws IOException {
+  public static void createAndRegister(StackdriverTraceConfiguration configuration)
+      throws IOException {
     synchronized (monitor) {
       checkState(handler == null, "Stackdriver exporter is already registered.");
-      registerInternal(StackdriverV2ExporterHandler.create(ServiceOptions.getDefaultProjectId()));
+      Credentials credentials = configuration.getCredentials();
+      String projectId = configuration.getProjectId();
+      registerInternal(
+          StackdriverV2ExporterHandler.createWithCredentials(
+              credentials != null ? credentials : GoogleCredentials.getApplicationDefault(),
+              projectId != null ? projectId : ServiceOptions.getDefaultProjectId()));
     }
   }
 
diff --git a/exporters/trace/stackdriver/src/test/java/io/opencensus/exporter/trace/stackdriver/StackdriverTraceConfigurationTest.java b/exporters/trace/stackdriver/src/test/java/io/opencensus/exporter/trace/stackdriver/StackdriverTraceConfigurationTest.java
new file mode 100644
index 00000000..6926e869
--- /dev/null
+++ b/exporters/trace/stackdriver/src/test/java/io/opencensus/exporter/trace/stackdriver/StackdriverTraceConfigurationTest.java
@@ -0,0 +1,54 @@
+/*
+ * Copyright 2018, OpenCensus 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.opencensus.exporter.trace.stackdriver;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.auth.Credentials;
+import com.google.auth.oauth2.AccessToken;
+import com.google.auth.oauth2.GoogleCredentials;
+import java.util.Date;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Unit tests for {@link StackdriverTraceConfiguration}. */
+@RunWith(JUnit4.class)
+public class StackdriverTraceConfigurationTest {
+
+  private static final Credentials FAKE_CREDENTIALS =
+      GoogleCredentials.newBuilder().setAccessToken(new AccessToken("fake", new Date(100))).build();
+  private static final String PROJECT_ID = "project";
+
+  @Test
+  public void defaultConfiguration() {
+    StackdriverTraceConfiguration configuration = StackdriverTraceConfiguration.builder().build();
+    assertThat(configuration.getCredentials()).isNull();
+    assertThat(configuration.getProjectId()).isNull();
+  }
+
+  @Test
+  public void updateAll() {
+    StackdriverTraceConfiguration configuration =
+        StackdriverTraceConfiguration.builder()
+            .setCredentials(FAKE_CREDENTIALS)
+            .setProjectId(PROJECT_ID)
+            .build();
+    assertThat(configuration.getCredentials()).isEqualTo(FAKE_CREDENTIALS);
+    assertThat(configuration.getProjectId()).isEqualTo(PROJECT_ID);
+  }
+}