in src/main/java/org/apache/commons/logging/LogFactory.java [225:353]
public abstract Log getInstance(Class clazz)
throws LogConfigurationException;
/**
* Construct (if necessary) and return a {@code Log} instance,
* using the factory's current set of configuration attributes.
* <p>
* <strong>NOTE</strong> - Depending upon the implementation of
* the {@code LogFactory} you are using, the {@code Log}
* instance you are returned may or may not be local to the current
* application, and may or may not be returned again on a subsequent
* call with the same name argument.
*
* @param name Logical name of the {@code Log} instance to be
* returned (the meaning of this name is only known to the underlying
* logging implementation that is being wrapped)
* @throws LogConfigurationException if a suitable {@code Log}
* instance cannot be returned
*/
public abstract Log getInstance(String name)
throws LogConfigurationException;
/**
* Release any internal references to previously created {@link Log}
* instances returned by this factory. This is useful in environments
* like servlet containers, which implement application reloading by
* throwing away a ClassLoader. Dangling references to objects in that
* class loader would prevent garbage collection.
*/
public abstract void release();
/**
* Remove any configuration attribute associated with the specified name.
* If there is no such attribute, no action is taken.
*
* @param name Name of the attribute to remove
*/
public abstract void removeAttribute(String name);
/**
* Set the configuration attribute with the specified name. Calling
* this with a {@code null} value is equivalent to calling
* {@code removeAttribute(name)}.
*
* @param name Name of the attribute to set
* @param value Value of the attribute to set, or {@code null}
* to remove any setting for this attribute
*/
public abstract void setAttribute(String name, Object value);
// ------------------------------------------------------- Static Variables
/**
* The previously constructed {@code LogFactory} instances, keyed by
* the {@code ClassLoader} with which it was created.
*/
protected static Hashtable factories;
/**
* Previously constructed {@code LogFactory} instance as in the
* {@code factories} map, but for the case where
* {@code getClassLoader} returns {@code null}.
* This can happen when:
* <ul>
* <li>using JDK1.1 and the calling code is loaded via the system
* classloader (very common)</li>
* <li>using JDK1.2+ and the calling code is loaded via the boot
* classloader (only likely for embedded systems work).</li>
* </ul>
* Note that {@code factories} is a <i>Hashtable</i> (not a HashMap),
* and hashtables don't allow null as a key.
* @deprecated since 1.1.2
*/
@Deprecated
protected static volatile LogFactory nullClassLoaderFactory;
/**
* Create the hashtable which will be used to store a map of
* (context-classloader -> logfactory-object). Version 1.2+ of Java
* supports "weak references", allowing a custom Hashtable class
* to be used which uses only weak references to its keys. Using weak
* references can fix memory leaks on webapp unload in some cases (though
* not all). Version 1.1 of Java does not support weak references, so we
* must dynamically determine which we are using. And just for fun, this
* code also supports the ability for a system property to specify an
* arbitrary Hashtable implementation name.
* <p>
* Note that the correct way to ensure no memory leaks occur is to ensure
* that LogFactory.release(contextClassLoader) is called whenever a
* webapp is undeployed.
*/
private static final Hashtable createFactoryStore() {
Hashtable result = null;
String storeImplementationClass;
try {
storeImplementationClass = getSystemProperty(HASHTABLE_IMPLEMENTATION_PROPERTY, null);
} catch (final SecurityException ex) {
// Permissions don't allow this to be accessed. Default to the "modern"
// weak hashtable implementation if it is available.
storeImplementationClass = null;
}
if (storeImplementationClass == null) {
storeImplementationClass = WEAK_HASHTABLE_CLASSNAME;
}
try {
final Class implementationClass = Class.forName(storeImplementationClass);
result = (Hashtable) implementationClass.newInstance();
} catch (final Throwable t) {
handleThrowable(t); // may re-throw t
// ignore
if (!WEAK_HASHTABLE_CLASSNAME.equals(storeImplementationClass)) {
// if the user's trying to set up a custom implementation, give a clue
if (isDiagnosticsEnabled()) {
// use internal logging to issue the warning
logDiagnostic("[ERROR] LogFactory: Load of custom hashtable failed");
} else {
// we *really* want this output, even if diagnostics weren't
// explicitly enabled by the user.
System.err.println("[ERROR] LogFactory: Load of custom hashtable failed");
}
}
}
if (result == null) {
result = new Hashtable();
}
return result;
}