Top Description Inners Fields Constructors Methods
org.slf4j

public Class MDC

extends Object
Class Inheritance
Imports
java.io.Closeable, java.util.Deque, .Map, org.slf4j.helpers.*, org.slf4j.spi.MDCAdapter, .SLF4JServiceProvider
This class hides and serves as a substitute for the underlying logging system's MDC implementation.

If the underlying logging system offers MDC functionality, then SLF4J's MDC, i.e. this class, will delegate to the underlying system's MDC. Note that at this time, only two logging systems, namely log4j and logback, offer MDC functionality. For java.util.logging which does not support MDC, BasicMDCAdapter will be used. For other systems, i.e. slf4j-simple and slf4j-nop, NOPMDCAdapter will be used.

Thus, as a SLF4J user, you can take advantage of MDC in the presence of log4j, logback, or java.util.logging, but without forcing these systems as dependencies upon your users.

For more information on MDC please see the chapter on MDC in the logback manual.

Please note that all methods in this class are static.

Author
Ceki Gülcü
Since
1.4.1

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
MDC.MDCCloseable

An adapter to remove the key when done.

Field Summary

Modifier and TypeField and Description
pack-priv static MDCAdapter
MDC_ADAPTER

private static final String
MDC_APAPTER_CANNOT_BE_NULL_MESSAGE

pack-priv static final String
NO_STATIC_MDC_BINDER_URL

pack-priv static final String
NULL_MDCA_URL

Constructor Summary

AccessConstructor and Description
private
MDC()

Method Summary

Modifier and TypeMethod and Description
public static void
clear()

Clear all entries in the MDC of the underlying implementation.

private static void
emitTemporaryMDCAdapterWarningIfNeeded(SLF4JServiceProvider provider)

public static String

Returns:

the string value identified by the key parameter.
get(String
a key
key)

Get the diagnostic context identified by the key parameter.

public static Map<String, String>

Returns:

A copy of the current thread's context map. May be null.
getCopyOfContextMap()

Return a copy of the current thread's context map, with keys and values of type String.

public Deque<String>

Returns:

copy of stack referenced by 'key'. May be null.
getCopyOfDequeByKey(String
identifies the stack
key)

Returns a copy of the deque(stack) referenced by 'key'.

public static MDCAdapter

Returns:

the MDcAdapter instance currently in use.
getMDCAdapter()

Returns the MDCAdapter instance currently in use.

private static MDCAdapter
getMDCAdapterGivenByProvider()

public static String

Returns:

the value just popped. May be null/
popByKey(String
identifies the deque(stack)
key)

Pop the stack referenced by 'key' and return the value possibly null.

public static void
pushByKey(String
identifies the appropriate stack
key, String
the value to push into the stack
value)

Push a value into the deque(stack) referenced by 'key'.

public static void
put(String
non-null key
key, String
value to put in the map
val)

Put a diagnostic context value (the val parameter) as identified with the key parameter into the current thread's diagnostic context map.

public static MDC.MDCCloseable

Returns:

a Closeable who can remove key when close is called.
putCloseable(String
non-null key
key, String
value to put in the map
val)

Put a diagnostic context value (the val parameter) as identified with the key parameter into the current thread's diagnostic context map.

public static void
remove(String
a key
key)

Remove the diagnostic context identified by the key parameter using the underlying system's MDC implementation.

public static void
setContextMap(Map<String, String>
must contain only keys and values of type String
contextMap)

Set the current thread's context map by first clearing any existing map and then copying the map passed as parameter.

pack-priv static void
setMDCAdapter(MDCAdapter anMDCAdapter)

Set MDCAdapter instance to use.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

MDC_ADAPTERback to summary
pack-priv static MDCAdapter MDC_ADAPTER
MDC_APAPTER_CANNOT_BE_NULL_MESSAGEback to summary
private static final String MDC_APAPTER_CANNOT_BE_NULL_MESSAGE
NO_STATIC_MDC_BINDER_URLback to summary
pack-priv static final String NO_STATIC_MDC_BINDER_URL
NULL_MDCA_URLback to summary
pack-priv static final String NULL_MDCA_URL

Constructor Detail

MDCback to summary
private MDC()

Method Detail

clearback to summary
public static void clear()

Clear all entries in the MDC of the underlying implementation.

emitTemporaryMDCAdapterWarningIfNeededback to summary
private static void emitTemporaryMDCAdapterWarningIfNeeded(SLF4JServiceProvider provider)
getback to summary
public static String get(String key) throws IllegalArgumentException

Get the diagnostic context identified by the key parameter. The key parameter cannot be null.

This method delegates all work to the MDC of the underlying logging system.

Parameters
key:String

a key

Returns:String

the string value identified by the key parameter.

