This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-logging.git
The following commit(s) were added to refs/heads/master by this push:
new ff0fee9 Port from Doxia 1 to 2
ff0fee9 is described below
commit ff0fee9d0cebe037d4a3a991ee6840ddcc469d7c
Author: Gary D. Gregory <[email protected]>
AuthorDate: Thu Jan 23 16:38:24 2025 -0500
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.
-->
-<document>
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Building</title>
<author email="[email protected]">Commons Documentation Team</author>
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 @@
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>User Guide</title>
<author email="[email protected]">Commons Documentation Team</author>
@@ -28,7 +29,6 @@
<body>
<section name='Contents'>
- <p>
<ol>
<li><a href='#Introduction'>Introduction</a></li>
<li><a href='#Quick Start'>Quick Start</a>
@@ -85,7 +85,6 @@
<li><a href='#Frequently Asked Questions'>Frequently Asked
Questions</a>
</li>
</ol>
- </p>
</section>
<section name="Introduction">
<p>
@@ -228,18 +227,16 @@ is responsible for handling such issues.
</section>
<section name='Developing With JCL'>
<subsection name="Obtaining a Log Object">
- <p>
+ <p>
To use the JCL SPI from a Java class,
include the following import statements:
- </p>
- <ul>
- <code>
+ </p>
+ <code>
import org.apache.commons.logging.Log;
<br/>
import org.apache.commons.logging.LogFactory;
<br/>
</code>
- </ul>
<p>
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
<code>log</code> attribute as follows:
</p>
- <ul>
<source>
public class CLASS
{
@@ -259,7 +255,6 @@ public class CLASS
...
;
</source>
- </ul>
<p>
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 <code>org.apache.commons.logging.Log</code> interface
defines the
following methods for use
in writing log/trace messages to the log:
</p>
- <ul>
<source>
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);
</source>
- </ul>
<p>
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.
<p>
In addition to the logging methods, the following are provided for code guards:
</p>
- <ul>
<source>
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();
</source>
- </ul>
</subsection>
<subsection name="Serialization Issues">
<p>Prior to release 1.0.4, none of the standard Log implementations were
@@ -434,13 +425,13 @@ The following guidelines are suggested:
<li>
<b>fatal</b> - Severe errors that cause premature termination.
Expect these to be immediately visible on a status console.
-See also <a HREF="#National%20Language%20Support%20And%20Internationalization">
+See also <a href="#National%20Language%20Support%20And%20Internationalization">
Internationalization</a>.
</li>
<li>
<b>error</b> - Other runtime errors or unexpected conditions.
Expect these to be immediately visible on a status console.
-See also <a HREF="#National%20Language%20Support%20And%20Internationalization">
+See also <a href="#National%20Language%20Support%20And%20Internationalization">
Internationalization</a>.
</li>
<li>
@@ -448,14 +439,14 @@ Internationalization</a>.
other runtime situations that are undesirable or unexpected, but not
necessarily "wrong".
Expect these to be immediately visible on a status console.
-See also <a HREF="#National%20Language%20Support%20And%20Internationalization">
+See also <a href="#National%20Language%20Support%20And%20Internationalization">
Internationalization</a>.
</li>
<li>
<b>info</b> - Interesting runtime events (startup/shutdown).
Expect these to be immediately visible on a console,
so be conservative and keep to a minimum.
-See also <a HREF="#National%20Language%20Support%20And%20Internationalization">
+See also <a href="#National%20Language%20Support%20And%20Internationalization">
Internationalization</a>.
</li>
<li>
@@ -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:
</p>
- <ul>
<source>
Log log = LogFactory.getLog("org.apache.<i>component</i>.enterprise");
</source>
- </ul>
<p>
This allows the 'enterprise' level information to be turned on/off explicitly
by most logger implementations.
@@ -669,29 +658,29 @@ new <code>LogFactory</code> implementations that provide
alternative discovery s
When creating new implementations for <code>Log</code> and
<code>LogFactory</code>,
it is important to understand the implied contract between the factory
and the log implementations:
- <ul>
- <li><b>Life cycle</b>
- <blockquote>
+ </p>
+ <ul>
+ <li><b>Life cycle</b>
+ <blockquote>
The JCL LogFactory implementation must assume responsibility for
either connecting/disconnecting to a logging toolkit,
or instantiating/initializing/destroying a logging toolkit.
- </blockquote>
+ </blockquote>
</li>
- <li><b>Exception handling</b>
- <blockquote>
+ <li><b>Exception handling</b>
+ <blockquote>
The JCL Log interface doesn't specify any exceptions to be handled,
the implementation must catch any exceptions.
</blockquote>
</li>
- <li><b>Multiple threads</b>
- <blockquote>
+ <li><b>Multiple threads</b>
+ <blockquote>
The JCL Log and LogFactory implementations must ensure
that any synchronization required by the logging toolkit
is met.
</blockquote>
</li>
</ul>
- </p>
</subsection>
<subsection name='Creating a Log Implementation'>
<p>
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 @@
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Overview</title>
<author email="[email protected]">Commons Documentation Team</author>
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.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>JUnit Test Results</title>
<author email="[email protected]">Commons Documentation Team</author>
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 @@
-->
-<document>
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Proposal for Logging Library Package</title>
</properties>
@@ -51,21 +53,21 @@ implementations.
<p>
The package should :
+</p>
<ul>
<li>Have an API which should be as simple to use as possible</li>
<li>Provide support for Log4j</li>
<li>Provide pluggable support for other logging APIs</li>
</ul>
-</p>
<p>
Non-goals:
+</p>
<ul>
<li>This package will not perform logging itself, except at the most basic
level.</li>
<li>We do not seek to become a "standard" API.</li>
</ul>
-</p>
</subsection>
<subsection name="(1.5) Interaction With Other Packages">
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.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Technology Guide</title>
<author email="[email protected]">Commons Documentation Team</author>
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 @@
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Troubleshooting Guide</title>
<author email="[email protected]">Commons Documentation Team</author>
@@ -37,7 +38,6 @@
<ul>
<li>
<a href="#When To Use Diagnostic Logging">When To Use Diagnostic Logging</a>
-<ul/>
</li>
<li>
<a href="#How To Use Diagnostic logging">How To Use Diagnostic logging</a>
@@ -86,15 +86,12 @@
<ul>
<li>
<a href="#Apache Tomcat">Apache Tomcat</a>
-<ul/>
</li>
<li>
<a href="#JBoss Application Server">JBoss Application Server</a>
-<ul/>
</li>
<li>
<a href="#Other Containers">Other Containers</a>
-<ul/>
</li>
</ul>
</li>
@@ -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 <code>toString</code> implementations.
These are of the form:
</p>
-<code><pre>
+<code>
<em>classname</em>@<em>system identity hash code</em>
-</pre></code>
+</code>
<p>
The <em>system identity hash code</em> is found by calling
<code>System.identityHashCode()</code>
which should uniquely identify a particular instance. The classname is usually
the fully qualified
class name though in a few cases,
<code>org.apache.commons.logging.impl.LogFactoryImpl</code> may be
shortened to <code>LogFactoryImpl</code> to increase ease of reading. For
example:
</p>
-<code><pre>
+<code>
sun.misc.Launcher$AppClassLoader@20120943
LogFactoryImpl@1671711
-</pre></code>
+</code>
<p>
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:
</p>
-<code><pre>
+<code>
[<em>class-identifier</em> from <em>ClassLoader OID</em>]
-</pre></code>
+</code>
<p>
<em>ClassLoader OID</em> is the <a href='#OIDs'>OID</a> of a classloader which
loaded
the class issuing the message.
@@ -170,19 +167,19 @@ the class issuing the message.
In the case of
<code>LogFactory</code>, this is just <code>LogFactory</code>. For example
(line split):
</p>
-<code><pre>
+<code>
[LogFactory
from sun.misc.Launcher$AppClassLoader@20120943] BOOTSTRAP COMPLETED
-</pre></code>
+</code>
<p>
In the case of
<code>LogFactoryImpl</code>, 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):
</p>
-<code><pre>
+<code>
[LogFactoryImpl@1671711
from sun.misc.Launcher$AppClassLoader@20120943] Instance created.
-</pre></code>
+</code>
</subsection>
<subsection name='ClassLoader Hierarchy Tree'>
<p>
@@ -193,12 +190,12 @@ Each classloader is represented (visually) by an OID (to
allow cross referencing
and the relationship indicated in <code><em>child</em> -->
<em>parent</em></code> fashion.
For example (line split for easy reading):
</p>
-<code><pre>
+<code>
ClassLoader tree:java.net.URLClassLoader@3526198
--> sun.misc.Launcher$AppClassLoader@20120943 (SYSTEM)
--> sun.misc.Launcher$ExtClassLoader@11126876
--> BOOT
-</pre></code>
+</code>
<p>
Represents a hierarchy with four elements ending in the boot classloader.
</p>
@@ -216,15 +213,15 @@ are logged.
<p>
Many Sun classloaders have confusing <code>toString</code> values. For
example, the OID may be
</p>
-<code><pre>
+<code>
sun.misc.Launcher$AppClassLoader@20120943
-</pre></code>
+</code>
<p>
with a <code>toString</code> value of
</p>
-<code><pre>
+<code>
sun.misc.Launcher$AppClassLoader@133056f
-</pre></code>
+</code>
<p>
Other classloader implementations may give very useful information (such as
the local classpath).
</p>
@@ -252,7 +249,7 @@ allowing the <a href='#OIDs'>OID</a> later to be
cross-referenced to the <code>t
and the <a href='#ClassLoader%20Hierarchy%20Tree'>classloader tree</a>. For
example, the
following log snippet details the TCCL (lines split):
</p>
-<code><pre>
+<code>
[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
-</pre></code>
+</code>
</subsection>
<subsection name='Log Discovery Diagnostics'>
<p>
@@ -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.
</p>
<subsection name='The Incompatible LogFactory Issue'>
- <subsection name='Symptoms'>
+ <h4 id='Symptoms'>Symptoms</h4>
<p>
An exception is thrown by JCL with a message similar to:
</p>
- <code><pre>
+ <code>
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.
- </pre></code>
+ </code>
<p>
This is a WebSphere example so the name of the custom LogFactory is
<code>com.ibm.ws.commons.logging.TrLogFactory</code>. For other containers,
this class name will
differ.
</p>
- </subsection>
- <subsection name='Explanation'>
+ <h4 id='Explanation'>Explanation</h4>
<p>
A custom <code>LogFactory</code> implementation can only be used if the
implementation class loaded
dynamically at runtime can be cast to the <code>LogFactory</code> 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.
</p>
- </subsection>
- <subsection name='Fixes'>
+ <h4 id='Fixes'>Fixes</h4>
<p>
There are various ways to fix this problem. Which fix is right depends on the
circumstances.
</p>
@@ -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:
</p>
- <code><pre>
+ <code>
-Dorg.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl
- </pre></code>
+ </code>
<p>
If you want to continue to use the default container mechanism then:
</p>
@@ -392,7 +387,6 @@ implementation.
If you encounter difficulties when applying the fixes recommended, please
turn on
<a href='#Using JCL Diagnostics'>diagnostics</a> and consult the logs.
</p>
- </subsection>
</subsection>
</section>
<section name='Containers With Custom ClassLoading Behaviour for Logging'>
