Make public API setters fluent (#294)

elastic · Dec 13, 2018 · f2a89b3 · f2a89b3
1 parent dea72f3
commit f2a89b3
Show file tree

Hide file tree

Showing 15 changed files with 421 additions and 116 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@
  * Added `capture_headers` configuration option.
    Set to `false` to disable capturing request and response headers.
    This will reduce the allocation rate of the agent and can save you network bandwidth and disk space.
+ * Makes the API methods `addTag`, `setName`, `setType`, `setUser` and `setResult` fluent, so that calls can be chained. 
 
 ## Bug Fixes
 

diff --git a/apm-agent-api/src/main/java/co/elastic/apm/api/AbstractSpanImpl.java b/apm-agent-api/src/main/java/co/elastic/apm/api/AbstractSpanImpl.java
@@ -0,0 +1,73 @@
+package co.elastic.apm.api;
+
+import javax.annotation.Nonnull;
+
+public abstract class AbstractSpanImpl implements Span {
+    @Nonnull
+    // co.elastic.apm.impl.transaction.AbstractSpan
+    protected final Object span;
+
+    AbstractSpanImpl(@Nonnull Object span) {
+        this.span = span;
+    }
+
+    @Nonnull
+    @Override
+    public Span createSpan() {
+        Object span = doCreateSpan();
+        return span != null ? new SpanImpl(span) : NoopSpan.INSTANCE;
+    }
+
+    private Object doCreateSpan() {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation$DoCreateSpanInstrumentation.doCreateSpan
+        return null;
+    }
+
+    void doSetName(String name) {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation$SetNameInstrumentation.doSetName
+    }
+
+    void doSetType(String type) {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation$SetTypeInstrumentation.doSetType
+    }
+
+    void doAddTag(String key, String value) {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation$AddTagInstrumentation.doAddTag
+    }
+
+    @Override
+    public void end() {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation$EndInstrumentation.end
+    }
+
+    @Override
+    public void captureException(Throwable throwable) {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation.CaptureExceptionInstrumentation
+    }
+
+    @Nonnull
+    @Override
+    public String getId() {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation.GetIdInstrumentation
+        return "";
+    }
+
+    @Nonnull
+    @Override
+    public String getTraceId() {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation.GetTraceIdInstrumentation
+        return "";
+    }
+
+    @Override
+    public Scope activate() {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation.ActivateInstrumentation
+        return new ScopeImpl(span);
+    }
+
+    @Override
+    public boolean isSampled() {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation.IsSampledInstrumentation
+        return false;
+    }
+}
diff --git a/apm-agent-api/src/main/java/co/elastic/apm/api/NoopSpan.java b/apm-agent-api/src/main/java/co/elastic/apm/api/NoopSpan.java
@@ -24,19 +24,25 @@
 enum NoopSpan implements Span {
     INSTANCE;
 
+    @Nonnull
     @Override
-    public void setName(String name) {
+    public Span setName(String name) {
         // noop
+        return this;
     }
 
+    @Nonnull
     @Override
-    public void setType(String type) {
+    public Span setType(String type) {
         // noop
+        return this;
     }
 
+    @Nonnull
     @Override
-    public void addTag(String key, String value) {
+    public Span addTag(String key, String value) {
         // noop
+        return this;
     }
 
     @Override
@@ -66,6 +72,7 @@ public Scope activate() {
         return NoopScope.INSTANCE;
     }
 
+    @Nonnull
     @Override
     public boolean isSampled() {
         return false;

diff --git a/apm-agent-api/src/main/java/co/elastic/apm/api/NoopTransaction.java b/apm-agent-api/src/main/java/co/elastic/apm/api/NoopTransaction.java
@@ -25,29 +25,37 @@ enum NoopTransaction implements Transaction {
 
     INSTANCE;
 
+    @Nonnull
     @Override
-    public void setName(String name) {
+    public Transaction setName(String name) {
         // noop
+        return this;
     }
 
+    @Nonnull
     @Override
-    public void setType(String type) {
+    public Transaction setType(String type) {
         // noop
+        return this;
     }
 
+    @Nonnull
     @Override
-    public void addTag(String key, String value) {
+    public Transaction addTag(String key, String value) {
         // noop
+        return this;
     }
 
     @Override
-    public void setUser(String id, String email, String username) {
+    public Transaction setUser(String id, String email, String username) {
         // noop
+        return this;
     }
 
     @Override
-    public void setResult(String result) {
+    public Transaction setResult(String result) {
         // noop
+        return this;
     }
 
     @Override
@@ -83,6 +91,7 @@ public Scope activate() {
         return NoopScope.INSTANCE;
     }
 
+    @Nonnull
     @Override
     public boolean isSampled() {
         return false;

diff --git a/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java b/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java
@@ -46,7 +46,8 @@ public interface Span {
      *
      * @param name the name of the span
      */
-    void setName(String name);
+    @Nonnull
+    Span setName(String name);
 
     /**
      * Sets the type of span.
@@ -61,7 +62,8 @@ public interface Span {
      *
      * @param type the type of the span
      */
-    void setType(String type);
+    @Nonnull
+    Span setType(String type);
 
     /**
      * A flat mapping of user-defined tags with string values.
@@ -76,7 +78,8 @@ public interface Span {
      * @param key   The tag key.
      * @param value The tag value.
      */
-    void addTag(String key, String value);
+    @Nonnull
+    Span addTag(String key, String value);
 
     /**
      * Start and return a new custom span as a child of this span.
@@ -105,6 +108,7 @@ public interface Span {
      *
      * @return the started span, never {@code null}
      */
+    @Nonnull
     Span createSpan();
 
     /**

diff --git a/apm-agent-api/src/main/java/co/elastic/apm/api/SpanImpl.java b/apm-agent-api/src/main/java/co/elastic/apm/api/SpanImpl.java
@@ -22,83 +22,36 @@
 import javax.annotation.Nonnull;
 
 /**
- * If the agent is active, it injects the implementation from
- * co.elastic.apm.agent.plugin.api.SpanInstrumentation
- * into this class.
+ * If the agent is active, it injects the implementation into this class.
  * <p>
  * Otherwise, this class is a noop.
  * </p>
  */
-class SpanImpl implements Span {
-
-    @Nonnull
-    // co.elastic.apm.agent.impl.transaction.AbstractSpan
-    protected final Object span;
+class SpanImpl extends AbstractSpanImpl {
 
     SpanImpl(@Nonnull Object span) {
-        this.span = span;
-    }
-
-    @Override
-    public void setName(String name) {
-        // co.elastic.apm.agent.plugin.api.SpanInstrumentation$SetNameInstrumentation.setName
-    }
-
-    @Override
-    public void setType(String type) {
-        // co.elastic.apm.agent.plugin.api.SpanInstrumentation$SetTypeInstrumentation.setType
-    }
-
-    @Override
-    public void addTag(String key, String value) {
-        // co.elastic.apm.agent.plugin.api.SpanInstrumentation$AddTagInstrumentation.addTag
-    }
-
-    @Override
-    public Span createSpan() {
-        Object span = doCreateSpan();
-        return span != null ? new SpanImpl(span) : NoopSpan.INSTANCE;
-    }
-
-    private Object doCreateSpan() {
-        // co.elastic.apm.agent.plugin.api.SpanInstrumentation$DoCreateSpanInstrumentation.doCreateSpan
-        return null;
-    }
-
-    @Override
-    public void end() {
-        // co.elastic.apm.agent.plugin.api.SpanInstrumentation$EndInstrumentation.end
-    }
-
-    @Override
-    public void captureException(Throwable throwable) {
-        // co.elastic.apm.agent.plugin.api.SpanInstrumentation.CaptureExceptionInstrumentation
+        super(span);
     }
 
     @Nonnull
     @Override
-    public String getId() {
-        // co.elastic.apm.agent.plugin.api.SpanInstrumentation.GetIdInstrumentation
-        return "";
+    public Span setName(String name) {
+        doSetName(name);
+        return this;
     }
 
     @Nonnull
     @Override
-    public String getTraceId() {
-        // co.elastic.apm.agent.plugin.api.SpanInstrumentation.GetTraceIdInstrumentation
-        return "";
-    }
-
-    @Override
-    public Scope activate() {
-        // co.elastic.apm.agent.plugin.api.SpanInstrumentation.ActivateInstrumentation
-        return new ScopeImpl(span);
+    public Span setType(String type) {
+        doSetType(type);
+        return this;
     }
 
+    @Nonnull
     @Override
-    public boolean isSampled() {
-        // co.elastic.apm.agent.plugin.api.SpanInstrumentation.IsSampledInstrumentation
-        return false;
+    public Span addTag(String key, String value) {
+        doAddTag(key, value);
+        return this;
     }
 
 }
diff --git a/apm-agent-api/src/main/java/co/elastic/apm/api/Transaction.java b/apm-agent-api/src/main/java/co/elastic/apm/api/Transaction.java
@@ -42,7 +42,8 @@ public interface Transaction extends Span {
      *
      * @param name A string describing name of the transaction.
      */
-    void setName(String name);
+    @Nonnull
+    Transaction setName(String name);
 
     /**
      * The type of the transaction.
@@ -54,7 +55,11 @@ public interface Transaction extends Span {
      *
      * @param type The type of the transaction.
      */
-    void setType(String type);
+    @Nonnull
+    Transaction setType(String type);
+
+    @Nonnull
+    Transaction addTag(String key, String value);
 
     /**
      * Call this to enrich collected performance data and errors with information about the user/client.
@@ -70,15 +75,15 @@ public interface Transaction extends Span {
      * @param email    The user's email address or {@code null}, if not applicable.
      * @param username The user's name or {@code null}, if not applicable.
      */
-    void setUser(String id, String email, String username);
+    Transaction setUser(String id, String email, String username);
 
     /**
      * A string describing the result of the transaction.
      * This is typically the HTTP status code, or e.g. "success" for a background task
      *
      * @param result a string describing the result of the transaction
      */
-    void setResult(String result);
+    Transaction setResult(String result);
 
     /**
      * End tracking the transaction.
@@ -111,6 +116,7 @@ public interface Transaction extends Span {
      *
      * @return the started span, never {@code null}
      */
+    @Nonnull
     Span createSpan();
 
     /**