1 /*
2 * ModeShape (http://www.modeshape.org)
3 * See the COPYRIGHT.txt file distributed with this work for information
4 * regarding copyright ownership. Some portions may be licensed
5 * to Red Hat, Inc. under one or more contributor license agreements.
6 * See the AUTHORS.txt file in the distribution for a full listing of
7 * individual contributors.
8 *
9 * ModeShape is free software. Unless otherwise indicated, all code in ModeShape
10 * is licensed to you under the terms of the GNU Lesser General Public License as
11 * published by the Free Software Foundation; either version 2.1 of
12 * the License, or (at your option) any later version.
13 *
14 * ModeShape is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this software; if not, write to the Free
21 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
22 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
23 */
24 package org.modeshape.common.util;
25
26 import net.jcip.annotations.Immutable;
27 import org.slf4j.MDC;
28
29 /**
30 * Provides a "mapped diagnostic context" (MDC) for use in capturing extra context information to be included in logs of
31 * multithreaded applications. Not all logging implementations support MDC, although a few do (including <a
32 * href="http://logging.apache.org/log4j/1.3/index.html">Log4J</a> and <a href="http://logback.qos.ch/">Logback</a>). Note that if
33 * the logging implementation does not support MDC, this information is ignored.
34 * <p>
35 * It can be difficult to understand what is going on within a multithreaded application. When multiple threads are working
36 * simultaneously, their log messages are mixed together. Thus, it's difficult to follow the log messages of a single thread. Log
37 * contexts provide a way to associate additional information with "the current context", and log messages can include that
38 * additional information in the messages.
39 * </p>
40 * <p>
41 * Log contexts are managed for you, and so using them is very straightforward. Typically, log contexts are used within
42 * well-defined activities, and additional information is recorded in the context at the beginning of the activity and cleared at
43 * the end of the activity.
44 * </p>
45 * <p>
46 * The following example shows how to set and clear this additional information:
47 *
48 * <pre>
49 * LogContext.set("username","jsmith");
50 * LogContext.set("operation","process");
51 * ...
52 * // do work here
53 * ...
54 * LogContext.clear();
55 * </pre>
56 *
57 * Note that the actually values would not be hardcoded but would be retrieved from other objects available at the time.
58 * </p>
59 * <p>
60 * If the logging system doesn't support MDC, then the additional information provided via LogContext is ignored. However, if the
61 * logging system is able to use MDC and it is set up with patterns that reference the keys, then those log messages will contain
62 * the values for those keys.
63 * </p>
64 */
65 @Immutable
66 public class LogContext {
67
68 /**
69 * Put a context value (the <code>val</code> parameter) as identified with the <code>key</code> parameter into the current
70 * thread's context map. The <code>key</code> parameter cannot be null. The code>val</code> parameter can be null only if the
71 * underlying implementation supports it.
72 * <p>
73 * This method delegates all work to the MDC of the underlying logging system.
74 *
75 * @param key the key
76 * @param value the value
77 * @throws IllegalArgumentException in case the "key" parameter is null
78 */
79 public static void set( String key,
80 String value ) {
81 MDC.put(key, value);
82 }
83
84 /**
85 * Get the context identified by the <code>key</code> parameter. The <code>key</code> parameter cannot be null.
86 * <p>
87 * This method delegates all work to the MDC of the underlying logging system.
88 *
89 * @param key the key
90 * @return the string value identified by the <code>key</code> parameter.
91 * @throws IllegalArgumentException in case the "key" parameter is null
92 */
93 public static String get( String key ) {
94 return MDC.get(key);
95 }
96
97 /**
98 * Remove the the context identified by the <code>key</code> parameter using the underlying system's MDC implementation. The
99 * <code>key</code> parameter cannot be null. This method does nothing if there is no previous value associated with
100 * <code>key</code>.
101 *
102 * @param key the key
103 * @throws IllegalArgumentException in case the "key" parameter is null
104 */
105 public static void remove( String key ) {
106 MDC.remove(key);
107 }
108
109 /**
110 * Clear all entries in the MDC of the underlying implementation.
111 */
112 public static void clear() {
113 MDC.clear();
114 }
115
116 }