Exceptions
IllegalArgumentException:
in case the "key" parameter is null
getCopyOfContextMapback to summary
public static Map<String, String> getCopyOfContextMap()

Return a copy of the current thread's context map, with keys and values of type String. Returned value may be null.

Returns:Map<String, String>

A copy of the current thread's context map. May be null.

Since
1.5.1
getCopyOfDequeByKeyback to summary
public Deque<String> getCopyOfDequeByKey(String key)

Returns a copy of the deque(stack) referenced by 'key'. May be null.

Parameters
key:String

identifies the stack

Returns:Deque<String>

copy of stack referenced by 'key'. May be null.

Since
2.0.0
getMDCAdapterback to summary
public static MDCAdapter getMDCAdapter()

Returns the MDCAdapter instance currently in use. Since 2.0.17, if the MDCAdapter instance is null, then this method set it to use the adapter returned by the SLF4JProvider. However, in the vast majority of cases the MDCAdapter will be set earlier (during initialization) by LoggerFactory.

Returns:MDCAdapter

the MDcAdapter instance currently in use.

Since
1.4.2
getMDCAdapterGivenByProviderback to summary
private static MDCAdapter getMDCAdapterGivenByProvider()
popByKeyback to summary
public static String popByKey(String key)

Pop the stack referenced by 'key' and return the value possibly null.

Parameters
key:String

identifies the deque(stack)

Returns:String

the value just popped. May be null/

Since
2.0.0
pushByKeyback to summary
public static void pushByKey(String key, String value)

Push a value into the deque(stack) referenced by 'key'.

Parameters
key:String

identifies the appropriate stack

value:String

the value to push into the stack

Since
2.0.0
putback to summary
public static void put(String key, String val) throws IllegalArgumentException

Put a diagnostic context value (the val parameter) as identified with the key parameter into the current thread's diagnostic context map. The key parameter cannot be null. The val parameter can be null only if the underlying implementation supports it.

This method delegates all work to the MDC of the underlying logging system.

Parameters
key:String

non-null key

val:String

value to put in the map

Exceptions
IllegalArgumentException:
in case the "key" parameter is null
putCloseableback to summary
public static MDC.MDCCloseable putCloseable(String key, String val) throws IllegalArgumentException

Put a diagnostic context value (the val parameter) as identified with the key parameter into the current thread's diagnostic context map. The key parameter cannot be null. The val parameter can be null only if the underlying implementation supports it.

This method delegates all work to the MDC of the underlying logging system.

This method return a Closeable object who can remove key when close is called.

Useful with Java 7 for example : try(MDC.MDCCloseable closeable = MDC.putCloseable(key, value)) { .... }

Parameters
key:String

non-null key

val:String

value to put in the map

Returns:MDC.MDCCloseable

a Closeable who can remove key when close is called.

Exceptions
IllegalArgumentException:
in case the "key" parameter is null
removeback to summary
public static void remove(String key) throws IllegalArgumentException

Remove the diagnostic context identified by the key parameter using the underlying system's MDC implementation. The key parameter cannot be null. This method does nothing if there is no previous value associated with key.

Parameters
key:String

a key

Exceptions
IllegalArgumentException:
in case the "key" parameter is null
setContextMapback to summary
public static void setContextMap(Map<String, String> contextMap)

Set the current thread's context map by first clearing any existing map and then copying the map passed as parameter. The context map passed as parameter must only contain keys and values of type String. Null valued argument is allowed (since SLF4J version 2.0.0).

Parameters
contextMap:Map<String, String>

must contain only keys and values of type String

Since
1.5.1
setMDCAdapterback to summary
pack-priv static void setMDCAdapter(MDCAdapter anMDCAdapter)

Set MDCAdapter instance to use.

Since
2.0.17
org.slf4j back to summary

public Class MDC.MDCCloseable

extends Object
implements Closeable
Class Inheritance
All Implemented Interfaces
java.io.Closeable, java.lang.AutoCloseable
An adapter to remove the key when done.

Field Summary

Modifier and TypeField and Description
private final String
key

Constructor Summary

AccessConstructor and Description
private
MDCCloseable(String key)

Method Summary

Modifier and TypeMethod and Description
public void
close()

Implements java.io.Closeable.close.

Closes this stream and releases any system resources associated with it.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

keyback to summary
private final String key

Constructor Detail

MDCCloseableback to summary
private MDCCloseable(String key)

Method Detail

closeback to summary
public void close()

Implements java.io.Closeable.close.

Doc from java.io.Closeable.close.

Closes this stream and releases any system resources associated with it. If the stream is already closed then invoking this method has no effect.

As noted in AutoCloseable#close(), cases where the close may fail require careful attention. It is strongly advised to relinquish the underlying resources and to internally mark the Closeable as closed, prior to throwing the IOException.