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