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ülcü 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 }