1 /**
2 * Copyright (c) 2004-2011 QOS.ch
3 * All rights reserved.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining
6 * a copy of this software and associated documentation files (the
7 * "Software"), to deal in the Software without restriction, including
8 * without limitation the rights to use, copy, modify, merge, publish,
9 * distribute, sublicense, and/or sell copies of the Software, and to
10 * permit persons to whom the Software is furnished to do so, subject to
11 * the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be
14 * included in all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 *
24 */
25 package org.slf4j.spi;
26
27 import java.util.Deque;
28 import java.util.Map;
29
30 /**
31 * This interface abstracts the service offered by various MDC
32 * implementations.
33 *
34 * @author Ceki Gülcü
35 * @since 1.4.1
36 */
37 public interface MDCAdapter {
38
39 /**
40 * Put a context value (the <code>val</code> parameter) as identified with
41 * the <code>key</code> parameter into the current thread's context map.
42 * The <code>key</code> parameter cannot be null. The <code>val</code> parameter
43 * can be null only if the underlying implementation supports it.
44 *
45 * <p>If the current thread does not have a context map it is created as a side
46 * effect of this call.
47 */
48 public void put(String key, String val);
49
50 /**
51 * Get the context identified by the <code>key</code> parameter.
52 * The <code>key</code> parameter cannot be null.
53 *
54 * @return the string value identified by the <code>key</code> parameter.
55 */
56 public String get(String key);
57
58 /**
59 * Remove the the context identified by the <code>key</code> parameter.
60 * The <code>key</code> parameter cannot be null.
61 *
62 * <p>
63 * This method does nothing if there is no previous value
64 * associated with <code>key</code>.
65 */
66 public void remove(String key);
67
68 /**
69 * Clear all entries in the MDC.
70 */
71 public void clear();
72
73 /**
74 * Return a copy of the current thread's context map, with keys and
75 * values of type String. Returned value may be null.
76 *
77 * @return A copy of the current thread's context map. May be null.
78 * @since 1.5.1
79 */
80 public Map<String, String> getCopyOfContextMap();
81
82 /**
83 * Set the current thread's context map by first clearing any existing
84 * map and then copying the map passed as parameter. The context map
85 * parameter must only contain keys and values of type String.
86 *
87 * Implementations must support null valued map passed as parameter.
88 *
89 * @param contextMap must contain only keys and values of type String
90 *
91 * @since 1.5.1
92 */
93 public void setContextMap(Map<String, String> contextMap);
94
95 /**
96 * Push a value into the deque(stack) referenced by 'key'.
97 *
98 * @param key identifies the appropriate stack
99 * @param value the value to push into the stack
100 * @since 2.0.0
101 */
102 public void pushByKey(String key, String value);
103
104 /**
105 * Pop the stack referenced by 'key' and return the value possibly null.
106 *
107 * @param key identifies the deque(stack)
108 * @return the value just popped. May be null/
109 * @since 2.0.0
110 */
111 public String popByKey(String key);
112
113 /**
114 * Returns a copy of the deque(stack) referenced by 'key'. May be null.
115 *
116 * @param key identifies the stack
117 * @return copy of stack referenced by 'key'. May be null.
118 *
119 * @since 2.0.0
120 */
121 public Deque<String> getCopyOfDequeByKey(String key);
122
123
124 /**
125 * Clear the deque(stack) referenced by 'key'.
126 *
127 * @param key identifies the stack
128 *
129 * @since 2.0.0
130 */
131 public void clearDequeByKey(String key);
132
133 }