Add MessageEvent and deprecate NetworkEvent. (closes #858) (#894)

Author: HailongWen

api/src/main/java/io/opencensus/internal/BaseMessageEventUtil.java

@@ -0,0 +1,80 @@
+/*
+ * 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.internal;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import io.opencensus.trace.MessageEvent;
+
+/**
+ * Helper class to convert/cast between for {@link MessageEvent} and {@link NetworkEvent}.
+ *
+ * @since 0.12
+ */
+@SuppressWarnings("deprecation")
+public final class BaseMessageEventUtil {
+  /**
+   * Cast or convert a {@link io.opencensus.trace.BaseMessageEvent} to {@link MessageEvent}.
+   *
+   * <p>Warning: if the input is a {@code io.opencensus.trace.NetworkEvent} and contains {@code
+   * kernelTimestamp} information, this information will be dropped.
+   *
+   * @param event the {@code BaseMessageEvent} that is being cast or converted.
+   * @return a {@code MessageEvent} representation of the input.
+   */
+  public static MessageEvent asMessageEvent(io.opencensus.trace.BaseMessageEvent event) {
+    checkNotNull(event);
+    if (event instanceof MessageEvent) {
+      return (MessageEvent) event;
+    }
+    io.opencensus.trace.NetworkEvent networkEvent = (io.opencensus.trace.NetworkEvent) event;
+    MessageEvent.Type type =
+        (networkEvent.getType() == io.opencensus.trace.NetworkEvent.Type.RECV)
+            ? MessageEvent.Type.RECEIVED
+            : MessageEvent.Type.SENT;
+    return MessageEvent.builder(type, networkEvent.getMessageId())
+        .setUncompressedMessageSize(networkEvent.getUncompressedMessageSize())
+        .setCompressedMessageSize(networkEvent.getCompressedMessageSize())
+        .build();
+  }
+
+  /**
+   * Cast or convert a {@link io.opencensus.trace.BaseMessageEvent} to {@link
+   * io.opencensus.trace.NetworkEvent}.
+   *
+   * @param event the {@code BaseMessageEvent} that is being cast or converted.
+   * @return a {@code io.opencensus.trace.NetworkEvent} representation of the input.
+   */
+  public static io.opencensus.trace.NetworkEvent asNetworkEvent(
+      io.opencensus.trace.BaseMessageEvent event) {
+    checkNotNull(event);
+    if (event instanceof io.opencensus.trace.NetworkEvent) {
+      return (io.opencensus.trace.NetworkEvent) event;
+    }
+    MessageEvent messageEvent = (MessageEvent) event;
+    io.opencensus.trace.NetworkEvent.Type type =
+        (messageEvent.getType() == MessageEvent.Type.RECEIVED)
+            ? io.opencensus.trace.NetworkEvent.Type.RECV
+            : io.opencensus.trace.NetworkEvent.Type.SENT;
+    return io.opencensus.trace.NetworkEvent.builder(type, messageEvent.getMessageId())
+        .setUncompressedMessageSize(messageEvent.getUncompressedMessageSize())
+        .setCompressedMessageSize(messageEvent.getCompressedMessageSize())
+        .build();
+  }
+
+  private BaseMessageEventUtil() {}
+}

api/src/main/java/io/opencensus/trace/BaseMessageEvent.java

@@ -0,0 +1,37 @@
+/*
+ * 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.trace;
+
+/**
+ * Superclass for {@link MessageEvent} and {@link NetworkEvent} to resolve API backward
+ * compatibility issue.
+ *
+ * <p>{@code SpanData.create} can't be overloaded with parameter types that differ only in the type
+ * of the TimedEvent, because the signatures are the same after generic type erasure. {@code
+ * BaseMessageEvent} allows the same method to accept both {@code TimedEvents<NetworkEvent>} and
+ * {@code TimedEvents<MessageEvent>}.
+ *
+ * <p>This class should only be extended by {@code NetworkEvent} and {@code MessageEvent}.
+ *
+ * @deprecated This class is for internal use only.
+ * @since 0.12
+ */
+@Deprecated
+public abstract class BaseMessageEvent {
+  // package protected to avoid users to extend it.
+  BaseMessageEvent() {}
+}

api/src/main/java/io/opencensus/trace/BlankSpan.java

@@ -58,8 +58,13 @@ public void addAnnotation(Annotation annotation) {}
 
   /** No-op implementation of the {@link Span#addNetworkEvent(NetworkEvent)} method. */
   @Override
+  @Deprecated
   public void addNetworkEvent(NetworkEvent networkEvent) {}
 
+  /** No-op implementation of the {@link Span#addMessageEvent(MessageEvent)} method. */
+  @Override
+  public void addMessageEvent(MessageEvent messageEvent) {}
+
   /** No-op implementation of the {@link Span#addLink(Link)} method. */
   @Override
   public void addLink(Link link) {}

api/src/main/java/io/opencensus/trace/MessageEvent.java

@@ -0,0 +1,154 @@
+/*
+ * 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.trace;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.auto.value.AutoValue;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * A class that represents a generic messaging event. This class can represent messaging happened in
+ * any layer, especially higher application layer. Thus, it can be used when recording events in
+ * pipeline works, in-process bidirectional streams and batch processing.
+ *
+ * <p>It requires a {@link Type type} and a message id that serves to uniquely identify each
+ * message. It can optionally have information about the message size.
+ *
+ * @since 0.12
+ */
+@Immutable
+@AutoValue
+// Suppress Checker Framework warning about missing @Nullable in generated equals method.
+@AutoValue.CopyAnnotations
+@SuppressWarnings({"nullness", "deprecation"})
+public abstract class MessageEvent extends BaseMessageEvent {
+  /**
+   * Available types for a {@code MessageEvent}.
+   *
+   * @since 0.12
+   */
+  public enum Type {
+    /**
+     * When the message was sent.
+     *
+     * @since 0.12
+     */
+    SENT,
+    /**
+     * When the message was received.
+     *
+     * @since 0.12
+     */
+    RECEIVED,
+  }
+
+  /**
+   * Returns a new {@link Builder} with default values.
+   *
+   * @param type designates whether this is a send or receive message.
+   * @param messageId serves to uniquely identify each message.
+   * @return a new {@code Builder} with default values.
+   * @throws NullPointerException if {@code type} is {@code null}.
+   * @since 0.12
+   */
+  public static Builder builder(Type type, long messageId) {
+    return new AutoValue_MessageEvent.Builder()
+        .setType(checkNotNull(type, "type"))
+        .setMessageId(messageId)
+        // We need to set a value for the message size because the autovalue requires all
+        // primitives to be initialized.
+        .setUncompressedMessageSize(0)
+        .setCompressedMessageSize(0);
+  }
+
+  /**
+   * Returns the type of the {@code MessageEvent}.
+   *
+   * @return the type of the {@code MessageEvent}.
+   * @since 0.12
+   */
+  public abstract Type getType();
+
+  /**
+   * Returns the message id argument that serves to uniquely identify each message.
+   *
+   * @return the message id of the {@code MessageEvent}.
+   * @since 0.12
+   */
+  public abstract long getMessageId();
+
+  /**
+   * Returns the uncompressed size in bytes of the {@code MessageEvent}.
+   *
+   * @return the uncompressed size in bytes of the {@code MessageEvent}.
+   * @since 0.12
+   */
+  public abstract long getUncompressedMessageSize();
+
+  /**
+   * Returns the compressed size in bytes of the {@code MessageEvent}.
+   *
+   * @return the compressed size in bytes of the {@code MessageEvent}.
+   * @since 0.12
+   */
+  public abstract long getCompressedMessageSize();
+
+  /**
+   * Builder class for {@link MessageEvent}.
+   *
+   * @since 0.12
+   */
+  @AutoValue.Builder
+  public abstract static class Builder {
+    // Package protected methods because these values are mandatory and set only in the
+    // MessageEvent#builder() function.
+    abstract Builder setType(Type type);
+
+    abstract Builder setMessageId(long messageId);
+
+    /**
+     * Sets the uncompressed message size.
+     *
+     * @param uncompressedMessageSize represents the uncompressed size in bytes of this message.
+     * @return this.
+     * @since 0.12
+     */
+    public abstract Builder setUncompressedMessageSize(long uncompressedMessageSize);
+
+    /**
+     * Sets the compressed message size.
+     *
+     * @param compressedMessageSize represents the compressed size in bytes of this message.
+     * @return this.
+     * @since 0.12
+     */
+    public abstract Builder setCompressedMessageSize(long compressedMessageSize);
+
+    /**
+     * Builds and returns a {@code MessageEvent} with the desired values.
+     *
+     * @return a {@code MessageEvent} with the desired values.
+     * @since 0.12
+     */
+    public abstract MessageEvent build();
+
+    Builder() {}
+  }
+
+  MessageEvent() {}
+}

api/src/main/java/io/opencensus/trace/NetworkEvent.java

@@ -28,14 +28,16 @@
  * serves to uniquely identify each network message. It can optionally can have information about
  * the kernel time and message size.
  *
+ * @deprecated Use {@link MessageEvent}.
  * @since 0.5
  */
 @Immutable
 @AutoValue
 // Suppress Checker Framework warning about missing @Nullable in generated equals method.
 @AutoValue.CopyAnnotations
 @SuppressWarnings("nullness")
-public abstract class NetworkEvent {
+@Deprecated
+public abstract class NetworkEvent extends io.opencensus.trace.BaseMessageEvent {
   /**
    * Available types for a {@code NetworkEvent}.
    *
@@ -131,9 +133,12 @@ public long getMessageSize() {
   /**
    * Builder class for {@link NetworkEvent}.
    *
+   * @deprecated {@link NetworkEvent} is deprecated. Please use {@link MessageEvent} and its builder
+   *     {@link MessageEvent.Builder}.
    * @since 0.5
    */
   @AutoValue.Builder
+  @Deprecated
   public abstract static class Builder {
     // Package protected methods because these values are mandatory and set only in the
     // NetworkEvent#builder() function.

api/src/main/java/io/opencensus/trace/Span.java

@@ -19,6 +19,7 @@
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkNotNull;
 
+import io.opencensus.internal.BaseMessageEventUtil;
 import java.util.Collections;
 import java.util.EnumSet;
 import java.util.Map;
@@ -159,9 +160,30 @@ public final void addAnnotation(String description) {
    * higher level applications.
    *
    * @param networkEvent the network event to add.
+   * @deprecated Use {@link #addMessageEvent}.
    * @since 0.5
    */
-  public abstract void addNetworkEvent(NetworkEvent networkEvent);
+  @Deprecated
+  public void addNetworkEvent(NetworkEvent networkEvent) {
+    addMessageEvent(BaseMessageEventUtil.asMessageEvent(networkEvent));
+  }
+
+  /**
+   * Adds a MessageEvent to the {@code Span}.
+   *
+   * <p>This function can be used by higher level applications to record messaging event.
+   *
+   * <p>This method should always be overridden by users whose API versions are larger or equal to
+   * {@code 0.12}.
+   *
+   * @param messageEvent the message to add.
+   * @since 0.12
+   */
+  public void addMessageEvent(MessageEvent messageEvent) {
+    // Default implementation by invoking addNetworkEvent() so that any existing derived classes,
+    // including implementation and the mocked ones, do not need to override this method explicitly.
+    addNetworkEvent(BaseMessageEventUtil.asNetworkEvent(messageEvent));
+  }
 
   /**
    * Adds a {@link Link} to the {@code Span}.