{@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);
* }
*
* 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. + * + *
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}: + * + *
{@code
+ * Foo result = ScopedLoggingContexts.newContext()
+ * .withTags(Tags.of("my_tag", someValue))
+ * .call(MyClass::doFoo);
+ * }
*/
@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
diff --git a/api/src/main/java/com/google/common/flogger/context/ScopedLoggingContexts.java b/api/src/main/java/com/google/common/flogger/context/ScopedLoggingContexts.java
new file mode 100644
index 00000000..af08f1aa
--- /dev/null
+++ b/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.
+ *
+ * {@code
+ * Foo result = ScopedLoggingContexts.newContext()
+ * .withTags(Tags.of("my_tag", someValue))
+ * .call(MyClass::doFoo);
+ * }
+ */
+ @CheckReturnValue
+ public static ScopedLoggingContext.Builder newContext() {
+ return ScopedLoggingContext.getInstance().newContext();
+ }
+}
diff --git a/api/src/test/java/com/google/common/flogger/context/ScopedLoggingContextTest.java b/api/src/test/java/com/google/common/flogger/context/ScopedLoggingContextTest.java
index 9aae0350..0d2309eb 100644
--- a/api/src/test/java/com/google/common/flogger/context/ScopedLoggingContextTest.java
+++ b/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");
diff --git a/api/src/test/java/com/google/common/flogger/testing/AbstractScopedLoggingContextTest.java b/api/src/test/java/com/google/common/flogger/testing/AbstractScopedLoggingContextTest.java
index 3568327a..52c8543a 100644
--- a/api/src/test/java/com/google/common/flogger/testing/AbstractScopedLoggingContextTest.java
+++ b/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(
() -> {
diff --git a/grpc/src/main/java/com/google/common/flogger/grpc/GrpcScopedLoggingContext.java b/grpc/src/main/java/com/google/common/flogger/grpc/GrpcScopedLoggingContext.java
index d949dd90..99785bd3 100644
--- a/grpc/src/main/java/com/google/common/flogger/grpc/GrpcScopedLoggingContext.java
+++ b/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);
}