Deprecate Stats.setState, and throw an exception when it is called after getState. (#792)

* Throw IllegalStateException if setState is called after getState

* Deprecate Stats.setState

* Remove a test that has potential race condition.

* Remove Deprecated from impl

1 files changed, 13 insertions, 1 deletions

diff --git a/api/src/main/java/io/opencensus/stats/Stats.java b/api/src/main/java/io/opencensus/stats/Stats.java
index 016455e9..3bc78640 100644
--- a/api/src/main/java/io/opencensus/stats/Stats.java
+++ b/api/src/main/java/io/opencensus/stats/Stats.java
@@ -44,6 +44,9 @@ public final class Stats {
    * <p>When no implementation is available, {@code getState} always returns {@link
    * StatsCollectionState#DISABLED}.
    *
+   * <p>Once {@link #getState()} is called, subsequent calls to {@link
+   * #setState(StatsCollectionState)} will throw an {@code IllegalStateException}.
+   *
    * @return the current {@code StatsCollectionState}.
    */
   public static StatsCollectionState getState() {
@@ -53,10 +56,19 @@ public final class Stats {
   /**
    * Sets the current {@code StatsCollectionState}.
    *
-   * <p>When no implementation is available, {@code setState} has no effect.
+   * <p>When no implementation is available, {@code setState} does not change the state.
+   *
+   * <p>If state is set to {@link StatsCollectionState#DISABLED}, all stats that are previously
+   * recorded will be cleared.
    *
    * @param state the new {@code StatsCollectionState}.
+   * @throws IllegalStateException if {@link #getState()} was previously called.
+   * @deprecated This method is deprecated because other libraries could cache the result of {@link
+   *     #getState()}, use a stale value, and behave incorrectly. It is only safe to call early in
+   *     initialization. This method throws {@link IllegalStateException} after {@code getState()}
+   *     has been called, in order to prevent the result of {@code getState()} from changing.
    */
+  @Deprecated
   public static void setState(StatsCollectionState state) {
     statsComponent.setState(state);
   }