Siphalor/tweed5-commons-logging
1
0
Fork 0
Code Activity

Port from Doxia 1 to 2

Browse Source
This commit is contained in:
Gary D. Gregory
2025-01-23 16:38:24 -05:00
parent 664e27d753
commit ff0fee9d0c
7 changed files with 64 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/site/xdoc/building.xml
View File

@@ -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="dev@commons.apache.org">Commons Documentation Team</author>

49
src/site/xdoc/guide.xml
View File

@@ -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="dev@commons.apache.org">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>

5
src/site/xdoc/index.xml
View File

@@ -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="dev@commons.apache.org">Commons Documentation Team</author>

5
src/site/xdoc/junit-report.xml
View File

@@ -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="dev@commons.apache.org">Commons Documentation Team</author>

8
src/site/xdoc/proposal.xml
View File

@@ -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">

5
src/site/xdoc/tech.xml
View File

@@ -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="dev@commons.apache.org">Commons Documentation Team</author>

62
src/site/xdoc/troubleshooting.xml
View File

@@ -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="dev@commons.apache.org">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'>