--- /dev/null
+/*
+ * 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.
+ */
+
+// Contributors: Dan Milstein
+// Ray Millard
+
+package org.apache.log4j;
+
+import java.util.Hashtable;
+import java.util.Stack;
+import java.util.Enumeration;
+import java.util.Vector;
+
+import org.apache.log4j.helpers.LogLog;
+
+/**
+ The NDC class implements <i>nested diagnostic contexts</i> as
+ defined by Neil Harrison in the article "Patterns for Logging
+ Diagnostic Messages" part of the book "<i>Pattern Languages of
+ Program Design 3</i>" edited by Martin et al.
+
+ <p>A Nested Diagnostic Context, or NDC in short, is an instrument
+ to distinguish interleaved log output from different sources. Log
+ output is typically interleaved when a server handles multiple
+ clients near-simultaneously.
+
+ <p>Interleaved log output can still be meaningful if each log entry
+ from different contexts had a distinctive stamp. This is where NDCs
+ come into play.
+
+ <p><em><b>Note that NDCs are managed on a per thread
+ basis</b></em>. NDC operations such as {@link #push push}, {@link
+ #pop}, {@link #clear}, {@link #getDepth} and {@link #setMaxDepth}
+ affect the NDC of the <em>current</em> thread only. NDCs of other
+ threads remain unaffected.
+
+ <p>For example, a servlet can build a per client request NDC
+ consisting the clients host name and other information contained in
+ the the request. <em>Cookies</em> are another source of distinctive
+ information. To build an NDC one uses the {@link #push push}
+ operation. Simply put,
+
+ <p><ul>
+ <li>Contexts can be nested.
+
+ <p><li>When entering a context, call <code>NDC.push</code>. As a
+ side effect, if there is no nested diagnostic context for the
+ current thread, this method will create it.
+
+ <p><li>When leaving a context, call <code>NDC.pop</code>.
+
+ <p><li><b>When exiting a thread make sure to call {@link #remove
+ NDC.remove()}</b>.
+ </ul>
+
+ <p>There is no penalty for forgetting to match each
+ <code>push</code> operation with a corresponding <code>pop</code>,
+ except the obvious mismatch between the real application context
+ and the context set in the NDC.
+
+ <p>If configured to do so, {@link PatternLayout} and {@link
+ TTCCLayout} instances automatically retrieve the nested diagnostic
+ context for the current thread without any user intervention.
+ Hence, even if a servlet is serving multiple clients
+ simultaneously, the logs emanating from the same code (belonging to
+ the same category) can still be distinguished because each client
+ request will have a different NDC tag.
+
+ <p>Heavy duty systems should call the {@link #remove} method when
+ leaving the run method of a thread. This ensures that the memory
+ used by the thread can be freed by the Java garbage
+ collector. There is a mechanism to lazily remove references to dead
+ threads. In practice, this means that you can be a little sloppy
+ and sometimes forget to call {@link #remove} before exiting a
+ thread.
+
+ <p>A thread may inherit the nested diagnostic context of another
+ (possibly parent) thread using the {@link #inherit inherit}
+ method. A thread may obtain a copy of its NDC with the {@link
+ #cloneStack cloneStack} method and pass the reference to any other
+ thread, in particular to a child.
+
+ @author Ceki Gülcü
+ @since 0.7.0
+
+*/
+
+public class NDC {
+
+ // The synchronized keyword is not used in this class. This may seem
+ // dangerous, especially since the class will be used by
+ // multiple-threads. In particular, all threads share the same
+ // hashtable (the "ht" variable). This is OK since java hashtables
+ // are thread safe. Same goes for Stacks.
+
+ // More importantly, when inheriting diagnostic contexts the child
+ // thread is handed a clone of the parent's NDC. It follows that
+ // each thread has its own NDC (i.e. stack).
+
+ static Hashtable ht = new Hashtable();
+
+ static int pushCounter = 0; // the number of times push has been called
+ // after the latest call to lazyRemove
+
+ // The number of times we allow push to be called before we call lazyRemove
+ // 5 is a relatively small number. As such, lazyRemove is not called too
+ // frequently. We thus avoid the cost of creating an Enumeration too often.
+ // The higher this number, the longer is the avarage period for which all
+ // logging calls in all threads are blocked.
+ static final int REAP_THRESHOLD = 5;
+
+ // No instances allowed.
+ private NDC() {}
+
+ /**
+ * Get NDC stack for current thread.
+ * @return NDC stack for current thread.
+ */
+ private static Stack getCurrentStack() {
+ if (ht != null) {
+ return (Stack) ht.get(Thread.currentThread());
+ }
+ return null;
+ }
+
+
+ /**
+ Clear any nested diagnostic information if any. This method is
+ useful in cases where the same thread can be potentially used
+ over and over in different unrelated contexts.
+
+ <p>This method is equivalent to calling the {@link #setMaxDepth}
+ method with a zero <code>maxDepth</code> argument.
+
+ @since 0.8.4c */
+ public
+ static
+ void clear() {
+ Stack stack = getCurrentStack();
+ if(stack != null) {
+ stack.setSize(0);
+ }
+ }
+
+
+ /**
+ Clone the diagnostic context for the current thread.
+
+ <p>Internally a diagnostic context is represented as a stack. A
+ given thread can supply the stack (i.e. diagnostic context) to a
+ child thread so that the child can inherit the parent thread's
+ diagnostic context.
+
+ <p>The child thread uses the {@link #inherit inherit} method to
+ inherit the parent's diagnostic context.
+
+ @return Stack A clone of the current thread's diagnostic context.
+
+ */
+ public
+ static
+ Stack cloneStack() {
+ Stack stack = getCurrentStack();
+ if(stack == null) {
+ return null;
+ } else {
+ return (Stack) stack.clone();
+ }
+ }
+
+
+ /**
+ Inherit the diagnostic context of another thread.
+
+ <p>The parent thread can obtain a reference to its diagnostic
+ context using the {@link #cloneStack} method. It should
+ communicate this information to its child so that it may inherit
+ the parent's diagnostic context.
+
+ <p>The parent's diagnostic context is cloned before being
+ inherited. In other words, once inherited, the two diagnostic
+ contexts can be managed independently.
+
+ <p>In java, a child thread cannot obtain a reference to its
+ parent, unless it is directly handed the reference. Consequently,
+ there is no client-transparent way of inheriting diagnostic
+ contexts. Do you know any solution to this problem?
+
+ @param stack The diagnostic context of the parent thread.
+
+ */
+ public
+ static
+ void inherit(Stack stack) {
+ if(stack != null) {
+ ht.put(Thread.currentThread(), stack);
+ }
+ }
+
+
+ /**
+ <font color="#FF4040"><b>Never use this method directly, use the {@link
+ org.apache.log4j.spi.LoggingEvent#getNDC} method instead</b></font>.
+ */
+ static
+ public
+ String get() {
+ Stack s = getCurrentStack();
+ if(s != null && !s.isEmpty()) {
+ return ((DiagnosticContext) s.peek()).fullMessage;
+ } else {
+ return null;
+ }
+ }
+
+ /**
+ * Get the current nesting depth of this diagnostic context.
+ *
+ * @see #setMaxDepth
+ * @since 0.7.5
+ */
+ public
+ static
+ int getDepth() {
+ Stack stack = getCurrentStack();
+ if(stack == null) {
+ return 0;
+ } else {
+ return stack.size();
+ }
+ }
+
+ private
+ static
+ void lazyRemove() {
+ if (ht == null) {
+ return;
+ }
+
+ // The synchronization on ht is necessary to prevent JDK 1.2.x from
+ // throwing ConcurrentModificationExceptions at us. This sucks BIG-TIME.
+ // One solution is to write our own hashtable implementation.
+ Vector v;
+
+ synchronized(ht) {
+ // Avoid calling clean-up too often.
+ if(++pushCounter <= REAP_THRESHOLD) {
+ return; // We release the lock ASAP.
+ } else {
+ pushCounter = 0; // OK let's do some work.
+ }
+
+ int misses = 0;
+ v = new Vector();
+ Enumeration enumeration = ht.keys();
+ // We give up after 4 straigt missses. That is 4 consecutive
+ // inspected threads in 'ht' that turn out to be alive.
+ // The higher the proportion on dead threads in ht, the higher the
+ // chances of removal.
+ while(enumeration.hasMoreElements() && (misses <= 4)) {
+ Thread t = (Thread) enumeration.nextElement();
+ if(t.isAlive()) {
+ misses++;
+ } else {
+ misses = 0;
+ v.addElement(t);
+ }
+ }
+ } // synchronized
+
+ int size = v.size();
+ for(int i = 0; i < size; i++) {
+ Thread t = (Thread) v.elementAt(i);
+ LogLog.debug("Lazy NDC removal for thread [" + t.getName() + "] ("+
+ ht.size() + ").");
+ ht.remove(t);
+ }
+ }
+
+ /**
+ Clients should call this method before leaving a diagnostic
+ context.
+
+ <p>The returned value is the value that was pushed last. If no
+ context is available, then the empty string "" is returned.
+
+ @return String The innermost diagnostic context.
+
+ */
+ public
+ static
+ String pop() {
+ Stack stack = getCurrentStack();
+ if(stack != null && !stack.isEmpty()) {
+ return ((DiagnosticContext) stack.pop()).message;
+ } else {
+ return "";
+ }
+ }
+
+ /**
+ 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.
+
+ @return String The innermost diagnostic context.
+
+ */
+ public
+ static
+ String peek() {
+ Stack stack = getCurrentStack();
+ if(stack != null && !stack.isEmpty()) {
+ return ((DiagnosticContext) stack.peek()).message;
+ } else {
+ return "";
+ }
+ }
+
+ /**
+ Push new diagnostic context information for the current thread.
+
+ <p>The contents of the <code>message</code> parameter is
+ determined solely by the client.
+
+ @param message The new diagnostic context information. */
+ public
+ static
+ void push(String message) {
+ Stack stack = getCurrentStack();
+
+ if(stack == null) {
+ DiagnosticContext dc = new DiagnosticContext(message, null);
+ stack = new Stack();
+ Thread key = Thread.currentThread();
+ ht.put(key, stack);
+ stack.push(dc);
+ } else if (stack.isEmpty()) {
+ DiagnosticContext dc = new DiagnosticContext(message, null);
+ stack.push(dc);
+ } else {
+ DiagnosticContext parent = (DiagnosticContext) stack.peek();
+ stack.push(new DiagnosticContext(message, parent));
+ }
+ }
+
+ /**
+ Remove 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>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.
+
+ */
+ static
+ public
+ void remove() {
+ if (ht != null) {
+ ht.remove(Thread.currentThread());
+
+ // Lazily remove dead-thread references in ht.
+ lazyRemove();
+ }
+ }
+
+ /**
+ Set maximum depth of this diagnostic context. If the current
+ depth is smaller or equal to <code>maxDepth</code>, then no
+ action is taken.
+
+ <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 NDC is
+ unpredictable. The <code>setMaxDepth</code> method circumvents
+ this problem.
+
+ <p>For example, the combination
+ <pre>
+ void foo() {
+ int depth = NDC.getDepth();
+
+ ... complex sequence of calls
+
+ NDC.setMaxDepth(depth);
+ }
+ </pre>
+
+ ensures that between the entry and exit of foo the depth of the
+ diagnostic stack is conserved.
+
+ @see #getDepth
+ @since 0.7.5 */
+ static
+ public
+ void setMaxDepth(int maxDepth) {
+ Stack stack = getCurrentStack();
+ if(stack != null && maxDepth < stack.size()) {
+ stack.setSize(maxDepth);
+ }
+ }
+
+ // =====================================================================
+ private static class DiagnosticContext {
+
+ String fullMessage;
+ String message;
+
+ DiagnosticContext(String message, DiagnosticContext parent) {
+ this.message = message;
+ if(parent != null) {
+ fullMessage = parent.fullMessage + ' ' + message;
+ } else {
+ fullMessage = message;
+ }
+ }
+ }
+}
+
git://source.jalview.org / jalview.git / blobdiff