1 /* 2 * Copyright 2017, 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 java.util.Collections; 22 import java.util.HashMap; 23 import java.util.Map; 24 import javax.annotation.concurrent.Immutable; 25 26 /** 27 * A text annotation with a set of attributes. 28 * 29 * @since 0.5 30 */ 31 @Immutable 32 @AutoValue 33 public abstract class Annotation { 34 private static final Map<String, AttributeValue> EMPTY_ATTRIBUTES = 35 Collections.unmodifiableMap(Collections.<String, AttributeValue>emptyMap()); 36 37 /** 38 * Returns a new {@code Annotation} with the given description. 39 * 40 * @param description the text description of the {@code Annotation}. 41 * @return a new {@code Annotation} with the given description. 42 * @throws NullPointerException if {@code description} is {@code null}. 43 * @since 0.5 44 */ fromDescription(String description)45 public static Annotation fromDescription(String description) { 46 return new AutoValue_Annotation(description, EMPTY_ATTRIBUTES); 47 } 48 49 /** 50 * Returns a new {@code Annotation} with the given description and set of attributes. 51 * 52 * @param description the text description of the {@code Annotation}. 53 * @param attributes the attributes of the {@code Annotation}. 54 * @return a new {@code Annotation} with the given description and set of attributes. 55 * @throws NullPointerException if {@code description} or {@code attributes} are {@code null}. 56 * @since 0.5 57 */ fromDescriptionAndAttributes( String description, Map<String, AttributeValue> attributes)58 public static Annotation fromDescriptionAndAttributes( 59 String description, Map<String, AttributeValue> attributes) { 60 return new AutoValue_Annotation( 61 description, 62 Collections.unmodifiableMap( 63 new HashMap<String, AttributeValue>(Utils.checkNotNull(attributes, "attributes")))); 64 } 65 66 /** 67 * Return the description of the {@code Annotation}. 68 * 69 * @return the description of the {@code Annotation}. 70 * @since 0.5 71 */ getDescription()72 public abstract String getDescription(); 73 74 /** 75 * Return the attributes of the {@code Annotation}. 76 * 77 * @return the attributes of the {@code Annotation}. 78 * @since 0.5 79 */ getAttributes()80 public abstract Map<String, AttributeValue> getAttributes(); 81 Annotation()82 Annotation() {} 83 } 84