From d102883962aad25cc25f1ceb47c01d15ca8872cc Mon Sep 17 00:00:00 2001 From: Simon Kitching Date: Sun, 22 Jan 2006 08:13:27 +0000 Subject: [PATCH] Add info about new commons-logging-adapters jar Remove info about non-existent optional jar Update info about commons-logging-api jar git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/logging/trunk@371233 13f79535-47bb-0310-9956-ffa450edef68 --- xdocs/guide.xml | 94 ++++++++++++++++++++++++------------------------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/xdocs/guide.xml b/xdocs/guide.xml index 70d429a..ae5b524 100644 --- a/xdocs/guide.xml +++ b/xdocs/guide.xml @@ -45,8 +45,8 @@
  • Jars Included in the Standard Distribution
    1. commons-logging.jar
      2. -
    2. commons-logging-optional.jar
    3. commons-logging-api.jar
      4. +
    4. commons-logging-adapters.jar
  • JCL Best Practices
    • @@ -348,43 +348,48 @@ pre-1.4 systems. In most cases, including 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. -

    +default 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. +
    @@ -618,20 +623,15 @@ classloader (and thus to all the classes loaded by it) will be held in 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