commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From robert burrell donkin <robertburrelldon...@blueyonder.co.uk>
Subject Re: svn commit: r384600 - /jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml
Date Thu, 09 Mar 2006 20:36:32 GMT
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


Mime
View raw message