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 * Object for creating new {@link TagContext}s and {@code TagContext}s based on the current context. 23 * 24 * <p>This class returns {@link TagContextBuilder builders} that can be used to create the 25 * implementation-dependent {@link TagContext}s. 26 * 27 * <p>Implementations may have different constraints and are free to convert tag contexts to their 28 * own subtypes. This means callers cannot assume the {@link #getCurrentTagContext() current 29 * context} is the same instance as the one {@link #withTagContext(TagContext) placed into scope}. 30 * 31 * @since 0.8 32 */ 33 public abstract class Tagger { 34 35 /** 36 * Returns an empty {@code TagContext}. 37 * 38 * @return an empty {@code TagContext}. 39 * @since 0.8 40 */ empty()41 public abstract TagContext empty(); 42 43 /** 44 * Returns the current {@code TagContext}. 45 * 46 * @return the current {@code TagContext}. 47 * @since 0.8 48 */ getCurrentTagContext()49 public abstract TagContext getCurrentTagContext(); 50 51 /** 52 * Returns a new empty {@code Builder}. 53 * 54 * @return a new empty {@code Builder}. 55 * @since 0.8 56 */ emptyBuilder()57 public abstract TagContextBuilder emptyBuilder(); 58 59 /** 60 * Returns a builder based on this {@code TagContext}. 61 * 62 * @return a builder based on this {@code TagContext}. 63 * @since 0.8 64 */ toBuilder(TagContext tags)65 public abstract TagContextBuilder toBuilder(TagContext tags); 66 67 /** 68 * Returns a new builder created from the current {@code TagContext}. 69 * 70 * @return a new builder created from the current {@code TagContext}. 71 * @since 0.8 72 */ currentBuilder()73 public abstract TagContextBuilder currentBuilder(); 74 75 /** 76 * Enters the scope of code where the given {@code TagContext} is in the current context 77 * (replacing the previous {@code TagContext}) and returns an object that represents that scope. 78 * The scope is exited when the returned object is closed. 79 * 80 * @param tags the {@code TagContext} to be set to the current context. 81 * @return an object that defines a scope where the given {@code TagContext} is set to the current 82 * context. 83 * @since 0.8 84 */ withTagContext(TagContext tags)85 public abstract Scope withTagContext(TagContext tags); 86 } 87