001: /*
002: * Copyright 2001-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.commons.logging;
018:
019: import org.apache.commons.logging.impl.SLF4JLogFactory;
020:
021: /**
022: * <p>
023: * Factory for creating {@link Log} instances, which always delegates to an instance of
024: * {@link SLF4JLogFactory}.
025: *
026: * </p>
027: *
028: * @author Craig R. McClanahan
029: * @author Costin Manolache
030: * @author Richard A. Sitze
031: * @author Ceki Gülcü
032: */
033:
034: public abstract class LogFactory {
035:
036: static LogFactory logFactory = new SLF4JLogFactory();
037:
038: /**
039: * The name of the property used to identify the LogFactory implementation
040: * class name.
041: * <p>
042: * This property is not used but preserved here for compatibility.
043: */
044: public static final String FACTORY_PROPERTY = "org.apache.commons.logging.LogFactory";
045:
046: /**
047: * The fully qualified class name of the fallback <code>LogFactory</code>
048: * implementation class to use, if no other can be found.
049: *
050: * <p>This property is not used but preserved here for compatibility.
051: */
052: public static final String FACTORY_DEFAULT = "org.apache.commons.logging.impl.SLF4JLogFactory";
053:
054: /**
055: * The name of the properties file to search for.
056: * <p>
057: * This property is not used but preserved here for compatibility.
058: */
059: public static final String FACTORY_PROPERTIES = "commons-logging.properties";
060:
061: /**
062: * Protected constructor that is not available for public use.
063: */
064: protected LogFactory() {
065: }
066:
067: // --------------------------------------------------------- Public Methods
068:
069: /**
070: * Return the configuration attribute with the specified name (if any), or
071: * <code>null</code> if there is no such attribute.
072: *
073: * @param name
074: * Name of the attribute to return
075: */
076: public abstract Object getAttribute(String name);
077:
078: /**
079: * Return an array containing the names of all currently defined configuration
080: * attributes. If there are no such attributes, a zero length array is
081: * returned.
082: */
083: public abstract String[] getAttributeNames();
084:
085: /**
086: * Convenience method to derive a name from the specified class and call
087: * <code>getInstance(String)</code> with it.
088: *
089: * @param clazz
090: * Class for which a suitable Log name will be derived
091: *
092: * @exception LogConfigurationException
093: * if a suitable <code>Log</code> instance cannot be returned
094: */
095: public abstract Log getInstance(Class clazz)
096: throws LogConfigurationException;
097:
098: /**
099: * <p>
100: * Construct (if necessary) and return a <code>Log</code> instance, using
101: * the factory's current set of configuration attributes.
102: * </p>
103: *
104: * <p>
105: * <strong>NOTE </strong>- Depending upon the implementation of the
106: * <code>LogFactory</code> you are using, the <code>Log</code> instance
107: * you are returned may or may not be local to the current application, and
108: * may or may not be returned again on a subsequent call with the same name
109: * argument.
110: * </p>
111: *
112: * @param name
113: * Logical name of the <code>Log</code> instance to be returned
114: * (the meaning of this name is only known to the underlying logging
115: * implementation that is being wrapped)
116: *
117: * @exception LogConfigurationException
118: * if a suitable <code>Log</code> instance cannot be returned
119: */
120: public abstract Log getInstance(String name)
121: throws LogConfigurationException;
122:
123: /**
124: * Release any internal references to previously created {@link Log}instances
125: * returned by this factory. This is useful in environments like servlet
126: * containers, which implement application reloading by throwing away a
127: * ClassLoader. Dangling references to objects in that class loader would
128: * prevent garbage collection.
129: */
130: public abstract void release();
131:
132: /**
133: * Remove any configuration attribute associated with the specified name. If
134: * there is no such attribute, no action is taken.
135: *
136: * @param name
137: * Name of the attribute to remove
138: */
139: public abstract void removeAttribute(String name);
140:
141: /**
142: * Set the configuration attribute with the specified name. Calling this with
143: * a <code>null</code> value is equivalent to calling
144: * <code>removeAttribute(name)</code>.
145: *
146: * @param name
147: * Name of the attribute to set
148: * @param value
149: * Value of the attribute to set, or <code>null</code> to remove
150: * any setting for this attribute
151: */
152: public abstract void setAttribute(String name, Object value);
153:
154: // --------------------------------------------------------- Static Methods
155:
156: /**
157: * <p>
158: * Construct (if necessary) and return a <code>LogFactory</code> instance,
159: * using the following ordered lookup procedure to determine the name of the
160: * implementation class to be loaded.
161: * </p>
162: * <ul>
163: * <li>The <code>org.apache.commons.logging.LogFactory</code> system
164: * property.</li>
165: * <li>The JDK 1.3 Service Discovery mechanism</li>
166: * <li>Use the properties file <code>commons-logging.properties</code>
167: * file, if found in the class path of this class. The configuration file is
168: * in standard <code>java.util.Properties</code> format and contains the
169: * fully qualified name of the implementation class with the key being the
170: * system property defined above.</li>
171: * <li>Fall back to a default implementation class (
172: * <code>org.apache.commons.logging.impl.SLF4FLogFactory</code>).</li>
173: * </ul>
174: *
175: * <p>
176: * <em>NOTE</em>- If the properties file method of identifying the
177: * <code>LogFactory</code> implementation class is utilized, all of the
178: * properties defined in this file will be set as configuration attributes on
179: * the corresponding <code>LogFactory</code> instance.
180: * </p>
181: *
182: * @exception LogConfigurationException
183: * if the implementation class is not available or cannot be
184: * instantiated.
185: */
186: public static LogFactory getFactory()
187: throws LogConfigurationException {
188: return logFactory;
189: }
190:
191: /**
192: * Convenience method to return a named logger, without the application having
193: * to care about factories.
194: *
195: * @param clazz
196: * Class from which a log name will be derived
197: *
198: * @exception LogConfigurationException
199: * if a suitable <code>Log</code> instance cannot be returned
200: */
201: public static Log getLog(Class clazz)
202: throws LogConfigurationException {
203: return (getFactory().getInstance(clazz));
204: }
205:
206: /**
207: * Convenience method to return a named logger, without the application having
208: * to care about factories.
209: *
210: * @param name
211: * Logical name of the <code>Log</code> instance to be returned
212: * (the meaning of this name is only known to the underlying logging
213: * implementation that is being wrapped)
214: *
215: * @exception LogConfigurationException
216: * if a suitable <code>Log</code> instance cannot be returned
217: */
218: public static Log getLog(String name)
219: throws LogConfigurationException {
220: return (getFactory().getInstance(name));
221: }
222:
223: /**
224: * Release any internal references to previously created {@link LogFactory}
225: * instances that have been associated with the specified class loader (if
226: * any), after calling the instance method <code>release()</code> on each of
227: * them.
228: *
229: * @param classLoader
230: * ClassLoader for which to release the LogFactory
231: */
232: public static void release(ClassLoader classLoader) {
233: // since SLF4J based JCL does not make use of classloaders, there is nothing
234: // to do here
235: }
236:
237: /**
238: * Release any internal references to previously created {@link LogFactory}
239: * instances, after calling the instance method <code>release()</code> on
240: * each of them. This is useful in environments like servlet containers, which
241: * implement application reloading by throwing away a ClassLoader. Dangling
242: * references to objects in that class loader would prevent garbage
243: * collection.
244: */
245: public static void releaseAll() {
246: // since SLF4J based JCL does not make use of classloaders, there is nothing
247: // to do here
248: }
249:
250: }
|