Add ScopedLoggingContext.newContext(), a new name for newScope(),…

… and `ScopedLoggingContexts`, a container for static equivalents to instance methods on `ScopedLoggingContext`.

Replace usages and implementations of `newScope()` with `newContext()`.

RELNOTES=Renamed `ScopedLoggingContext.newScope()` to `newContext()` and added `ScopedLoggingContexts`, a container for static equivalents to instance methods on `ScopedLoggingContext`.
PiperOrigin-RevId: 364797028

api/src/main/java/com/google/common/flogger/backend/NoOpContextDataProvider.java

@@ -66,7 +66,7 @@ private void logWarningOnceOnly() {
     }
 
     @Override
-    public ScopedLoggingContext.Builder newScope() {
+    public ScopedLoggingContext.Builder newContext() {
       return new ScopedLoggingContext.Builder() {
         @Override
         public LoggingContextCloseable install() {

api/src/main/java/com/google/common/flogger/backend/system/LoggingContext.java

@@ -38,7 +38,7 @@ public ScopedLoggingContext getContextApiSingleton() {
   private static final class NoOpScopedLoggingContext extends ScopedLoggingContext
       implements LoggingContextCloseable {
     @Override
-    public ScopedLoggingContext.Builder newScope() {
+    public ScopedLoggingContext.Builder newContext() {
       return new ScopedLoggingContext.Builder() {
         @Override
         public LoggingContextCloseable install() {

api/src/main/java/com/google/common/flogger/context/ScopedLoggingContext.java

@@ -19,8 +19,8 @@
 import static com.google.common.flogger.util.Checks.checkNotNull;
 import static com.google.common.flogger.util.Checks.checkState;
 
-import com.google.common.flogger.MetadataKey;
 import com.google.common.flogger.LoggingScope;
+import com.google.common.flogger.MetadataKey;
 import com.google.errorprone.annotations.CheckReturnValue;
 import com.google.errorprone.annotations.MustBeClosed;
 import java.io.Closeable;
@@ -331,14 +331,36 @@ protected ScopedLoggingContext() {}
    *
    * <pre>{@code
    * ScopedLoggingContext ctx = ScopedLoggingContext.getInstance();
-   * Foo result = ctx.newScope().withTags(Tags.of("my_tag", someValue)).call(MyClass::doFoo);
+   * Foo result = ctx.newContext().withTags(Tags.of("my_tag", someValue)).call(MyClass::doFoo);
    * }</pre>
    *
    * <p>Implementations of this API must return a subclass of {@link Builder} which can install all
    * necessary metadata into a new context from the builder's current state.
+   *
+   * <p>Note for users: if you don't need an instance of {@code ScopedLoggingContext} for some
+   * reason such as testability (injecting it, for example), consider using the static methods in
+   * {@link ScopedLoggingContexts} instead to avoid the need to call {@link #getInstance}:
+   *
+   * <pre>{@code
+   * Foo result = ScopedLoggingContexts.newContext()
+   *     .withTags(Tags.of("my_tag", someValue))
+   *     .call(MyClass::doFoo);
+   * }</pre>
    */
   @CheckReturnValue
-  public abstract Builder newScope();
+  public abstract Builder newContext();
+
+  /**
+   * Deprecated equivalent to {@link #newContext()}.
+   *
+   * @deprecated implementers and callers should use {@link #newContext()} instead. This method will
+   *     be removed in the next Flogger release.
+   */
+  @Deprecated
+  @CheckReturnValue
+  public Builder newScope() {
+    return newContext();
+  }
 
   /**
    * Adds tags to the current set of log tags for the current context. Tags are merged together and

api/src/main/java/com/google/common/flogger/context/ScopedLoggingContexts.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright (C) 2021 The Flogger Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.common.flogger.context;
+
+import com.google.errorprone.annotations.CheckReturnValue;
+
+/**
+ * Static methods equivalent to the instance methods on {@link ScopedLoggingContext} but which
+ * always operate on the current {@link ScopedLoggingContext} that would be returned by {@link
+ * ScopedLoggingContext#getInstance}.
+ */
+public final class ScopedLoggingContexts {
+
+  private ScopedLoggingContexts() {}
+
+  /**
+   * Creates a new {@link ScopedLoggingContext.Builder} to which additional logging metadata can be
+   * attached before being installed or used to wrap some existing code.
+   *
+   * <pre>{@code
+   * Foo result = ScopedLoggingContexts.newContext()
+   *     .withTags(Tags.of("my_tag", someValue))
+   *     .call(MyClass::doFoo);
+   * }</pre>
+   */
+  @CheckReturnValue
+  public static ScopedLoggingContext.Builder newContext() {
+    return ScopedLoggingContext.getInstance().newContext();
+  }
+}

api/src/test/java/com/google/common/flogger/context/ScopedLoggingContextTest.java

@@ -33,7 +33,7 @@ public class ScopedLoggingContextTest {
   private static final ScopedLoggingContext ERROR_CONTEXT =
       new ScopedLoggingContext() {
         @Override
-        public ScopedLoggingContext.Builder newScope() {
+        public ScopedLoggingContext.Builder newContext() {
           return new ScopedLoggingContext.Builder() {
             @Override
             public LoggingContextCloseable install() {
@@ -60,7 +60,7 @@ public void testErrorHandlingWithoutUserError() {
     InvalidLoggingContextStateException e =
         assertThrows(
             InvalidLoggingContextStateException.class,
-            () -> ERROR_CONTEXT.newScope().run(() -> {}));
+            () -> ERROR_CONTEXT.newContext().run(() -> {}));
     assertThat(e).hasCauseThat().isInstanceOf(IllegalArgumentException.class);
     assertThat(e).hasCauseThat().hasMessageThat().isEqualTo("BAD CONTEXT");
   }
@@ -72,7 +72,7 @@ public void testErrorHandlingWithUserError() {
             IllegalArgumentException.class,
             () ->
                 ERROR_CONTEXT
-                    .newScope()
+                    .newContext()
                     .run(
                         () -> {
                           throw new IllegalArgumentException("User error");

api/src/test/java/com/google/common/flogger/testing/AbstractScopedLoggingContextTest.java

@@ -83,10 +83,10 @@ private BooleanSubject assertLogging(String name, Level level) {
   }
 
   @Test
-  public void testNewScope_withTags() {
+  public void testNewContext_withTags() {
     assertThat(getTagMap()).isEmpty();
     context
-        .newScope()
+        .newContext()
         .withTags(Tags.of("foo", "bar"))
         .run(
             () -> {
@@ -99,10 +99,10 @@ public void testNewScope_withTags() {
   }
 
   @Test
-  public void testNewScope_withMetadata() {
+  public void testNewContext_withMetadata() {
     assertThat(getMetadata()).hasSize(0);
     context
-        .newScope()
+        .newContext()
         .withMetadata(FOO_KEY, "foo")
         .run(
             () -> {
@@ -115,11 +115,11 @@ public void testNewScope_withMetadata() {
   }
 
   @Test
-  public void testNewScope_withLogLevelMap() {
+  public void testNewContext_withLogLevelMap() {
     assertThat(dataProvider.shouldForceLogging("foo.bar.Bar", Level.FINE, false)).isFalse();
     LogLevelMap levelMap = LogLevelMap.create(ImmutableMap.of("foo.bar", Level.FINE), Level.FINE);
     context
-        .newScope()
+        .newContext()
         .withLogLevelMap(levelMap)
         .run(
             () -> {
@@ -132,17 +132,17 @@ public void testNewScope_withLogLevelMap() {
   }
 
   @Test
-  public void testNewScope_withMergedTags() {
+  public void testNewContext_withMergedTags() {
     assertThat(getTagMap()).isEmpty();
     context
-        .newScope()
+        .newContext()
         .withTags(Tags.of("foo", "bar"))
         .run(
             () -> {
               assertThat(getTagMap()).hasSize(1);
               assertThat(getTagMap().get("foo")).containsExactly("bar");
               context
-                  .newScope()
+                  .newContext()
                   .withTags(Tags.of("foo", "baz"))
                   .run(
                       () -> {
@@ -160,10 +160,10 @@ public void testNewScope_withMergedTags() {
   }
 
   @Test
-  public void testNewScope_withConcatenatedMetadata() {
+  public void testNewContext_withConcatenatedMetadata() {
     assertThat(getMetadata()).hasSize(0);
     context
-        .newScope()
+        .newContext()
         .withMetadata(FOO_KEY, "first")
         .withMetadata(BAR_KEY, "one")
         .run(
@@ -173,7 +173,7 @@ public void testNewScope_withConcatenatedMetadata() {
               assertThat(getMetadata().findValue(FOO_KEY)).isEqualTo("first");
               assertThat(getMetadata()).containsEntries(BAR_KEY, "one");
               context
-                  .newScope()
+                  .newContext()
                   .withMetadata(FOO_KEY, "second")
                   .withMetadata(BAR_KEY, "two")
                   .run(
@@ -199,14 +199,14 @@ public void testNewScope_withConcatenatedMetadata() {
   }
 
   @Test
-  public void testNewScope_withMergedLevelMap() {
+  public void testNewContext_withMergedLevelMap() {
     assertLogging("other.package", Level.FINE).isFalse();
     assertLogging("foo.bar", Level.FINE).isFalse();
     assertLogging("foo.bar.Baz", Level.FINE).isFalse();
     // Everything in "foo.bar" gets at least FINE logging.
     LogLevelMap fooBarFine = LogLevelMap.create(ImmutableMap.of("foo.bar", Level.FINE), Level.INFO);
     context
-        .newScope()
+        .newContext()
         .withLogLevelMap(fooBarFine)
         .run(
             () -> {
@@ -218,7 +218,7 @@ public void testNewScope_withMergedLevelMap() {
               LogLevelMap bazFinest =
                   LogLevelMap.create(ImmutableMap.of("foo.bar.Baz", Level.FINEST), Level.INFO);
               context
-                  .newScope()
+                  .newContext()
                   .withLogLevelMap(bazFinest)
                   .run(
                       () -> {

grpc/src/main/java/com/google/common/flogger/grpc/GrpcScopedLoggingContext.java

@@ -45,7 +45,7 @@ static ScopedLoggingContext getGrpcConfigInstance() {
 
   @Override
   @CheckReturnValue
-  public ScopedLoggingContext.Builder newScope() {
+  public ScopedLoggingContext.Builder newContext() {
     return newBuilder(null);
   }