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.stats; 18 19 /** 20 * Class that holds the implementations for {@link ViewManager} and {@link StatsRecorder}. 21 * 22 * <p>All objects returned by methods on {@code StatsComponent} are cacheable. 23 * 24 * @since 0.8 25 */ 26 public abstract class StatsComponent { 27 28 /** 29 * Returns the default {@link ViewManager}. 30 * 31 * @since 0.8 32 */ getViewManager()33 public abstract ViewManager getViewManager(); 34 35 /** 36 * Returns the default {@link StatsRecorder}. 37 * 38 * @since 0.8 39 */ getStatsRecorder()40 public abstract StatsRecorder getStatsRecorder(); 41 42 /** 43 * Returns the current {@code StatsCollectionState}. 44 * 45 * <p>When no implementation is available, {@code getState} always returns {@link 46 * StatsCollectionState#DISABLED}. 47 * 48 * <p>Once {@link #getState()} is called, subsequent calls to {@link 49 * #setState(StatsCollectionState)} will throw an {@code IllegalStateException}. 50 * 51 * @return the current {@code StatsCollectionState}. 52 * @since 0.8 53 */ getState()54 public abstract StatsCollectionState getState(); 55 56 /** 57 * Sets the current {@code StatsCollectionState}. 58 * 59 * <p>When no implementation is available, {@code setState} does not change the state. 60 * 61 * <p>If state is set to {@link StatsCollectionState#DISABLED}, all stats that are previously 62 * recorded will be cleared. 63 * 64 * @param state the new {@code StatsCollectionState}. 65 * @throws IllegalStateException if {@link #getState()} was previously called. 66 * @deprecated This method is deprecated because other libraries could cache the result of {@link 67 * #getState()}, use a stale value, and behave incorrectly. It is only safe to call early in 68 * initialization. This method throws {@link IllegalStateException} after {@code getState()} 69 * has been called, in order to limit changes to the result of {@code getState()}. 70 * @since 0.8 71 */ 72 @Deprecated setState(StatsCollectionState state)73 public abstract void setState(StatsCollectionState state); 74 } 75