001/**
002 * Copyright (c) 2004-2011 QOS.ch
003 * All rights reserved.
004 *
005 * Permission is hereby granted, free  of charge, to any person obtaining
006 * a  copy  of this  software  and  associated  documentation files  (the
007 * "Software"), to  deal in  the Software without  restriction, including
008 * without limitation  the rights to  use, copy, modify,  merge, publish,
009 * distribute,  sublicense, and/or sell  copies of  the Software,  and to
010 * permit persons to whom the Software  is furnished to do so, subject to
011 * the following conditions:
012 *
013 * The  above  copyright  notice  and  this permission  notice  shall  be
014 * included in all copies or substantial portions of the Software.
015 *
016 * THE  SOFTWARE IS  PROVIDED  "AS  IS", WITHOUT  WARRANTY  OF ANY  KIND,
017 * EXPRESS OR  IMPLIED, INCLUDING  BUT NOT LIMITED  TO THE  WARRANTIES OF
018 * MERCHANTABILITY,    FITNESS    FOR    A   PARTICULAR    PURPOSE    AND
019 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
020 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
021 * OF CONTRACT, TORT OR OTHERWISE,  ARISING FROM, OUT OF OR IN CONNECTION
022 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
023 *
024 */
025package org.slf4j;
026
027import java.io.Closeable;
028import java.util.Map;
029
030import org.slf4j.helpers.BasicMDCAdapter;
031import org.slf4j.helpers.NOPMDCAdapter;
032import org.slf4j.helpers.Util;
033import org.slf4j.spi.MDCAdapter;
034import org.slf4j.spi.SLF4JServiceProvider;
035
036/**
037 * This class hides and serves as a substitute for the underlying logging
038 * system's MDC implementation.
039 * 
040 * <p>
041 * If the underlying logging system offers MDC functionality, then SLF4J's MDC,
042 * i.e. this class, will delegate to the underlying system's MDC. Note that at
043 * this time, only two logging systems, namely log4j and logback, offer MDC
044 * functionality. For java.util.logging which does not support MDC,
045 * {@link BasicMDCAdapter} will be used. For other systems, i.e. slf4j-simple
046 * and slf4j-nop, {@link NOPMDCAdapter} will be used.
047 *
048 * <p>
049 * Thus, as a SLF4J user, you can take advantage of MDC in the presence of log4j,
050 * logback, or java.util.logging, but without forcing these systems as
051 * dependencies upon your users.
052 * 
053 * <p>
054 * For more information on MDC please see the <a
055 * href="http://logback.qos.ch/manual/mdc.html">chapter on MDC</a> in the
056 * logback manual.
057 * 
058 * <p>
059 * Please note that all methods in this class are static.
060 * 
061 * @author Ceki G&uuml;lc&uuml;
062 * @since 1.4.1
063 */
064public class MDC {
065
066    static final String NULL_MDCA_URL = "http://www.slf4j.org/codes.html#null_MDCA";
067    static final String NO_STATIC_MDC_BINDER_URL = "http://www.slf4j.org/codes.html#no_static_mdc_binder";
068    static MDCAdapter mdcAdapter;
069
070    /**
071     * An adapter to remove the key when done.
072     */
073    public static class MDCCloseable implements Closeable {
074        private final String key;
075
076        private MDCCloseable(String key) {
077            this.key = key;
078        }
079
080        public void close() {
081            MDC.remove(this.key);
082        }
083    }
084
085    private MDC() {
086    }
087
088    static {
089        SLF4JServiceProvider provider = LoggerFactory.getProvider();
090        if (provider != null) {
091            mdcAdapter = provider.getMDCAdapter();
092        } else {
093            Util.report("Failed to find provider.");
094            Util.report("Defaulting to no-operation MDCAdapter implementation.");
095            mdcAdapter = new NOPMDCAdapter();
096        }
097    }
098
099    /**
100     * Put a diagnostic context value (the <code>val</code> parameter) as identified with the
101     * <code>key</code> parameter into the current thread's diagnostic context map. The
102     * <code>key</code> parameter cannot be null. The <code>val</code> parameter
103     * can be null only if the underlying implementation supports it.
104     * 
105     * <p>
106     * This method delegates all work to the MDC of the underlying logging system.
107     *
108     * @param key non-null key 
109     * @param val value to put in the map
110     * 
111     * @throws IllegalArgumentException
112     *           in case the "key" parameter is null
113     */
114    public static void put(String key, String val) throws IllegalArgumentException {
115        if (key == null) {
116            throw new IllegalArgumentException("key parameter cannot be null");
117        }
118        if (mdcAdapter == null) {
119            throw new IllegalStateException("MDCAdapter cannot be null. See also " + NULL_MDCA_URL);
120        }
121        mdcAdapter.put(key, val);
122    }
123
124    /**
125     * Put a diagnostic context value (the <code>val</code> parameter) as identified with the
126     * <code>key</code> parameter into the current thread's diagnostic context map. The
127     * <code>key</code> parameter cannot be null. The <code>val</code> parameter
128     * can be null only if the underlying implementation supports it.
129     *
130     * <p>
131     * This method delegates all work to the MDC of the underlying logging system.
132     * <p>
133     * This method return a <code>Closeable</code> object who can remove <code>key</code> when
134     * <code>close</code> is called.
135     *
136     * <p>
137     * Useful with Java 7 for example :
138     * <code>
139     *   try(MDC.MDCCloseable closeable = MDC.putCloseable(key, value)) {
140     *     ....
141     *   }
142     * </code>
143     *
144     * @param key non-null key
145     * @param val value to put in the map
146     * @return a <code>Closeable</code> who can remove <code>key</code> when <code>close</code>
147     * is called.
148     *
149     * @throws IllegalArgumentException
150     *           in case the "key" parameter is null
151     */
152    public static MDCCloseable putCloseable(String key, String val) throws IllegalArgumentException {
153        put(key, val);
154        return new MDCCloseable(key);
155    }
156
157    /**
158     * Get the diagnostic context identified by the <code>key</code> parameter. The
159     * <code>key</code> parameter cannot be null.
160     * 
161     * <p>
162     * This method delegates all work to the MDC of the underlying logging system.
163     *
164     * @param key  
165     * @return the string value identified by the <code>key</code> parameter.
166     * @throws IllegalArgumentException
167     *           in case the "key" parameter is null
168     */
169    public static String get(String key) throws IllegalArgumentException {
170        if (key == null) {
171            throw new IllegalArgumentException("key parameter cannot be null");
172        }
173
174        if (mdcAdapter == null) {
175            throw new IllegalStateException("MDCAdapter cannot be null. See also " + NULL_MDCA_URL);
176        }
177        return mdcAdapter.get(key);
178    }
179
180    /**
181     * Remove the diagnostic context identified by the <code>key</code> parameter using
182     * the underlying system's MDC implementation. The <code>key</code> parameter
183     * cannot be null. This method does nothing if there is no previous value
184     * associated with <code>key</code>.
185     *
186     * @param key  
187     * @throws IllegalArgumentException
188     *           in case the "key" parameter is null
189     */
190    public static void remove(String key) throws IllegalArgumentException {
191        if (key == null) {
192            throw new IllegalArgumentException("key parameter cannot be null");
193        }
194
195        if (mdcAdapter == null) {
196            throw new IllegalStateException("MDCAdapter cannot be null. See also " + NULL_MDCA_URL);
197        }
198        mdcAdapter.remove(key);
199    }
200
201    /**
202     * Clear all entries in the MDC of the underlying implementation.
203     */
204    public static void clear() {
205        if (mdcAdapter == null) {
206            throw new IllegalStateException("MDCAdapter cannot be null. See also " + NULL_MDCA_URL);
207        }
208        mdcAdapter.clear();
209    }
210
211    /**
212     * Return a copy of the current thread's context map, with keys and values of
213     * type String. Returned value may be null.
214     * 
215     * @return A copy of the current thread's context map. May be null.
216     * @since 1.5.1
217     */
218    public static Map<String, String> getCopyOfContextMap() {
219        if (mdcAdapter == null) {
220            throw new IllegalStateException("MDCAdapter cannot be null. See also " + NULL_MDCA_URL);
221        }
222        return mdcAdapter.getCopyOfContextMap();
223    }
224
225    /**
226     * Set the current thread's context map by first clearing any existing map and
227     * then copying the map passed as parameter. The context map passed as
228     * parameter must only contain keys and values of type String.
229     * 
230     * @param contextMap
231     *          must contain only keys and values of type String
232     * @since 1.5.1
233     */
234    public static void setContextMap(Map<String, String> contextMap) {
235        if (mdcAdapter == null) {
236            throw new IllegalStateException("MDCAdapter cannot be null. See also " + NULL_MDCA_URL);
237        }
238        mdcAdapter.setContextMap(contextMap);
239    }
240
241    /**
242     * Returns the MDCAdapter instance currently in use.
243     * 
244     * @return the MDcAdapter instance currently in use.
245     * @since 1.4.2
246     */
247    public static MDCAdapter getMDCAdapter() {
248        return mdcAdapter;
249    }
250
251}