001 /*
002 * JBoss DNA (http://www.jboss.org/dna)
003 * See the COPYRIGHT.txt file distributed with this work for information
004 * regarding copyright ownership. Some portions may be licensed
005 * to Red Hat, Inc. under one or more contributor license agreements.
006 * See the AUTHORS.txt file in the distribution for a full listing of
007 * individual contributors.
008 *
009 * JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA
010 * is licensed to you under the terms of the GNU Lesser General Public License as
011 * published by the Free Software Foundation; either version 2.1 of
012 * the License, or (at your option) any later version.
013 *
014 * JBoss DNA is distributed in the hope that it will be useful,
015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
017 * Lesser General Public License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this software; if not, write to the Free
021 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
022 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
023 */
024 package org.jboss.dna.common.util;
025
026 import org.slf4j.MDC;
027
028 /**
029 * Provides a "mapped diagnostic context" (MDC) for use in capturing extra context information to be included in logs of
030 * multithreaded applications. Not all logging implementations support MDC, although a few do (including <a
031 * href="http://logging.apache.org/log4j/1.3/index.html">Log4J</a> and <a href="http://logback.qos.ch/">Logback</a>). Note that
032 * if the logging implementation does not support MDC, this information is ignored.
033 * <p>
034 * It can be difficult to understand what is going on within a multithreaded application. When multiple threads are working
035 * simultaneously, their log messages are mixed together. Thus, it's difficult to follow the log messages of a single thread. Log
036 * contexts provide a way to associate additional information with "the current context", and log messages can include that
037 * additional information in the messages.
038 * </p>
039 * <p>
040 * Log contexts are managed for you, and so using them is very straightforward. Typically, log contexts are used within
041 * well-defined activities, and additional information is recorded in the context at the beginning of the activity and cleared at
042 * the end of the activity.
043 * </p>
044 * <p>
045 * The following example shows how to set and clear this additional information:
046 *
047 * <pre>
048 * LogContext.set("username","jsmith");
049 * LogContext.set("operation","process");
050 * ...
051 * // do work here
052 * ...
053 * LogContext.clear();
054 * </pre>
055 *
056 * Note that the actually values would not be hardcoded but would be retrieved from other objects available at the time.
057 * </p>
058 * <p>
059 * If the logging system doesn't support MDC, then the additional information provided via LogContext is ignored. However, if the
060 * logging system is able to use MDC and it is set up with patterns that reference the keys, then those log messages will contain
061 * the values for those keys.
062 * </p>
063 */
064 public class LogContext {
065
066 /**
067 * Put a context value (the <code>val</code> parameter) as identified with the <code>key</code> parameter into the current
068 * thread's context map. The <code>key</code> parameter cannot be null. The code>val</code> parameter can be null only if
069 * the underlying implementation supports it.
070 * <p>
071 * This method delegates all work to the MDC of the underlying logging system.
072 * @param key the key
073 * @param value the value
074 * @throws IllegalArgumentException in case the "key" parameter is null
075 */
076 public static void set( String key, String value ) {
077 MDC.put(key, value);
078 }
079
080 /**
081 * Get the context identified by the <code>key</code> parameter. The <code>key</code> parameter cannot be null.
082 * <p>
083 * This method delegates all work to the MDC of the underlying logging system.
084 * @param key the key
085 * @return the string value identified by the <code>key</code> parameter.
086 * @throws IllegalArgumentException in case the "key" parameter is null
087 */
088 public static String get( String key ) {
089 return MDC.get(key);
090 }
091
092 /**
093 * Remove the the context identified by the <code>key</code> parameter using the underlying system's MDC implementation. The
094 * <code>key</code> parameter cannot be null. This method does nothing if there is no previous value associated with
095 * <code>key</code>.
096 * @param key the key
097 * @throws IllegalArgumentException in case the "key" parameter is null
098 */
099 public static void remove( String key ) {
100 MDC.remove(key);
101 }
102
103 /**
104 * Clear all entries in the MDC of the underlying implementation.
105 */
106 public static void clear() {
107 MDC.clear();
108 }
109
110 }