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.tags; 18 19 import io.opencensus.common.Scope; 20 21 /** 22 * Builder for the {@link TagContext} class. 23 * 24 * @since 0.8 25 */ 26 public abstract class TagContextBuilder { 27 28 /** 29 * Adds the key/value pair regardless of whether the key is present. 30 * 31 * @param key the {@code TagKey} which will be set. 32 * @param value the {@code TagValue} to set for the given key. 33 * @return this 34 * @since 0.8 35 */ put(TagKey key, TagValue value)36 public abstract TagContextBuilder put(TagKey key, TagValue value); 37 38 /** 39 * Removes the key if it exists. 40 * 41 * @param key the {@code TagKey} which will be removed. 42 * @return this 43 * @since 0.8 44 */ remove(TagKey key)45 public abstract TagContextBuilder remove(TagKey key); 46 47 /** 48 * Creates a {@code TagContext} from this builder. 49 * 50 * @return a {@code TagContext} with the same tags as this builder. 51 * @since 0.8 52 */ build()53 public abstract TagContext build(); 54 55 /** 56 * Enters the scope of code where the {@link TagContext} created from this builder is in the 57 * current context and returns an object that represents that scope. The scope is exited when the 58 * returned object is closed. 59 * 60 * @return an object that defines a scope where the {@code TagContext} created from this builder 61 * is set to the current context. 62 * @since 0.8 63 */ buildScoped()64 public abstract Scope buildScoped(); 65 } 66