ppkarwasz commented on code in PR #2438: URL: https://github.com/apache/logging-log4j2/pull/2438#discussion_r1553097482
########## log4j-api/src/main/java/org/apache/logging/log4j/message/package-info.java: ########## @@ -20,7 +20,7 @@ */ @Export /** - * Bumped to 2.22.0, since FormattedMessage behavior changed. + * Bumped to 2.24.0, since FormattedMessage behavior changede. Review Comment: This can be reverted, since the PR does not contain any changes to the `o.a.l.l.message` package. ########## log4j-api-test/src/test/java/org/apache/logging/log4j/ResourceLoggerTest.java: ########## @@ -0,0 +1,143 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you 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 org.apache.logging.log4j; + +import static org.hamcrest.MatcherAssert.assertThat; +import static org.hamcrest.Matchers.containsString; +import static org.hamcrest.Matchers.hasSize; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.concurrent.atomic.AtomicLong; +import java.util.function.Supplier; +import org.apache.logging.log4j.test.TestLogger; +import org.apache.logging.log4j.test.TestLoggerContextFactory; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Disabled; +import org.junit.jupiter.api.Test; + +/** + * Class Description goes here. + */ +@Disabled("Does not work with the NO-OP implementation of ScopedContextProvider in the API.") Review Comment: I disabled it in my PR, but you can probably enable it again. ########## log4j-api/src/main/java/org/apache/logging/log4j/spi/internal/DefaultScopedContextProvider.java: ########## @@ -0,0 +1,399 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you 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 org.apache.logging.log4j.spi.internal; + +import java.util.Collection; +import java.util.Collections; +import java.util.HashMap; +import java.util.Map; +import java.util.Optional; +import java.util.concurrent.Callable; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Future; +import java.util.function.Supplier; +import org.apache.logging.log4j.Logger; +import org.apache.logging.log4j.ScopedContext; +import org.apache.logging.log4j.ThreadContext; +import org.apache.logging.log4j.spi.ScopedContextProvider; +import org.apache.logging.log4j.status.StatusLogger; +import org.apache.logging.log4j.util.StringMap; + +/** + * An implementation of {@link ScopedContextProvider} that uses the simplest implementation. + * @since 2.24.0 + */ +public class DefaultScopedContextProvider implements ScopedContextProvider { + + public static final Logger LOGGER = StatusLogger.getLogger(); + public static final ScopedContextProvider INSTANCE = new DefaultScopedContextProvider(); + + private final ThreadLocal<Instance> scopedContext = new ThreadLocal<>(); + + /** + * Returns an immutable Map containing all the key/value pairs as Object objects. + * @return The current context Instance. + */ + private Optional<Instance> getContext() { + return Optional.ofNullable(scopedContext.get()); + } + + /** + * Add the ScopeContext. + * @param context The ScopeContext. + */ + private void addScopedContext(final Instance context) { + Instance current = scopedContext.get(); + scopedContext.set(context); + } + + /** + * Remove the top ScopeContext. + */ + private void removeScopedContext() { + final Instance current = scopedContext.get(); + if (current != null) { + if (current.parent != null) { + scopedContext.set(current.parent); + } else { + scopedContext.remove(); + } + } + } + + @Override + public Map<String, ?> getContextMap() { + final Optional<Instance> context = getContext(); + return context.isPresent() + && context.get().contextMap != null + && !context.get().contextMap.isEmpty() + ? Collections.unmodifiableMap(context.get().contextMap) + : Collections.emptyMap(); + } + + /** + * Return the value of the key from the current ScopedContext, if there is one and the key exists. + * @param key The key. + * @return The value of the key in the current ScopedContext. + */ + @Override + public Object getValue(final String key) { + final Optional<Instance> context = getContext(); + return context.map(instance -> instance.contextMap) + .map(map -> map.get(key)) + .orElse(null); + } + + /** + * Return String value of the key from the current ScopedContext, if there is one and the key exists. + * @param key The key. + * @return The value of the key in the current ScopedContext. + */ + @Override + public String getString(final String key) { + final Optional<Instance> context = getContext(); + if (context.isPresent()) { + final Object obj = context.get().contextMap.get(key); + if (obj != null) { + return obj.toString(); + } + } + return null; + } + + /** + * Adds all the String rendered objects in the context map to the provided Map. + * @param map The Map to add entries to. + */ + @Override + public void addContextMapTo(final StringMap map) { + final Optional<Instance> context = getContext(); + if (context.isPresent()) { + final Map<String, ?> contextMap = context.get().contextMap; + if (contextMap != null && !contextMap.isEmpty()) { + contextMap.forEach((key, value) -> map.putValue(key, value.toString())); + } + } + } + + @Override + public ScopedContext.Instance newScopedContext() { + return getContext().isPresent() ? getContext().get() : null; + } + + /** + * Creates a ScopedContext Instance with a key/value pair. + * + * @param key the key to add. + * @param value the value associated with the key. + * @return the Instance constructed if a valid key and value were provided. Otherwise, either the + * current Instance is returned or a new Instance is created if there is no current Instance. + */ + @Override + public ScopedContext.Instance newScopedContext(final String key, final Object value) { + if (value != null) { + final Instance parent = getContext().isPresent() ? getContext().get() : null; + if (parent != null) { + return new Instance(parent, key, value); + } else { + return new Instance(this, key, value); + } + } else { + if (getContext().isPresent()) { + final Map<String, ?> map = getContextMap(); + map.remove(key); + return new Instance(this, map); + } + } + return newScopedContext(); + } + + /** + * Creates a ScopedContext Instance with a Map of keys and values. + * @param map the Map. + * @return the ScopedContext Instance constructed. + */ + @Override + public ScopedContext.Instance newScopedContext(final Map<String, ?> map) { + if (map != null && !map.isEmpty()) { + final Map<String, Object> objectMap = new HashMap<>(); + if (getContext().isPresent()) { + objectMap.putAll(getContext().get().contextMap); + } + map.forEach((key, value) -> { + if (value == null || (value instanceof String && ((String) value).isEmpty())) { + objectMap.remove(key); + } else { + objectMap.put(key, value); + } + }); + return new Instance(this, objectMap); + } else { + return getContext().isPresent() ? getContext().get() : null; + } + } + + private static void setupContext( + final Map<String, Object> contextMap, + final Map<String, String> threadContextMap, + final Collection<String> contextStack, + final Instance context) { + Instance scopedContext = context; + // If the current context has a Map then we can just use it. + if (context.contextMap == null) { + do { + if (scopedContext.contextMap != null) { + // Once we hit a scope with an already populated Map we won't need to go any further. + contextMap.putAll(scopedContext.contextMap); + break; + } else if (scopedContext.key != null) { + contextMap.putIfAbsent(scopedContext.key, scopedContext.value); + } + scopedContext = scopedContext.parent; + } while (scopedContext != null); + scopedContext = new Instance(context.getProvider(), contextMap); + } + if (threadContextMap != null && !threadContextMap.isEmpty()) { + ThreadContext.putAll(threadContextMap); + } + if (contextStack != null) { + ThreadContext.setStack(contextStack); + } + context.getProvider().addScopedContext(scopedContext); + } + + private static final class Instance implements ScopedContext.Instance { + + private final DefaultScopedContextProvider provider; + private final Instance parent; + private final String key; + private final Object value; + private final Map<String, ?> contextMap; Review Comment: Can we simplify this? I guess that the reason for the existence of `parent`, `key` and `value` is to prevent the allocation of a `Map` object if the users needs only one key. Well, in that case we don't allocate a `Map`, but we still allocate an `Instance`. :wink: Also if you guarantee that `contextMap` is not null, you can remove a lot of null checks. Since `Instance` is immutable, we can have a preinstantiated object that contains no data. ########## log4j-api/src/main/java/org/apache/logging/log4j/ScopedContext.java: ########## @@ -0,0 +1,225 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you 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 org.apache.logging.log4j; + +import java.util.Map; +import java.util.concurrent.Callable; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Future; +import java.util.function.Supplier; +import org.apache.logging.log4j.spi.ScopedContextProvider; +import org.apache.logging.log4j.util.ProviderUtil; + +/** + * Context that can be used for data to be logged in a block of code. + * <p> + * While this is influenced by ScopedValues from Java 21 it does not share the same API. While it can perform a + * similar function as a set of ScopedValues it is really meant to allow a block of code to include a set of keys and + * values in all the log events within that block. The underlying implementation must provide support for + * logging the ScopedContext for that to happen. + * </p> + * <p> + * The ScopedContext will not be bound to the current thread until either a run or call method is invoked. The + * contexts are nested so creating and running or calling via a second ScopedContext will result in the first + * ScopedContext being hidden until the call is returned. Thus the values from the first ScopedContext need to + * be added to the second to be included. + * </p> + * <p> + * The ScopedContext can be passed to child threads by including the ExecutorService to be used to manage the + * run or call methods. The caller should interact with the ExecutorService as if they were submitting their + * run or call methods directly to it. The ScopedContext performs no error handling other than to ensure the + * ThreadContext and ScopedContext are cleaned up from the executed Thread. + * </p> + * @since 2.24.0 + */ +public final class ScopedContext { + + private static final ScopedContextProvider provider = + ProviderUtil.getProvider().getScopedContextProvider(); + + private ScopedContext() {} + + /** + * Creates a ScopedContext Instance with a key/value pair. + * + * @param key the key to add. + * @param value the value associated with the key. + * @return the Instance constructed if a valid key and value were provided. Otherwise, either the + * current Instance is returned or a new Instance is created if there is no current Instance. + */ + public static Instance where(final String key, final Object value) { + return provider.newScopedContext(key, value); + } + + /** + * Adds a key/value pair to the ScopedContext being constructed. + * + * @param key the key to add. + * @param supplier the function to generate the value. + * @return the ScopedContext being constructed. + */ + public static Instance where(final String key, final Supplier<Object> supplier) { + return where(key, supplier.get()); + } + + /** + * Creates a ScopedContext Instance with a Map of keys and values. + * @param map the Map. + * @return the ScopedContext Instance constructed. + */ + public static Instance where(final Map<String, ?> map) { + return provider.newScopedContext(map); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method. + * @param key the key. + * @param value the value associated with the key. + * @param task the Runnable to call. + */ + public static void runWhere(final String key, final Object value, final Runnable task) { + provider.newScopedContext(key, value).run(task); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method on a separate Thread. + * @param key the key. + * @param value the value associated with the key. + * @param executorService the ExecutorService to dispatch the work. + * @param task the Runnable to call. + */ + public static Future<Void> runWhere( + final String key, final Object value, final ExecutorService executorService, final Runnable task) { + return provider.newScopedContext(key, value).run(executorService, task); + } + + /** + * Creates a ScopedContext with a Map of keys and values and calls a method. + * @param map the Map. + * @param task the Runnable to call. + */ + public static void runWhere(final Map<String, ?> map, final Runnable task) { + provider.newScopedContext(map).run(task); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method. + * @param key the key. + * @param value the value associated with the key. + * @param task the Runnable to call. + */ + public static <R> R callWhere(final String key, final Object value, final Callable<R> task) throws Exception { + return provider.newScopedContext(key, value).call(task); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method on a separate Thread. + * @param key the key. + * @param value the value associated with the key. + * @param executorService the ExecutorService to dispatch the work. + * @param task the Callable to call. + */ + public static <R> Future<R> callWhere( + final String key, final Object value, final ExecutorService executorService, final Callable<R> task) { + return provider.newScopedContext(key, value).call(executorService, task); + } + + /** + * Creates a ScopedContext with a Map of keys and values and calls a method. + * @param map the Map. + * @param task the Runnable to call. + */ + public static <R> R callWhere(final Map<String, ?> map, final Callable<R> task) throws Exception { + return provider.newScopedContext(map).call(task); + } + + /** + * Return the object with the specified key from the current context. + * @param key the key. + * @return the value of the key or null. + * @param <T> The type of object expected. + * @throws ClassCastException if the specified type does not match the object stored. + */ + @SuppressWarnings("unchecked") + public static <T> T get(String key) { + return (T) provider.getValue(key); + } + + /** + * Return String value of the key from the current ScopedContext, if there is one and the key exists. + * @param key The key. + * @return The value of the key in the current ScopedContext. + */ + public static String getString(String key) { + return provider.getString(key); + } + + /** + * A holder of scoped context data. + */ + public interface Instance { + + /** + * Adds a key/value pair to the ScopedContext being constructed. + * + * @param key the key to add. + * @param value the value associated with the key. + * @return the ScopedContext being constructed. + */ + Instance where(String key, Object value); + + /** + * Adds a key/value pair to the ScopedContext being constructed. + * + * @param key the key to add. + * @param supplier the function to generate the value. + * @return the ScopedContext being constructed. + */ + Instance where(String key, Supplier<Object> supplier); + + /** + * Executes a code block that includes all the key/value pairs added to the ScopedContext. + * + * @param task the code block to execute. + */ + void run(Runnable task); + + /** + * Executes a code block that includes all the key/value pairs added to the ScopedContext on a different Thread. + * + * @param task the code block to execute. + * @return a Future representing pending completion of the task + */ + Future<Void> run(ExecutorService executorService, Runnable task); Review Comment: I am not sure if we are not missing some use cases by not providing a: ```java Runnable wrap(Runnable task); ``` method. For example with the available API we must write: ```java ScopedContext.Instance scopedContext = ...; asyncContext.startAsync(() -> scopedContext.run(() -> doSomething()); ``` (where `asyncContext` is an [`AsyncContext`](https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/asynccontext#start(java.lang.Runnable))). With a `wrap` method we can do it with one less lambda: ```java ScopedContext.Instance scopedContext = ...; asyncContext.startAsync(scopedContext.wrap(() -> doSomething()); ``` Note that the `run` and `call` methods could still be provided as shortcuts, but can have default implementations: ```java default Future<Void> run(ExecutorService executorService, Runnable task) { executorService.submit(wrap(task), null); } ``` ########## log4j-api/src/main/java/org/apache/logging/log4j/ScopedContext.java: ########## @@ -0,0 +1,225 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you 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 org.apache.logging.log4j; + +import java.util.Map; +import java.util.concurrent.Callable; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Future; +import java.util.function.Supplier; +import org.apache.logging.log4j.spi.ScopedContextProvider; +import org.apache.logging.log4j.util.ProviderUtil; + +/** + * Context that can be used for data to be logged in a block of code. + * <p> + * While this is influenced by ScopedValues from Java 21 it does not share the same API. While it can perform a + * similar function as a set of ScopedValues it is really meant to allow a block of code to include a set of keys and + * values in all the log events within that block. The underlying implementation must provide support for + * logging the ScopedContext for that to happen. + * </p> + * <p> + * The ScopedContext will not be bound to the current thread until either a run or call method is invoked. The + * contexts are nested so creating and running or calling via a second ScopedContext will result in the first + * ScopedContext being hidden until the call is returned. Thus the values from the first ScopedContext need to + * be added to the second to be included. + * </p> + * <p> + * The ScopedContext can be passed to child threads by including the ExecutorService to be used to manage the + * run or call methods. The caller should interact with the ExecutorService as if they were submitting their + * run or call methods directly to it. The ScopedContext performs no error handling other than to ensure the + * ThreadContext and ScopedContext are cleaned up from the executed Thread. + * </p> + * @since 2.24.0 + */ +public final class ScopedContext { + + private static final ScopedContextProvider provider = + ProviderUtil.getProvider().getScopedContextProvider(); + + private ScopedContext() {} + + /** + * Creates a ScopedContext Instance with a key/value pair. + * + * @param key the key to add. + * @param value the value associated with the key. + * @return the Instance constructed if a valid key and value were provided. Otherwise, either the + * current Instance is returned or a new Instance is created if there is no current Instance. + */ + public static Instance where(final String key, final Object value) { + return provider.newScopedContext(key, value); + } + + /** + * Adds a key/value pair to the ScopedContext being constructed. + * + * @param key the key to add. + * @param supplier the function to generate the value. + * @return the ScopedContext being constructed. + */ + public static Instance where(final String key, final Supplier<Object> supplier) { + return where(key, supplier.get()); + } + + /** + * Creates a ScopedContext Instance with a Map of keys and values. + * @param map the Map. + * @return the ScopedContext Instance constructed. + */ + public static Instance where(final Map<String, ?> map) { + return provider.newScopedContext(map); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method. + * @param key the key. + * @param value the value associated with the key. + * @param task the Runnable to call. + */ + public static void runWhere(final String key, final Object value, final Runnable task) { + provider.newScopedContext(key, value).run(task); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method on a separate Thread. + * @param key the key. + * @param value the value associated with the key. + * @param executorService the ExecutorService to dispatch the work. + * @param task the Runnable to call. + */ + public static Future<Void> runWhere( + final String key, final Object value, final ExecutorService executorService, final Runnable task) { + return provider.newScopedContext(key, value).run(executorService, task); + } + + /** + * Creates a ScopedContext with a Map of keys and values and calls a method. + * @param map the Map. + * @param task the Runnable to call. + */ + public static void runWhere(final Map<String, ?> map, final Runnable task) { + provider.newScopedContext(map).run(task); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method. + * @param key the key. + * @param value the value associated with the key. + * @param task the Runnable to call. + */ + public static <R> R callWhere(final String key, final Object value, final Callable<R> task) throws Exception { + return provider.newScopedContext(key, value).call(task); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method on a separate Thread. + * @param key the key. + * @param value the value associated with the key. + * @param executorService the ExecutorService to dispatch the work. + * @param task the Callable to call. + */ + public static <R> Future<R> callWhere( + final String key, final Object value, final ExecutorService executorService, final Callable<R> task) { + return provider.newScopedContext(key, value).call(executorService, task); + } + + /** + * Creates a ScopedContext with a Map of keys and values and calls a method. + * @param map the Map. + * @param task the Runnable to call. + */ + public static <R> R callWhere(final Map<String, ?> map, final Callable<R> task) throws Exception { + return provider.newScopedContext(map).call(task); + } + + /** + * Return the object with the specified key from the current context. + * @param key the key. + * @return the value of the key or null. + * @param <T> The type of object expected. + * @throws ClassCastException if the specified type does not match the object stored. + */ + @SuppressWarnings("unchecked") + public static <T> T get(String key) { + return (T) provider.getValue(key); + } Review Comment: I don't think this method should be in the `ScopedContext` class: having `ScopedContextProvider#getValue` is enough for integrators to extract values from the context, but normal users should not use `ScopedContext` as a generic service to set values that they retrieve further down the stack. If the value is important, they should pass it as method parameter. Note that the absence of getters is in line with what OpenTelemetry does for tracing: [`Span`](https://javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/trace/Span.html) has no getters. As far as I understood that is one of the reasons they invented `Baggage`. My rule of thumb is: - for technical debt, baggage and similar, users should use `Baggage` or the (soon to be deprecated) `ThreadContext`, - for pure logging purposes they should use `ScopedContext` instead. **BTW**: the signature of this method is terrible: it is a `ClassCastException` waiting to happen and Error Prone will soon point it out. ########## log4j-api/src/main/java/org/apache/logging/log4j/ScopedContext.java: ########## @@ -0,0 +1,225 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you 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 org.apache.logging.log4j; + +import java.util.Map; +import java.util.concurrent.Callable; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Future; +import java.util.function.Supplier; +import org.apache.logging.log4j.spi.ScopedContextProvider; +import org.apache.logging.log4j.util.ProviderUtil; + +/** + * Context that can be used for data to be logged in a block of code. + * <p> + * While this is influenced by ScopedValues from Java 21 it does not share the same API. While it can perform a + * similar function as a set of ScopedValues it is really meant to allow a block of code to include a set of keys and + * values in all the log events within that block. The underlying implementation must provide support for + * logging the ScopedContext for that to happen. + * </p> + * <p> + * The ScopedContext will not be bound to the current thread until either a run or call method is invoked. The + * contexts are nested so creating and running or calling via a second ScopedContext will result in the first + * ScopedContext being hidden until the call is returned. Thus the values from the first ScopedContext need to + * be added to the second to be included. + * </p> + * <p> + * The ScopedContext can be passed to child threads by including the ExecutorService to be used to manage the + * run or call methods. The caller should interact with the ExecutorService as if they were submitting their + * run or call methods directly to it. The ScopedContext performs no error handling other than to ensure the + * ThreadContext and ScopedContext are cleaned up from the executed Thread. + * </p> + * @since 2.24.0 + */ +public final class ScopedContext { + + private static final ScopedContextProvider provider = + ProviderUtil.getProvider().getScopedContextProvider(); + + private ScopedContext() {} + + /** + * Creates a ScopedContext Instance with a key/value pair. + * + * @param key the key to add. + * @param value the value associated with the key. + * @return the Instance constructed if a valid key and value were provided. Otherwise, either the + * current Instance is returned or a new Instance is created if there is no current Instance. + */ + public static Instance where(final String key, final Object value) { + return provider.newScopedContext(key, value); + } + + /** + * Adds a key/value pair to the ScopedContext being constructed. + * + * @param key the key to add. + * @param supplier the function to generate the value. + * @return the ScopedContext being constructed. + */ + public static Instance where(final String key, final Supplier<Object> supplier) { + return where(key, supplier.get()); + } + + /** + * Creates a ScopedContext Instance with a Map of keys and values. + * @param map the Map. + * @return the ScopedContext Instance constructed. + */ + public static Instance where(final Map<String, ?> map) { + return provider.newScopedContext(map); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method. + * @param key the key. + * @param value the value associated with the key. + * @param task the Runnable to call. + */ + public static void runWhere(final String key, final Object value, final Runnable task) { + provider.newScopedContext(key, value).run(task); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method on a separate Thread. + * @param key the key. + * @param value the value associated with the key. + * @param executorService the ExecutorService to dispatch the work. + * @param task the Runnable to call. + */ + public static Future<Void> runWhere( + final String key, final Object value, final ExecutorService executorService, final Runnable task) { + return provider.newScopedContext(key, value).run(executorService, task); + } + + /** + * Creates a ScopedContext with a Map of keys and values and calls a method. + * @param map the Map. + * @param task the Runnable to call. + */ + public static void runWhere(final Map<String, ?> map, final Runnable task) { + provider.newScopedContext(map).run(task); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method. + * @param key the key. + * @param value the value associated with the key. + * @param task the Runnable to call. + */ + public static <R> R callWhere(final String key, final Object value, final Callable<R> task) throws Exception { + return provider.newScopedContext(key, value).call(task); + } + + /** + * Creates a ScopedContext with a single key/value pair and calls a method on a separate Thread. + * @param key the key. + * @param value the value associated with the key. + * @param executorService the ExecutorService to dispatch the work. + * @param task the Callable to call. + */ + public static <R> Future<R> callWhere( + final String key, final Object value, final ExecutorService executorService, final Callable<R> task) { + return provider.newScopedContext(key, value).call(executorService, task); + } + + /** + * Creates a ScopedContext with a Map of keys and values and calls a method. + * @param map the Map. + * @param task the Runnable to call. + */ + public static <R> R callWhere(final Map<String, ?> map, final Callable<R> task) throws Exception { + return provider.newScopedContext(map).call(task); + } + + /** + * Return the object with the specified key from the current context. + * @param key the key. + * @return the value of the key or null. + * @param <T> The type of object expected. + * @throws ClassCastException if the specified type does not match the object stored. + */ + @SuppressWarnings("unchecked") + public static <T> T get(String key) { + return (T) provider.getValue(key); + } + + /** + * Return String value of the key from the current ScopedContext, if there is one and the key exists. + * @param key The key. + * @return The value of the key in the current ScopedContext. + */ + public static String getString(String key) { + return provider.getString(key); + } Review Comment: Same as above, please don't expose this to the public API. ########## log4j-api/src/main/java/org/apache/logging/log4j/spi/internal/DefaultScopedContextProvider.java: ########## @@ -0,0 +1,399 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you 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 org.apache.logging.log4j.spi.internal; + +import java.util.Collection; +import java.util.Collections; +import java.util.HashMap; +import java.util.Map; +import java.util.Optional; +import java.util.concurrent.Callable; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Future; +import java.util.function.Supplier; +import org.apache.logging.log4j.Logger; +import org.apache.logging.log4j.ScopedContext; +import org.apache.logging.log4j.ThreadContext; +import org.apache.logging.log4j.spi.ScopedContextProvider; +import org.apache.logging.log4j.status.StatusLogger; +import org.apache.logging.log4j.util.StringMap; + +/** + * An implementation of {@link ScopedContextProvider} that uses the simplest implementation. + * @since 2.24.0 + */ +public class DefaultScopedContextProvider implements ScopedContextProvider { + + public static final Logger LOGGER = StatusLogger.getLogger(); + public static final ScopedContextProvider INSTANCE = new DefaultScopedContextProvider(); + + private final ThreadLocal<Instance> scopedContext = new ThreadLocal<>(); + + /** + * Returns an immutable Map containing all the key/value pairs as Object objects. + * @return The current context Instance. + */ + private Optional<Instance> getContext() { + return Optional.ofNullable(scopedContext.get()); + } + + /** + * Add the ScopeContext. + * @param context The ScopeContext. + */ + private void addScopedContext(final Instance context) { + Instance current = scopedContext.get(); + scopedContext.set(context); + } + + /** + * Remove the top ScopeContext. + */ + private void removeScopedContext() { + final Instance current = scopedContext.get(); + if (current != null) { + if (current.parent != null) { + scopedContext.set(current.parent); + } else { + scopedContext.remove(); + } + } + } + + @Override + public Map<String, ?> getContextMap() { + final Optional<Instance> context = getContext(); + return context.isPresent() + && context.get().contextMap != null + && !context.get().contextMap.isEmpty() + ? Collections.unmodifiableMap(context.get().contextMap) + : Collections.emptyMap(); + } + + /** + * Return the value of the key from the current ScopedContext, if there is one and the key exists. + * @param key The key. + * @return The value of the key in the current ScopedContext. + */ + @Override + public Object getValue(final String key) { + final Optional<Instance> context = getContext(); + return context.map(instance -> instance.contextMap) + .map(map -> map.get(key)) + .orElse(null); + } + + /** + * Return String value of the key from the current ScopedContext, if there is one and the key exists. + * @param key The key. + * @return The value of the key in the current ScopedContext. + */ + @Override + public String getString(final String key) { + final Optional<Instance> context = getContext(); + if (context.isPresent()) { + final Object obj = context.get().contextMap.get(key); + if (obj != null) { + return obj.toString(); + } + } + return null; + } + + /** + * Adds all the String rendered objects in the context map to the provided Map. + * @param map The Map to add entries to. + */ + @Override + public void addContextMapTo(final StringMap map) { + final Optional<Instance> context = getContext(); + if (context.isPresent()) { + final Map<String, ?> contextMap = context.get().contextMap; + if (contextMap != null && !contextMap.isEmpty()) { + contextMap.forEach((key, value) -> map.putValue(key, value.toString())); + } + } + } + + @Override + public ScopedContext.Instance newScopedContext() { + return getContext().isPresent() ? getContext().get() : null; + } + + /** + * Creates a ScopedContext Instance with a key/value pair. + * + * @param key the key to add. + * @param value the value associated with the key. + * @return the Instance constructed if a valid key and value were provided. Otherwise, either the + * current Instance is returned or a new Instance is created if there is no current Instance. + */ + @Override + public ScopedContext.Instance newScopedContext(final String key, final Object value) { + if (value != null) { + final Instance parent = getContext().isPresent() ? getContext().get() : null; + if (parent != null) { + return new Instance(parent, key, value); + } else { + return new Instance(this, key, value); + } + } else { + if (getContext().isPresent()) { + final Map<String, ?> map = getContextMap(); + map.remove(key); + return new Instance(this, map); + } + } + return newScopedContext(); + } + + /** + * Creates a ScopedContext Instance with a Map of keys and values. + * @param map the Map. + * @return the ScopedContext Instance constructed. + */ + @Override + public ScopedContext.Instance newScopedContext(final Map<String, ?> map) { + if (map != null && !map.isEmpty()) { + final Map<String, Object> objectMap = new HashMap<>(); + if (getContext().isPresent()) { + objectMap.putAll(getContext().get().contextMap); + } + map.forEach((key, value) -> { + if (value == null || (value instanceof String && ((String) value).isEmpty())) { + objectMap.remove(key); + } else { + objectMap.put(key, value); + } + }); + return new Instance(this, objectMap); + } else { + return getContext().isPresent() ? getContext().get() : null; + } + } + + private static void setupContext( + final Map<String, Object> contextMap, + final Map<String, String> threadContextMap, + final Collection<String> contextStack, + final Instance context) { + Instance scopedContext = context; + // If the current context has a Map then we can just use it. + if (context.contextMap == null) { + do { + if (scopedContext.contextMap != null) { + // Once we hit a scope with an already populated Map we won't need to go any further. + contextMap.putAll(scopedContext.contextMap); + break; + } else if (scopedContext.key != null) { + contextMap.putIfAbsent(scopedContext.key, scopedContext.value); + } + scopedContext = scopedContext.parent; + } while (scopedContext != null); + scopedContext = new Instance(context.getProvider(), contextMap); + } + if (threadContextMap != null && !threadContextMap.isEmpty()) { + ThreadContext.putAll(threadContextMap); + } + if (contextStack != null) { + ThreadContext.setStack(contextStack); + } + context.getProvider().addScopedContext(scopedContext); + } + + private static final class Instance implements ScopedContext.Instance { + + private final DefaultScopedContextProvider provider; + private final Instance parent; + private final String key; + private final Object value; + private final Map<String, ?> contextMap; + + private Instance(final DefaultScopedContextProvider provider) { + this.provider = provider; + parent = null; + key = null; + value = null; + contextMap = null; + } + + private Instance(final DefaultScopedContextProvider provider, final Map<String, ?> map) { + this.provider = provider; + parent = null; + key = null; + value = null; + contextMap = map; + } + + private Instance(final DefaultScopedContextProvider provider, final String key, final Object value) { + this.provider = provider; + parent = null; + this.key = key; + this.value = value; + contextMap = null; + } + + private Instance(final Instance parent, final String key, final Object value) { + provider = parent.getProvider(); + this.parent = parent; + this.key = key; + this.value = value; + contextMap = null; + } + + public Instance getParent() { + return parent; + } + + /** + * Adds a key/value pair to the ScopedContext being constructed. + * + * @param key the key to add. + * @param value the value associated with the key. + * @return the ScopedContext being constructed. + */ + @Override + public Instance where(final String key, final Object value) { + return addObject(key, value); + } + + /** + * Adds a key/value pair to the ScopedContext being constructed. + * + * @param key the key to add. + * @param supplier the function to generate the value. + * @return the ScopedContext being constructed. + */ + @Override + public Instance where(final String key, final Supplier<Object> supplier) { + return addObject(key, supplier.get()); + } + + private Instance addObject(final String key, final Object obj) { + return obj != null ? new Instance(this, key, obj) : this; + } + + /** + * Executes a code block that includes all the key/value pairs added to the ScopedContext. + * + * @param task the code block to execute. + */ + @Override + public void run(final Runnable task) { + new Runner(this, null, null, task).run(); + } + + /** + * Executes a code block that includes all the key/value pairs added to the ScopedContext on a different Thread. + * + * @param task the code block to execute. + * @return a Future representing pending completion of the task + */ + @Override + public Future<Void> run(final ExecutorService executorService, final Runnable task) { + return executorService.submit( + new Runner(this, ThreadContext.getContext(), ThreadContext.getImmutableStack(), task), null); + } + + /** + * Executes a code block that includes all the key/value pairs added to the ScopedContext. + * + * @param task the code block to execute. + * @return the return value from the code block. + */ + @Override + public <R> R call(final Callable<R> task) throws Exception { + return new Caller<>(this, null, null, task).call(); + } + + /** + * Executes a code block that includes all the key/value pairs added to the ScopedContext on a different Thread. + * + * @param task the code block to execute. + * @return a Future representing pending completion of the task + */ + @Override + public <R> Future<R> call(final ExecutorService executorService, final Callable<R> task) { + return executorService.submit( + new Caller<>(this, ThreadContext.getContext(), ThreadContext.getImmutableStack(), task)); + } + + private DefaultScopedContextProvider getProvider() { + return provider; + } + } + + private static class Runner implements Runnable { + private final Map<String, Object> contextMap = new HashMap<>(); + private final Map<String, String> threadContextMap; + private final ThreadContext.ContextStack contextStack; + private final Instance context; Review Comment: Should we integrate the propagation of `ThreadContext` into `ScopedContext`? I have mixed feelings about that. Since this API is supposed to replace `ThreadContext`, maybe we should keep the propagation of the two separate. Users of `ThreadContext` do have ways to propagate it anyway. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
