public class LogFactoryImpl extends LogFactory
LogFactory
that implements the
following algorithm to dynamically select a logging implementation
class to instantiate a wrapper for:
org.apache.commons.logging.Log
to identify the
requested implementation class.org.apache.commons.logging.Log
system property
to identify the requested implementation class.org.apache.commons.logging.impl.Log4JLogger
.org.apache.commons.logging.impl.Jdk14Logger
.org.apache.commons.logging.impl.SimpleLog
.
If the selected Log
implementation class has a
setLogFactory()
method that accepts a LogFactory
parameter, this method will be called on each newly created instance
to identify the associated factory. This makes factory configuration
attributes available to the Log instance, if it so desires.
This factory will remember previously created Log
instances
for the same name, and will return them on repeated requests to the
getInstance()
method.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
ALLOW_FLAWED_CONTEXT_PROPERTY
The name (
org.apache.commons.logging.Log.allowFlawedContext )
of the system property which can be set true/false to
determine system behaviour when a bad context-classloader is encountered. |
static java.lang.String |
ALLOW_FLAWED_DISCOVERY_PROPERTY
The name (
org.apache.commons.logging.Log.allowFlawedDiscovery )
of the system property which can be set true/false to
determine system behaviour when a bad logging adapter class is
encountered during logging discovery. |
static java.lang.String |
ALLOW_FLAWED_HIERARCHY_PROPERTY
The name (
org.apache.commons.logging.Log.allowFlawedHierarchy )
of the system property which can be set true/false to
determine system behaviour when a logging adapter class is
encountered which has bound to the wrong Log class implementation. |
private boolean |
allowFlawedContext
See getBaseClassLoader and initConfiguration.
|
private boolean |
allowFlawedDiscovery
See handleFlawedDiscovery and initConfiguration.
|
private boolean |
allowFlawedHierarchy
See handleFlawedHierarchy and initConfiguration.
|
protected java.util.Hashtable |
attributes
Configuration attributes.
|
private static java.lang.String[] |
classesToDiscover
The names of classes that will be tried (in order) as logging
adapters.
|
private java.lang.String |
diagnosticPrefix
The string prefixed to every message output by the logDiagnostic method.
|
protected java.util.Hashtable |
instances
The
Log instances that have
already been created, keyed by logger name. |
static java.lang.String |
LOG_PROPERTY
The name (
org.apache.commons.logging.Log ) of the system
property identifying our Log implementation class. |
protected static java.lang.String |
LOG_PROPERTY_OLD
The deprecated system property used for backwards compatibility with
old versions of JCL.
|
private java.lang.String |
logClassName
Name of the class implementing the Log interface.
|
protected java.lang.reflect.Constructor |
logConstructor
The one-argument constructor of the
Log
implementation class that will be used to create new instances. |
protected java.lang.Class[] |
logConstructorSignature
The signature of the Constructor to be used.
|
private static java.lang.String |
LOGGING_IMPL_JDK14_LOGGER
Jdk14Logger class name
|
private static java.lang.String |
LOGGING_IMPL_LOG4J_LOGGER
Log4JLogger class name
|
private static java.lang.String |
LOGGING_IMPL_LUMBERJACK_LOGGER
Jdk13LumberjackLogger class name
|
private static java.lang.String |
LOGGING_IMPL_SIMPLE_LOGGER
SimpleLog class name
|
protected java.lang.reflect.Method |
logMethod
The one-argument
setLogFactory method of the selected
Log method, if it exists. |
protected java.lang.Class[] |
logMethodSignature
The signature of the
setLogFactory method to be used. |
private static java.lang.String |
PKG_IMPL |
private static int |
PKG_LEN |
private boolean |
useTCCL
Determines whether logging classes should be loaded using the thread-context
classloader, or via the classloader that loaded this LogFactoryImpl class.
|
DIAGNOSTICS_DEST_PROPERTY, factories, FACTORY_DEFAULT, FACTORY_PROPERTIES, FACTORY_PROPERTY, HASHTABLE_IMPLEMENTATION_PROPERTY, nullClassLoaderFactory, PRIORITY_KEY, SERVICE_ID, TCCL_KEY
Constructor and Description |
---|
LogFactoryImpl()
Public no-arguments constructor required by the lookup mechanism.
|
Modifier and Type | Method and Description |
---|---|
private Log |
createLogFromClass(java.lang.String logAdapterClassName,
java.lang.String logCategory,
boolean affectState)
Attempts to load the given class, find a suitable constructor,
and instantiate an instance of Log.
|
private Log |
discoverLogImplementation(java.lang.String logCategory)
Attempts to create a Log instance for the given category name.
|
private java.lang.String |
findUserSpecifiedLogClassName()
Checks system properties and the attribute map for
a Log implementation specified by the user under the
property names
LOG_PROPERTY or LOG_PROPERTY_OLD . |
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. |
java.lang.String[] |
getAttributeNames()
Return an array containing the names of all currently defined
configuration attributes.
|
private java.lang.ClassLoader |
getBaseClassLoader()
Return the classloader from which we should try to load the logging
adapter classes.
|
private boolean |
getBooleanConfiguration(java.lang.String key,
boolean dflt)
Get the setting for the user-configurable behaviour specified by key.
|
protected static java.lang.ClassLoader |
getClassLoader(java.lang.Class clazz)
Workaround for bug in Java1.2; in theory this method is not needed.
|
private java.lang.String |
getConfigurationValue(java.lang.String property)
Attempt to find an attribute (see method setAttribute) or a
system property with the provided name and return its value.
|
protected static java.lang.ClassLoader |
getContextClassLoader()
Gets the context classloader.
|
private static java.lang.ClassLoader |
getContextClassLoaderInternal()
Calls LogFactory.directGetContextClassLoader under the control of an
AccessController class.
|
Log |
getInstance(java.lang.Class clazz)
Convenience method to derive a name from the specified class and
call
getInstance(String) with it. |
Log |
getInstance(java.lang.String name)
Construct (if necessary) and return a
Log instance,
using the factory's current set of configuration attributes. |
protected java.lang.String |
getLogClassName()
Deprecated.
Never invoked by this class; subclasses should not assume
it will be.
|
protected java.lang.reflect.Constructor |
getLogConstructor()
Deprecated.
Never invoked by this class; subclasses should not assume
it will be.
|
private java.lang.ClassLoader |
getLowestClassLoader(java.lang.ClassLoader c1,
java.lang.ClassLoader c2)
Given two related classloaders, return the one which is a child of
the other.
|
private java.lang.ClassLoader |
getParentClassLoader(java.lang.ClassLoader cl)
Fetch the parent classloader of a specified classloader.
|
private static java.lang.String |
getSystemProperty(java.lang.String key,
java.lang.String def)
Read the specified system property, using an AccessController so that
the property can be read if JCL has been granted the appropriate
security rights even if the calling code has not.
|
private void |
handleFlawedDiscovery(java.lang.String logAdapterClassName,
java.lang.ClassLoader classLoader,
java.lang.Throwable discoveryFlaw)
Generates an internal diagnostic logging of the discovery failure and
then throws a
LogConfigurationException that wraps
the passed Throwable . |
private void |
handleFlawedHierarchy(java.lang.ClassLoader badClassLoader,
java.lang.Class badClass)
Report a problem loading the log adapter, then either return
(if the situation is considered recoverable) or throw a
LogConfigurationException.
|
private void |
informUponSimilarName(java.lang.StringBuffer messageBuffer,
java.lang.String name,
java.lang.String candidate)
Appends message if the given name is similar to the candidate.
|
private void |
initConfiguration()
Initialize a number of variables that control the behaviour of this
class and that can be tweaked by the user.
|
private void |
initDiagnostics()
Calculate and cache a string that uniquely identifies this instance,
including which classloader the object was loaded from.
|
protected static boolean |
isDiagnosticsEnabled()
Workaround for bug in Java1.2; in theory this method is not needed.
|
protected boolean |
isJdk13LumberjackAvailable()
Deprecated.
Never invoked by this class; subclasses should not assume
it will be.
|
protected boolean |
isJdk14Available()
Deprecated.
Never invoked by this class; subclasses should not assume
it will be.
|
protected boolean |
isLog4JAvailable()
Deprecated.
Never invoked by this class; subclasses should not assume
it will be.
|
private boolean |
isLogLibraryAvailable(java.lang.String name,
java.lang.String classname)
Utility method to check whether a particular logging library is
present and available for use.
|
protected void |
logDiagnostic(java.lang.String msg)
Output a diagnostic message to a user-specified destination (if the
user has enabled diagnostic logging).
|
protected Log |
newInstance(java.lang.String name)
Create and return a new
Log
instance for the specified name. |
void |
release()
Release any internal references to previously created
Log
instances returned by this factory. |
void |
removeAttribute(java.lang.String name)
Remove any configuration attribute associated with the specified name.
|
void |
setAttribute(java.lang.String name,
java.lang.Object value)
Set the configuration attribute with the specified name.
|
createFactory, directGetContextClassLoader, getFactory, getLog, getLog, handleThrowable, logRawDiagnostic, newFactory, newFactory, objectId, release, releaseAll
private static final java.lang.String LOGGING_IMPL_LOG4J_LOGGER
private static final java.lang.String LOGGING_IMPL_JDK14_LOGGER
private static final java.lang.String LOGGING_IMPL_LUMBERJACK_LOGGER
private static final java.lang.String LOGGING_IMPL_SIMPLE_LOGGER
private static final java.lang.String PKG_IMPL
private static final int PKG_LEN
public static final java.lang.String LOG_PROPERTY
org.apache.commons.logging.Log
) of the system
property identifying our Log
implementation class.protected static final java.lang.String LOG_PROPERTY_OLD
public static final java.lang.String ALLOW_FLAWED_CONTEXT_PROPERTY
org.apache.commons.logging.Log.allowFlawedContext
)
of the system property which can be set true/false to
determine system behaviour when a bad context-classloader is encountered.
When set to false, a LogConfigurationException is thrown if
LogFactoryImpl is loaded via a child classloader of the TCCL (this
should never happen in sane systems).
Default behaviour: true (tolerates bad context classloaders)
See also method setAttribute.public static final java.lang.String ALLOW_FLAWED_DISCOVERY_PROPERTY
org.apache.commons.logging.Log.allowFlawedDiscovery
)
of the system property which can be set true/false to
determine system behaviour when a bad logging adapter class is
encountered during logging discovery. When set to false, an
exception will be thrown and the app will fail to start. When set
to true, discovery will continue (though the user might end up
with a different logging implementation than they expected).
Default behaviour: true (tolerates bad logging adapters) See also method setAttribute.
public static final java.lang.String ALLOW_FLAWED_HIERARCHY_PROPERTY
org.apache.commons.logging.Log.allowFlawedHierarchy
)
of the system property which can be set true/false to
determine system behaviour when a logging adapter class is
encountered which has bound to the wrong Log class implementation.
When set to false, an exception will be thrown and the app will fail
to start. When set to true, discovery will continue (though the user
might end up with a different logging implementation than they expected).
Default behaviour: true (tolerates bad Log class hierarchy) See also method setAttribute.
private static final java.lang.String[] classesToDiscover
private boolean useTCCL
private java.lang.String diagnosticPrefix
protected java.util.Hashtable attributes
protected java.util.Hashtable instances
Log
instances that have
already been created, keyed by logger name.private java.lang.String logClassName
protected java.lang.reflect.Constructor logConstructor
Log
implementation class that will be used to create new instances.
This value is initialized by getLogConstructor()
,
and then returned repeatedly.protected java.lang.Class[] logConstructorSignature
protected java.lang.reflect.Method logMethod
setLogFactory
method of the selected
Log
method, if it exists.protected java.lang.Class[] logMethodSignature
setLogFactory
method to be used.private boolean allowFlawedContext
private boolean allowFlawedDiscovery
private boolean allowFlawedHierarchy
public LogFactoryImpl()
public java.lang.Object getAttribute(java.lang.String name)
null
if there is no such attribute.getAttribute
in class LogFactory
name
- Name of the attribute to returnpublic java.lang.String[] getAttributeNames()
getAttributeNames
in class LogFactory
public Log getInstance(java.lang.Class clazz) throws LogConfigurationException
getInstance(String)
with it.getInstance
in class LogFactory
clazz
- Class for which a suitable Log name will be derivedLogConfigurationException
- if a suitable Log
instance cannot be returnedpublic Log getInstance(java.lang.String name) throws LogConfigurationException
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.
getInstance
in class LogFactory
name
- Logical name of the Log
instance to be
returned (the meaning of this name is only known to the underlying
logging implementation that is being wrapped)LogConfigurationException
- if a suitable Log
instance cannot be returnedpublic void release()
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.release
in class LogFactory
public void removeAttribute(java.lang.String name)
removeAttribute
in class LogFactory
name
- Name of the attribute to removepublic void setAttribute(java.lang.String name, java.lang.Object value)
null
value is equivalent to calling
removeAttribute(name)
.
This method can be used to set logging configuration programmatically rather than via system properties. It can also be used in code running within a container (such as a webapp) to configure behaviour on a per-component level instead of globally as system properties would do. To use this method instead of a system property, call
LogFactory.getFactory().setAttribute(...)This must be done before the first Log object is created; configuration changes after that point will be ignored.
This method is also called automatically if LogFactory detects a commons-logging.properties file; every entry in that file is set automatically as an attribute here.
setAttribute
in class LogFactory
name
- Name of the attribute to setvalue
- Value of the attribute to set, or null
to remove any setting for this attributeprotected static java.lang.ClassLoader getContextClassLoader() throws LogConfigurationException
LogConfigurationException
protected static boolean isDiagnosticsEnabled()
protected static java.lang.ClassLoader getClassLoader(java.lang.Class clazz)
private void initDiagnostics()
This string will later be prefixed to each "internal logging" message emitted, so that users can clearly see any unexpected behaviour.
Note that this method does not detect whether internal logging is enabled or not, nor where to output stuff if it is; that is all handled by the parent LogFactory class. This method just computes its own unique prefix for log messages.
protected void logDiagnostic(java.lang.String msg)
msg
- diagnostic messageprotected java.lang.String getLogClassName()
Log
implementation we will be using.protected java.lang.reflect.Constructor getLogConstructor() throws LogConfigurationException
Return the Constructor
that can be called to instantiate
new Log
instances.
IMPLEMENTATION NOTE - Race conditions caused by
calling this method from more than one thread are ignored, because
the same Constructor
instance will ultimately be derived
in all circumstances.
LogConfigurationException
- if a suitable constructor
cannot be returnedprotected boolean isJdk13LumberjackAvailable()
protected boolean isJdk14Available()
true
if JDK 1.4 or later logging
is available. Also checks that the Throwable
class
supports getStackTrace()
, which is required by
Jdk14Logger.protected boolean isLog4JAvailable()
protected Log newInstance(java.lang.String name) throws LogConfigurationException
Log
instance for the specified name.name
- Name of the new loggerLogConfigurationException
- if a new instance cannot
be createdprivate static java.lang.ClassLoader getContextClassLoaderInternal() throws LogConfigurationException
LogConfigurationException
- if there was some weird error while
attempting to get the context classloader.java.lang.SecurityException
- if the current java security policy doesn't
allow this class to access the context classloader.private static java.lang.String getSystemProperty(java.lang.String key, java.lang.String def) throws java.lang.SecurityException
Take care not to expose the value returned by this method to the calling application in any way; otherwise the calling app can use that info to access data that should not be available to it.
java.lang.SecurityException
private java.lang.ClassLoader getParentClassLoader(java.lang.ClassLoader cl)
If a SecurityException occurs, null is returned.
Note that this method is non-static merely so logDiagnostic is available.
private boolean isLogLibraryAvailable(java.lang.String name, java.lang.String classname)
private java.lang.String getConfigurationValue(java.lang.String property)
The attributes associated with this object are checked before system properties in case someone has explicitly called setAttribute, or a configuration property has been set in a commons-logging.properties file.
private boolean getBooleanConfiguration(java.lang.String key, boolean dflt)
private void initConfiguration()
private Log discoverLogImplementation(java.lang.String logCategory) throws LogConfigurationException
logCategory
- the name of the log categoryLogConfigurationException
- if an error in discovery occurs,
or if no adapter at all can be instantiatedprivate void informUponSimilarName(java.lang.StringBuffer messageBuffer, java.lang.String name, java.lang.String candidate)
messageBuffer
- StringBuffer
the message should be appended to,
not nullname
- the (trimmed) name to be test against the candidate, not nullcandidate
- the candidate name (not null)private java.lang.String findUserSpecifiedLogClassName()
LOG_PROPERTY
or LOG_PROPERTY_OLD
.null
private Log createLogFromClass(java.lang.String logAdapterClassName, java.lang.String logCategory, boolean affectState) throws LogConfigurationException
logAdapterClassName
- classname of the Log implementationlogCategory
- argument to pass to the Log implementation's constructoraffectState
- true
if this object's state should
be affected by this method call, false
otherwise.LogConfigurationException
- if there was a serious error with
configuration and the handleFlawedDiscovery method decided this
problem was fatal.private java.lang.ClassLoader getBaseClassLoader() throws LogConfigurationException
This method usually returns the context classloader. However if it is discovered that the classloader which loaded this class is a child of the context classloader and the allowFlawedContext option has been set then the classloader which loaded this class is returned instead.
The only time when the classloader which loaded this class is a descendant (rather than the same as or an ancestor of the context classloader) is when an app has created custom classloaders but failed to correctly set the context classloader. This is a bug in the calling application; however we provide the option for JCL to simply generate a warning rather than fail outright.
LogConfigurationException
private java.lang.ClassLoader getLowestClassLoader(java.lang.ClassLoader c1, java.lang.ClassLoader c2)
c1
- is a classloader (including the null classloader)c2
- is a classloader (including the null classloader)private void handleFlawedDiscovery(java.lang.String logAdapterClassName, java.lang.ClassLoader classLoader, java.lang.Throwable discoveryFlaw)
LogConfigurationException
that wraps
the passed Throwable
.logAdapterClassName
- is the class name of the Log implementation
that could not be instantiated. Cannot be null
.classLoader
- is the classloader that we were trying to load the
logAdapterClassName from when the exception occurred.discoveryFlaw
- is the Throwable created by the classloaderLogConfigurationException
- ALWAYSprivate void handleFlawedHierarchy(java.lang.ClassLoader badClassLoader, java.lang.Class badClass) throws LogConfigurationException
There are two possible reasons why we successfully loaded the specified log adapter class then failed to cast it to a Log object:
Here we try to figure out which case has occurred so we can give the user some reasonable feedback.
badClassLoader
- is the classloader we loaded the problem class from,
ie it is equivalent to badClass.getClassLoader().badClass
- is a Class object with the desired name, but which
does not implement Log correctly.LogConfigurationException
- when the situation
should not be recovered from.