1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache license, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the license for the specific language governing permissions and
15 * limitations under the license.
16 */
17 package org.apache.logging.log4j.spi;
18
19 import java.util.Map;
20
21 import org.apache.logging.log4j.ThreadContext;
22 import org.apache.logging.log4j.util.StringMap;
23
24 /**
25 * Read-only view of the data structure that implements MDC behavior for {@link org.apache.logging.log4j.ThreadContext}.
26 * <p>
27 * {@code ThreadContextMap} implementations that also implement this interface can be accessed
28 * by applications via the {@link ThreadContext#getThreadContextMap()} method.
29 * </p>
30 *
31 * @see ThreadContext#getThreadContextMap()
32 * @since 2.8
33 */
34 public interface ReadOnlyThreadContextMap {
35
36 /**
37 * Clears the context.
38 */
39 void clear();
40
41 /**
42 * Determines if the key is in the context.
43 * @param key The key to locate.
44 * @return True if the key is in the context, false otherwise.
45 */
46 boolean containsKey(final String key);
47
48 /**
49 * Gets the context identified by the <code>key</code> parameter.
50 *
51 * <p>This method has no side effects.</p>
52 * @param key The key to locate.
53 * @return The value associated with the key or null.
54 */
55 String get(final String key);
56
57 /**
58 * Gets a non-{@code null} mutable copy of current thread's context Map.
59 * @return a mutable copy of the context.
60 */
61 Map<String, String> getCopy();
62
63 /**
64 * Returns an immutable view on the context Map or {@code null} if the context map is empty.
65 * @return an immutable context Map or {@code null}.
66 */
67 Map<String, String> getImmutableMapOrNull();
68
69 /**
70 * Returns the context data for reading. Note that regardless of whether the returned context data has been
71 * {@linkplain StringMap#freeze() frozen} (made read-only) or not, callers should not attempt to modify
72 * the returned data structure.
73 * <p>
74 * <b>Thread safety note:</b>
75 * </p>
76 * <p>
77 * If this {@code ReadOnlyThreadContextMap} implements {@link CopyOnWrite}, then the returned {@code StringMap} can
78 * safely be passed to another thread: future changes in the underlying context data will not be reflected in the
79 * returned {@code StringMap}.
80 * </p><p>
81 * Otherwise, if this {@code ReadOnlyThreadContextMap} does <em>not</em> implement {@link CopyOnWrite}, then it is
82 * not safe to pass the returned {@code StringMap} to another thread because changes in the underlying context may
83 * be reflected in the returned object. It is the responsibility of the caller to make a copy to pass to another
84 * thread.
85 * </p>
86 *
87 * @return a {@code StringMap} containing context data key-value pairs
88 */
89 StringMap getReadOnlyContextData();
90
91 /**
92 * Returns true if the Map is empty.
93 * @return true if the Map is empty, false otherwise.
94 */
95 boolean isEmpty();
96 }