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 org.apache.logging.log4j.Logger;
20 import org.apache.logging.log4j.message.MessageFactory;
21
22 /**
23 * Anchor point for logging implementations.
24 */
25 public interface LoggerContext {
26
27 /**
28 * Empty array.
29 */
30 LoggerContext[] EMPTY_ARRAY = {};
31
32 /**
33 * Gets the anchor for some other context, such as a ClassLoader or ServletContext.
34 * @return The external context.
35 */
36 Object getExternalContext();
37
38 /**
39 * Gets an ExtendedLogger using the fully qualified name of the Class as the Logger name.
40 * @param cls The Class whose name should be used as the Logger name.
41 * @return The logger.
42 * @since 2.14.0
43 */
44 default ExtendedLogger getLogger(Class<?> cls) {
45 final String canonicalName = cls.getCanonicalName();
46 return getLogger(canonicalName != null ? canonicalName : cls.getName());
47 }
48
49
50 /**
51 * Gets an ExtendedLogger using the fully qualified name of the Class as the Logger name.
52 * @param cls The Class whose name should be used as the Logger name.
53 * @param messageFactory The message factory is used only when creating a logger, subsequent use does not change the
54 * logger but will log a warning if mismatched.
55 * @return The logger.
56 * @since 2.14.0
57 */
58 default ExtendedLogger getLogger(Class<?> cls, MessageFactory messageFactory) {
59 final String canonicalName = cls.getCanonicalName();
60 return getLogger(canonicalName != null ? canonicalName : cls.getName(), messageFactory);
61 }
62
63 /**
64 * Gets an ExtendedLogger.
65 * @param name The name of the Logger to return.
66 * @return The logger with the specified name.
67 */
68 ExtendedLogger getLogger(String name);
69
70 /**
71 * Gets an ExtendedLogger.
72 * @param name The name of the Logger to return.
73 * @param messageFactory The message factory is used only when creating a logger, subsequent use does not change
74 * the logger but will log a warning if mismatched.
75 * @return The logger with the specified name.
76 */
77 ExtendedLogger getLogger(String name, MessageFactory messageFactory);
78
79 /**
80 * Gets the LoggerRegistry.
81 *
82 * @return the LoggerRegistry.
83 * @since 2.17.2
84 */
85 default LoggerRegistry<? extends Logger> getLoggerRegistry() {
86 return null;
87 }
88
89 /**
90 * Gets an object by its name.
91 * @param key The object's key.
92 * @return The Object that is associated with the key, if any.
93 * @since 2.13.0
94 */
95 default Object getObject(String key) {
96 return null;
97 }
98
99 /**
100 * Tests if a Logger with the specified name exists.
101 * @param name The Logger name to search for.
102 * @return true if the Logger exists, false otherwise.
103 */
104 boolean hasLogger(String name);
105
106 /**
107 * Tests if a Logger with the specified name and MessageFactory type exists.
108 * @param name The Logger name to search for.
109 * @param messageFactoryClass The message factory class to search for.
110 * @return true if the Logger exists, false otherwise.
111 * @since 2.5
112 */
113 boolean hasLogger(String name, Class<? extends MessageFactory> messageFactoryClass);
114
115 /**
116 * Tests if a Logger with the specified name and MessageFactory exists.
117 * @param name The Logger name to search for.
118 * @param messageFactory The message factory to search for.
119 * @return true if the Logger exists, false otherwise.
120 * @since 2.5
121 */
122 boolean hasLogger(String name, MessageFactory messageFactory);
123
124 /**
125 * Associates an object into the LoggerContext by name for later use.
126 * @param key The object's key.
127 * @param value The object.
128 * @return The previous object or null.
129 * @since 2.13.0
130 */
131 default Object putObject(String key, Object value) {
132 return null;
133 }
134
135 /**
136 * Associates an object into the LoggerContext by name for later use if an object is not already stored with that key.
137 * @param key The object's key.
138 * @param value The object.
139 * @return The previous object or null.
140 * @since 2.13.0
141 */
142 default Object putObjectIfAbsent(String key, Object value) {
143 return null;
144 }
145
146 /**
147 * Removes an object if it is present.
148 * @param key The object's key.
149 * @return The object if it was present, null if it was not.
150 * @since 2.13.0
151 */
152 default Object removeObject(String key) {
153 return null;
154 }
155
156 /**
157 * Removes an object if it is present and the provided object is stored.
158 * @param key The object's key.
159 * @param value The object.
160 * @return The object if it was present, null if it was not.
161 * @since 2.13.0
162 */
163 default boolean removeObject(String key, Object value) {
164 return false;
165 }
166 }
167