LogFactory


1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.apache.commons.logging;
18  
19  import org.apache.commons.logging.impl.SLF4JLogFactory;
20  
21  /**
22   * <p>
23   * Factory for creating {@link Log} instances, which always delegates to an instance of
24   * {@link SLF4JLogFactory}.
25   * 
26   * </p>
27   * 
28   * @author Craig R. McClanahan
29   * @author Costin Manolache
30   * @author Richard A. Sitze
31   * @author Ceki G&uuml;lc&uuml; 
32   */
33  
34  public abstract class LogFactory {
35  
36    static LogFactory logFactory = new SLF4JLogFactory();
37  
38    /**
39     * The name of the property used to identify the LogFactory implementation
40     * class name.
41     * <p>
42     * This property is not used but preserved here for compatibility.
43     */
44    public static final String   FACTORY_PROPERTY =
45        "org.apache.commons.logging.LogFactory";
46  
47    /**
48     * The fully qualified class name of the fallback <code>LogFactory</code>
49     * implementation class to use, if no other can be found. 
50     * 
51     * <p>This property is not used but preserved here for compatibility.
52     */
53    public static final String   FACTORY_DEFAULT =
54        "org.apache.commons.logging.impl.SLF4JLogFactory";
55  
56    /**
57     * The name of the properties file to search for. 
58     * <p>
59     * This property is not used but preserved here for compatibility.
60     */
61    public static final String   FACTORY_PROPERTIES =
62        "commons-logging.properties";
63  
64    
65    /**
66     * Protected constructor that is not available for public use.
67     */
68    protected LogFactory() {
69    }
70  
71    // --------------------------------------------------------- Public Methods
72  
73    /**
74     * Return the configuration attribute with the specified name (if any), or
75     * <code>null</code> if there is no such attribute.
76     * 
77     * @param name
78     *          Name of the attribute to return
79     */
80    public abstract Object   getAttribute(String   name);
81  
82    /**
83     * Return an array containing the names of all currently defined configuration
84     * attributes. If there are no such attributes, a zero length array is
85     * returned.
86     */
87    public abstract String  [] getAttributeNames();
88  
89    /**
90     * Convenience method to derive a name from the specified class and call
91     * <code>getInstance(String)</code> with it.
92     * 
93     * @param clazz
94     *          Class for which a suitable Log name will be derived
95     * 
96     * @exception LogConfigurationException
97     *              if a suitable <code>Log</code> instance cannot be returned
98     */
99    public abstract Log getInstance(Class   clazz) throws LogConfigurationException;
100 
101   /**
102    * <p>
103    * Construct (if necessary) and return a <code>Log</code> instance, using
104    * the factory's current set of configuration attributes.
105    * </p>
106    * 
107    * <p>
108    * <strong>NOTE </strong>- Depending upon the implementation of the
109    * <code>LogFactory</code> you are using, the <code>Log</code> instance
110    * you are returned may or may not be local to the current application, and
111    * may or may not be returned again on a subsequent call with the same name
112    * argument.
113    * </p>
114    * 
115    * @param name
116    *          Logical name of the <code>Log</code> instance to be returned
117    *          (the meaning of this name is only known to the underlying logging
118    *          implementation that is being wrapped)
119    * 
120    * @exception LogConfigurationException
121    *              if a suitable <code>Log</code> instance cannot be returned
122    */
123   public abstract Log getInstance(String   name) throws LogConfigurationException;
124 
125   /**
126    * Release any internal references to previously created {@link Log}instances
127    * returned by this factory. This is useful in environments like servlet
128    * containers, which implement application reloading by throwing away a
129    * ClassLoader. Dangling references to objects in that class loader would
130    * prevent garbage collection.
131    */
132   public abstract void release();
133 
134   /**
135    * Remove any configuration attribute associated with the specified name. If
136    * there is no such attribute, no action is taken.
137    * 
138    * @param name
139    *          Name of the attribute to remove
140    */
141   public abstract void removeAttribute(String   name);
142 
143   /**
144    * Set the configuration attribute with the specified name. Calling this with
145    * a <code>null</code> value is equivalent to calling
146    * <code>removeAttribute(name)</code>.
147    * 
148    * @param name
149    *          Name of the attribute to set
150    * @param value
151    *          Value of the attribute to set, or <code>null</code> to remove
152    *          any setting for this attribute
153    */
154   public abstract void setAttribute(String   name, Object   value);
155 
156   // --------------------------------------------------------- Static Methods
157 
158   /**
159    * <p>
160    * Construct (if necessary) and return a <code>LogFactory</code> instance,
161    * using the following ordered lookup procedure to determine the name of the
162    * implementation class to be loaded.
163    * </p>
164    * <ul>
165    * <li>The <code>org.apache.commons.logging.LogFactory</code> system
166    * property.</li>
167    * <li>The JDK 1.3 Service Discovery mechanism</li>
168    * <li>Use the properties file <code>commons-logging.properties</code>
169    * file, if found in the class path of this class. The configuration file is
170    * in standard <code>java.util.Properties</code> format and contains the
171    * fully qualified name of the implementation class with the key being the
172    * system property defined above.</li>
173    * <li>Fall back to a default implementation class (
174    * <code>org.apache.commons.logging.impl.SLF4FLogFactory</code>).</li>
175    * </ul>
176    * 
177    * <p>
178    * <em>NOTE</em>- If the properties file method of identifying the
179    * <code>LogFactory</code> implementation class is utilized, all of the
180    * properties defined in this file will be set as configuration attributes on
181    * the corresponding <code>LogFactory</code> instance.
182    * </p>
183    * 
184    * @exception LogConfigurationException
185    *              if the implementation class is not available or cannot be
186    *              instantiated.
187    */
188   public static LogFactory getFactory() throws LogConfigurationException {
189     return logFactory;
190   }
191 
192   /**
193    * Convenience method to return a named logger, without the application having
194    * to care about factories.
195    * 
196    * @param clazz
197    *          Class from which a log name will be derived
198    * 
199    * @exception LogConfigurationException
200    *              if a suitable <code>Log</code> instance cannot be returned
201    */
202   public static Log getLog(Class   clazz) throws LogConfigurationException {
203 
204     return (getFactory().getInstance(clazz));
205   }
206 
207   /**
208    * Convenience method to return a named logger, without the application having
209    * to care about factories.
210    * 
211    * @param name
212    *          Logical name of the <code>Log</code> instance to be returned
213    *          (the meaning of this name is only known to the underlying logging
214    *          implementation that is being wrapped)
215    * 
216    * @exception LogConfigurationException
217    *              if a suitable <code>Log</code> instance cannot be returned
218    */
219   public static Log getLog(String   name) throws LogConfigurationException {
220 
221     return (getFactory().getInstance(name));
222 
223   }
224 
225   /**
226    * Release any internal references to previously created {@link LogFactory}
227    * instances that have been associated with the specified class loader (if
228    * any), after calling the instance method <code>release()</code> on each of
229    * them.
230    * 
231    * @param classLoader
232    *          ClassLoader for which to release the LogFactory
233    */
234   public static void release(ClassLoader   classLoader) {
235     // since SLF4J based JCL does not make use of classloaders, there is nothing
236     // to do here
237   }
238 
239   /**
240    * Release any internal references to previously created {@link LogFactory}
241    * instances, after calling the instance method <code>release()</code> on
242    * each of them. This is useful in environments like servlet containers, which
243    * implement application reloading by throwing away a ClassLoader. Dangling
244    * references to objects in that class loader would prevent garbage
245    * collection.
246    */
247   public static void releaseAll() {
248     // since SLF4J based JCL does not make use of classloaders, there is nothing
249     // to do here
250   }
251 
252 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags