001: /*
002: * Copyright (c) 2004-2007 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:
025: package org.slf4j;
026:
027: import org.slf4j.helpers.Util;
028: import org.slf4j.impl.StaticMDCBinder;
029: import org.slf4j.spi.MDCAdapter;
030:
031: /**
032: * This class hides and serves as a substitute for the underlying logging
033: * system's MDC implementation.
034: *
035: * <p>
036: * If the underlying logging system offers MDC functionality, then SLF4J's MDC,
037: * i.e. this class, will delegate to the underlying system's MDC. Note that at
038: * this time, only two logging systems, namely log4j and logback, offer MDC
039: * functionality. If the undelying system does not support MDC, then SLF4J will
040: * silently drop MDC information.
041: *
042: * <p>
043: * Thus, as a SLF4J user, you can take advantage of MDC in the presence of log4j
044: * or logback, but without forcing log4j or logback as dependencies upon your
045: * users.
046: *
047: * <p>
048: * For more information on MDC please see the <a
049: * href="http://logback.qos.ch/manual/mdc.html">chapter on MDC</a> in the
050: * logback manual.
051: *
052: * <p>
053: * Please note that all methods in this class are static.
054: *
055: * @author Ceki Gülcü
056: * @since 1.4.1
057: */
058: public class MDC {
059:
060: static final String NULL_MDCA_URL = "http://www.slf4j.org/codes.html#null_MDCA";
061: static final String NO_STATIC_MDC_BINDER_URL = "http://www.slf4j.org/codes.html#no_static_mdc_binder";
062: static MDCAdapter mdcAdapter;
063:
064: private MDC() {
065: }
066:
067: static {
068: try {
069: mdcAdapter = StaticMDCBinder.SINGLETON.getMDCA();
070: } catch (NoClassDefFoundError ncde) {
071: String msg = ncde.getMessage();
072: if (msg != null
073: && msg.indexOf("org/slf4j/impl/StaticMDCBinder") != -1) {
074: Util
075: .reportFailure("Failed to load class \"org.slf4j.impl.StaticMDCBinder\".");
076: Util.reportFailure("See " + NO_STATIC_MDC_BINDER_URL
077: + " for further details.");
078:
079: }
080: throw ncde;
081: } catch (Exception e) {
082: // we should never get here
083: Util.reportFailure(
084: "Could not bind with an instance of class ["
085: + StaticMDCBinder.SINGLETON
086: .getMDCAdapterClassStr() + "]", e);
087: }
088: }
089:
090: /**
091: * Put a context value (the <code>val</code> parameter) as identified with
092: * the <code>key</code> parameter into the current thread's context map.
093: * The <code>key</code> parameter cannot be null. The code>val</code> parameter
094: * can be null only if the underlying implementation supports it.
095: *
096: * <p>
097: * This method delegates all work to the MDC of the underlying logging system.
098: *
099: * @throws IllegalArgumentException in case the "key" parameter is null
100: */
101: public static void put(String key, String val)
102: throws IllegalArgumentException {
103: if (key == null) {
104: throw new IllegalArgumentException(
105: "key parameter cannot be null");
106: }
107: if (mdcAdapter == null) {
108: throw new IllegalStateException(
109: "MDCAdapter cannot be null. See also "
110: + NULL_MDCA_URL);
111: }
112: mdcAdapter.put(key, val);
113: }
114:
115: /**
116: * Get the context identified by the <code>key</code> parameter. The
117: * <code>key</code> parameter cannot be null.
118: *
119: * <p>This method delegates all work to the MDC of the underlying logging system.
120: *
121: * @return the string value identified by the <code>key</code> parameter.
122: * @throws IllegalArgumentException in case the "key" parameter is null
123: */
124: public static String get(String key)
125: throws IllegalArgumentException {
126: if (key == null) {
127: throw new IllegalArgumentException(
128: "key parameter cannot be null");
129: }
130:
131: if (mdcAdapter == null) {
132: throw new IllegalStateException(
133: "MDCAdapter cannot be null. See also "
134: + NULL_MDCA_URL);
135: }
136: return mdcAdapter.get(key);
137: }
138:
139: /**
140: * Remove the the context identified by the <code>key</code> parameter using
141: * the underlying system's MDC implementation. The <code>key</code> parameter
142: * cannot be null. This method does nothing if there is no previous value
143: * associated with <code>key</code>.
144: *
145: * @throws IllegalArgumentException in case the "key" parameter is null
146: */
147: public static void remove(String key)
148: throws IllegalArgumentException {
149: if (key == null) {
150: throw new IllegalArgumentException(
151: "key parameter cannot be null");
152: }
153:
154: if (mdcAdapter == null) {
155: throw new IllegalStateException(
156: "MDCAdapter cannot be null. See also "
157: + NULL_MDCA_URL);
158: }
159: mdcAdapter.remove(key);
160: }
161:
162: /**
163: * Clear all entries in the MDC of the underlying implementation.
164: */
165: public static void clear() {
166: if (mdcAdapter == null) {
167: throw new IllegalStateException(
168: "MDCAdapter cannot be null. See also "
169: + NULL_MDCA_URL);
170: }
171: mdcAdapter.clear();
172: }
173:
174: /**
175: * Returns the MDCAdapter instance currently in use.
176: *
177: * @return the MDcAdapter instance currently in use.
178: * @since 1.4.2
179: */
180: public static MDCAdapter getMDCAdapter() {
181: return mdcAdapter;
182: }
183: }
|