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 java.util.Hashtable; 20 21 import org.apache.commons.logging.impl.SLF4JLogFactory; 22 23 /** 24 * <p> 25 * Factory for creating {@link Log} instances, which always delegates to an 26 * instance of {@link SLF4JLogFactory}. 27 * 28 * </p> 29 * 30 * @author Craig R. McClanahan 31 * @author Costin Manolache 32 * @author Richard A. Sitze 33 * @author Ceki Gülcü 34 */ 35 36 public abstract class LogFactory { 37 38 static String UNSUPPORTED_OPERATION_IN_JCL_OVER_SLF4J = "http://www.slf4j.org/codes.html#unsupported_operation_in_jcl_over_slf4j"; 39 40 static LogFactory logFactory = new SLF4JLogFactory(); 41 42 /** 43 * The name (<code>priority</code>) of the key in the config file used to 44 * specify the priority of that particular config file. The associated value 45 * is a floating-point number; higher values take priority over lower values. 46 * 47 * <p> 48 * This property is not used but preserved here for compatibility. 49 */ 50 public static final String PRIORITY_KEY = "priority"; 51 52 /** 53 * The name (<code>use_tccl</code>) of the key in the config file used to 54 * specify whether logging classes should be loaded via the thread context 55 * class loader (TCCL), or not. By default, the TCCL is used. 56 * 57 * <p> 58 * This property is not used but preserved here for compatibility. 59 */ 60 public static final String TCCL_KEY = "use_tccl"; 61 62 /** 63 * The name of the property used to identify the LogFactory implementation 64 * class name. 65 * <p> 66 * This property is not used but preserved here for compatibility. 67 */ 68 public static final String FACTORY_PROPERTY = "org.apache.commons.logging.LogFactory"; 69 70 /** 71 * The fully qualified class name of the fallback <code>LogFactory</code> 72 * implementation class to use, if no other can be found. 73 * 74 * <p> 75 * This property is not used but preserved here for compatibility. 76 */ 77 public static final String FACTORY_DEFAULT = "org.apache.commons.logging.impl.SLF4JLogFactory"; 78 79 /** 80 * The name of the properties file to search for. 81 * <p> 82 * This property is not used but preserved here for compatibility. 83 */ 84 public static final String FACTORY_PROPERTIES = "commons-logging.properties"; 85 86 87 /** 88 * JDK1.3+ <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Service%20Provider"> 89 * 'Service Provider' specification</a>. 90 * <p> 91 * This property is not used but preserved here for compatibility. 92 */ 93 protected static final String SERVICE_ID = 94 "META-INF/services/org.apache.commons.logging.LogFactory"; 95 96 /** 97 * The name (<code>org.apache.commons.logging.diagnostics.dest</code>) of 98 * the property used to enable internal commons-logging diagnostic output, in 99 * order to get information on what logging implementations are being 100 * discovered, what classloaders they are loaded through, etc. 101 * 102 * <p> 103 * This property is not used but preserved here for compatibility. 104 */ 105 public static final String DIAGNOSTICS_DEST_PROPERTY = "org.apache.commons.logging.diagnostics.dest"; 106 107 /** 108 * <p> 109 * Setting this system property value allows the <code>Hashtable</code> used 110 * to store classloaders to be substituted by an alternative implementation. 111 * <p> 112 * This property is not used but preserved here for compatibility. 113 */ 114 public static final String HASHTABLE_IMPLEMENTATION_PROPERTY = "org.apache.commons.logging.LogFactory.HashtableImpl"; 115 116 /** 117 * The previously constructed <code>LogFactory</code> instances, keyed by 118 * the <code>ClassLoader</code> with which it was created. 119 * 120 * <p> 121 * This property is not used but preserved here for compatibility. 122 */ 123 protected static Hashtable factories = null; 124 125 /** 126 * <p> 127 * This property is not used but preserved here for compatibility. 128 */ 129 protected static LogFactory nullClassLoaderFactory = null; 130 131 /** 132 * Protected constructor that is not available for public use. 133 */ 134 protected LogFactory() { 135 } 136 137 // --------------------------------------------------------- Public Methods 138 139 /** 140 * Return the configuration attribute with the specified name (if any), or 141 * <code>null</code> if there is no such attribute. 142 * 143 * @param name 144 * Name of the attribute to return 145 */ 146 public abstract Object getAttribute(String name); 147 148 /** 149 * Return an array containing the names of all currently defined configuration 150 * attributes. If there are no such attributes, a zero length array is 151 * returned. 152 */ 153 public abstract String[] getAttributeNames(); 154 155 /** 156 * Convenience method to derive a name from the specified class and call 157 * <code>getInstance(String)</code> with it. 158 * 159 * @param clazz 160 * Class for which a suitable Log name will be derived 161 * 162 * @exception LogConfigurationException 163 * if a suitable <code>Log</code> instance cannot be 164 * returned 165 */ 166 public abstract Log getInstance(Class clazz) throws LogConfigurationException; 167 168 /** 169 * <p> 170 * Construct (if necessary) and return a <code>Log</code> instance, using 171 * the factory's current set of configuration attributes. 172 * </p> 173 * 174 * <p> 175 * <strong>NOTE </strong>- Depending upon the implementation of the 176 * <code>LogFactory</code> you are using, the <code>Log</code> instance 177 * you are returned may or may not be local to the current application, and 178 * may or may not be returned again on a subsequent call with the same name 179 * argument. 180 * </p> 181 * 182 * @param name 183 * Logical name of the <code>Log</code> instance to be 184 * returned (the meaning of this name is only known to the 185 * underlying logging implementation that is being wrapped) 186 * 187 * @exception LogConfigurationException 188 * if a suitable <code>Log</code> instance cannot be 189 * returned 190 */ 191 public abstract Log getInstance(String name) throws LogConfigurationException; 192 193 /** 194 * Release any internal references to previously created {@link Log}instances 195 * returned by this factory. This is useful in environments like servlet 196 * containers, which implement application reloading by throwing away a 197 * ClassLoader. Dangling references to objects in that class loader would 198 * prevent garbage collection. 199 */ 200 public abstract void release(); 201 202 /** 203 * Remove any configuration attribute associated with the specified name. If 204 * there is no such attribute, no action is taken. 205 * 206 * @param name 207 * Name of the attribute to remove 208 */ 209 public abstract void removeAttribute(String name); 210 211 /** 212 * Set the configuration attribute with the specified name. Calling this with 213 * a <code>null</code> value is equivalent to calling 214 * <code>removeAttribute(name)</code>. 215 * 216 * @param name 217 * Name of the attribute to set 218 * @param value 219 * Value of the attribute to set, or <code>null</code> to 220 * remove any setting for this attribute 221 */ 222 public abstract void setAttribute(String name, Object value); 223 224 // --------------------------------------------------------- Static Methods 225 226 /** 227 * <p> 228 * Construct (if necessary) and return a <code>LogFactory</code> instance, 229 * using the following ordered lookup procedure to determine the name of the 230 * implementation class to be loaded. 231 * </p> 232 * <ul> 233 * <li>The <code>org.apache.commons.logging.LogFactory</code> system 234 * property.</li> 235 * <li>The JDK 1.3 Service Discovery mechanism</li> 236 * <li>Use the properties file <code>commons-logging.properties</code> 237 * file, if found in the class path of this class. The configuration file is 238 * in standard <code>java.util.Properties</code> format and contains the 239 * fully qualified name of the implementation class with the key being the 240 * system property defined above.</li> 241 * <li>Fall back to a default implementation class ( 242 * <code>org.apache.commons.logging.impl.SLF4FLogFactory</code>).</li> 243 * </ul> 244 * 245 * <p> 246 * <em>NOTE</em>- If the properties file method of identifying the 247 * <code>LogFactory</code> implementation class is utilized, all of the 248 * properties defined in this file will be set as configuration attributes on 249 * the corresponding <code>LogFactory</code> instance. 250 * </p> 251 * 252 * @exception LogConfigurationException 253 * if the implementation class is not available or cannot 254 * be instantiated. 255 */ 256 public static LogFactory getFactory() throws LogConfigurationException { 257 return logFactory; 258 } 259 260 /** 261 * Convenience method to return a named logger, without the application having 262 * to care about factories. 263 * 264 * @param clazz 265 * Class from which a log name will be derived 266 * 267 * @exception LogConfigurationException 268 * if a suitable <code>Log</code> instance cannot be 269 * returned 270 */ 271 public static Log getLog(Class clazz) throws LogConfigurationException { 272 return (getFactory().getInstance(clazz)); 273 } 274 275 /** 276 * Convenience method to return a named logger, without the application having 277 * to care about factories. 278 * 279 * @param name 280 * Logical name of the <code>Log</code> instance to be 281 * returned (the meaning of this name is only known to the 282 * underlying logging implementation that is being wrapped) 283 * 284 * @exception LogConfigurationException 285 * if a suitable <code>Log</code> instance cannot be 286 * returned 287 */ 288 public static Log getLog(String name) throws LogConfigurationException { 289 return (getFactory().getInstance(name)); 290 } 291 292 /** 293 * Release any internal references to previously created {@link LogFactory} 294 * instances that have been associated with the specified class loader (if 295 * any), after calling the instance method <code>release()</code> on each of 296 * them. 297 * 298 * @param classLoader 299 * ClassLoader for which to release the LogFactory 300 */ 301 public static void release(ClassLoader classLoader) { 302 // since SLF4J based JCL does not make use of classloaders, there is nothing 303 // to do here 304 } 305 306 /** 307 * Release any internal references to previously created {@link LogFactory} 308 * instances, after calling the instance method <code>release()</code> on 309 * each of them. This is useful in environments like servlet containers, which 310 * implement application reloading by throwing away a ClassLoader. Dangling 311 * references to objects in that class loader would prevent garbage 312 * collection. 313 */ 314 public static void releaseAll() { 315 // since SLF4J based JCL does not make use of classloaders, there is nothing 316 // to do here 317 } 318 319 /** 320 * Returns a string that uniquely identifies the specified object, including 321 * its class. 322 * <p> 323 * The returned string is of form "classname@hashcode", ie is the same as the 324 * return value of the Object.toString() method, but works even when the 325 * specified object's class has overidden the toString method. 326 * 327 * @param o 328 * may be null. 329 * @return a string of form classname@hashcode, or "null" if param o is null. 330 * @since 1.1 331 */ 332 public static String objectId(Object o) { 333 if (o == null) { 334 return "null"; 335 } else { 336 return o.getClass().getName() + "@" + System.identityHashCode(o); 337 } 338 } 339 340 // protected methods which were added in JCL 1.1. These are not used 341 // by SLF4JLogFactory 342 343 /** 344 * This method exists to ensure signature compatibility. 345 */ 346 protected static Object createFactory(String factoryClass, ClassLoader classLoader) { 347 throw new UnsupportedOperationException( 348 "Operation [factoryClass] is not supported in jcl-over-slf4j. See also " 349 + UNSUPPORTED_OPERATION_IN_JCL_OVER_SLF4J); 350 } 351 352 /** 353 * This method exists to ensure signature compatibility. 354 */ 355 protected static ClassLoader directGetContextClassLoader() { 356 throw new UnsupportedOperationException( 357 "Operation [directGetContextClassLoader] is not supported in jcl-over-slf4j. See also " 358 + UNSUPPORTED_OPERATION_IN_JCL_OVER_SLF4J); 359 } 360 361 /** 362 * This method exists to ensure signature compatibility. 363 */ 364 protected static ClassLoader getContextClassLoader() 365 throws LogConfigurationException { 366 throw new UnsupportedOperationException( 367 "Operation [getContextClassLoader] is not supported in jcl-over-slf4j. See also " 368 + UNSUPPORTED_OPERATION_IN_JCL_OVER_SLF4J); 369 } 370 371 /** 372 * This method exists to ensure signature compatibility. 373 */ 374 protected static ClassLoader getClassLoader(Class clazz) { 375 throw new UnsupportedOperationException( 376 "Operation [getClassLoader] is not supported in jcl-over-slf4j. See also " 377 + UNSUPPORTED_OPERATION_IN_JCL_OVER_SLF4J); 378 } 379 380 /** 381 * This method exists to ensure signature compatibility. 382 */ 383 protected static boolean isDiagnosticsEnabled() { 384 throw new UnsupportedOperationException( 385 "Operation [isDiagnosticsEnabled] is not supported in jcl-over-slf4j. See also " 386 + UNSUPPORTED_OPERATION_IN_JCL_OVER_SLF4J); 387 } 388 389 /** 390 * This method exists to ensure signature compatibility. 391 */ 392 protected static void logRawDiagnostic(String msg) { 393 throw new UnsupportedOperationException( 394 "Operation [logRawDiagnostic] is not supported in jcl-over-slf4j. See also " 395 + UNSUPPORTED_OPERATION_IN_JCL_OVER_SLF4J); 396 } 397 398 /** 399 * This method exists to ensure signature compatibility. 400 */ 401 protected static LogFactory newFactory(final String factoryClass, 402 final ClassLoader classLoader, final ClassLoader contextClassLoader) { 403 throw new UnsupportedOperationException( 404 "Operation [logRawDiagnostic] is not supported in jcl-over-slf4j. See also " 405 + UNSUPPORTED_OPERATION_IN_JCL_OVER_SLF4J); 406 } 407 408 /** 409 * This method exists to ensure signature compatibility. 410 */ 411 protected static LogFactory newFactory(final String factoryClass, 412 final ClassLoader classLoader) { 413 throw new UnsupportedOperationException( 414 "Operation [newFactory] is not supported in jcl-over-slf4j. See also " 415 + UNSUPPORTED_OPERATION_IN_JCL_OVER_SLF4J); 416 } 417 418 419 }