View Javadoc
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.core.config;
18  
19  import java.net.URI;
20  import java.util.ArrayList;
21  import java.util.List;
22  import java.util.Map;
23  import java.util.concurrent.TimeUnit;
24  
25  import org.apache.logging.log4j.Level;
26  import org.apache.logging.log4j.LogManager;
27  import org.apache.logging.log4j.Logger;
28  import org.apache.logging.log4j.core.LoggerContext;
29  import org.apache.logging.log4j.core.impl.Log4jContextFactory;
30  import org.apache.logging.log4j.core.util.NetUtils;
31  import org.apache.logging.log4j.spi.LoggerContextFactory;
32  import org.apache.logging.log4j.status.StatusLogger;
33  import org.apache.logging.log4j.util.Strings;
34  
35  /**
36   * Initializes and configure the Logging system. This class provides several ways to construct a LoggerContext using
37   * the location of a configuration file, a context name, and various optional parameters.
38   */
39  public final class Configurator {
40  
41      private static final String FQCN = Configurator.class.getName();
42  
43      private static final Logger LOGGER = StatusLogger.getLogger();
44  
45      private static Log4jContextFactory getFactory() {
46          final LoggerContextFactory factory = LogManager.getFactory();
47          if (factory instanceof Log4jContextFactory) {
48              return (Log4jContextFactory) factory;
49          } else if (factory != null) {
50              LOGGER.error("LogManager returned an instance of {} which does not implement {}. Unable to initialize Log4j.",
51                      factory.getClass().getName(), Log4jContextFactory.class.getName());
52              return null;
53          } else {
54              LOGGER.fatal("LogManager did not return a LoggerContextFactory. This indicates something has gone terribly wrong!");
55              return null;
56          }
57      }
58  
59      /**
60       * Initializes the Logging Context.
61       * @param loader The ClassLoader for the Context (or null).
62       * @param source The InputSource for the configuration.
63       * @return The LoggerContext.
64       */
65      public static LoggerContext initialize(final ClassLoader loader,
66                                             final ConfigurationSource source) {
67          return initialize(loader, source, null);
68      }
69  
70      /**
71       * Initializes the Logging Context.
72       * @param loader The ClassLoader for the Context (or null).
73       * @param source The InputSource for the configuration.
74       * @param externalContext The external context to be attached to the LoggerContext.
75       * @return The LoggerContext.
76       */
77  
78      public static LoggerContext initialize(final ClassLoader loader,
79                                             final ConfigurationSource source,
80                                             final Object externalContext)
81      {
82  
83          try {
84              final Log4jContextFactory factory = getFactory();
85              return factory == null ? null :
86                      factory.getContext(FQCN, loader, externalContext, false, source);
87          } catch (final Exception ex) {
88              LOGGER.error("There was a problem obtaining a LoggerContext using the configuration source [{}]", source, ex);
89          }
90          return null;
91      }
92  
93      /**
94       * Initializes the Logging Context.
95       * @param name The Context name.
96       * @param loader The ClassLoader for the Context (or null).
97       * @param configLocation The configuration for the logging context.
98       * @return The LoggerContext or null if an error occurred (check the status logger).
99       */
100     public static LoggerContext initialize(final String name, final ClassLoader loader, final String configLocation) {
101         return initialize(name, loader, configLocation, null);
102 
103     }
104 
105     /**
106      * Initializes the Logging Context.
107      * @param name The Context name.
108      * @param loader The ClassLoader for the Context (or null).
109      * @param configLocation The configuration for the logging context (or null, or blank).
110      * @param externalContext The external context to be attached to the LoggerContext
111      * @return The LoggerContext or null if an error occurred (check the status logger).
112      */
113     public static LoggerContext initialize(final String name, final ClassLoader loader, final String configLocation,
114             final Object externalContext) {
115         if (Strings.isBlank(configLocation)) {
116             return initialize(name, loader, (URI) null, externalContext);
117         }
118         if (configLocation.contains(",")) {
119             final String[] parts = configLocation.split(",");
120             String scheme = null;
121             final List<URI> uris = new ArrayList<>(parts.length);
122             for (final String part : parts) {
123                 final URI uri = NetUtils.toURI(scheme != null ? scheme + ":" + part.trim() : part.trim());
124                 if (scheme == null && uri.getScheme() != null) {
125                     scheme = uri.getScheme();
126                 }
127                 uris.add(uri);
128             }
129             return initialize(name, loader, uris, externalContext);
130         }
131         return initialize(name, loader, NetUtils.toURI(configLocation), externalContext);
132     }
133 
134     /**
135      * Initializes the Logging Context.
136      * @param name The Context name.
137      * @param loader The ClassLoader for the Context (or null).
138      * @param configLocation The configuration for the logging context.
139      * @return The LoggerContext.
140      */
141     public static LoggerContext initialize(final String name, final ClassLoader loader, final URI configLocation) {
142         return initialize(name, loader, configLocation, null);
143     }
144 
145     /**
146      * Initializes the Logging Context.
147      * @param name The Context name.
148      * @param loader The ClassLoader for the Context (or null).
149      * @param configLocation The configuration for the logging context (or null).
150      * @param externalContext The external context to be attached to the LoggerContext
151      * @return The LoggerContext.
152      */
153     public static LoggerContext initialize(final String name, final ClassLoader loader, final URI configLocation,
154                                            final Object externalContext) {
155 
156         try {
157             final Log4jContextFactory factory = getFactory();
158             return factory == null ? null :
159                     factory.getContext(FQCN, loader, externalContext, false, configLocation, name);
160         } catch (final Exception ex) {
161             LOGGER.error("There was a problem initializing the LoggerContext [{}] using configuration at [{}].",
162                     name, configLocation, ex);
163         }
164         return null;
165     }
166 
167     public static LoggerContext initialize(final String name, final ClassLoader loader, final List<URI> configLocations,
168             final Object externalContext) {
169         try {
170             final Log4jContextFactory factory = getFactory();
171             return factory == null ?
172                     null :
173                     factory.getContext(FQCN, loader, externalContext, false, configLocations, name);
174         } catch (final Exception ex) {
175             LOGGER.error("There was a problem initializing the LoggerContext [{}] using configurations at [{}].", name,
176                     configLocations, ex);
177         }
178         return null;
179     }
180 
181     /**
182      * Initializes the Logging Context.
183      * @param name The Context name.
184      * @param configLocation The configuration for the logging context.
185      * @return The LoggerContext or null if an error occurred (check the status logger).
186      */
187     public static LoggerContext initialize(final String name, final String configLocation) {
188         return initialize(name, null, configLocation);
189     }
190 
191     /**
192      * Initializes the Logging Context.
193      * @param configuration The Configuration.
194      * @return The LoggerContext.
195      */
196     public static LoggerContext initialize(final Configuration configuration) {
197         return initialize(null, configuration, null);
198     }
199 
200     /**
201      * Initializes the Logging Context.
202      * @param loader The ClassLoader.
203      * @param configuration The Configuration.
204      * @return The LoggerContext.
205      */
206     public static LoggerContext initialize(final ClassLoader loader, final Configuration configuration) {
207         return initialize(loader, configuration, null);
208     }
209 
210     /**
211      * Initializes the Logging Context.
212      * @param loader The ClassLoader.
213      * @param configuration The Configuration.
214      * @param externalContext - The external context to be attached to the LoggerContext.
215      * @return The LoggerContext.
216      */
217     public static LoggerContext initialize(final ClassLoader loader, final Configuration configuration, final Object externalContext) {
218         try {
219             final Log4jContextFactory factory = getFactory();
220             return factory == null ? null :
221                     factory.getContext(FQCN, loader, externalContext, false, configuration);
222         } catch (final Exception ex) {
223             LOGGER.error("There was a problem initializing the LoggerContext using configuration {}",
224                     configuration.getName(), ex);
225         }
226         return null;
227     }
228 
229     /**
230      * Sets the levels of <code>parentLogger</code> and all 'child' loggers to the given <code>level</code>.
231      * @param parentLogger the parent logger
232      * @param level the new level
233      */
234     public static void setAllLevels(final String parentLogger, final Level level) {
235         // 1) get logger config
236         // 2) if exact match, use it, if not, create it.
237         // 3) set level on logger config
238         // 4) update child logger configs with level
239         // 5) update loggers
240         final LoggerContext loggerContext = LoggerContext.getContext(false);
241         final Configuration config = loggerContext.getConfiguration();
242         boolean set = setLevel(parentLogger, level, config);
243         for (final Map.Entry<String, LoggerConfig> entry : config.getLoggers().entrySet()) {
244             if (entry.getKey().startsWith(parentLogger)) {
245                 set |= setLevel(entry.getValue(), level);
246             }
247         }
248         if (set) {
249             loggerContext.updateLoggers();
250         }
251     }
252 
253     private static boolean setLevel(final LoggerConfig loggerConfig, final Level level) {
254         final boolean set = !loggerConfig.getLevel().equals(level);
255         if (set) {
256             loggerConfig.setLevel(level);
257         }
258         return set;
259     }
260 
261     /**
262      * Sets logger levels.
263      *
264      * @param levelMap
265      *            a levelMap where keys are level names and values are new
266      *            Levels.
267      */
268     public static void setLevel(final Map<String, Level> levelMap) {
269         final LoggerContext loggerContext = LoggerContext.getContext(false);
270         final Configuration config = loggerContext.getConfiguration();
271         boolean set = false;
272         for (final Map.Entry<String, Level> entry : levelMap.entrySet()) {
273             final String loggerName = entry.getKey();
274             final Level level = entry.getValue();
275             set |= setLevel(loggerName, level, config);
276         }
277         if (set) {
278             loggerContext.updateLoggers();
279         }
280     }
281 
282     /**
283      * Sets a logger's level.
284      *
285      * @param loggerName
286      *            the logger name
287      * @param level
288      *            the new level
289      */
290     public static void setLevel(final String loggerName, final Level level) {
291         final LoggerContext loggerContext = LoggerContext.getContext(false);
292         if (Strings.isEmpty(loggerName)) {
293             setRootLevel(level);
294         } else {
295             if (setLevel(loggerName, level, loggerContext.getConfiguration())) {
296                 loggerContext.updateLoggers();
297             }
298         }
299     }
300 
301     private static boolean setLevel(final String loggerName, final Level level, final Configuration config) {
302         boolean set;
303         LoggerConfig loggerConfig = config.getLoggerConfig(loggerName);
304         if (!loggerName.equals(loggerConfig.getName())) {
305             // TODO Should additivity be inherited?
306             loggerConfig = new LoggerConfig(loggerName, level, true);
307             config.addLogger(loggerName, loggerConfig);
308             loggerConfig.setLevel(level);
309             set = true;
310         } else {
311             set = setLevel(loggerConfig, level);
312         }
313         return set;
314     }
315 
316     /**
317      * Sets the root logger's level.
318      *
319      * @param level
320      *            the new level
321      */
322     public static void setRootLevel(final Level level) {
323         final LoggerContext loggerContext = LoggerContext.getContext(false);
324         final LoggerConfig loggerConfig = loggerContext.getConfiguration().getRootLogger();
325         if (!loggerConfig.getLevel().equals(level)) {
326             loggerConfig.setLevel(level);
327             loggerContext.updateLoggers();
328         }
329     }
330 
331     /**
332      * Shuts down the given logger context. This request does not wait for Log4j tasks to complete.
333      * <p>
334      * Log4j starts threads to perform certain actions like file rollovers; calling this method will not wait until the
335      * rollover thread is done. When this method returns, these tasks' status are undefined, the tasks may be done or
336      * not.
337      * </p>
338      * 
339      * @param ctx
340      *            the logger context to shut down, may be null.
341      */
342     public static void shutdown(final LoggerContext ctx) {
343         if (ctx != null) {
344             ctx.stop();
345         }
346     }
347 
348     /**
349      * Blocks until all Log4j tasks have completed execution after a shutdown request, or the timeout occurs, or the
350      * current thread is interrupted, whichever happens first.
351      * <p>
352      * Log4j can start threads to perform certain actions like file rollovers, calling this method with a timeout will
353      * block until the rollover thread is done.
354      * </p>
355      * 
356      * @param ctx
357      *            the logger context to shut down, may be null.
358      * @param timeout
359      *            the maximum time to wait
360      * @param timeUnit
361      *            the time unit of the timeout argument
362      * @return {@code true} if the logger context terminated and {@code false} if the timeout elapsed before
363      *         termination.
364      */
365     public static boolean shutdown(final LoggerContext ctx, final long timeout, final TimeUnit timeUnit) {
366         if (ctx != null) {
367             return ctx.stop(timeout, timeUnit);
368         }
369         return true;
370     }
371 
372     private Configurator() {
373         // empty
374     }
375 }