Checkstyle: DeclarationOrder; autoformatted Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/4432ec27 Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/4432ec27 Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/4432ec27
Branch: refs/heads/master Commit: 4432ec27e7eb3f35cf1c3019526e3346ed1c0d08 Parents: 2891a5d Author: rpopma <[email protected]> Authored: Thu Sep 24 08:59:37 2015 +0200 Committer: rpopma <[email protected]> Committed: Thu Sep 24 08:59:37 2015 +0200 ---------------------------------------------------------------------- .../org/apache/logging/log4j/ThreadContext.java | 143 +++++++++++-------- 1 file changed, 86 insertions(+), 57 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/4432ec27/log4j-api/src/main/java/org/apache/logging/log4j/ThreadContext.java ---------------------------------------------------------------------- diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/ThreadContext.java b/log4j-api/src/main/java/org/apache/logging/log4j/ThreadContext.java index bc63663..2b06e79 100644 --- a/log4j-api/src/main/java/org/apache/logging/log4j/ThreadContext.java +++ b/log4j-api/src/main/java/org/apache/logging/log4j/ThreadContext.java @@ -43,7 +43,7 @@ import org.apache.logging.log4j.util.ProviderUtil; * the mapped diagnostic context of its parent. * </p> */ -public final class ThreadContext { +public final class ThreadContext { /** * An empty read-only ThreadContextStack. @@ -95,7 +95,7 @@ public final class ThreadContext { // Same as java.util.Collections.EmptyList.hashCode() return 1; } - + @Override public ContextStack copy() { return this; @@ -149,6 +149,7 @@ public final class ThreadContext { /** * An empty iterator. Since Java 1.7 added the Collections.emptyIterator() method, we have to make do. + * * @param <E> the type of the empty iterator */ private static class EmptyIterator<E> implements Iterator<E> { @@ -173,7 +174,8 @@ public final class ThreadContext { * Empty, immutable Map. */ // ironically, this annotation gives an "unsupported @SuppressWarnings" warning in Eclipse - @SuppressWarnings("PublicStaticCollectionField") // I like irony, so I won't delete it... + @SuppressWarnings("PublicStaticCollectionField") + // I like irony, so I won't delete it... public static final Map<String, String> EMPTY_MAP = Collections.emptyMap(); /** @@ -198,7 +200,11 @@ public final class ThreadContext { static { init(); } - + + private ThreadContext() { + // empty + } + /** * <em>Consider private, used for testing.</em> */ @@ -235,7 +241,7 @@ public final class ThreadContext { break; } catch (final Exception e) { LOGGER.error("Unable to locate or load configured ThreadContextMap {}", - provider.getThreadContextMap(), e); + provider.getThreadContextMap(), e); contextMap = new DefaultThreadContextMap(useMap); } } @@ -247,17 +253,14 @@ public final class ThreadContext { } } - private ThreadContext() { - // empty - } - /** - * Puts a context value (the <code>value</code> parameter) as identified - * with the <code>key</code> parameter into the current thread's - * context map. + * Puts a context value (the <code>value</code> parameter) as identified with the <code>key</code> parameter into + * the current thread's context map. * - * <p>If the current thread does not have a context map it is - * created as a side effect.</p> + * <p> + * If the current thread does not have a context map it is created as a side effect. + * </p> + * * @param key The key name. * @param value The key value. */ @@ -268,7 +271,10 @@ public final class ThreadContext { /** * Gets the context value identified by the <code>key</code> parameter. * - * <p>This method has no side effects.</p> + * <p> + * This method has no side effects. + * </p> + * * @param key The key to locate. * @return The value associated with the key or null. */ @@ -278,6 +284,7 @@ public final class ThreadContext { /** * Removes the context value identified by the <code>key</code> parameter. + * * @param key The key to remove. */ public static void remove(final String key) { @@ -301,6 +308,7 @@ public final class ThreadContext { /** * Determines if the key is in the context. + * * @param key The key to locate. * @return True if the key is in the context, false otherwise. */ @@ -310,6 +318,7 @@ public final class ThreadContext { /** * Returns a mutable copy of current thread's context Map. + * * @return a mutable copy of the context. */ public static Map<String, String> getContext() { @@ -318,6 +327,7 @@ public final class ThreadContext { /** * Returns an immutable view of the current thread's context Map. + * * @return An immutable view of the ThreadContext Map. */ public static Map<String, String> getImmutableContext() { @@ -327,6 +337,7 @@ public final class ThreadContext { /** * Returns true if the Map is empty. + * * @return true if the Map is empty, false otherwise. */ public static boolean isEmpty() { @@ -342,6 +353,7 @@ public final class ThreadContext { /** * Returns a copy of this thread's stack. + * * @return A copy of this thread's stack. */ public static ContextStack cloneStack() { @@ -350,6 +362,7 @@ public final class ThreadContext { /** * Gets an immutable copy of this current thread's context stack. + * * @return an immutable copy of the ThreadContext stack. */ public static ContextStack getImmutableStack() { @@ -359,6 +372,7 @@ public final class ThreadContext { /** * Sets this thread's stack. + * * @param stack The stack to use. */ public static void setStack(final Collection<String> stack) { @@ -371,6 +385,7 @@ public final class ThreadContext { /** * Gets the current nesting depth of this thread's stack. + * * @return the number of items in the stack. * * @see #trim @@ -382,8 +397,10 @@ public final class ThreadContext { /** * Returns the value of the last item placed on the stack. * - * <p>The returned value is the value that was pushed last. If no - * context is available, then the empty string "" is returned.</p> + * <p> + * The returned value is the value that was pushed last. If no context is available, then the empty string "" is + * returned. + * </p> * * @return String The innermost diagnostic context. */ @@ -392,11 +409,12 @@ public final class ThreadContext { } /** - * Looks at the last diagnostic context at the top of this NDC - * without removing it. + * Looks at the last diagnostic context at the top of this NDC without removing it. * - * <p>The returned value is the value that was pushed last. If no - * context is available, then the empty string "" is returned.</p> + * <p> + * The returned value is the value that was pushed last. If no context is available, then the empty string "" is + * returned. + * </p> * * @return String The innermost diagnostic context. */ @@ -407,21 +425,24 @@ public final class ThreadContext { /** * Pushes new diagnostic context information for the current thread. * - * <p>The contents of the <code>message</code> parameter is - * determined solely by the client.</p> + * <p> + * The contents of the <code>message</code> parameter is determined solely by the client. + * </p> * * @param message The new diagnostic context information. */ public static void push(final String message) { contextStack.push(message); } + /** * Pushes new diagnostic context information for the current thread. * - * <p>The contents of the <code>message</code> and args parameters are - * determined solely by the client. The message will be treated as a format String - * and tokens will be replaced with the String value of the arguments in accordance - * with ParameterizedMessage.</p> + * <p> + * The contents of the <code>message</code> and args parameters are determined solely by the client. The message + * will be treated as a format String and tokens will be replaced with the String value of the arguments in + * accordance with ParameterizedMessage. + * </p> * * @param message The new diagnostic context information. * @param args Parameters for the message. @@ -433,50 +454,51 @@ public final class ThreadContext { /** * Removes the diagnostic context for this thread. * - * <p>Each thread that created a diagnostic context by calling - * {@link #push} should call this method before exiting. Otherwise, - * the memory used by the <b>thread</b> cannot be reclaimed by the - * VM.</p> + * <p> + * Each thread that created a diagnostic context by calling {@link #push} should call this method before exiting. + * Otherwise, the memory used by the <b>thread</b> cannot be reclaimed by the VM. + * </p> * - * <p>As this is such an important problem in heavy duty systems and - * because it is difficult to always guarantee that the remove - * method is called before exiting a thread, this method has been - * augmented to lazily remove references to dead threads. In - * practice, this means that you can be a little sloppy and - * occasionally forget to call {@link #remove} before exiting a - * thread. However, you must call <code>remove</code> sometime. If - * you never call it, then your application is sure to run out of - * memory.</p> + * <p> + * As this is such an important problem in heavy duty systems and because it is difficult to always guarantee that + * the remove method is called before exiting a thread, this method has been augmented to lazily remove references + * to dead threads. In practice, this means that you can be a little sloppy and occasionally forget to call + * {@link #remove} before exiting a thread. However, you must call <code>remove</code> sometime. If you never call + * it, then your application is sure to run out of memory. + * </p> */ public static void removeStack() { contextStack.clear(); } /** - * Trims elements from this diagnostic context. If the current - * depth is smaller or equal to <code>maxDepth</code>, then no - * action is taken. If the current depth is larger than newDepth - * then all elements at maxDepth or higher are discarded. + * Trims elements from this diagnostic context. If the current depth is smaller or equal to <code>maxDepth</code>, + * then no action is taken. If the current depth is larger than newDepth then all elements at maxDepth or higher are + * discarded. * - * <p>This method is a convenient alternative to multiple {@link - * #pop} calls. Moreover, it is often the case that at the end of - * complex call sequences, the depth of the ThreadContext is - * unpredictable. The <code>trim</code> method circumvents - * this problem.</p> + * <p> + * This method is a convenient alternative to multiple {@link #pop} calls. Moreover, it is often the case that at + * the end of complex call sequences, the depth of the ThreadContext is unpredictable. The <code>trim</code> method + * circumvents this problem. + * </p> * - * <p>For example, the combination</p> + * <p> + * For example, the combination + * </p> + * * <pre> * void foo() { * final int depth = ThreadContext.getDepth(); - * + * * // ... complex sequence of calls - * + * * ThreadContext.trim(depth); * } * </pre> * - * <p>ensures that between the entry and exit of {@code foo} the depth of the - * diagnostic stack is conserved.</p> + * <p> + * ensures that between the entry and exit of {@code foo} the depth of the diagnostic stack is conserved. + * </p> * * @see #getDepth * @param depth The number of elements to keep. @@ -492,6 +514,7 @@ public final class ThreadContext { /** * Returns the element at the top of the stack. + * * @return The element at the top of the stack. * @throws java.util.NoSuchElementException if the stack is empty. */ @@ -499,44 +522,50 @@ public final class ThreadContext { /** * Returns the element at the top of the stack without removing it or null if the stack is empty. + * * @return the element at the top of the stack or null if the stack is empty. */ String peek(); /** * Pushes an element onto the stack. + * * @param message The element to add. */ void push(String message); /** * Returns the number of elements in the stack. + * * @return the number of elements in the stack. */ int getDepth(); /** * Returns all the elements in the stack in a List. + * * @return all the elements in the stack in a List. */ List<String> asList(); /** * Trims elements from the end of the stack. + * * @param depth The maximum number of items in the stack to keep. */ void trim(int depth); /** * Returns a copy of the ContextStack. + * * @return a copy of the ContextStack. */ ContextStack copy(); /** - * Returns a ContextStack with the same contents as this ContextStack or {@code null}. - * Attempts to modify the returned stack may or may not throw an exception, but will not affect the contents - * of this ContextStack. + * Returns a ContextStack with the same contents as this ContextStack or {@code null}. Attempts to modify the + * returned stack may or may not throw an exception, but will not affect the contents of this ContextStack. + * * @return a ContextStack with the same contents as this ContextStack or {@code null}. */ ContextStack getImmutableStackOrNull();
