1 /*
2  * Copyright 2018, OpenCensus Authors
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package io.opencensus.trace;
18 
19 import com.google.auto.value.AutoValue;
20 import io.opencensus.internal.Utils;
21 import javax.annotation.concurrent.Immutable;
22 
23 /**
24  * A class that represents a generic messaging event. This class can represent messaging happened in
25  * any layer, especially higher application layer. Thus, it can be used when recording events in
26  * pipeline works, in-process bidirectional streams and batch processing.
27  *
28  * <p>It requires a {@link Type type} and a message id that serves to uniquely identify each
29  * message. It can optionally have information about the message size.
30  *
31  * @since 0.12
32  */
33 @Immutable
34 @AutoValue
35 @SuppressWarnings("deprecation")
36 public abstract class MessageEvent extends BaseMessageEvent {
37   /**
38    * Available types for a {@code MessageEvent}.
39    *
40    * @since 0.12
41    */
42   public enum Type {
43     /**
44      * When the message was sent.
45      *
46      * @since 0.12
47      */
48     SENT,
49     /**
50      * When the message was received.
51      *
52      * @since 0.12
53      */
54     RECEIVED,
55   }
56 
57   /**
58    * Returns a new {@link Builder} with default values.
59    *
60    * @param type designates whether this is a send or receive message.
61    * @param messageId serves to uniquely identify each message.
62    * @return a new {@code Builder} with default values.
63    * @throws NullPointerException if {@code type} is {@code null}.
64    * @since 0.12
65    */
builder(Type type, long messageId)66   public static Builder builder(Type type, long messageId) {
67     return new AutoValue_MessageEvent.Builder()
68         .setType(Utils.checkNotNull(type, "type"))
69         .setMessageId(messageId)
70         // We need to set a value for the message size because the autovalue requires all
71         // primitives to be initialized.
72         .setUncompressedMessageSize(0)
73         .setCompressedMessageSize(0);
74   }
75 
76   /**
77    * Returns the type of the {@code MessageEvent}.
78    *
79    * @return the type of the {@code MessageEvent}.
80    * @since 0.12
81    */
getType()82   public abstract Type getType();
83 
84   /**
85    * Returns the message id argument that serves to uniquely identify each message.
86    *
87    * @return the message id of the {@code MessageEvent}.
88    * @since 0.12
89    */
getMessageId()90   public abstract long getMessageId();
91 
92   /**
93    * Returns the uncompressed size in bytes of the {@code MessageEvent}.
94    *
95    * @return the uncompressed size in bytes of the {@code MessageEvent}.
96    * @since 0.12
97    */
getUncompressedMessageSize()98   public abstract long getUncompressedMessageSize();
99 
100   /**
101    * Returns the compressed size in bytes of the {@code MessageEvent}.
102    *
103    * @return the compressed size in bytes of the {@code MessageEvent}.
104    * @since 0.12
105    */
getCompressedMessageSize()106   public abstract long getCompressedMessageSize();
107 
108   /**
109    * Builder class for {@link MessageEvent}.
110    *
111    * @since 0.12
112    */
113   @AutoValue.Builder
114   public abstract static class Builder {
115     // Package protected methods because these values are mandatory and set only in the
116     // MessageEvent#builder() function.
setType(Type type)117     abstract Builder setType(Type type);
118 
setMessageId(long messageId)119     abstract Builder setMessageId(long messageId);
120 
121     /**
122      * Sets the uncompressed message size.
123      *
124      * @param uncompressedMessageSize represents the uncompressed size in bytes of this message.
125      * @return this.
126      * @since 0.12
127      */
setUncompressedMessageSize(long uncompressedMessageSize)128     public abstract Builder setUncompressedMessageSize(long uncompressedMessageSize);
129 
130     /**
131      * Sets the compressed message size.
132      *
133      * @param compressedMessageSize represents the compressed size in bytes of this message.
134      * @return this.
135      * @since 0.12
136      */
setCompressedMessageSize(long compressedMessageSize)137     public abstract Builder setCompressedMessageSize(long compressedMessageSize);
138 
139     /**
140      * Builds and returns a {@code MessageEvent} with the desired values.
141      *
142      * @return a {@code MessageEvent} with the desired values.
143      * @since 0.12
144      */
build()145     public abstract MessageEvent build();
146 
Builder()147     Builder() {}
148   }
149 
MessageEvent()150   MessageEvent() {}
151 }
152