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