Port from Doxia 1 to 2
This commit is contained in:
@@ -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
|
See the License for the specific language governing permissions and
|
||||||
limitations under the License.
|
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>
|
<properties>
|
||||||
<title>Building</title>
|
<title>Building</title>
|
||||||
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
||||||
|
|||||||
@@ -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>
|
<properties>
|
||||||
<title>User Guide</title>
|
<title>User Guide</title>
|
||||||
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
||||||
@@ -28,7 +29,6 @@
|
|||||||
|
|
||||||
<body>
|
<body>
|
||||||
<section name='Contents'>
|
<section name='Contents'>
|
||||||
<p>
|
|
||||||
<ol>
|
<ol>
|
||||||
<li><a href='#Introduction'>Introduction</a></li>
|
<li><a href='#Introduction'>Introduction</a></li>
|
||||||
<li><a href='#Quick Start'>Quick Start</a>
|
<li><a href='#Quick Start'>Quick Start</a>
|
||||||
@@ -85,7 +85,6 @@
|
|||||||
<li><a href='#Frequently Asked Questions'>Frequently Asked Questions</a>
|
<li><a href='#Frequently Asked Questions'>Frequently Asked Questions</a>
|
||||||
</li>
|
</li>
|
||||||
</ol>
|
</ol>
|
||||||
</p>
|
|
||||||
</section>
|
</section>
|
||||||
<section name="Introduction">
|
<section name="Introduction">
|
||||||
<p>
|
<p>
|
||||||
@@ -228,18 +227,16 @@ is responsible for handling such issues.
|
|||||||
</section>
|
</section>
|
||||||
<section name='Developing With JCL'>
|
<section name='Developing With JCL'>
|
||||||
<subsection name="Obtaining a Log Object">
|
<subsection name="Obtaining a Log Object">
|
||||||
<p>
|
<p>
|
||||||
To use the JCL SPI from a Java class,
|
To use the JCL SPI from a Java class,
|
||||||
include the following import statements:
|
include the following import statements:
|
||||||
</p>
|
</p>
|
||||||
<ul>
|
<code>
|
||||||
<code>
|
|
||||||
import org.apache.commons.logging.Log;
|
import org.apache.commons.logging.Log;
|
||||||
<br/>
|
<br/>
|
||||||
import org.apache.commons.logging.LogFactory;
|
import org.apache.commons.logging.LogFactory;
|
||||||
<br/>
|
<br/>
|
||||||
</code>
|
</code>
|
||||||
</ul>
|
|
||||||
<p>
|
<p>
|
||||||
Note that some components using JCL may
|
Note that some components using JCL may
|
||||||
either extend Log,
|
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
|
For each class definition, declare and initialize a
|
||||||
<code>log</code> attribute as follows:
|
<code>log</code> attribute as follows:
|
||||||
</p>
|
</p>
|
||||||
<ul>
|
|
||||||
<source>
|
<source>
|
||||||
public class CLASS
|
public class CLASS
|
||||||
{
|
{
|
||||||
@@ -259,7 +255,6 @@ public class CLASS
|
|||||||
...
|
...
|
||||||
;
|
;
|
||||||
</source>
|
</source>
|
||||||
</ul>
|
|
||||||
<p>
|
<p>
|
||||||
Note that for application code, declaring the log member as "static" is more
|
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.
|
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
|
following methods for use
|
||||||
in writing log/trace messages to the log:
|
in writing log/trace messages to the log:
|
||||||
</p>
|
</p>
|
||||||
<ul>
|
|
||||||
<source>
|
<source>
|
||||||
log.fatal(Object message);
|
log.fatal(Object message);
|
||||||
log.fatal(Object message, Throwable t);
|
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);
|
||||||
log.trace(Object message, Throwable t);
|
log.trace(Object message, Throwable t);
|
||||||
</source>
|
</source>
|
||||||
</ul>
|
|
||||||
<p>
|
<p>
|
||||||
Semantics for these methods are such that it is expected
|
Semantics for these methods are such that it is expected
|
||||||
that the severity, from highest to lowest, of messages is ordered as above.
|
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>
|
<p>
|
||||||
In addition to the logging methods, the following are provided for code guards:
|
In addition to the logging methods, the following are provided for code guards:
|
||||||
</p>
|
</p>
|
||||||
<ul>
|
|
||||||
<source>
|
<source>
|
||||||
log.isFatalEnabled();
|
log.isFatalEnabled();
|
||||||
log.isErrorEnabled();
|
log.isErrorEnabled();
|
||||||
@@ -310,7 +302,6 @@ In addition to the logging methods, the following are provided for code guards:
|
|||||||
log.isDebugEnabled();
|
log.isDebugEnabled();
|
||||||
log.isTraceEnabled();
|
log.isTraceEnabled();
|
||||||
</source>
|
</source>
|
||||||
</ul>
|
|
||||||
</subsection>
|
</subsection>
|
||||||
<subsection name="Serialization Issues">
|
<subsection name="Serialization Issues">
|
||||||
<p>Prior to release 1.0.4, none of the standard Log implementations were
|
<p>Prior to release 1.0.4, none of the standard Log implementations were
|
||||||
@@ -434,13 +425,13 @@ The following guidelines are suggested:
|
|||||||
<li>
|
<li>
|
||||||
<b>fatal</b> - Severe errors that cause premature termination.
|
<b>fatal</b> - Severe errors that cause premature termination.
|
||||||
Expect these to be immediately visible on a status console.
|
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>.
|
Internationalization</a>.
|
||||||
</li>
|
</li>
|
||||||
<li>
|
<li>
|
||||||
<b>error</b> - Other runtime errors or unexpected conditions.
|
<b>error</b> - Other runtime errors or unexpected conditions.
|
||||||
Expect these to be immediately visible on a status console.
|
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>.
|
Internationalization</a>.
|
||||||
</li>
|
</li>
|
||||||
<li>
|
<li>
|
||||||
@@ -448,14 +439,14 @@ Internationalization</a>.
|
|||||||
other runtime situations that are undesirable or unexpected, but not
|
other runtime situations that are undesirable or unexpected, but not
|
||||||
necessarily "wrong".
|
necessarily "wrong".
|
||||||
Expect these to be immediately visible on a status console.
|
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>.
|
Internationalization</a>.
|
||||||
</li>
|
</li>
|
||||||
<li>
|
<li>
|
||||||
<b>info</b> - Interesting runtime events (startup/shutdown).
|
<b>info</b> - Interesting runtime events (startup/shutdown).
|
||||||
Expect these to be immediately visible on a console,
|
Expect these to be immediately visible on a console,
|
||||||
so be conservative and keep to a minimum.
|
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>.
|
Internationalization</a>.
|
||||||
</li>
|
</li>
|
||||||
<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
|
'enterprise' exceptions, then consider creating a special
|
||||||
logger just for these exceptions:
|
logger just for these exceptions:
|
||||||
</p>
|
</p>
|
||||||
<ul>
|
|
||||||
<source>
|
<source>
|
||||||
Log log = LogFactory.getLog("org.apache.<i>component</i>.enterprise");
|
Log log = LogFactory.getLog("org.apache.<i>component</i>.enterprise");
|
||||||
</source>
|
</source>
|
||||||
</ul>
|
|
||||||
<p>
|
<p>
|
||||||
This allows the 'enterprise' level information to be turned on/off explicitly
|
This allows the 'enterprise' level information to be turned on/off explicitly
|
||||||
by most logger implementations.
|
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>,
|
When creating new implementations for <code>Log</code> and <code>LogFactory</code>,
|
||||||
it is important to understand the implied contract between the factory
|
it is important to understand the implied contract between the factory
|
||||||
and the log implementations:
|
and the log implementations:
|
||||||
<ul>
|
</p>
|
||||||
<li><b>Life cycle</b>
|
<ul>
|
||||||
<blockquote>
|
<li><b>Life cycle</b>
|
||||||
|
<blockquote>
|
||||||
The JCL LogFactory implementation must assume responsibility for
|
The JCL LogFactory implementation must assume responsibility for
|
||||||
either connecting/disconnecting to a logging toolkit,
|
either connecting/disconnecting to a logging toolkit,
|
||||||
or instantiating/initializing/destroying a logging toolkit.
|
or instantiating/initializing/destroying a logging toolkit.
|
||||||
</blockquote>
|
</blockquote>
|
||||||
</li>
|
</li>
|
||||||
<li><b>Exception handling</b>
|
<li><b>Exception handling</b>
|
||||||
<blockquote>
|
<blockquote>
|
||||||
The JCL Log interface doesn't specify any exceptions to be handled,
|
The JCL Log interface doesn't specify any exceptions to be handled,
|
||||||
the implementation must catch any exceptions.
|
the implementation must catch any exceptions.
|
||||||
</blockquote>
|
</blockquote>
|
||||||
</li>
|
</li>
|
||||||
<li><b>Multiple threads</b>
|
<li><b>Multiple threads</b>
|
||||||
<blockquote>
|
<blockquote>
|
||||||
The JCL Log and LogFactory implementations must ensure
|
The JCL Log and LogFactory implementations must ensure
|
||||||
that any synchronization required by the logging toolkit
|
that any synchronization required by the logging toolkit
|
||||||
is met.
|
is met.
|
||||||
</blockquote>
|
</blockquote>
|
||||||
</li>
|
</li>
|
||||||
</ul>
|
</ul>
|
||||||
</p>
|
|
||||||
</subsection>
|
</subsection>
|
||||||
<subsection name='Creating a Log Implementation'>
|
<subsection name='Creating a Log Implementation'>
|
||||||
<p>
|
<p>
|
||||||
|
|||||||
@@ -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>
|
<properties>
|
||||||
<title>Overview</title>
|
<title>Overview</title>
|
||||||
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
||||||
|
|||||||
@@ -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
|
See the License for the specific language governing permissions and
|
||||||
limitations under the License.
|
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>
|
<properties>
|
||||||
<title>JUnit Test Results</title>
|
<title>JUnit Test Results</title>
|
||||||
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
||||||
|
|||||||
@@ -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>
|
<properties>
|
||||||
<title>Proposal for Logging Library Package</title>
|
<title>Proposal for Logging Library Package</title>
|
||||||
</properties>
|
</properties>
|
||||||
@@ -51,21 +53,21 @@ implementations.
|
|||||||
|
|
||||||
<p>
|
<p>
|
||||||
The package should :
|
The package should :
|
||||||
|
</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>Have an API which should be as simple to use as possible</li>
|
<li>Have an API which should be as simple to use as possible</li>
|
||||||
<li>Provide support for Log4j</li>
|
<li>Provide support for Log4j</li>
|
||||||
<li>Provide pluggable support for other logging APIs</li>
|
<li>Provide pluggable support for other logging APIs</li>
|
||||||
</ul>
|
</ul>
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Non-goals:
|
Non-goals:
|
||||||
|
</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>This package will not perform logging itself, except at the most basic
|
<li>This package will not perform logging itself, except at the most basic
|
||||||
level.</li>
|
level.</li>
|
||||||
<li>We do not seek to become a "standard" API.</li>
|
<li>We do not seek to become a "standard" API.</li>
|
||||||
</ul>
|
</ul>
|
||||||
</p>
|
|
||||||
|
|
||||||
</subsection>
|
</subsection>
|
||||||
<subsection name="(1.5) Interaction With Other Packages">
|
<subsection name="(1.5) Interaction With Other Packages">
|
||||||
|
|||||||
@@ -17,8 +17,9 @@ See the License for the specific language governing permissions and
|
|||||||
limitations under the License.
|
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>
|
<properties>
|
||||||
<title>Technology Guide</title>
|
<title>Technology Guide</title>
|
||||||
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
||||||
|
|||||||
@@ -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>
|
<properties>
|
||||||
<title>Troubleshooting Guide</title>
|
<title>Troubleshooting Guide</title>
|
||||||
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
<author email="dev@commons.apache.org">Commons Documentation Team</author>
|
||||||
@@ -37,7 +38,6 @@
|
|||||||
<ul>
|
<ul>
|
||||||
<li>
|
<li>
|
||||||
<a href="#When To Use Diagnostic Logging">When To Use Diagnostic Logging</a>
|
<a href="#When To Use Diagnostic Logging">When To Use Diagnostic Logging</a>
|
||||||
<ul/>
|
|
||||||
</li>
|
</li>
|
||||||
<li>
|
<li>
|
||||||
<a href="#How To Use Diagnostic logging">How To Use Diagnostic logging</a>
|
<a href="#How To Use Diagnostic logging">How To Use Diagnostic logging</a>
|
||||||
@@ -86,15 +86,12 @@
|
|||||||
<ul>
|
<ul>
|
||||||
<li>
|
<li>
|
||||||
<a href="#Apache Tomcat">Apache Tomcat</a>
|
<a href="#Apache Tomcat">Apache Tomcat</a>
|
||||||
<ul/>
|
|
||||||
</li>
|
</li>
|
||||||
<li>
|
<li>
|
||||||
<a href="#JBoss Application Server">JBoss Application Server</a>
|
<a href="#JBoss Application Server">JBoss Application Server</a>
|
||||||
<ul/>
|
|
||||||
</li>
|
</li>
|
||||||
<li>
|
<li>
|
||||||
<a href="#Other Containers">Other Containers</a>
|
<a href="#Other Containers">Other Containers</a>
|
||||||
<ul/>
|
|
||||||
</li>
|
</li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</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.
|
to be tracked without relying on useful <code>toString</code> implementations.
|
||||||
These are of the form:
|
These are of the form:
|
||||||
</p>
|
</p>
|
||||||
<code><pre>
|
<code>
|
||||||
<em>classname</em>@<em>system identity hash code</em>
|
<em>classname</em>@<em>system identity hash code</em>
|
||||||
</pre></code>
|
</code>
|
||||||
<p>
|
<p>
|
||||||
The <em>system identity hash code</em> is found by calling <code>System.identityHashCode()</code>
|
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
|
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
|
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:
|
shortened to <code>LogFactoryImpl</code> to increase ease of reading. For example:
|
||||||
</p>
|
</p>
|
||||||
<code><pre>
|
<code>
|
||||||
sun.misc.Launcher$AppClassLoader@20120943
|
sun.misc.Launcher$AppClassLoader@20120943
|
||||||
LogFactoryImpl@1671711
|
LogFactoryImpl@1671711
|
||||||
</pre></code>
|
</code>
|
||||||
<p>
|
<p>
|
||||||
OIDs are intended to be used to cross-reference. They allow particular instances of classloaders
|
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
|
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.
|
Each diagnostic message is prefixed with details of the relevant class in a standard format.
|
||||||
This takes the form:
|
This takes the form:
|
||||||
</p>
|
</p>
|
||||||
<code><pre>
|
<code>
|
||||||
[<em>class-identifier</em> from <em>ClassLoader OID</em>]
|
[<em>class-identifier</em> from <em>ClassLoader OID</em>]
|
||||||
</pre></code>
|
</code>
|
||||||
<p>
|
<p>
|
||||||
<em>ClassLoader OID</em> is the <a href='#OIDs'>OID</a> of a classloader which loaded
|
<em>ClassLoader OID</em> is the <a href='#OIDs'>OID</a> of a classloader which loaded
|
||||||
the class issuing the message.
|
the class issuing the message.
|
||||||
@@ -170,19 +167,19 @@ the class issuing the message.
|
|||||||
In the case of
|
In the case of
|
||||||
<code>LogFactory</code>, this is just <code>LogFactory</code>. For example (line split):
|
<code>LogFactory</code>, this is just <code>LogFactory</code>. For example (line split):
|
||||||
</p>
|
</p>
|
||||||
<code><pre>
|
<code>
|
||||||
[LogFactory
|
[LogFactory
|
||||||
from sun.misc.Launcher$AppClassLoader@20120943] BOOTSTRAP COMPLETED
|
from sun.misc.Launcher$AppClassLoader@20120943] BOOTSTRAP COMPLETED
|
||||||
</pre></code>
|
</code>
|
||||||
<p>
|
<p>
|
||||||
In the case of
|
In the case of
|
||||||
<code>LogFactoryImpl</code>, the prefix is the instance OID. This can be cross referenced
|
<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):
|
to discover the details of the TCCL used to manage this instance. For example (line split):
|
||||||
</p>
|
</p>
|
||||||
<code><pre>
|
<code>
|
||||||
[LogFactoryImpl@1671711
|
[LogFactoryImpl@1671711
|
||||||
from sun.misc.Launcher$AppClassLoader@20120943] Instance created.
|
from sun.misc.Launcher$AppClassLoader@20120943] Instance created.
|
||||||
</pre></code>
|
</code>
|
||||||
</subsection>
|
</subsection>
|
||||||
<subsection name='ClassLoader Hierarchy Tree'>
|
<subsection name='ClassLoader Hierarchy Tree'>
|
||||||
<p>
|
<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.
|
and the relationship indicated in <code><em>child</em> --> <em>parent</em></code> fashion.
|
||||||
For example (line split for easy reading):
|
For example (line split for easy reading):
|
||||||
</p>
|
</p>
|
||||||
<code><pre>
|
<code>
|
||||||
ClassLoader tree:java.net.URLClassLoader@3526198
|
ClassLoader tree:java.net.URLClassLoader@3526198
|
||||||
--> sun.misc.Launcher$AppClassLoader@20120943 (SYSTEM)
|
--> sun.misc.Launcher$AppClassLoader@20120943 (SYSTEM)
|
||||||
--> sun.misc.Launcher$ExtClassLoader@11126876
|
--> sun.misc.Launcher$ExtClassLoader@11126876
|
||||||
--> BOOT
|
--> BOOT
|
||||||
</pre></code>
|
</code>
|
||||||
<p>
|
<p>
|
||||||
Represents a hierarchy with four elements ending in the boot classloader.
|
Represents a hierarchy with four elements ending in the boot classloader.
|
||||||
</p>
|
</p>
|
||||||
@@ -216,15 +213,15 @@ are logged.
|
|||||||
<p>
|
<p>
|
||||||
Many Sun classloaders have confusing <code>toString</code> values. For example, the OID may be
|
Many Sun classloaders have confusing <code>toString</code> values. For example, the OID may be
|
||||||
</p>
|
</p>
|
||||||
<code><pre>
|
<code>
|
||||||
sun.misc.Launcher$AppClassLoader@20120943
|
sun.misc.Launcher$AppClassLoader@20120943
|
||||||
</pre></code>
|
</code>
|
||||||
<p>
|
<p>
|
||||||
with a <code>toString</code> value of
|
with a <code>toString</code> value of
|
||||||
</p>
|
</p>
|
||||||
<code><pre>
|
<code>
|
||||||
sun.misc.Launcher$AppClassLoader@133056f
|
sun.misc.Launcher$AppClassLoader@133056f
|
||||||
</pre></code>
|
</code>
|
||||||
<p>
|
<p>
|
||||||
Other classloader implementations may give very useful information (such as the local classpath).
|
Other classloader implementations may give very useful information (such as the local classpath).
|
||||||
</p>
|
</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
|
and the <a href='#ClassLoader%20Hierarchy%20Tree'>classloader tree</a>. For example, the
|
||||||
following log snippet details the TCCL (lines split):
|
following log snippet details the TCCL (lines split):
|
||||||
</p>
|
</p>
|
||||||
<code><pre>
|
<code>
|
||||||
[LogFactory from sun.misc.Launcher$AppClassLoader@20120943]
|
[LogFactory from sun.misc.Launcher$AppClassLoader@20120943]
|
||||||
[LOOKUP] LogFactory implementation requested for the first time for context
|
[LOOKUP] LogFactory implementation requested for the first time for context
|
||||||
classloader java.net.URLClassLoader@3526198
|
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$AppClassLoader@20120943 (SYSTEM)
|
||||||
--> sun.misc.Launcher$ExtClassLoader@11126876
|
--> sun.misc.Launcher$ExtClassLoader@11126876
|
||||||
--> BOOT
|
--> BOOT
|
||||||
</pre></code>
|
</code>
|
||||||
</subsection>
|
</subsection>
|
||||||
<subsection name='Log Discovery Diagnostics'>
|
<subsection name='Log Discovery Diagnostics'>
|
||||||
<p>
|
<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.
|
of other containers using a custom implementation.
|
||||||
</p>
|
</p>
|
||||||
<subsection name='The Incompatible LogFactory Issue'>
|
<subsection name='The Incompatible LogFactory Issue'>
|
||||||
<subsection name='Symptoms'>
|
<h4 id='Symptoms'>Symptoms</h4>
|
||||||
<p>
|
<p>
|
||||||
An exception is thrown by JCL with a message similar to:
|
An exception is thrown by JCL with a message similar to:
|
||||||
</p>
|
</p>
|
||||||
<code><pre>
|
<code>
|
||||||
The chosen LogFactory implementation does not extend LogFactory. Please check your configuration.
|
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
|
(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
|
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.
|
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
|
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.
|
LogFactory from the command line. Help can be found @https//commons.apache.org/logging.
|
||||||
</pre></code>
|
</code>
|
||||||
<p>
|
<p>
|
||||||
This is a WebSphere example so the name of the custom LogFactory is
|
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
|
<code>com.ibm.ws.commons.logging.TrLogFactory</code>. For other containers, this class name will
|
||||||
differ.
|
differ.
|
||||||
</p>
|
</p>
|
||||||
</subsection>
|
<h4 id='Explanation'>Explanation</h4>
|
||||||
<subsection name='Explanation'>
|
|
||||||
<p>
|
<p>
|
||||||
A custom <code>LogFactory</code> implementation can only be used if the implementation class loaded
|
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
|
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
|
under certain classloading policies without the user knowingly specifying a custom
|
||||||
implementation.
|
implementation.
|
||||||
</p>
|
</p>
|
||||||
</subsection>
|
<h4 id='Fixes'>Fixes</h4>
|
||||||
<subsection name='Fixes'>
|
|
||||||
<p>
|
<p>
|
||||||
There are various ways to fix this problem. Which fix is right depends on the circumstances.
|
There are various ways to fix this problem. Which fix is right depends on the circumstances.
|
||||||
</p>
|
</p>
|
||||||
@@ -371,9 +366,9 @@ implementation.
|
|||||||
If you want to bypass the container adaption mechanism then set the appropriate system property
|
If you want to bypass the container adaption mechanism then set the appropriate system property
|
||||||
to the default value when the container is started:
|
to the default value when the container is started:
|
||||||
</p>
|
</p>
|
||||||
<code><pre>
|
<code>
|
||||||
-Dorg.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl
|
-Dorg.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl
|
||||||
</pre></code>
|
</code>
|
||||||
<p>
|
<p>
|
||||||
If you want to continue to use the default container mechanism then:
|
If you want to continue to use the default container mechanism then:
|
||||||
</p>
|
</p>
|
||||||
@@ -392,7 +387,6 @@ implementation.
|
|||||||
If you encounter difficulties when applying the fixes recommended, please turn on
|
If you encounter difficulties when applying the fixes recommended, please turn on
|
||||||
<a href='#Using JCL Diagnostics'>diagnostics</a> and consult the logs.
|
<a href='#Using JCL Diagnostics'>diagnostics</a> and consult the logs.
|
||||||
</p>
|
</p>
|
||||||
</subsection>
|
|
||||||
</subsection>
|
</subsection>
|
||||||
</section>
|
</section>
|
||||||
<section name='Containers With Custom ClassLoading Behaviour for Logging'>
|
<section name='Containers With Custom ClassLoading Behaviour for Logging'>
|
||||||
|
|||||||
Reference in New Issue
Block a user