[jboss-cvs] apache/commons-logging/src/java/org/apache/commons/logging ...
Scott Stark
scott.stark at jboss.com
Fri Feb 9 01:57:17 EST 2007
User: starksm
Date: 07/02/09 01:57:17
Modified: commons-logging/src/java/org/apache/commons/logging
package.html Log.java
LogConfigurationException.java LogSource.java
LogFactory.java
Log:
Update to the http://apache.ziply.com/jakarta/commons/logging/source/commons-logging-1.1-src.zip release
Revision Changes Path
1.2 +254 -254 apache/commons-logging/src/java/org/apache/commons/logging/package.html
(In the diff below, changes in quantity of whitespace are not shown.)
Index: package.html
===================================================================
RCS file: /cvsroot/jboss/apache/commons-logging/src/java/org/apache/commons/logging/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- package.html 17 Apr 2006 21:00:04 -0000 1.1
+++ package.html 9 Feb 2007 06:57:17 -0000 1.2
@@ -56,7 +56,7 @@
public class Foo {
- static Log log = LogFactory.getLog(Foo.class);
+ private Log log = LogFactory.getLog(Foo.class);
public void foo() {
...
@@ -221,7 +221,7 @@
public class MyComponent {
- protected static Log log =
+ protected Log log =
LogFactory.getLog(MyComponent.class);
// Called once at startup time
1.2 +245 -233 apache/commons-logging/src/java/org/apache/commons/logging/Log.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: Log.java
===================================================================
RCS file: /cvsroot/jboss/apache/commons-logging/src/java/org/apache/commons/logging/Log.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- Log.java 17 Apr 2006 21:00:04 -0000 1.1
+++ Log.java 9 Feb 2007 06:57:17 -0000 1.2
@@ -57,7 +57,7 @@
*
* @author <a href="mailto:sanders at apache.org">Scott Sanders</a>
* @author Rod Waldhoff
- * @version $Id: Log.java,v 1.1 2006/04/17 21:00:04 starksm Exp $
+ * @version $Id: Log.java,v 1.2 2007/02/09 06:57:17 starksm Exp $
*/
public interface Log {
@@ -71,6 +71,8 @@
* <p> Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than debug. </p>
+ *
+ * @return true if debug is enabled in the underlying logger.
*/
public boolean isDebugEnabled();
@@ -81,6 +83,8 @@
* <p> Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than error. </p>
+ *
+ * @return true if error is enabled in the underlying logger.
*/
public boolean isErrorEnabled();
@@ -91,6 +95,8 @@
* <p> Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than fatal. </p>
+ *
+ * @return true if fatal is enabled in the underlying logger.
*/
public boolean isFatalEnabled();
@@ -101,6 +107,8 @@
* <p> Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than info. </p>
+ *
+ * @return true if info is enabled in the underlying logger.
*/
public boolean isInfoEnabled();
@@ -111,6 +119,8 @@
* <p> Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than trace. </p>
+ *
+ * @return true if trace is enabled in the underlying logger.
*/
public boolean isTraceEnabled();
@@ -121,6 +131,8 @@
* <p> Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than warn. </p>
+ *
+ * @return true if warn is enabled in the underlying logger.
*/
public boolean isWarnEnabled();
1.2 +97 -97 apache/commons-logging/src/java/org/apache/commons/logging/LogConfigurationException.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: LogConfigurationException.java
===================================================================
RCS file: /cvsroot/jboss/apache/commons-logging/src/java/org/apache/commons/logging/LogConfigurationException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- LogConfigurationException.java 17 Apr 2006 21:00:04 -0000 1.1
+++ LogConfigurationException.java 9 Feb 2007 06:57:17 -0000 1.2
@@ -23,7 +23,7 @@
* factory methods.</p>
*
* @author Craig R. McClanahan
- * @version $Revision: 1.1 $ $Date: 2006/04/17 21:00:04 $
+ * @version $Revision: 1.2 $ $Date: 2007/02/09 06:57:17 $
*/
public class LogConfigurationException extends RuntimeException {
1.2 +261 -261 apache/commons-logging/src/java/org/apache/commons/logging/LogSource.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: LogSource.java
===================================================================
RCS file: /cvsroot/jboss/apache/commons-logging/src/java/org/apache/commons/logging/LogSource.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- LogSource.java 17 Apr 2006 21:00:04 -0000 1.1
+++ LogSource.java 9 Feb 2007 06:57:17 -0000 1.2
@@ -52,7 +52,7 @@
* implementation performs exactly the same algorithm as this class did
*
* @author Rod Waldhoff
- * @version $Id: LogSource.java,v 1.1 2006/04/17 21:00:04 starksm Exp $
+ * @version $Id: LogSource.java,v 1.2 2007/02/09 06:57:17 starksm Exp $
*/
public class LogSource {
1.3 +1730 -606 apache/commons-logging/src/java/org/apache/commons/logging/LogFactory.java
(In the diff below, changes in quantity of whitespace are not shown.)
Index: LogFactory.java
===================================================================
RCS file: /cvsroot/jboss/apache/commons-logging/src/java/org/apache/commons/logging/LogFactory.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- LogFactory.java 19 Apr 2006 02:34:20 -0000 1.2
+++ LogFactory.java 9 Feb 2007 06:57:17 -0000 1.3
@@ -1,5 +1,5 @@
/*
- * Copyright 2001-2004 The Apache Software Foundation.
+ * Copyright 2001-2006 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -18,19 +18,20 @@
import java.io.BufferedReader;
+import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
+import java.io.PrintStream;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
+import java.net.URL;
import java.security.AccessController;
import java.security.PrivilegedAction;
-import java.util.Collections;
import java.util.Enumeration;
-import java.util.Iterator;
-import java.util.Map;
+import java.util.Hashtable;
import java.util.Properties;
-import java.util.WeakHashMap;
+
/**
* <p>Factory for creating {@link Log} instances, with discovery and
@@ -44,8 +45,7 @@
* @author Craig R. McClanahan
* @author Costin Manolache
* @author Richard A. Sitze
- * @author Adrian Brock (jboss.org)
- * @version $Revision: 1.2 $ $Date: 2006/04/19 02:34:20 $
+ * @version $Revision: 1.3 $ $Date: 2007/02/09 06:57:17 $
*/
public abstract class LogFactory {
@@ -53,10 +53,25 @@
// ----------------------------------------------------- Manifest Constants
+ /**
+ * The name (<code>priority</code>) 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 PRIORITY_KEY = "priority";
+
+ /**
+ * The name (<code>use_tccl</code>) 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 TCCL_KEY = "use_tccl";
/**
- * The name of the property used to identify the LogFactory implementation
- * class name.
+ * The name (<code>org.apache.commons.logging.LogFactory</code>) 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_PROPERTY =
"org.apache.commons.logging.LogFactory";
@@ -69,7 +84,7 @@
"org.apache.commons.logging.impl.LogFactoryImpl";
/**
- * The name of the properties file to search for.
+ * The name (<code>commons-logging.properties</code>) of the properties file to search for.
*/
public static final String FACTORY_PROPERTIES =
"commons-logging.properties";
@@ -82,6 +97,88 @@
protected static final String SERVICE_ID =
"META-INF/services/org.apache.commons.logging.LogFactory";
+ /**
+ * The name (<code>org.apache.commons.logging.diagnostics.dest</code>)
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * Diagnostic logging should be used only to debug problematic
+ * configurations and should not be set in normal production use.
+ */
+ public static final String DIAGNOSTICS_DEST_PROPERTY =
+ "org.apache.commons.logging.diagnostics.dest";
+
+ /**
+ * When 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 PrintStream diagnosticsStream = null;
+
+ /**
+ * A 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.
+ */
+ private static String diagnosticPrefix;
+
+ /**
+ * <p>Setting this system property
+ * (<code>org.apache.commons.logging.LogFactory.HashtableImpl</code>)
+ * value allows the <code>Hashtable</code> used to store
+ * classloaders to be substituted by an alternative implementation.
+ * </p>
+ * <p>
+ * <strong>Note:</strong> <code>LogFactory</code> will print:
+ * <code><pre>
+ * [ERROR] LogFactory: Load of custom hashtable failed</em>
+ * </pre></code>
+ * to system error and then continue using a standard Hashtable.
+ * </p>
+ * <p>
+ * <strong>Usage:</strong> Set this property when Java is invoked
+ * and <code>LogFactory</code> will attempt to load a new instance
+ * of the given implementation class.
+ * For example, running the following ant scriplet:
+ * <code><pre>
+ * <java classname="${test.runner}" fork="yes" failonerror="${test.failonerror}">
+ * ...
+ * <sysproperty
+ * key="org.apache.commons.logging.LogFactory.HashtableImpl"
+ * value="org.apache.commons.logging.AltHashtable"/>
+ * </java>
+ * </pre></code>
+ * will mean that <code>LogFactory</code> will load an instance of
+ * <code>org.apache.commons.logging.AltHashtable</code>.
+ * </p>
+ * <p>
+ * 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 ;)
+ * </p>
+ */
+ public static final String HASHTABLE_IMPLEMENTATION_PROPERTY =
+ "org.apache.commons.logging.LogFactory.HashtableImpl";
+ /** Name used to load the weak hashtable implementation by names */
+ private static final String WEAK_HASHTABLE_CLASSNAME =
+ "org.apache.commons.logging.impl.WeakHashtable";
+
+ /**
+ * A 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.
+ */
+ private static ClassLoader thisClassLoader;
// ----------------------------------------------------------- Constructors
@@ -89,8 +186,8 @@
/**
* Protected constructor that is not available for public use.
*/
- protected LogFactory() { }
-
+ protected LogFactory() {
+ }
// --------------------------------------------------------- Public Methods
@@ -184,11 +281,73 @@
* The previously constructed <code>LogFactory</code> instances, keyed by
* the <code>ClassLoader</code> with which it was created.
*/
- protected static Map factories = Collections.synchronizedMap(new WeakHashMap());
+ protected static Hashtable factories = null;
- // --------------------------------------------------------- Static Methods
+ /**
+ * Prevously constructed <code>LogFactory</code> instance as in the
+ * <code>factories</code> map, but for the case where
+ * <code>getClassLoader</code> returns <code>null</code>.
+ * 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</code> is a <i>Hashtable</i> (not a HashMap),
+ * and hashtables don't allow null as a key.
+ */
+ protected static LogFactory nullClassLoaderFactory = null;
+
+ /**
+ * 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
+ = 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;
+ }
+ // --------------------------------------------------------- Static Methods
+
/**
* <p>Construct (if necessary) and return a <code>LogFactory</code>
* instance, using the following ordered lookup procedure to determine
@@ -211,62 +370,136 @@
* properties defined in this file will be set as configuration attributes
* on the corresponding <code>LogFactory</code> instance.</p>
*
+ * <p><em>NOTE</em> - In a multithreaded environment it is possible
+ * that two different instances will be returned for the same
+ * classloader environment.
+ * </p>
+ *
* @exception LogConfigurationException if the implementation class is not
* available or cannot be instantiated.
*/
public static LogFactory getFactory() throws LogConfigurationException {
-
// Identify the class loader we will be using
- ClassLoader contextClassLoader =
- (ClassLoader)AccessController.doPrivileged(
- new PrivilegedAction() {
- public Object run() {
- return getContextClassLoader();
+ 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)
+ 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.
- // Will be used one way or another in the end.
-
- Properties props=null;
- try {
- InputStream stream = getResourceAsStream(contextClassLoader,
- FACTORY_PROPERTIES);
-
- if (stream != null) {
- props = new Properties();
- props.load(stream);
- stream.close();
+ //
+ // 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;
+ }
}
- } catch (IOException e) {
- } catch (SecurityException e) {
}
+ // 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...");
+ }
- // First, try the system property
try {
String factoryClass = System.getProperty(FACTORY_PROPERTY);
if (factoryClass != null) {
- factory = newFactory(factoryClass, contextClassLoader);
+ 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 jar
- // discovery mechanism. This will allow users to plug a logger
- // by just placing it in the lib/ directory of the webapp ( or in
- // CLASSPATH or equivalent ). This is similar to the second
- // step, except that it uses the (standard?) jdk1.3 location in the jar.
+ // 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);
@@ -286,28 +519,71 @@
if (factoryClassName != null &&
! "".equals(factoryClassName)) {
-
- factory= newFactory( factoryClassName, contextClassLoader );
+ 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 a properties file.
- // If the properties file exists, it'll be read and the properties
- // used. IMHO ( costin ) System property and JDK1.3 jar service
- // should be enough for detecting the class name. The properties
- // should be used to set the attributes ( which may be specific to
- // the webapp, even if a default logger is set at JVM level by a
- // system property )
+ // Third try looking into the properties file read earlier (if found)
- if (factory == null && props != null) {
+ 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) {
- factory = newFactory(factoryClass, contextClassLoader);
+ 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..");
+ }
}
}
@@ -315,7 +591,23 @@
// Fourth, try the fallback implementation class
if (factory == null) {
- factory = newFactory(FACTORY_DEFAULT, LogFactory.class.getClassLoader());
+ 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) {
@@ -384,13 +676,23 @@
*/
public static void release(ClassLoader classLoader) {
+ 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);
}
}
+ }
}
@@ -405,13 +707,21 @@
*/
public static void releaseAll() {
+ if (isDiagnosticsEnabled()) {
+ logDiagnostic("Releasing factory for all classloaders.");
+ }
synchronized (factories) {
- Iterator elements = factories.values().iterator();
- while (elements.hasNext()) {
- LogFactory element = (LogFactory) elements.next();
+ Enumeration elements = factories.elements();
+ while (elements.hasMoreElements()) {
+ LogFactory element = (LogFactory) elements.nextElement();
element.release();
}
factories.clear();
+
+ if (nullClassLoaderFactory != null) {
+ nullClassLoaderFactory.release();
+ nullClassLoaderFactory = null;
+ }
}
}
@@ -419,29 +729,106 @@
// ------------------------------------------------------ Protected Methods
+ /**
+ * Safely get access to the classloader for the specified class.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ *
+ * @since 1.1
+ */
+ protected static ClassLoader getClassLoader(Class clazz) {
+ 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;
+ }
+ }
/**
- * Return the thread context class loader if available.
- * Otherwise return null.
+ * 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 the context classloader associated with the current thread,
+ * or null if security doesn't allow it.
+ *
+ * @throws LogConfigurationException if there was some weird error while
+ * attempting to get the context classloader.
+ *
+ * @throws SecurityException if the current java security policy doesn't
+ * allow this class to access the context classloader.
+ */
+ protected static ClassLoader getContextClassLoader()
+ throws LogConfigurationException {
+
+ return (ClassLoader)AccessController.doPrivileged(
+ new PrivilegedAction() {
+ public Object run() {
+ return directGetContextClassLoader();
+ }
+ });
+ }
+
+ /**
+ * Return the thread context class loader if available; otherwise return
+ * null.
+ * <p>
+ * Most/all code should call getContextClassLoader rather than calling
+ * this method directly.
+ * <p>
* The thread context class loader is available for JDK 1.2
* or later, if certain security conditions are met.
+ * <p>
+ * 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.
*
* @exception LogConfigurationException if a suitable class loader
* cannot be identified.
+ *
+ * @exception SecurityException if the java security policy forbids
+ * access to the context classloader from one of the classes in the
+ * current call stack.
+ * @since 1.1
*/
- protected static ClassLoader getContextClassLoader()
+ protected static ClassLoader directGetContextClassLoader()
throws LogConfigurationException
{
ClassLoader classLoader = null;
try {
// Are we running on a JDK 1.2 or later system?
- Method method = Thread.class.getMethod("getContextClassLoader", null);
+ 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(), null);
+ classLoader = (ClassLoader)method.invoke(Thread.currentThread(),
+ (Object[]) null);
} catch (IllegalAccessException e) {
throw new LogConfigurationException
("Unexpected IllegalAccessException", e);
@@ -473,7 +860,20 @@
}
} catch (NoSuchMethodException e) {
// Assume we are running on JDK 1.1
- classLoader = LogFactory.class.getClassLoader();
+ 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
@@ -482,43 +882,171 @@
/**
* Check cached factories (keyed by contextClassLoader)
+ *
+ * @param contextClassLoader is the context classloader associated
+ * with the current thread. This allows separate LogFactory objects
+ * per component within a container, provided each component has
+ * a distinct context classloader set. This parameter may be null
+ * in JDK1.1, and in embedded systems where jcl-using code is
+ * placed in the bootclasspath.
+ *
+ * @return the factory associated with the specified classloader if
+ * one has previously been created, or null if this is the first time
+ * we have seen this particular classloader.
*/
private static LogFactory getCachedFactory(ClassLoader contextClassLoader)
{
LogFactory factory = null;
- if (contextClassLoader != 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;
}
+ /**
+ * Remember this factory, so later calls to LogFactory.getCachedFactory
+ * can return the previously created object (together with all its
+ * cached Log objects).
+ *
+ * @param classLoader should be the current context classloader. Note that
+ * this can be null under some circumstances; this is ok.
+ *
+ * @param factory should be the factory to cache. This should never be null.
+ */
private static void cacheFactory(ClassLoader classLoader, LogFactory factory)
{
- if (classLoader != null && factory != null)
+ // 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);
}
+ }
+ }
/**
* Return a new instance of the specified <code>LogFactory</code>
* implementation class, loaded by the specified class loader.
* If that fails, try the class loader used to load this
* (abstract) LogFactory.
- *
+ * <p>
+ * <h2>ClassLoader conflicts</h2>
+ * 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.
+ * <p>
+ * The problem is the same one that can occur when loading a concrete Log
+ * subclass via a context classloader.
+ * <p>
+ * 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 at childloader. It cannot be cast to
+ * LogFactory at 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.
+ * <p>
+ * 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.
+ * <p>
* @param factoryClass Fully qualified name of the <code>LogFactory</code>
* implementation class
* @param classLoader ClassLoader from which to load this class
+ * @param contextClassLoader is the context that this new factory will
+ * manage logging for.
*
* @exception LogConfigurationException if a suitable instance
* cannot be created
+ * @since 1.1
*/
protected static LogFactory newFactory(final String factoryClass,
- final ClassLoader classLoader)
+ final ClassLoader classLoader,
+ final ClassLoader contextClassLoader)
throws LogConfigurationException
{
+ // 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;
+ }
+
+ /**
+ * Method provided for backwards compatibility; see newFactory version that
+ * takes 3 parameters.
+ * <p>
+ * 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.
+ */
+ protected static LogFactory newFactory(final String factoryClass,
+ final ClassLoader classLoader) {
+ return newFactory(factoryClass, classLoader, null);
+ }
+
+ /**
+ * Implements the operations described in the javadoc for newFactory.
+ *
+ * @param factoryClass
+ *
+ * @param classLoader used to load the specified factory class. This is
+ * expected to be either the TCCL or the classloader which loaded this
+ * class. Note that the classloader which loaded this class might be
+ * "null" (ie the bootloader) for embedded systems.
+ *
+ * @return either a LogFactory object or a LogConfigurationException object.
+ * @since 1.1
+ */
+ protected static Object createFactory(String factoryClass, ClassLoader classLoader) {
+
// This will be used to diagnose bad configurations
// and allow a useful message to be sent to the user
Class logFactoryClass = null;
@@ -530,49 +1058,145 @@
// 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 == LogFactory.class.getClassLoader()) {
+ 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 == LogFactory.class.getClassLoader()) {
+ 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.";
- } catch(ClassCastException e){
+ if (isDiagnosticsEnabled()) {
+ logDiagnostic(msg);
+ }
- if (classLoader == LogFactory.class.getClassLoader()) {
- // Nothing more to try, onwards (bug in loader implementation).
- throw e;
+ 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.
}
- // Ignore exception, continue
}
/* At this point, either classLoader == null, OR
* classLoader was unable to load factoryClass.
- * Try the class loader that loaded this class:
- * LogFactory.getClassLoader().
+ *
+ * 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:
- * a) LogFactory.class.getClassLoader() may return 'null'
+ * * LogFactory.class.getClassLoader() may return 'null'
* if LogFactory is loaded by the bootstrap classloader.
- * b) The Java endorsed library mechanism is instead
- * Class.forName(factoryClass);
*/
// 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.",
@@ -581,14 +1205,79 @@
return new LogConfigurationException(e);
}
}
- });
- if (result instanceof LogConfigurationException)
- throw (LogConfigurationException)result;
-
- return (LogFactory)result;
+ /**
+ * Determines whether the given class actually implements <code>LogFactory</code>.
+ * Diagnostic information is also logged.
+ * <p>
+ * <strong>Usage:</strong> to diagnose whether a classloader conflict is the cause
+ * of incompatibility. The test used is whether the class is assignable from
+ * the <code>LogFactory</code> class loaded by the class's classloader.
+ * @param logFactoryClass <code>Class</code> which may implement <code>LogFactory</code>
+ * @return true if the <code>logFactoryClass</code> does extend
+ * <code>LogFactory</code> when that class is loaded via the same
+ * classloader that loaded the <code>logFactoryClass</code>.
+ */
+ private static boolean implementsLogFactory(Class logFactoryClass) {
+ 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;
}
+ /**
+ * 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.
+ */
private static InputStream getResourceAsStream(final ClassLoader loader,
final String name)
{
@@ -603,4 +1292,439 @@
}
});
}
+
+ /**
+ * Given a filename, return an enumeration of URLs pointing to
+ * all the occurrences of that filename in the classpath.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ */
+ private static Enumeration getResources(final ClassLoader loader,
+ final String name)
+ {
+ 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;
+ }
+
+ /**
+ * 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.
+ * <p>
+ * Null is returned if the URL cannot be opened.
+ */
+ private static Properties getProperties(final URL url) {
+ 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);
+ }
+
+ /**
+ * Locate a user-provided configuration file.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ */
+ private static final Properties getConfigurationFile(
+ ClassLoader classLoader, String fileName) {
+
+ 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;
+ }
+
+ /**
+ * 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.
+ */
+ private static void initDiagnostics() {
+ 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 + "] ";
+ }
+
+ /**
+ * Indicates true if the user has enabled internal logging.
+ * <p>
+ * By the way, sorry for the incorrect grammar, but calling this method
+ * areDiagnosticsEnabled just isn't java beans style.
+ *
+ * @return true if calls to logDiagnostic will have any effect.
+ * @since 1.1
+ */
+ protected static boolean isDiagnosticsEnabled() {
+ return diagnosticsStream != null;
+ }
+
+ /**
+ * Write the specified message to the internal logging destination.
+ * <p>
+ * 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 at ....,
+ * while subclasses should put SomeSubClass at ...
+ * <p>
+ * Subclasses should instead compute their own prefix, then call
+ * logRawDiagnostic. Note that calling isDiagnosticsEnabled is
+ * fine for subclasses.
+ * <p>
+ * Note that it is safe to call this method before initDiagnostics
+ * is called; any output will just be ignored (as isDiagnosticsEnabled
+ * will return false).
+ *
+ * @param msg is the diagnostic message to be output.
+ */
+ private static final void logDiagnostic(String msg) {
+ if (diagnosticsStream != null) {
+ diagnosticsStream.print(diagnosticPrefix);
+ diagnosticsStream.println(msg);
+ diagnosticsStream.flush();
+ }
+ }
+
+ /**
+ * Write the specified message to the internal logging destination.
+ *
+ * @param msg is the diagnostic message to be output.
+ * @since 1.1
+ */
+ protected static final void logRawDiagnostic(String msg) {
+ if (diagnosticsStream != null) {
+ diagnosticsStream.println(msg);
+ diagnosticsStream.flush();
+ }
+ }
+
+ /**
+ * Generate useful diagnostics regarding the classloader tree for
+ * the specified class.
+ * <p>
+ * As an example, if the specified class was loaded via a webapp's
+ * classloader, then you may get the following output:
+ * <pre>
+ * Class com.acme.Foo was loaded via classloader 11111
+ * ClassLoader tree: 11111 -> 22222 (SYSTEM) -> 33333 -> BOOT
+ * </pre>
+ * <p>
+ * This method returns immediately if isDiagnosticsEnabled()
+ * returns false.
+ *
+ * @param clazz is the class whose classloader + tree are to be
+ * output.
+ */
+ private static void logClassLoaderEnvironment(Class clazz) {
+ 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);
+ }
+
+ /**
+ * 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.
+ * @param prefix
+ * @param classLoader
+ */
+ private static void logHierarchy(String prefix, ClassLoader classLoader) {
+ 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());
+ }
+ }
+
+ /**
+ * Returns a string that uniquely identifies the specified object, including
+ * its class.
+ * <p>
+ * The returned string is of form "classname at 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.
+ *
+ * @param o may be null.
+ * @return a string of form classname at hashcode, or "null" if param o is null.
+ * @since 1.1
+ */
+ public static String objectId(Object o) {
+ if (o == null) {
+ return "null";
+ } else {
+ return o.getClass().getName() + "@" + System.identityHashCode(o);
+ }
+ }
+
+ // ----------------------------------------------------------------------
+ // Static initialiser block to perform initialisation at class load time.
+ //
+ // We can't do this in the class constructor, as there are many
+ // static methods on this class that can be called before any
+ // LogFactory instances are created, and they depend upon this
+ // stuff having been set up.
+ //
+ // Note that this block must come after any variable declarations used
+ // by any methods called from this block, as we want any static initialiser
+ // associated with the variable to run first. If static initialisers for
+ // variables run after this code, then (a) their value might be needed
+ // by methods called from here, and (b) they might *override* any value
+ // computed here!
+ //
+ // So the wisest thing to do is just to place this code at the very end
+ // of the class file.
+ // ----------------------------------------------------------------------
+
+ static {
+ // note: it's safe to call methods before initDiagnostics.
+ thisClassLoader = getClassLoader(LogFactory.class);
+ initDiagnostics();
+ logClassLoaderEnvironment(LogFactory.class);
+ factories = createFactoryStore();
+ if (isDiagnosticsEnabled()) {
+ logDiagnostic("BOOTSTRAP COMPLETED");
+ }
+ }
}
More information about the jboss-cvs-commits
mailing list