| Fields Summary |
|---|
| public static final String | PRIORITY_KEYThe name (priority) of the key in the config file used to
specify the priority of that particular config file. The associated value
is a floating-point number; higher values take priority over lower values. |
| public static final String | TCCL_KEYThe name (use_tccl) of the key in the config file used
to specify whether logging classes should be loaded via the thread
context class loader (TCCL), or not. By default, the TCCL is used. |
| public static final String | FACTORY_PROPERTYThe name (org.apache.commons.logging.LogFactory) of the property
used to identify the LogFactory implementation
class name. This can be used as a system property, or as an entry in a
configuration properties file. |
| public static final String | FACTORY_DEFAULTThe fully qualified class name of the fallback LogFactory
implementation class to use, if no other can be found. |
| public static final String | FACTORY_PROPERTIESThe name (commons-logging.properties) of the properties file to search for. |
| protected static final String | SERVICE_IDJDK1.3+
'Service Provider' specification. |
| public static final String | DIAGNOSTICS_DEST_PROPERTYThe name (org.apache.commons.logging.diagnostics.dest)
of the property used to enable internal commons-logging
diagnostic output, in order to get information on what logging
implementations are being discovered, what classloaders they
are loaded through, etc.
If a system property of this name is set then the value is
assumed to be the name of a file. The special strings
STDOUT or STDERR (case-sensitive) indicate output to
System.out and System.err respectively.
Diagnostic logging should be used only to debug problematic
configurations and should not be set in normal production use. |
| private static PrintStream | diagnosticsStreamWhen null (the usual case), no diagnostic output will be
generated by LogFactory or LogFactoryImpl. When non-null,
interesting events will be written to the specified object. |
| private static String | diagnosticPrefixA string that gets prefixed to every message output by the
logDiagnostic method, so that users can clearly see which
LogFactory class is generating the output. |
| public static final String | HASHTABLE_IMPLEMENTATION_PROPERTY Setting this system property
(org.apache.commons.logging.LogFactory.HashtableImpl)
value allows the Hashtable used to store
classloaders to be substituted by an alternative implementation.
Note: LogFactory will print:
[ERROR] LogFactory: Load of custom hashtable failed
Usage: Set this property when Java is invoked
and LogFactory will attempt to load a new instance
of the given implementation class.
For example, running the following ant scriplet:
<java classname="${test.runner}" fork="yes" failonerror="${test.failonerror}">
...
<sysproperty
key="org.apache.commons.logging.LogFactory.HashtableImpl"
value="org.apache.commons.logging.AltHashtable"/>
</java>
LogFactory will load an instance of
org.apache.commons.logging.AltHashtable.
A typical use case is to allow a custom
Hashtable implementation using weak references to be substituted.
This will allow classloaders to be garbage collected without
the need to release them (on 1.3+ JVMs only, of course ;)
|
| private static final String | WEAK_HASHTABLE_CLASSNAMEName used to load the weak hashtable implementation by names |
| private static ClassLoader | thisClassLoaderA reference to the classloader that loaded this class. This is the
same as LogFactory.class.getClassLoader(). However computing this
value isn't quite as simple as that, as we potentially need to use
AccessControllers etc. It's more efficient to compute it once and
cache it here. |
| protected static Hashtable | factoriesThe previously constructed LogFactory instances, keyed by
the ClassLoader with which it was created. |
| protected static LogFactory | nullClassLoaderFactoryPrevously constructed LogFactory instance as in the
factories map, but for the case where
getClassLoader returns null.
This can happen when:
- using JDK1.1 and the calling code is loaded via the system
classloader (very common)
- using JDK1.2+ and the calling code is loaded via the boot
classloader (only likely for embedded systems work).
Note that factories is a Hashtable (not a HashMap),
and hashtables don't allow null as a key. |
| Methods Summary |
|---|
| private static void | cacheFactory(java.lang.ClassLoader classLoader, org.apache.commons.logging.LogFactory factory)Remember this factory, so later calls to LogFactory.getCachedFactory
can return the previously created object (together with all its
cached Log objects).
// Ideally we would assert(factory != null) here. However reporting
// errors from within a logging implementation is a little tricky!
if (factory != null) {
if (classLoader == null) {
nullClassLoaderFactory = factory;
} else {
factories.put(classLoader, factory);
}
}
|
| protected static java.lang.Object | createFactory(java.lang.String factoryClass, java.lang.ClassLoader classLoader)Implements the operations described in the javadoc for newFactory.
// This will be used to diagnose bad configurations
// and allow a useful message to be sent to the user
Class logFactoryClass = null;
try {
if (classLoader != null) {
try {
// First the given class loader param (thread class loader)
// Warning: must typecast here & allow exception
// to be generated/caught & recast properly.
logFactoryClass = classLoader.loadClass(factoryClass);
if (LogFactory.class.isAssignableFrom(logFactoryClass)) {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"Loaded class " + logFactoryClass.getName()
+ " from classloader " + objectId(classLoader));
}
} else {
//
// This indicates a problem with the ClassLoader tree.
// An incompatible ClassLoader was used to load the
// implementation.
// As the same classes
// must be available in multiple class loaders,
// it is very likely that multiple JCL jars are present.
// The most likely fix for this
// problem is to remove the extra JCL jars from the
// ClassLoader hierarchy.
//
if (isDiagnosticsEnabled()) {
logDiagnostic(
"Factory class " + logFactoryClass.getName()
+ " loaded from classloader " + objectId(logFactoryClass.getClassLoader())
+ " does not extend '" + LogFactory.class.getName()
+ "' as loaded by this classloader.");
logHierarchy("[BAD CL TREE] ", classLoader);
}
}
return (LogFactory) logFactoryClass.newInstance();
} catch (ClassNotFoundException ex) {
if (classLoader == thisClassLoader) {
// Nothing more to try, onwards.
if (isDiagnosticsEnabled()) {
logDiagnostic(
"Unable to locate any class called '" + factoryClass
+ "' via classloader " + objectId(classLoader));
}
throw ex;
}
// ignore exception, continue
} catch (NoClassDefFoundError e) {
if (classLoader == thisClassLoader) {
// Nothing more to try, onwards.
if (isDiagnosticsEnabled()) {
logDiagnostic(
"Class '" + factoryClass + "' cannot be loaded"
+ " via classloader " + objectId(classLoader)
+ " - it depends on some other class that cannot"
+ " be found.");
}
throw e;
}
// ignore exception, continue
} catch(ClassCastException e) {
if (classLoader == thisClassLoader) {
// There's no point in falling through to the code below that
// tries again with thisClassLoader, because we've just tried
// loading with that loader (not the TCCL). Just throw an
// appropriate exception here.
final boolean implementsLogFactory = implementsLogFactory(logFactoryClass);
//
// Construct a good message: users may not actual expect that a custom implementation
// has been specified. Several well known containers use this mechanism to adapt JCL
// to their native logging system.
//
String msg =
"The application has specified that a custom LogFactory implementation should be used but " +
"Class '" + factoryClass + "' cannot be converted to '"
+ LogFactory.class.getName() + "'. ";
if (implementsLogFactory) {
msg = msg + "The conflict is caused by the presence of multiple LogFactory classes in incompatible classloaders. " +
"Background can be found in http://jakarta.apache.org/commons/logging/tech.html. " +
"If you have not explicitly specified a custom LogFactory then it is likely that " +
"the container has set one without your knowledge. " +
"In this case, consider using the commons-logging-adapters.jar file or " +
"specifying the standard LogFactory from the command line. ";
} else {
msg = msg + "Please check the custom implementation. ";
}
msg = msg + "Help can be found @http://jakarta.apache.org/commons/logging/troubleshooting.html.";
if (isDiagnosticsEnabled()) {
logDiagnostic(msg);
}
ClassCastException ex = new ClassCastException(msg);
throw ex;
}
// Ignore exception, continue. Presumably the classloader was the
// TCCL; the code below will try to load the class via thisClassLoader.
// This will handle the case where the original calling class is in
// a shared classpath but the TCCL has a copy of LogFactory and the
// specified LogFactory implementation; we will fall back to using the
// LogFactory implementation from the same classloader as this class.
//
// Issue: this doesn't handle the reverse case, where this LogFactory
// is in the webapp, and the specified LogFactory implementation is
// in a shared classpath. In that case:
// (a) the class really does implement LogFactory (bad log msg above)
// (b) the fallback code will result in exactly the same problem.
}
}
/* At this point, either classLoader == null, OR
* classLoader was unable to load factoryClass.
*
* In either case, we call Class.forName, which is equivalent
* to LogFactory.class.getClassLoader().load(name), ie we ignore
* the classloader parameter the caller passed, and fall back
* to trying the classloader associated with this class. See the
* javadoc for the newFactory method for more info on the
* consequences of this.
*
* Notes:
* * LogFactory.class.getClassLoader() may return 'null'
* if LogFactory is loaded by the bootstrap classloader.
*/
// Warning: must typecast here & allow exception
// to be generated/caught & recast properly.
if (isDiagnosticsEnabled()) {
logDiagnostic(
"Unable to load factory class via classloader "
+ objectId(classLoader)
+ " - trying the classloader associated with this LogFactory.");
}
logFactoryClass = Class.forName(factoryClass);
return (LogFactory) logFactoryClass.newInstance();
} catch (Exception e) {
// Check to see if we've got a bad configuration
if (isDiagnosticsEnabled()) {
logDiagnostic("Unable to create LogFactory instance.");
}
if (logFactoryClass != null
&& !LogFactory.class.isAssignableFrom(logFactoryClass)) {
return new LogConfigurationException(
"The chosen LogFactory implementation does not extend LogFactory."
+ " Please check your configuration.",
e);
}
return new LogConfigurationException(e);
}
|
| private static final java.util.Hashtable | createFactoryStore()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.
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.
Hashtable result = null;
String storeImplementationClass
= System.getProperty(HASHTABLE_IMPLEMENTATION_PROPERTY);
if (storeImplementationClass == null) {
storeImplementationClass = WEAK_HASHTABLE_CLASSNAME;
}
try {
Class implementationClass = Class.forName(storeImplementationClass);
result = (Hashtable) implementationClass.newInstance();
} catch (Throwable 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;
|
| protected static java.lang.ClassLoader | directGetContextClassLoader()Return the thread context class loader if available; otherwise return
null.
Most/all code should call getContextClassLoader rather than calling
this method directly.
The thread context class loader is available for JDK 1.2
or later, if certain security conditions are met.
Note that no internal logging is done within this method because
this method is called every time LogFactory.getLogger() is called,
and we don't want too much output generated here.
ClassLoader classLoader = null;
try {
// Are we running on a JDK 1.2 or later system?
Method method = Thread.class.getMethod("getContextClassLoader",
(Class[]) null);
// Get the thread context class loader (if there is one)
try {
classLoader = (ClassLoader)method.invoke(Thread.currentThread(),
(Object[]) null);
} catch (IllegalAccessException e) {
throw new LogConfigurationException
("Unexpected IllegalAccessException", e);
} catch (InvocationTargetException e) {
/**
* InvocationTargetException is thrown by 'invoke' when
* the method being invoked (getContextClassLoader) throws
* an exception.
*
* getContextClassLoader() throws SecurityException when
* the context class loader isn't an ancestor of the
* calling class's class loader, or if security
* permissions are restricted.
*
* In the first case (not related), we want to ignore and
* keep going. We cannot help but also ignore the second
* with the logic below, but other calls elsewhere (to
* obtain a class loader) will trigger this exception where
* we can make a distinction.
*/
if (e.getTargetException() instanceof SecurityException) {
; // ignore
} else {
// Capture 'e.getTargetException()' exception for details
// alternate: log 'e.getTargetException()', and pass back 'e'.
throw new LogConfigurationException
("Unexpected InvocationTargetException", e.getTargetException());
}
}
} catch (NoSuchMethodException e) {
// Assume we are running on JDK 1.1
classLoader = getClassLoader(LogFactory.class);
// We deliberately don't log a message here to outputStream;
// this message would be output for every call to LogFactory.getLog()
// when running on JDK1.1
//
// if (outputStream != null) {
// outputStream.println(
// "Method Thread.getContextClassLoader does not exist;"
// + " assuming this is JDK 1.1, and that the context"
// + " classloader is the same as the class that loaded"
// + " the concrete LogFactory class.");
// }
}
// Return the selected class loader
return classLoader;
|
| public abstract java.lang.Object | getAttribute(java.lang.String name)Return the configuration attribute with the specified name (if any),
or null if there is no such attribute.
|
| public abstract java.lang.String[] | getAttributeNames()Return an array containing the names of all currently defined
configuration attributes. If there are no such attributes, a zero
length array is returned.
|
| private static org.apache.commons.logging.LogFactory | getCachedFactory(java.lang.ClassLoader contextClassLoader)Check cached factories (keyed by contextClassLoader)
LogFactory factory = null;
if (contextClassLoader == null) {
// We have to handle this specially, as factories is a Hashtable
// and those don't accept null as a key value.
//
// nb: nullClassLoaderFactory might be null. That's ok.
factory = nullClassLoaderFactory;
} else {
factory = (LogFactory) factories.get(contextClassLoader);
}
return factory;
|
| protected static java.lang.ClassLoader | getClassLoader(java.lang.Class clazz)Safely get access to the classloader for the specified class.
Theoretically, calling getClassLoader can throw a security exception,
and so should be done under an AccessController in order to provide
maximum flexibility. However in practice people don't appear to use
security policies that forbid getClassLoader calls. So for the moment
all code is written to call this method rather than Class.getClassLoader,
so that we could put AccessController stuff in this method without any
disruption later if we need to.
Even when using an AccessController, however, this method can still
throw SecurityException. Commons-logging basically relies on the
ability to access classloaders, ie a policy that forbids all
classloader access will also prevent commons-logging from working:
currently this method will throw an exception preventing the entire app
from starting up. Maybe it would be good to detect this situation and
just disable all commons-logging? Not high priority though - as stated
above, security policies that prevent classloader access aren't common.
try {
return clazz.getClassLoader();
} catch(SecurityException ex) {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"Unable to get classloader for class '" + clazz
+ "' due to security restrictions - " + ex.getMessage());
}
throw ex;
}
|
| private static final java.util.Properties | getConfigurationFile(java.lang.ClassLoader classLoader, java.lang.String fileName)Locate a user-provided configuration file.
The classpath of the specified classLoader (usually the context classloader)
is searched for properties files of the specified name. If none is found,
null is returned. If more than one is found, then the file with the greatest
value for its PRIORITY property is returned. If multiple files have the
same PRIORITY value then the first in the classpath is returned.
This differs from the 1.0.x releases; those always use the first one found.
However as the priority is a new field, this change is backwards compatible.
The purpose of the priority field is to allow a webserver administrator to
override logging settings in all webapps by placing a commons-logging.properties
file in a shared classpath location with a priority > 0; this overrides any
commons-logging.properties files without priorities which are in the
webapps. Webapps can also use explicit priorities to override a configuration
file in the shared classpath if needed.
Properties props = null;
double priority = 0.0;
URL propsUrl = null;
try {
Enumeration urls = getResources(classLoader, fileName);
if (urls == null) {
return null;
}
while (urls.hasMoreElements()) {
URL url = (URL) urls.nextElement();
Properties newProps = getProperties(url);
if (newProps != null) {
if (props == null) {
propsUrl = url;
props = newProps;
String priorityStr = props.getProperty(PRIORITY_KEY);
priority = 0.0;
if (priorityStr != null) {
priority = Double.parseDouble(priorityStr);
}
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] Properties file found at '" + url + "'"
+ " with priority " + priority);
}
} else {
String newPriorityStr = newProps.getProperty(PRIORITY_KEY);
double newPriority = 0.0;
if (newPriorityStr != null) {
newPriority = Double.parseDouble(newPriorityStr);
}
if (newPriority > priority) {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] Properties file at '" + url + "'"
+ " with priority " + newPriority
+ " overrides file at '" + propsUrl + "'"
+ " with priority " + priority);
}
propsUrl = url;
props = newProps;
priority = newPriority;
} else {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] Properties file at '" + url + "'"
+ " with priority " + newPriority
+ " does not override file at '" + propsUrl + "'"
+ " with priority " + priority);
}
}
}
}
}
} catch (SecurityException e) {
if (isDiagnosticsEnabled()) {
logDiagnostic("SecurityException thrown while trying to find/read config files.");
}
}
if (isDiagnosticsEnabled()) {
if (props == null) {
logDiagnostic(
"[LOOKUP] No properties file of name '" + fileName
+ "' found.");
} else {
logDiagnostic(
"[LOOKUP] Properties file of name '" + fileName
+ "' found at '" + propsUrl + '"");
}
}
return props;
|
| protected static java.lang.ClassLoader | getContextClassLoader()Calls LogFactory.directGetContextClassLoader under the control of an
AccessController class. This means that java code running under a
security manager that forbids access to ClassLoaders will still work
if this class is given appropriate privileges, even when the caller
doesn't have such privileges. Without using an AccessController, the
the entire call stack must have the privilege before the call is
allowed.
return (ClassLoader)AccessController.doPrivileged(
new PrivilegedAction() {
public Object run() {
return directGetContextClassLoader();
}
});
|
| public static org.apache.commons.logging.LogFactory | getFactory()Construct (if necessary) and return a LogFactory
instance, using the following ordered lookup procedure to determine
the name of the implementation class to be loaded.
- The
org.apache.commons.logging.LogFactory system
property.
- The JDK 1.3 Service Discovery mechanism
- Use the properties file
commons-logging.properties
file, if found in the class path of this class. The configuration
file is in standard java.util.Properties format and
contains the fully qualified name of the implementation class
with the key being the system property defined above.
- Fall back to a default implementation class
(
org.apache.commons.logging.impl.LogFactoryImpl).
NOTE - If the properties file method of identifying the
LogFactory implementation class is utilized, all of the
properties defined in this file will be set as configuration attributes
on the corresponding LogFactory instance.
NOTE - In a multithreaded environment it is possible
that two different instances will be returned for the same
classloader environment.
// Identify the class loader we will be using
ClassLoader contextClassLoader = getContextClassLoader();
if (contextClassLoader == null) {
// This is an odd enough situation to report about. This
// output will be a nuisance on JDK1.1, as the system
// classloader is null in that environment.
if (isDiagnosticsEnabled()) {
logDiagnostic("Context classloader is null.");
}
}
// Return any previously registered factory for this class loader
LogFactory factory = getCachedFactory(contextClassLoader);
if (factory != null) {
return factory;
}
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] LogFactory implementation requested for the first time for context classloader "
+ objectId(contextClassLoader));
logHierarchy("[LOOKUP] ", contextClassLoader);
}
// Load properties file.
//
// If the properties file exists, then its contents are used as
// "attributes" on the LogFactory implementation class. One particular
// property may also control which LogFactory concrete subclass is
// used, but only if other discovery mechanisms fail..
//
// As the properties file (if it exists) will be used one way or
// another in the end we may as well look for it first.
Properties props = getConfigurationFile(contextClassLoader, FACTORY_PROPERTIES);
// Determine whether we will be using the thread context class loader to
// load logging classes or not by checking the loaded properties file (if any).
ClassLoader baseClassLoader = contextClassLoader;
if (props != null) {
String useTCCLStr = props.getProperty(TCCL_KEY);
if (useTCCLStr != null) {
// The Boolean.valueOf(useTCCLStr).booleanValue() formulation
// is required for Java 1.2 compatability.
if (Boolean.valueOf(useTCCLStr).booleanValue() == false) {
// Don't use current context classloader when locating any
// LogFactory or Log classes, just use the class that loaded
// this abstract class. When this class is deployed in a shared
// classpath of a container, it means webapps cannot deploy their
// own logging implementations. It also means that it is up to the
// implementation whether to load library-specific config files
// from the TCCL or not.
baseClassLoader = thisClassLoader;
}
}
}
// Determine which concrete LogFactory subclass to use.
// First, try a global system property
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] Looking for system property [" + FACTORY_PROPERTY
+ "] to define the LogFactory subclass to use...");
}
try {
String factoryClass = System.getProperty(FACTORY_PROPERTY);
if (factoryClass != null) {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] Creating an instance of LogFactory class '" + factoryClass
+ "' as specified by system property " + FACTORY_PROPERTY);
}
factory = newFactory(factoryClass, baseClassLoader, contextClassLoader);
} else {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] No system property [" + FACTORY_PROPERTY
+ "] defined.");
}
}
} catch (SecurityException e) {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] A security exception occurred while trying to create an"
+ " instance of the custom factory class"
+ ": [" + e.getMessage().trim()
+ "]. Trying alternative implementations...");
}
; // ignore
} catch(RuntimeException e) {
// This is not consistent with the behaviour when a bad LogFactory class is
// specified in a services file.
//
// One possible exception that can occur here is a ClassCastException when
// the specified class wasn't castable to this LogFactory type.
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] An exception occurred while trying to create an"
+ " instance of the custom factory class"
+ ": [" + e.getMessage().trim()
+ "] as specified by a system property.");
}
throw e;
}
// Second, try to find a service by using the JDK1.3 class
// discovery mechanism, which involves putting a file with the name
// of an interface class in the META-INF/services directory, where the
// contents of the file is a single line specifying a concrete class
// that implements the desired interface.
if (factory == null) {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] Looking for a resource file of name [" + SERVICE_ID
+ "] to define the LogFactory subclass to use...");
}
try {
InputStream is = getResourceAsStream(contextClassLoader,
SERVICE_ID);
if( is != null ) {
// This code is needed by EBCDIC and other strange systems.
// It's a fix for bugs reported in xerces
BufferedReader rd;
try {
rd = new BufferedReader(new InputStreamReader(is, "UTF-8"));
} catch (java.io.UnsupportedEncodingException e) {
rd = new BufferedReader(new InputStreamReader(is));
}
String factoryClassName = rd.readLine();
rd.close();
if (factoryClassName != null &&
! "".equals(factoryClassName)) {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] Creating an instance of LogFactory class " + factoryClassName
+ " as specified by file '" + SERVICE_ID
+ "' which was present in the path of the context"
+ " classloader.");
}
factory = newFactory(factoryClassName, baseClassLoader, contextClassLoader );
}
} else {
// is == null
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] No resource file with name '" + SERVICE_ID
+ "' found.");
}
}
} catch( Exception ex ) {
// note: if the specified LogFactory class wasn't compatible with LogFactory
// for some reason, a ClassCastException will be caught here, and attempts will
// continue to find a compatible class.
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] A security exception occurred while trying to create an"
+ " instance of the custom factory class"
+ ": [" + ex.getMessage().trim()
+ "]. Trying alternative implementations...");
}
; // ignore
}
}
// Third try looking into the properties file read earlier (if found)
if (factory == null) {
if (props != null) {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] Looking in properties file for entry with key '"
+ FACTORY_PROPERTY
+ "' to define the LogFactory subclass to use...");
}
String factoryClass = props.getProperty(FACTORY_PROPERTY);
if (factoryClass != null) {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] Properties file specifies LogFactory subclass '"
+ factoryClass + "'");
}
factory = newFactory(factoryClass, baseClassLoader, contextClassLoader);
// TODO: think about whether we need to handle exceptions from newFactory
} else {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] Properties file has no entry specifying LogFactory subclass.");
}
}
} else {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] No properties file available to determine"
+ " LogFactory subclass from..");
}
}
}
// Fourth, try the fallback implementation class
if (factory == null) {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"[LOOKUP] Loading the default LogFactory implementation '" + FACTORY_DEFAULT
+ "' via the same classloader that loaded this LogFactory"
+ " class (ie not looking in the context classloader).");
}
// Note: unlike the above code which can try to load custom LogFactory
// implementations via the TCCL, we don't try to load the default LogFactory
// implementation via the context classloader because:
// * that can cause problems (see comments in newFactory method)
// * no-one should be customising the code of the default class
// Yes, we do give up the ability for the child to ship a newer
// version of the LogFactoryImpl class and have it used dynamically
// by an old LogFactory class in the parent, but that isn't
// necessarily a good idea anyway.
factory = newFactory(FACTORY_DEFAULT, thisClassLoader, contextClassLoader);
}
if (factory != null) {
/**
* Always cache using context class loader.
*/
cacheFactory(contextClassLoader, factory);
if( props!=null ) {
Enumeration names = props.propertyNames();
while (names.hasMoreElements()) {
String name = (String) names.nextElement();
String value = props.getProperty(name);
factory.setAttribute(name, value);
}
}
}
return factory;
|
| public abstract org.apache.commons.logging.Log | getInstance(java.lang.Class clazz)Convenience method to derive a name from the specified class and
call getInstance(String) with it.
|
| public abstract org.apache.commons.logging.Log | getInstance(java.lang.String name)Construct (if necessary) and return a Log instance,
using the factory's current set of configuration attributes.
NOTE - Depending upon the implementation of
the LogFactory you are using, the 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.
|
| public static org.apache.commons.logging.Log | getLog(java.lang.Class clazz)Convenience method to return a named logger, without the application
having to care about factories.
// BEGIN android-added
return getLog(clazz.getName());
// END android-added
// BEGIN android-deleted
//return (getFactory().getInstance(clazz));
// END android-deleted
|
| public static org.apache.commons.logging.Log | getLog(java.lang.String name)Convenience method to return a named logger, without the application
having to care about factories.
// BEGIN android-added
return new org.apache.commons.logging.impl.Jdk14Logger(name);
// END android-added
// BEGIN android-deleted
//return (getFactory().getInstance(name));
// END android-deleted
|
| private static java.util.Properties | getProperties(java.net.URL url)Given a URL that refers to a .properties file, load that file.
This is done under an AccessController so that this method will
succeed when this jarfile is privileged but the caller is not.
This method must therefore remain private to avoid security issues.
Null is returned if the URL cannot be opened.
PrivilegedAction action =
new PrivilegedAction() {
public Object run() {
try {
InputStream stream = url.openStream();
if (stream != null) {
Properties props = new Properties();
props.load(stream);
stream.close();
return props;
}
} catch(IOException e) {
if (isDiagnosticsEnabled()) {
logDiagnostic("Unable to read URL " + url);
}
}
return null;
}
};
return (Properties) AccessController.doPrivileged(action);
|
| private static java.io.InputStream | getResourceAsStream(java.lang.ClassLoader loader, java.lang.String name)Applets may run in an environment where accessing resources of a loader is
a secure operation, but where the commons-logging library has explicitly
been granted permission for that operation. In this case, we need to
run the operation using an AccessController.
return (InputStream)AccessController.doPrivileged(
new PrivilegedAction() {
public Object run() {
if (loader != null) {
return loader.getResourceAsStream(name);
} else {
return ClassLoader.getSystemResourceAsStream(name);
}
}
});
|
| private static java.util.Enumeration | getResources(java.lang.ClassLoader loader, java.lang.String name)Given a filename, return an enumeration of URLs pointing to
all the occurrences of that filename in the classpath.
This is just like ClassLoader.getResources except that the
operation is done under an AccessController so that this method will
succeed when this jarfile is privileged but the caller is not.
This method must therefore remain private to avoid security issues.
If no instances are found, an Enumeration is returned whose
hasMoreElements method returns false (ie an "empty" enumeration).
If resources could not be listed for some reason, null is returned.
PrivilegedAction action =
new PrivilegedAction() {
public Object run() {
try {
if (loader != null) {
return loader.getResources(name);
} else {
return ClassLoader.getSystemResources(name);
}
} catch(IOException e) {
if (isDiagnosticsEnabled()) {
logDiagnostic(
"Exception while trying to find configuration file "
+ name + ":" + e.getMessage());
}
return null;
} catch(NoSuchMethodError e) {
// we must be running on a 1.1 JVM which doesn't support
// ClassLoader.getSystemResources; just return null in
// this case.
return null;
}
}
};
Object result = AccessController.doPrivileged(action);
return (Enumeration) result;
|
| private static boolean | implementsLogFactory(java.lang.Class logFactoryClass)Determines whether the given class actually implements LogFactory.
Diagnostic information is also logged.
Usage: to diagnose whether a classloader conflict is the cause
of incompatibility. The test used is whether the class is assignable from
the LogFactory class loaded by the class's classloader.
boolean implementsLogFactory = false;
if (logFactoryClass != null) {
try {
ClassLoader logFactoryClassLoader = logFactoryClass.getClassLoader();
if (logFactoryClassLoader == null) {
logDiagnostic("[CUSTOM LOG FACTORY] was loaded by the boot classloader");
} else {
logHierarchy("[CUSTOM LOG FACTORY] ", logFactoryClassLoader);
Class factoryFromCustomLoader
= Class.forName("org.apache.commons.logging.LogFactory", false, logFactoryClassLoader);
implementsLogFactory = factoryFromCustomLoader.isAssignableFrom(logFactoryClass);
if (implementsLogFactory) {
logDiagnostic("[CUSTOM LOG FACTORY] " + logFactoryClass.getName()
+ " implements LogFactory but was loaded by an incompatible classloader.");
} else {
logDiagnostic("[CUSTOM LOG FACTORY] " + logFactoryClass.getName()
+ " does not implement LogFactory.");
}
}
} catch (SecurityException e) {
//
// The application is running within a hostile security environment.
// This will make it very hard to diagnose issues with JCL.
// Consider running less securely whilst debugging this issue.
//
logDiagnostic("[CUSTOM LOG FACTORY] SecurityException thrown whilst trying to determine whether " +
"the compatibility was caused by a classloader conflict: "
+ e.getMessage());
} catch (LinkageError e) {
//
// This should be an unusual circumstance.
// LinkageError's usually indicate that a dependent class has incompatibly changed.
// Another possibility may be an exception thrown by an initializer.
// Time for a clean rebuild?
//
logDiagnostic("[CUSTOM LOG FACTORY] LinkageError thrown whilst trying to determine whether " +
"the compatibility was caused by a classloader conflict: "
+ e.getMessage());
} catch (ClassNotFoundException e) {
//
// LogFactory cannot be loaded by the classloader which loaded the custom factory implementation.
// The custom implementation is not viable until this is corrected.
// Ensure that the JCL jar and the custom class are available from the same classloader.
// Running with diagnostics on should give information about the classloaders used
// to load the custom factory.
//
logDiagnostic("[CUSTOM LOG FACTORY] LogFactory class cannot be loaded by classloader which loaded the " +
"custom LogFactory implementation. Is the custom factory in the right classloader?");
}
}
return implementsLogFactory;
|
| private static void | initDiagnostics()Determines whether the user wants internal diagnostic output. If so,
returns an appropriate writer object. Users can enable diagnostic
output by setting the system property named {@link #DIAGNOSTICS_DEST_PROPERTY} to
a filename, or the special values STDOUT or STDERR.
String dest;
try {
dest = System.getProperty(DIAGNOSTICS_DEST_PROPERTY);
if (dest == null) {
return;
}
} catch(SecurityException ex) {
// We must be running in some very secure environment.
// We just have to assume output is not wanted..
return;
}
if (dest.equals("STDOUT")) {
diagnosticsStream = System.out;
} else if (dest.equals("STDERR")) {
diagnosticsStream = System.err;
} else {
try {
// open the file in append mode
FileOutputStream fos = new FileOutputStream(dest, true);
diagnosticsStream = new PrintStream(fos);
} catch(IOException ex) {
// We should report this to the user - but how?
return;
}
}
// In order to avoid confusion where multiple instances of JCL are
// being used via different classloaders within the same app, we
// ensure each logged message has a prefix of form
// [LogFactory from classloader OID]
//
// Note that this prefix should be kept consistent with that
// in LogFactoryImpl. However here we don't need to output info
// about the actual *instance* of LogFactory, as all methods that
// output diagnostics from this class are static.
String classLoaderName;
try {
ClassLoader classLoader = thisClassLoader;
if (thisClassLoader == null) {
classLoaderName = "BOOTLOADER";
} else {
classLoaderName = objectId(classLoader);
}
} catch(SecurityException e) {
classLoaderName = "UNKNOWN";
}
diagnosticPrefix = "[LogFactory from " + classLoaderName + "] ";
|
| protected static boolean | isDiagnosticsEnabled()Indicates true if the user has enabled internal logging.
By the way, sorry for the incorrect grammar, but calling this method
areDiagnosticsEnabled just isn't java beans style.
return diagnosticsStream != null;
|
| private static void | logClassLoaderEnvironment(java.lang.Class clazz)Generate useful diagnostics regarding the classloader tree for
the specified class.
As an example, if the specified class was loaded via a webapp's
classloader, then you may get the following output:
Class com.acme.Foo was loaded via classloader 11111
ClassLoader tree: 11111 -> 22222 (SYSTEM) -> 33333 -> BOOT
This method returns immediately if isDiagnosticsEnabled()
returns false.
if (!isDiagnosticsEnabled()) {
return;
}
try {
logDiagnostic("[ENV] Extension directories (java.ext.dir): " + System.getProperty("java.ext.dir"));
logDiagnostic("[ENV] Application classpath (java.class.path): " + System.getProperty("java.class.path"));
} catch(SecurityException ex) {
logDiagnostic("[ENV] Security setting prevent interrogation of system classpaths.");
}
String className = clazz.getName();
ClassLoader classLoader;
try {
classLoader = getClassLoader(clazz);
} catch(SecurityException ex) {
// not much useful diagnostics we can print here!
logDiagnostic(
"[ENV] Security forbids determining the classloader for " + className);
return;
}
logDiagnostic(
"[ENV] Class " + className + " was loaded via classloader "
+ objectId(classLoader));
logHierarchy("[ENV] Ancestry of classloader which loaded " + className + " is ", classLoader);
|
| private static final void | logDiagnostic(java.lang.String msg)Write the specified message to the internal logging destination.
Note that this method is private; concrete subclasses of this class
should not call it because the diagnosticPrefix string this
method puts in front of all its messages is LogFactory@....,
while subclasses should put SomeSubClass@...
Subclasses should instead compute their own prefix, then call
logRawDiagnostic. Note that calling isDiagnosticsEnabled is
fine for subclasses.
Note that it is safe to call this method before initDiagnostics
is called; any output will just be ignored (as isDiagnosticsEnabled
will return false).
if (diagnosticsStream != null) {
diagnosticsStream.print(diagnosticPrefix);
diagnosticsStream.println(msg);
diagnosticsStream.flush();
}
|
| private static void | logHierarchy(java.lang.String prefix, java.lang.ClassLoader classLoader)Logs diagnostic messages about the given classloader
and it's hierarchy. The prefix is prepended to the message
and is intended to make it easier to understand the logs.
if (!isDiagnosticsEnabled()) {
return;
}
ClassLoader systemClassLoader;
if (classLoader != null) {
final String classLoaderString = classLoader.toString();
logDiagnostic(prefix + objectId(classLoader) + " == '" + classLoaderString + "'");
}
try {
systemClassLoader = ClassLoader.getSystemClassLoader();
} catch(SecurityException ex) {
logDiagnostic(
prefix + "Security forbids determining the system classloader.");
return;
}
if (classLoader != null) {
StringBuffer buf = new StringBuffer(prefix + "ClassLoader tree:");
for(;;) {
buf.append(objectId(classLoader));
if (classLoader == systemClassLoader) {
buf.append(" (SYSTEM) ");
}
try {
classLoader = classLoader.getParent();
} catch(SecurityException ex) {
buf.append(" --> SECRET");
break;
}
buf.append(" --> ");
if (classLoader == null) {
buf.append("BOOT");
break;
}
}
logDiagnostic(buf.toString());
}
|
| protected static final void | logRawDiagnostic(java.lang.String msg)Write the specified message to the internal logging destination.
if (diagnosticsStream != null) {
diagnosticsStream.println(msg);
diagnosticsStream.flush();
}
|
| protected static org.apache.commons.logging.LogFactory | newFactory(java.lang.String factoryClass, java.lang.ClassLoader classLoader, java.lang.ClassLoader contextClassLoader)Return a new instance of the specified LogFactory
implementation class, loaded by the specified class loader.
If that fails, try the class loader used to load this
(abstract) LogFactory.
ClassLoader conflicts
Note that there can be problems if the specified ClassLoader is not the
same as the classloader that loaded this class, ie when loading a
concrete LogFactory subclass via a context classloader.
The problem is the same one that can occur when loading a concrete Log
subclass via a context classloader.
The problem occurs when code running in the context classloader calls
class X which was loaded via a parent classloader, and class X then calls
LogFactory.getFactory (either directly or via LogFactory.getLog). Because
class X was loaded via the parent, it binds to LogFactory loaded via
the parent. When the code in this method finds some LogFactoryYYYY
class in the child (context) classloader, and there also happens to be a
LogFactory class defined in the child classloader, then LogFactoryYYYY
will be bound to LogFactory@childloader. It cannot be cast to
LogFactory@parentloader, ie this method cannot return the object as
the desired type. Note that it doesn't matter if the LogFactory class
in the child classloader is identical to the LogFactory class in the
parent classloader, they are not compatible.
The solution taken here is to simply print out an error message when
this occurs then throw an exception. The deployer of the application
must ensure they remove all occurrences of the LogFactory class from
the child classloader in order to resolve the issue. Note that they
do not have to move the custom LogFactory subclass; that is ok as
long as the only LogFactory class it can find to bind to is in the
parent classloader.
// Note that any unchecked exceptions thrown by the createFactory
// method will propagate out of this method; in particular a
// ClassCastException can be thrown.
Object result = AccessController.doPrivileged(
new PrivilegedAction() {
public Object run() {
return createFactory(factoryClass, classLoader);
}
});
if (result instanceof LogConfigurationException) {
LogConfigurationException ex = (LogConfigurationException) result;
if (isDiagnosticsEnabled()) {
logDiagnostic(
"An error occurred while loading the factory class:"
+ ex.getMessage());
}
throw ex;
}
if (isDiagnosticsEnabled()) {
logDiagnostic(
"Created object " + objectId(result)
+ " to manage classloader " + objectId(contextClassLoader));
}
return (LogFactory)result;
|
| protected static org.apache.commons.logging.LogFactory | newFactory(java.lang.String factoryClass, java.lang.ClassLoader classLoader)Method provided for backwards compatibility; see newFactory version that
takes 3 parameters.
This method would only ever be called in some rather odd situation.
Note that this method is static, so overriding in a subclass doesn't
have any effect unless this method is called from a method in that
subclass. However this method only makes sense to use from the
getFactory method, and as that is almost always invoked via
LogFactory.getFactory, any custom definition in a subclass would be
pointless. Only a class with a custom getFactory method, then invoked
directly via CustomFactoryImpl.getFactory or similar would ever call
this. Anyway, it's here just in case, though the "managed class loader"
value output to the diagnostics will not report the correct value.
return newFactory(factoryClass, classLoader, null);
|
| public static java.lang.String | objectId(java.lang.Object o)Returns a string that uniquely identifies the specified object, including
its class.
The returned string is of form "classname@hashcode", ie is the same as
the return value of the Object.toString() method, but works even when
the specified object's class has overidden the toString method.
if (o == null) {
return "null";
} else {
return o.getClass().getName() + "@" + System.identityHashCode(o);
}
|
| public static void | release(java.lang.ClassLoader classLoader)Release any internal references to previously created {@link LogFactory}
instances that have been associated with the specified class loader
(if any), after calling the instance method release() on
each of them.
if (isDiagnosticsEnabled()) {
logDiagnostic("Releasing factory for classloader " + objectId(classLoader));
}
synchronized (factories) {
if (classLoader == null) {
if (nullClassLoaderFactory != null) {
nullClassLoaderFactory.release();
nullClassLoaderFactory = null;
}
} else {
LogFactory factory = (LogFactory) factories.get(classLoader);
if (factory != null) {
factory.release();
factories.remove(classLoader);
}
}
}
|
| public abstract void | release()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 static void | releaseAll()Release any internal references to previously created {@link LogFactory}
instances, after calling the instance method release() on
each of them. 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.
if (isDiagnosticsEnabled()) {
logDiagnostic("Releasing factory for all classloaders.");
}
synchronized (factories) {
Enumeration elements = factories.elements();
while (elements.hasMoreElements()) {
LogFactory element = (LogFactory) elements.nextElement();
element.release();
}
factories.clear();
if (nullClassLoaderFactory != null) {
nullClassLoaderFactory.release();
nullClassLoaderFactory = null;
}
}
|
| public abstract void | removeAttribute(java.lang.String name)Remove any configuration attribute associated with the specified name.
If there is no such attribute, no action is taken.
|
| public abstract void | setAttribute(java.lang.String name, java.lang.Object value)Set the configuration attribute with the specified name. Calling
this with a null value is equivalent to calling
removeAttribute(name).
|
