1 files changed, 124 insertions, 0 deletions
diff --git a/api/src/main/java/io/opencensus/trace/Link.java b/api/src/main/java/io/opencensus/trace/Link.java
new file mode 100644
index 00000000..1de79710
--- /dev/null
+++ b/api/src/main/java/io/opencensus/trace/Link.java
@@ -0,0 +1,124 @@
+/*
+ * Copyright 2017, 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.trace;
+
+import com.google.auto.value.AutoValue;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * A link to a {@link Span} from a different trace.
+ *
+ * <p>It requires a {@link Type} which describes the relationship with the linked {@code Span} and
+ * the identifiers of the linked {@code Span}.
+ *
+ * <p>Used (for example) in batching operations, where a single batch handler processes multiple
+ * requests from different traces.
+ *
+ * @since 0.5
+ */
+@Immutable
+@AutoValue
+public abstract class Link {
+  private static final Map<String, AttributeValue> EMPTY_ATTRIBUTES = Collections.emptyMap();
+
+  /**
+   * The relationship with the linked {@code Span} relative to the current {@code Span}.
+   *
+   * @since 0.5
+   */
+  public enum Type {
+    /**
+     * When the linked {@code Span} is a child of the current {@code Span}.
+     *
+     * @since 0.5
+     */
+    CHILD_LINKED_SPAN,
+    /**
+     * When the linked {@code Span} is a parent of the current {@code Span}.
+     *
+     * @since 0.5
+     */
+    PARENT_LINKED_SPAN
+  }
+
+  /**
+   * Returns a new {@code Link}.
+   *
+   * @param context the context of the linked {@code Span}.
+   * @param type the type of the relationship with the linked {@code Span}.
+   * @return a new {@code Link}.
+   * @since 0.5
+   */
+  public static Link fromSpanContext(SpanContext context, Type type) {
+    return new AutoValue_Link(context.getTraceId(), context.getSpanId(), type, EMPTY_ATTRIBUTES);
+  }
+
+  /**
+   * Returns a new {@code Link}.
+   *
+   * @param context the context of the linked {@code Span}.
+   * @param type the type of the relationship with the linked {@code Span}.
+   * @param attributes the attributes of the {@code Link}.
+   * @return a new {@code Link}.
+   * @since 0.5
+   */
+  public static Link fromSpanContext(
+      SpanContext context, Type type, Map<String, AttributeValue> attributes) {
+    return new AutoValue_Link(
+        context.getTraceId(),
+        context.getSpanId(),
+        type,
+        Collections.unmodifiableMap(new HashMap<String, AttributeValue>(attributes)));
+  }
+
+  /**
+   * Returns the {@code TraceId}.
+   *
+   * @return the {@code TraceId}.
+   * @since 0.5
+   */
+  public abstract TraceId getTraceId();
+
+  /**
+   * Returns the {@code SpanId}.
+   *
+   * @return the {@code SpanId}
+   * @since 0.5
+   */
+  public abstract SpanId getSpanId();
+
+  /**
+   * Returns the {@code Type}.
+   *
+   * @return the {@code Type}.
+   * @since 0.5
+   */
+  public abstract Type getType();
+
+  /**
+   * Returns the set of attributes.
+   *
+   * @return the set of attributes.
+   * @since 0.5
+   */
+  public abstract Map<String, AttributeValue> getAttributes();
+
+  Link() {}
+}