You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by rd...@apache.org on 2006/03/09 21:21:28 UTC
svn commit: r384600 -
/jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml
Author: rdonkin
Date: Thu Mar 9 12:21:28 2006
New Revision: 384600
URL: http://svn.apache.org/viewcvs?rev=384600&view=rev
Log:
First draft on troubleshooting WAS (and other containers that use custom LogFactory implementations).
Modified:
jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml
Modified: jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml?rev=384600&r1=384599&r2=384600&view=diff
==============================================================================
--- jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml (original)
+++ jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml Thu Mar 9 12:21:28 2006
@@ -207,5 +207,109 @@
</p>
</subsection>
</section>
+ <section name='Containers With Custom LogFactory Implementations'>
+ <p>
+ Some containers use a custom <code>LogFactory</code> implementation to adapt JCL to their particular
+ logging system. This has some important consequences for deploying applications using JCL within these
+ containers.
+ </p>
+ <p>
+ Containers known to use this mechanism:
+ </p>
+ <ul>
+ <li><a href='http://www.ibm.com/software/websphere/'>WebSphere Application Server</a> from
+ <a href='http://www.ibm.com/software/websphere/'>IBM</a> versions 5 and 6.</li>
+ </ul>
+ <p>
+ Containers suspected to use this mechanism:
+ </p>
+ <ul>
+ <li><a href='http://www.macromedia.com/software/jrun/'>JRun</a> from
+ <a href='http://www.macromedia.com/'>Adobe Macromedia</a>.</li>
+ </ul>
+ <subsection name='The Incompatible LogFactory Issue'>
+ <subsection name='Symptoms'>
+ <p>
+ An exception is thrown by JCL with a message similar to:
+ </p>
+ <code><pre>
+ 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
+ to 'org.apache.commons.logging.LogFactory'. The conflict is caused by the presence of multiple
+ LogFactory classes in incompatible classloaders. Background can be found in
+ http://jakarta.apache.org/commons/logging/tech.html. If you have not explicitly specified a custom
+ 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 @http://jakarta.apache.org/commons/logging.
+ </pre></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'>
+ <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
+ several ways in which this cast can fail. The most obvious is that the source code may not actually
+ extend <code>LogFactory</code>. The source may be compatible but if the <code>LogFactory</code> class
+ against which the source is compiled is not binary compatible then the cast will also fail.
+ </p>
+ <p>
+ There is also another more unusual way in which this cast can fail: even when the binary is compatible,
+ the implementation class loaded at runtime may be linked to a different instance of the
+ <code>LogFactory</code> class. For more information, see the <a href='tech.html'>tech guide</a>.
+ </p>
+ <p>
+ This situation may be encountered in containers which use a custom <code>LogFactory</code> implementation.
+ The implementation will typically be provided in a shared, high level classloader together with JCL.
+ When an application classloader contains <code>LogFactory</code>, the implementation will be loaded
+ from that higher level classloader. The implementation class will be linked to the <code>LogFactory</code>
+ class loaded by the higher level classloader. Even if the
+ <code>LogFactory</code> implementations are binary compatible, since they are loaded by different classloaders
+ the two <code>LogFactory</code> Class instances are not equal and so the cast must fail.
+ </p>
+ <p>
+The policy adopted by JCL in this situation is to re-throw this exception. Addition information
+is included in the message to help diagnosis. The reasoning behind this choice is that a
+particular <code>LogFactory</code> implementation has been actively specified and this
+choice should not be ignored. This policy has unfortunate consequences when running in
+containers which have custom implementations: the above runtime exception will be thrown.
+ </p>
+ </subsection>
+ <subsection name='Fixes'>
+ <p>
+ There are various ways to fix this problem. Which fix is right depends on the circumstances.
+ </p>
+ <p>
+ If you want to bypass the container adaption mechanism then set the appropriate system property
+ to it's default value when the container is started:
+ </p>
+ <code><pre>
+ -Dorg.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl
+ </pre></code>
+ <p>
+ If you want to continue to use the default container mechanism then:
+ </p>
+ <ul>
+ <li>
+ Find and replace the commons-logging implementation used by the container with
+ the most modern release
+ </li>
+ <li>
+ Replace the commons-logging jar in the application with the commons-logging-adapter jar.
+ This will ensure that application classloader will delegate to it's parent when loading
+ <code>LogFactory</code>.
+ </li>
+ </ul>
+ <p>
+ If you encounter difficulties when applying the fixes recommended, please turn on
+ <a href='#Using%20JCL%20Diagnostics'>diagnostics</a> and consult the logs.
+ </p>
+ </subsection>
+ </subsection>
+ </section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: svn commit: r384600 -
/jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml
Posted by robert burrell donkin <ro...@blueyonder.co.uk>.
i've committed a first draft so that people can take an early look and
offer improvements.
- robert
On Thu, 2006-03-09 at 20:21 +0000, rdonkin@apache.org wrote:
> Author: rdonkin
> Date: Thu Mar 9 12:21:28 2006
> New Revision: 384600
>
> URL: http://svn.apache.org/viewcvs?rev=384600&view=rev
> Log:
> First draft on troubleshooting WAS (and other containers that use custom LogFactory implementations).
>
> Modified:
> jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml
>
> Modified: jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml
> URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml?rev=384600&r1=384599&r2=384600&view=diff
> ==============================================================================
> --- jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml (original)
> +++ jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml Thu Mar 9 12:21:28 2006
> @@ -207,5 +207,109 @@
> </p>
> </subsection>
> </section>
> + <section name='Containers With Custom LogFactory Implementations'>
> + <p>
> + Some containers use a custom <code>LogFactory</code> implementation to adapt JCL to their particular
> + logging system. This has some important consequences for deploying applications using JCL within these
> + containers.
> + </p>
> + <p>
> + Containers known to use this mechanism:
> + </p>
> + <ul>
> + <li><a href='http://www.ibm.com/software/websphere/'>WebSphere Application Server</a> from
> + <a href='http://www.ibm.com/software/websphere/'>IBM</a> versions 5 and 6.</li>
> + </ul>
> + <p>
> + Containers suspected to use this mechanism:
> + </p>
> + <ul>
> + <li><a href='http://www.macromedia.com/software/jrun/'>JRun</a> from
> + <a href='http://www.macromedia.com/'>Adobe Macromedia</a>.</li>
> + </ul>
> + <subsection name='The Incompatible LogFactory Issue'>
> + <subsection name='Symptoms'>
> + <p>
> + An exception is thrown by JCL with a message similar to:
> + </p>
> + <code><pre>
> + 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
> + to 'org.apache.commons.logging.LogFactory'. The conflict is caused by the presence of multiple
> + LogFactory classes in incompatible classloaders. Background can be found in
> + http://jakarta.apache.org/commons/logging/tech.html. If you have not explicitly specified a custom
> + 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 @http://jakarta.apache.org/commons/logging.
> + </pre></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'>
> + <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
> + several ways in which this cast can fail. The most obvious is that the source code may not actually
> + extend <code>LogFactory</code>. The source may be compatible but if the <code>LogFactory</code> class
> + against which the source is compiled is not binary compatible then the cast will also fail.
> + </p>
> + <p>
> + There is also another more unusual way in which this cast can fail: even when the binary is compatible,
> + the implementation class loaded at runtime may be linked to a different instance of the
> + <code>LogFactory</code> class. For more information, see the <a href='tech.html'>tech guide</a>.
> + </p>
> + <p>
> + This situation may be encountered in containers which use a custom <code>LogFactory</code> implementation.
> + The implementation will typically be provided in a shared, high level classloader together with JCL.
> + When an application classloader contains <code>LogFactory</code>, the implementation will be loaded
> + from that higher level classloader. The implementation class will be linked to the <code>LogFactory</code>
> + class loaded by the higher level classloader. Even if the
> + <code>LogFactory</code> implementations are binary compatible, since they are loaded by different classloaders
> + the two <code>LogFactory</code> Class instances are not equal and so the cast must fail.
> + </p>
> + <p>
> +The policy adopted by JCL in this situation is to re-throw this exception. Addition information
> +is included in the message to help diagnosis. The reasoning behind this choice is that a
> +particular <code>LogFactory</code> implementation has been actively specified and this
> +choice should not be ignored. This policy has unfortunate consequences when running in
> +containers which have custom implementations: the above runtime exception will be thrown.
> + </p>
> + </subsection>
> + <subsection name='Fixes'>
> + <p>
> + There are various ways to fix this problem. Which fix is right depends on the circumstances.
> + </p>
> + <p>
> + If you want to bypass the container adaption mechanism then set the appropriate system property
> + to it's default value when the container is started:
> + </p>
> + <code><pre>
> + -Dorg.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl
> + </pre></code>
> + <p>
> + If you want to continue to use the default container mechanism then:
> + </p>
> + <ul>
> + <li>
> + Find and replace the commons-logging implementation used by the container with
> + the most modern release
> + </li>
> + <li>
> + Replace the commons-logging jar in the application with the commons-logging-adapter jar.
> + This will ensure that application classloader will delegate to it's parent when loading
> + <code>LogFactory</code>.
> + </li>
> + </ul>
> + <p>
> + If you encounter difficulties when applying the fixes recommended, please turn on
> + <a href='#Using%20JCL%20Diagnostics'>diagnostics</a> and consult the logs.
> + </p>
> + </subsection>
> + </subsection>
> + </section>
> </body>
> </document>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: svn commit: r384600 -
/jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml
Posted by robert burrell donkin <ro...@blueyonder.co.uk>.
On Fri, 2006-03-10 at 09:31 +1300, Simon Kitching wrote:
> On Thu, 2006-03-09 at 20:21 +0000, rdonkin@apache.org wrote:
> > First draft on troubleshooting WAS (and other containers that use custom LogFactory implementations).
>
> Looks good!
>
>
> One note though:
> > + This will ensure that application classloader will delegate to it's parent when loading
>
> The possessive third person is "its", not "it's".
> his
> her
> its
yep. well spotted 8-)
i use <code>SomeClass</code>'s as the possessive third person
intentionally since the grammatically correct form
<code>SomeClasses</code> or <code>SomeClasses</code>es is much harder to
read in html documents.
> Sorry to be a pedant!
that's what we pay you for ;)
- robert
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: svn commit: r384600 -
/jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml
Posted by Simon Kitching <sk...@apache.org>.
On Thu, 2006-03-09 at 20:21 +0000, rdonkin@apache.org wrote:
> First draft on troubleshooting WAS (and other containers that use custom LogFactory implementations).
Looks good!
One note though:
> + This will ensure that application classloader will delegate to it's parent when loading
The possessive third person is "its", not "it's".
his
her
its
Sorry to be a pedant!
Cheers,
Simon
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org