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.net.URISyntaxException;
21  
22  import org.apache.logging.log4j.LogManager;
23  import org.apache.logging.log4j.Logger;
24  import org.apache.logging.log4j.core.LoggerContext;
25  import org.apache.logging.log4j.core.impl.Log4jContextFactory;
26  import org.apache.logging.log4j.core.util.FileUtils;
27  import org.apache.logging.log4j.spi.LoggerContextFactory;
28  import org.apache.logging.log4j.status.StatusLogger;
29  
30  /**
31   * Initializes and configure the Logging system. This class provides several ways to construct a LoggerContext using
32   * the location of a configuration file, a context name, and various optional parameters.
33   */
34  public final class Configurator {
35  
36      private static final Logger LOGGER = StatusLogger.getLogger();
37  
38      private static final String FQCN = Configurator.class.getName();
39  
40      private Configurator() {
41      }
42  
43  
44      /**
45       * Initializes the Logging Context.
46       * @param name The Context name.
47       * @param loader The ClassLoader for the Context (or null).
48       * @param configLocation The configuration for the logging context.
49       * @return The LoggerContext.
50       */
51      public static LoggerContext initialize(final String name, final ClassLoader loader, final String configLocation) {
52          return initialize(name, loader, configLocation, null);
53  
54      }
55  
56      /**
57       * Initializes the Logging Context.
58       * @param name The Context name.
59       * @param loader The ClassLoader for the Context (or null).
60       * @param configLocation The configuration for the logging context.
61       * @param externalContext The external context to be attached to the LoggerContext
62       * @return The LoggerContext.
63       */
64      public static LoggerContext initialize(final String name, final ClassLoader loader, final String configLocation,
65                                             final Object externalContext) {
66  
67          try {
68              final URI uri = configLocation == null ? null : FileUtils.getCorrectedFilePathUri(configLocation);
69              return initialize(name, loader, uri, externalContext);
70          } catch (final URISyntaxException ex) {
71              LOGGER.error("There was a problem parsing the configuration location [{}].", configLocation, ex);
72          }
73          return null;
74      }
75  
76      /**
77       * Initializes the Logging Context.
78       * @param name The Context name.
79       * @param configLocation The configuration for the logging context.
80       * @return The LoggerContext.
81       */
82      public static LoggerContext initialize(final String name, final String configLocation) {
83          return initialize(name, null, configLocation);
84      }
85  
86      /**
87       * Initializes the Logging Context.
88       * @param name The Context name.
89       * @param loader The ClassLoader for the Context (or null).
90       * @param configLocation The configuration for the logging context.
91       * @return The LoggerContext.
92       */
93      public static LoggerContext initialize(final String name, final ClassLoader loader, final URI configLocation) {
94          return initialize(name, loader, configLocation, null);
95      }
96  
97      /**
98       * Initializes the Logging Context.
99       * @param name The Context name.
100      * @param loader The ClassLoader for the Context (or null).
101      * @param configLocation The configuration for the logging context.
102      * @param externalContext The external context to be attached to the LoggerContext
103      * @return The LoggerContext.
104      */
105     public static LoggerContext initialize(final String name, final ClassLoader loader, final URI configLocation,
106                                            final Object externalContext) {
107 
108         try {
109             final Log4jContextFactory factory = getFactory();
110             return factory == null ? null :
111                     factory.getContext(FQCN, loader, externalContext, false, configLocation, name);
112         } catch (final Exception ex) {
113             LOGGER.error("There was a problem initializing the LoggerContext [{}] using configuration at [{}].",
114                     name, configLocation, ex);
115         }
116         return null;
117     }
118 
119     /**
120      * Initializes the Logging Context.
121      * @param loader The ClassLoader for the Context (or null).
122      * @param source The InputSource for the configuration.
123      * @return The LoggerContext.
124      */
125     public static LoggerContext initialize(final ClassLoader loader,
126                                            final ConfigurationSource source) {
127         return initialize(loader, source, null);
128     }
129 
130     /**
131      * Initializes the Logging Context.
132      * @param loader The ClassLoader for the Context (or null).
133      * @param source The InputSource for the configuration.
134      * @param externalContext The external context to be attached to the LoggerContext.
135      * @return The LoggerContext.
136      */
137 
138     public static LoggerContext initialize(final ClassLoader loader,
139                                            final ConfigurationSource source,
140                                            final Object externalContext)
141     {
142 
143         try {
144             final Log4jContextFactory factory = getFactory();
145             return factory == null ? null :
146                     factory.getContext(FQCN, loader, externalContext, false, source);
147         } catch (final Exception ex) {
148             LOGGER.error("There was a problem obtaining a LoggerContext using the configuration source [{}]", source, ex);
149         }
150         return null;
151     }
152 
153     private static Log4jContextFactory getFactory() {
154         final LoggerContextFactory factory = LogManager.getFactory();
155         if (factory instanceof Log4jContextFactory) {
156             return (Log4jContextFactory) factory;
157         } else if (factory != null) {
158             LOGGER.error("LogManager returned an instance of {} which does not implement {}. Unable to initialize Log4j.",
159                     factory.getClass().getName(), Log4jContextFactory.class.getName());
160             return null;
161         } else {
162             LOGGER.error("LogManager did not return a LoggerContextFactory. This indicates something has gone terribly wrong!");
163             return null;
164         }
165     }
166 
167     /**
168      * Shuts down the given logging context.
169      * @param ctx the logging context to shut down, may be null.
170      */
171     public static void shutdown(final LoggerContext ctx) {
172         if (ctx != null) {
173             ctx.stop();
174         }
175     }
176 }