From ff0fee9d0cebe037d4a3a991ee6840ddcc469d7c Mon Sep 17 00:00:00 2001 From: "Gary D. Gregory" Date: Thu, 23 Jan 2025 16:38:24 -0500 Subject: [PATCH] Port from Doxia 1 to 2 --- src/site/xdoc/building.xml | 4 +- src/site/xdoc/guide.xml | 49 ++++++++++-------------- src/site/xdoc/index.xml | 5 ++- src/site/xdoc/junit-report.xml | 5 ++- src/site/xdoc/proposal.xml | 8 ++-- src/site/xdoc/tech.xml | 5 ++- src/site/xdoc/troubleshooting.xml | 62 ++++++++++++++----------------- 7 files changed, 64 insertions(+), 74 deletions(-) diff --git a/src/site/xdoc/building.xml b/src/site/xdoc/building.xml index c2805a2..f0cb8b4 100644 --- a/src/site/xdoc/building.xml +++ b/src/site/xdoc/building.xml @@ -15,7 +15,9 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> - + Building Commons Documentation Team diff --git a/src/site/xdoc/guide.xml b/src/site/xdoc/guide.xml index 469ef75..2f7a7f4 100644 --- a/src/site/xdoc/guide.xml +++ b/src/site/xdoc/guide.xml @@ -19,8 +19,9 @@ --> - - + User Guide Commons Documentation Team @@ -28,7 +29,6 @@
-

  1. Introduction
  2. Quick Start @@ -85,7 +85,6 @@
  3. Frequently Asked Questions
-

@@ -228,18 +227,16 @@ is responsible for handling such issues.

-

+

To use the JCL SPI from a Java class, include the following import statements: -

-
    - +

    + import org.apache.commons.logging.Log;
    import org.apache.commons.logging.LogFactory;
    -

Note that some components using JCL may either extend Log, @@ -251,7 +248,6 @@ on how commons-logging should be used in such components. For each class definition, declare and initialize a log attribute as follows:

