commons-logging.jar and your preferred
logging implementation in the classpath should be all that is required to
use JCL.
-
-
-
-The optional jar includes, oddly enough, optional classes that are useful but
-not strictly required to make JCL functional. As these classes introduce
-dependencies on JDK 1.3+ JVMs and a goal of JCL is to be usable on JDK 1.2
-and earlier JVMs, these optional classes are not included in the main
-commons-logging.jar.
-
-Included in the optional jar are classes which allow JCL to (potentially) improve
-it's memory utilization (see
-Classloader and Memory Management
-below). It is therefore recommended that (when running on a 1.3+ JDK) the optional jar
-be deployed alongside the
-main commons-logging.jar. It should be deployed such that it will be loaded
-by the same classloader that loads LogFactory. When so deployed, JCL will
-discover the appropriate classes and configure itself to use them.
+
The commons-logging-api.jar file includes the JCL API and the
-default LogFactory implementation, but does not include the
-wrapper Log implementations for Log4j,
-Avalon and Lumberjack. This jar is intended for
-use in specialized containers such as
-Tomcat that wish to use
-JCL internally but also need to make JCL available for use by deployed
-applications.
-
- If this jar is used, in order to benefit from improved memory management in modern JVMs (1.3+),
- it is recommended that the commons-logging-optional.jar is deployed in
- the same classloader as this jar.
-
LogFactory implementation as well as the built-in
+Log implementations SimpleLog and NoOpLog. However it does not
+include the wrapper Log implementations that require additional
+libraries such as Log4j, Avalon and
+Lumberjack.
+
++This jar is intended for use by projects that recompile the commons-logging +source using alternate java environments, and cannot compile against all of +the optional libraries that the Apache release of commons-logging supports. +Because of the reduced dependencies of this jarfile, such projects should be +able to create an equivalent of this library with fewer difficulties. +
++This jar is also useful for build environments that automatically track +dependencies, and thus have difficulty with the concept that the main +commons-logging.jar has "optional" dependencies on various logging +implementations that can safely go unsatisfied at runtime. +
+
+The commons-logging-adapters.jar file includes only adapters
+to third-party logging implementations, and none of the core commons-logging
+framework. As such, it cannot be used alone; either commons-logging.jar or
+commons-logging-api.jar must also be present in the classpath.
+
+This library will not often be used; it is only intended for situations where +a container has deployed commons-logging-api.jar in a shared classpath but a +webapp wants to bind logging to one of the external logging implementations +that the api jar does not include. In this situation, deploying the +commons-logging.jar file within the webapp can cause problems as this leads to +duplicates of the core commons-logging classes (Log, LogFactory, etc) in +the classpath which in turn can cause unpleasant ClassCastException exceptions +to occur. Deploying only the adapters avoids this problem. +
LogFactory's static hashtable.
-Beginning with JCL 1.0.5, LogFactory will attempt to cache factory
-implementations in a
-WeakHashtable.
-This class is analogous to java.util.WeakHashMap in that it holds
-WeakReferences to its keys, thus allowing classloaders to be GC'd
+Beginning with JCL 1.1, LogFactory caches factory implementations in a
+"WeakHashtable". This class is similar to java.util.WeakHashMap in that it holds a
+WeakReference to each key's value, thus allowing classloaders to be GC'd
even if LogFactory.release() is never invoked.
-Because WeakHashtable depends on JDK 1.3+ features, it cannot
-be included in the main commons-logging.jar file. It is found
-in commons-logging-optional.jar. J2EE container
-implementors who distribute JCL with their application are strongly
-encouraged to place commons-logging-optional.jar on the classpath
-in the same location where LogFactory is loaded.
+Because WeakHashtable depends on JDK 1.3+ features, it is dynamically
+loaded depending on the JVM version; when commons-logging is run on java versions
+prior to 1.3 the code defaults to a standard Hashtable instead.
In a particular usage scenario, WeakHashtable alone will
@@ -642,8 +642,8 @@ loaded by a parent classloader and a concrete subclass implementation of
implementation will have a strong reference to the child classloader via the
chain getClass().getClassLoader(). The WeakHashtable
will have a strong reference to the LogFactory implementation as
-one of the values in its map. This chain of references will prevent
-collection of the child classloader.
+one of the keys in its map (only values can use weak references). This chain
+of references will prevent collection of the child classloader.
Such a situation would typically only occur if commons-logging.jar were