1 /* 2 * Copyright 2016-17, 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.common.Timestamp; 21 import io.opencensus.internal.Utils; 22 import javax.annotation.Nullable; 23 import javax.annotation.concurrent.Immutable; 24 25 /** 26 * A class that represents a network event. It requires a {@link Type type} and a message id that 27 * serves to uniquely identify each network message. It can optionally can have information about 28 * the kernel time and message size. 29 * 30 * @deprecated Use {@link MessageEvent}. 31 * @since 0.5 32 */ 33 @Immutable 34 @AutoValue 35 @AutoValue.CopyAnnotations 36 @Deprecated 37 public abstract class NetworkEvent extends io.opencensus.trace.BaseMessageEvent { 38 /** 39 * Available types for a {@code NetworkEvent}. 40 * 41 * @since 0.5 42 */ 43 public enum Type { 44 /** 45 * When the message was sent. 46 * 47 * @since 0.5 48 */ 49 SENT, 50 /** 51 * When the message was received. 52 * 53 * @since 0.5 54 */ 55 RECV, 56 } 57 58 /** 59 * Returns a new {@link Builder} with default values. 60 * 61 * @param type designates whether this is a network send or receive message. 62 * @param messageId serves to uniquely identify each network message. 63 * @return a new {@code Builder} with default values. 64 * @throws NullPointerException if {@code type} is {@code null}. 65 * @since 0.5 66 */ builder(Type type, long messageId)67 public static Builder builder(Type type, long messageId) { 68 return new AutoValue_NetworkEvent.Builder() 69 .setType(Utils.checkNotNull(type, "type")) 70 .setMessageId(messageId) 71 // We need to set a value for the message size because the autovalue requires all 72 // primitives to be initialized. 73 .setUncompressedMessageSize(0) 74 .setCompressedMessageSize(0); 75 } 76 77 /** 78 * Returns the kernel timestamp associated with the {@code NetworkEvent} or {@code null} if not 79 * set. 80 * 81 * @return the kernel timestamp associated with the {@code NetworkEvent} or {@code null} if not 82 * set. 83 * @since 0.5 84 */ 85 @Nullable getKernelTimestamp()86 public abstract Timestamp getKernelTimestamp(); 87 88 /** 89 * Returns the type of the {@code NetworkEvent}. 90 * 91 * @return the type of the {@code NetworkEvent}. 92 * @since 0.5 93 */ getType()94 public abstract Type getType(); 95 96 /** 97 * Returns the message id argument that serves to uniquely identify each network message. 98 * 99 * @return the message id of the {@code NetworkEvent}. 100 * @since 0.5 101 */ getMessageId()102 public abstract long getMessageId(); 103 104 /** 105 * Returns the uncompressed size in bytes of the {@code NetworkEvent}. 106 * 107 * @return the uncompressed size in bytes of the {@code NetworkEvent}. 108 * @since 0.6 109 */ getUncompressedMessageSize()110 public abstract long getUncompressedMessageSize(); 111 112 /** 113 * Returns the compressed size in bytes of the {@code NetworkEvent}. 114 * 115 * @return the compressed size in bytes of the {@code NetworkEvent}. 116 * @since 0.6 117 */ getCompressedMessageSize()118 public abstract long getCompressedMessageSize(); 119 120 /** 121 * Returns the uncompressed size in bytes of the {@code NetworkEvent}. 122 * 123 * @deprecated Use {@link #getUncompressedMessageSize}. 124 * @return the uncompressed size in bytes of the {@code NetworkEvent}. 125 * @since 0.5 126 */ 127 @Deprecated getMessageSize()128 public long getMessageSize() { 129 return getUncompressedMessageSize(); 130 } 131 132 /** 133 * Builder class for {@link NetworkEvent}. 134 * 135 * @deprecated {@link NetworkEvent} is deprecated. Please use {@link MessageEvent} and its builder 136 * {@link MessageEvent.Builder}. 137 * @since 0.5 138 */ 139 @AutoValue.Builder 140 @Deprecated 141 public abstract static class Builder { 142 // Package protected methods because these values are mandatory and set only in the 143 // NetworkEvent#builder() function. setType(Type type)144 abstract Builder setType(Type type); 145 setMessageId(long messageId)146 abstract Builder setMessageId(long messageId); 147 148 /** 149 * Sets the kernel timestamp. 150 * 151 * @param kernelTimestamp The kernel timestamp of the event. 152 * @return this. 153 * @since 0.5 154 */ setKernelTimestamp(@ullable Timestamp kernelTimestamp)155 public abstract Builder setKernelTimestamp(@Nullable Timestamp kernelTimestamp); 156 157 /** 158 * Sets the uncompressed message size. 159 * 160 * @deprecated Use {@link #setUncompressedMessageSize}. 161 * @param messageSize represents the uncompressed size in bytes of this message. 162 * @return this. 163 * @since 0.5 164 */ 165 @Deprecated setMessageSize(long messageSize)166 public Builder setMessageSize(long messageSize) { 167 return setUncompressedMessageSize(messageSize); 168 } 169 170 /** 171 * Sets the uncompressed message size. 172 * 173 * @param uncompressedMessageSize represents the uncompressed size in bytes of this message. 174 * @return this. 175 * @since 0.6 176 */ setUncompressedMessageSize(long uncompressedMessageSize)177 public abstract Builder setUncompressedMessageSize(long uncompressedMessageSize); 178 179 /** 180 * Sets the compressed message size. 181 * 182 * @param compressedMessageSize represents the compressed size in bytes of this message. 183 * @return this. 184 * @since 0.6 185 */ setCompressedMessageSize(long compressedMessageSize)186 public abstract Builder setCompressedMessageSize(long compressedMessageSize); 187 188 /** 189 * Builds and returns a {@code NetworkEvent} with the desired values. 190 * 191 * @return a {@code NetworkEvent} with the desired values. 192 * @since 0.5 193 */ build()194 public abstract NetworkEvent build(); 195 Builder()196 Builder() {} 197 } 198 NetworkEvent()199 NetworkEvent() {} 200 } 201