-
    public class CLASS { @@ -259,7 +255,6 @@ public class CLASS ... ; -

Note that for application code, declaring the log member as "static" is more efficient as one Log object is created per class, and is recommended. @@ -278,7 +273,6 @@ The org.apache.commons.logging.Log interface defines the following methods for use in writing log/trace messages to the log:

-
    log.fatal(Object message); log.fatal(Object message, Throwable t); @@ -293,7 +287,6 @@ in writing log/trace messages to the log: log.trace(Object message); log.trace(Object message, Throwable t); -

Semantics for these methods are such that it is expected that the severity, from highest to lowest, of messages is ordered as above. @@ -301,7 +294,6 @@ that the severity, from highest to lowest, of messages is ordered as above.

In addition to the logging methods, the following are provided for code guards:

-
    log.isFatalEnabled(); log.isErrorEnabled(); @@ -310,7 +302,6 @@ In addition to the logging methods, the following are provided for code guards: log.isDebugEnabled(); log.isTraceEnabled(); -

Prior to release 1.0.4, none of the standard Log implementations were @@ -434,13 +425,13 @@ The following guidelines are suggested:

  • fatal - Severe errors that cause premature termination. Expect these to be immediately visible on a status console. -See also +See also Internationalization.
  • error - Other runtime errors or unexpected conditions. Expect these to be immediately visible on a status console. -See also +See also Internationalization.
  • @@ -448,14 +439,14 @@ Internationalization. other runtime situations that are undesirable or unexpected, but not necessarily "wrong". Expect these to be immediately visible on a status console. -See also +See also Internationalization.
  • info - Interesting runtime events (startup/shutdown). Expect these to be immediately visible on a console, so be conservative and keep to a minimum. -See also +See also Internationalization.
  • @@ -561,11 +552,9 @@ If more control is desired for the level of detail of these 'enterprise' exceptions, then consider creating a special logger just for these exceptions:

    -
      Log log = LogFactory.getLog("org.apache.component.enterprise"); -

    This allows the 'enterprise' level information to be turned on/off explicitly by most logger implementations. @@ -669,29 +658,29 @@ new LogFactory implementations that provide alternative discovery s When creating new implementations for Log and LogFactory, it is important to understand the implied contract between the factory and the log implementations: -

      -
    • Life cycle -
      +

      +
        +
      • Life cycle +
        The JCL LogFactory implementation must assume responsibility for either connecting/disconnecting to a logging toolkit, or instantiating/initializing/destroying a logging toolkit. -
        +
      • -
    • Exception handling -
      +
    • Exception handling +
      The JCL Log interface doesn't specify any exceptions to be handled, the implementation must catch any exceptions.
      • -
    • Multiple threads -
      +
    • Multiple threads +
      The JCL Log and LogFactory implementations must ensure that any synchronization required by the logging toolkit is met.
    -

    diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml index 9e8b8b9..8a56f2e 100644 --- a/src/site/xdoc/index.xml +++ b/src/site/xdoc/index.xml @@ -19,8 +19,9 @@ --> - - + Overview Commons Documentation Team diff --git a/src/site/xdoc/junit-report.xml b/src/site/xdoc/junit-report.xml index f48dcd9..63edf44 100644 --- a/src/site/xdoc/junit-report.xml +++ b/src/site/xdoc/junit-report.xml @@ -15,8 +15,9 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> - - + JUnit Test Results Commons Documentation Team diff --git a/src/site/xdoc/proposal.xml b/src/site/xdoc/proposal.xml index 555bc71..26e4ad5 100644 --- a/src/site/xdoc/proposal.xml +++ b/src/site/xdoc/proposal.xml @@ -17,7 +17,9 @@ --> - + Proposal for Logging Library Package @@ -51,21 +53,21 @@ implementations.

    The package should : +

    • Have an API which should be as simple to use as possible
    • Provide support for Log4j
    • Provide pluggable support for other logging APIs
    -

    Non-goals: +

    • This package will not perform logging itself, except at the most basic level.
    • We do not seek to become a "standard" API.
    -

     diff --git a/src/site/xdoc/tech.xml b/src/site/xdoc/tech.xml index bf30a48..9667248 100644 --- a/src/site/xdoc/tech.xml +++ b/src/site/xdoc/tech.xml @@ -17,8 +17,9 @@ See the License for the specific language governing permissions and limitations under the License. --> - - + Technology Guide Commons Documentation Team diff --git a/src/site/xdoc/troubleshooting.xml b/src/site/xdoc/troubleshooting.xml index a97faf7..e0c6cab 100644 --- a/src/site/xdoc/troubleshooting.xml +++ b/src/site/xdoc/troubleshooting.xml @@ -19,8 +19,9 @@ --> - - + Troubleshooting Guide Commons Documentation Team @@ -37,7 +38,6 @@
    • When To Use Diagnostic Logging -
      • How To Use Diagnostic logging @@ -86,15 +86,12 @@
        • Apache Tomcat -
          • JBoss Application Server -
            • Other Containers -
              • @@ -134,19 +131,19 @@ Diagnostics uses the concept of an Object ID (OID). This allows the identity of to be tracked without relying on useful toString implementations. These are of the form:

              -
              +
 classname@system identity hash code
-
              +

              The system identity hash code is found by calling System.identityHashCode() which should uniquely identify a particular instance. The classname is usually the fully qualified class name though in a few cases, org.apache.commons.logging.impl.LogFactoryImpl may be shortened to LogFactoryImpl to increase ease of reading. For example:

              -
              +
 sun.misc.Launcher$AppClassLoader@20120943
 LogFactoryImpl@1671711
-
              +

              OIDs are intended to be used to cross-reference. They allow particular instances of classloaders and JCL classes to be tracked in different contexts. This plays a vital role in building @@ -158,9 +155,9 @@ up the understanding of the classloader environment required to diagnose JCL pro Each diagnostic message is prefixed with details of the relevant class in a standard format. This takes the form:

              -
              +
 [class-identifier from ClassLoader OID]
-
              +

              ClassLoader OID is the OID of a classloader which loaded the class issuing the message. @@ -170,19 +167,19 @@ the class issuing the message. In the case of LogFactory, this is just LogFactory. For example (line split):

              -
              +
 [LogFactory 
    from sun.misc.Launcher$AppClassLoader@20120943] BOOTSTRAP COMPLETED
-
              +

              In the case of LogFactoryImpl, the prefix is the instance OID. This can be cross referenced to discover the details of the TCCL used to manage this instance. For example (line split):

              -
              +
 [LogFactoryImpl@1671711 
    from sun.misc.Launcher$AppClassLoader@20120943] Instance created.
-
              +

              @@ -193,12 +190,12 @@ Each classloader is represented (visually) by an OID (to allow cross referencing and the relationship indicated in child --> parent fashion. For example (line split for easy reading):

              -
              +
 ClassLoader tree:java.net.URLClassLoader@3526198  
       --> sun.misc.Launcher$AppClassLoader@20120943 (SYSTEM) 
       --> sun.misc.Launcher$ExtClassLoader@11126876 
       --> BOOT
-
              +

              Represents a hierarchy with four elements ending in the boot classloader.

              @@ -216,15 +213,15 @@ are logged.

              Many Sun classloaders have confusing toString values. For example, the OID may be

              -
              +
 sun.misc.Launcher$AppClassLoader@20120943
-
              +

              with a toString value of

              -
              +
 sun.misc.Launcher$AppClassLoader@133056f
-
              +

              Other classloader implementations may give very useful information (such as the local classpath).

              @@ -252,7 +249,7 @@ allowing the OID later to be cross-referenced to the t and the classloader tree. For example, the following log snippet details the TCCL (lines split):

              -
              +
 [LogFactory from sun.misc.Launcher$AppClassLoader@20120943] 
     [LOOKUP] LogFactory implementation requested for the first time for context 
         classloader java.net.URLClassLoader@3526198
@@ -263,7 +260,7 @@ following log snippet details the TCCL (lines split):
         --> sun.misc.Launcher$AppClassLoader@20120943 (SYSTEM)  
           --> sun.misc.Launcher$ExtClassLoader@11126876 
             --> BOOT
-
              +

              @@ -305,11 +302,11 @@ The Apache Commons team would be grateful if reports were posted to the developm of other containers using a custom implementation.

              - +

              Symptoms

              An exception is thrown by JCL with a message similar to:

              - 
              +  
   The chosen LogFactory implementation does not extend LogFactory. Please check your configuration. 
   (Caused by java.lang.ClassCastException: The application has specified that a custom LogFactory 
   implementation should be used but Class 'com.ibm.ws.commons.logging.TrLogFactory' cannot be converted 
@@ -319,14 +316,13 @@ of other containers using a custom implementation.
   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. Help can be found @https//commons.apache.org/logging.
-
              +

              This is a WebSphere example so the name of the custom LogFactory is com.ibm.ws.commons.logging.TrLogFactory. For other containers, this class name will differ.

              -               - +

              Explanation

              A custom LogFactory implementation can only be used if the implementation class loaded dynamically at runtime can be cast to the LogFactory class that loaded it. There are @@ -357,8 +353,7 @@ containers which have custom implementations: the above runtime exception may be under certain classloading policies without the user knowingly specifying a custom implementation.

              -               - +

              Fixes

              There are various ways to fix this problem. Which fix is right depends on the circumstances.

              @@ -371,9 +366,9 @@ implementation. If you want to bypass the container adaption mechanism then set the appropriate system property to the default value when the container is started:

              - 
              + 
  -Dorg.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl
-
              +

              If you want to continue to use the default container mechanism then:

              @@ -392,7 +387,6 @@ implementation. If you encounter difficulties when applying the fixes recommended, please turn on diagnostics and consult the logs.

              -