src/site/xdoc/docs/app_server.xml - axis-axis2-java-core - Git at Google

 <?xml version="1.0" encoding="iso-8859-1"?>
 <!--
   ~ Licensed to the Apache Software Foundation (ASF) under one
   ~ or more contributor license agreements. See the NOTICE file
   ~ distributed with this work for additional information
   ~ regarding copyright ownership. The ASF licenses this file
   ~ to you under the Apache License, Version 2.0 (the
   ~ "License"); you may not use this file except in compliance
   ~ with the License. You may obtain a copy of the License at
   ~
   ~ http://www.apache.org/licenses/LICENSE-2.0
   ~
   ~ Unless required by applicable law or agreed to in writing,
   ~ software distributed under the License is distributed on an
   ~ "AS IS" BASIS, 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 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 http://maven.apache.org/xsd/xdoc-2.0.xsd">
     <properties>
         <title>Application Server Specific Configuration Guide</title>
     </properties>
     <body>
         <h1>Application Server Specific Configuration Guide</h1>
         <p>This document provides configuration information required for
         your Application Server to run Apache Axis2 to its fullest
         potential.</p>
         <section name="WebLogic">
             <subsection name="Use exploded configuration to deploy Axis2 WAR">
                 <p>We recommend using the exploded configuration to deploy Axis2
                 WAR in WebLogic application server to support the
                 hotupdate/ hotdeployment features in Axis2. However, if you want to
                 deploy custom WARs, say in a clustering environment, you need to
                 add two additional files into the WEB-INF named "services.list" and
                 "modules.list" under the modules and services directory
                 respectively.</p>
                 <ul>
                 <li><b>WEB-INF/services/services.list</b> : should list all the
                 services (aar files) that you want to expose.</li>
                 <li><b>WEB-INF/modules/modules.list</b> : should list all the
                 modules (mar files) that you want to use.</li>
                 </ul>
                 NOTE: In both cases, please list one entry per line.
                 <p>WebLogic ships with JARs that conflict with JARs present in
                 Axis2. Therefore use &lt;prefer-web-inf-classes&gt; to ensure that
                 JARs packaged in Axis2 WAR are picked up from WEB-INF/lib. You can
                 do this by setting the &lt;prefer-web-inf-classes&gt; element in
                 WEB-INF/weblogic.xml to true. An example of weblogic.xml is shown
                 below:</p>
 <pre>
 &lt;weblogic-web-app&gt;
  &lt;container-descriptor&gt;
     &lt;prefer-web-inf-classes&gt;true&lt;/prefer-web-inf-classes&gt;
   &lt;/container-descriptor&gt;
 &lt;/weblogic-web-app&gt;
 </pre>
                 <p>If set to true, the &lt;prefer-web-inf-classes&gt; element will
                 force WebLogic's classloader to load classes located in the WEB-INF
                 directory of a Web application in preference to application or
                 system classes. This is a recommended approach since it only
                 impacts a single Web module.</p>
                 <p>Please refer to the following documents in WebLogic
                 for more information:</p>
                 <ul>
                 <li><s><a href=
                 "http://e-docs.bea.com/wls/docs81/programming/classloading.html">WebLogic
                 ServerApplication Classloading</a></s> <em>(BEA docs may be inaccessible since Oracle acquisition)</em>- For more information on how
                 WebLogic's class loader works</li>
                 <li><s><a href=
                 "http://e-docs.bea.com/wls/docs81/webapp/deployment.html">Redeploying
                 a Web Application in Exploded Directory Format</a></s> <em>(BEA docs may be inaccessible since Oracle acquisition)</em></li>
                 </ul>
             </subsection>
             <subsection name="Lack of namespacing on serialised items">
                 <p>BEA WebLogic Server 9.0 comes with its own StAX implementation.
                 This results in lack of namespacing on serialised items. In turn,
                 WebLogic server (WLS) breaks with AXIOM on the WLS classpath. Hence
                 a filtering classloader is required:</p>
                 <p>Adding the following to weblogic-application.xml should resolve
                 this issue:</p>
 <pre>
 &lt;prefer-application-packages&gt;
 &lt;package-name&gt;com.ctc.wstx.*&lt;/package-name&gt;
 &lt;package-name&gt;javax.xml.*&lt;/package-name&gt;
 &lt;package-name&gt;org.apache.*&lt;/package-name&gt;
 &lt;/prefer-application-packages&gt;
 </pre>
                 <p>Note that the libraries listed--Xerces, StAX API, Woodstox--need
                 to be on the application classpath.</p>
             </subsection>
         </section>
         <section name="WebSphere">
             <subsection name="Avoiding conflicts with WebSphere's JAX-WS runtime">
                 <p>
                     The JAX-WS runtime in WebSphere Application Server is based on a modified version of Axis2 and these
                     classes are visible to application class loaders. This means that when deploying
                     a standard version of Axis2 on WAS 7.0 (and WAS 6.1 with the Web Services feature pack installed),
                     special configuration is required to avoid conflicts with the Axis2 classes used internally by WebSphere.
                     In particular it is necessary to change the class loader policy of the Web module to parent last. However,
                     this is not sufficient because Axis2 creates additional class loaders for modules and services, and
                     these use parent first class loading by default. Therefore, two things must be done to make a standard
                     Axis2 distribution work with WebSphere:
                 </p>
                 <ol>
                     <li>
                         Before deploying the Axis2 WAR, edit the <tt>axis2.xml</tt> file and set the
                         <tt>EnableChildFirstClassLoading</tt> parameter to <tt>true</tt>.
                         Please note that this parameter is only supported in Axis2 1.5.5 or higher.
                         The parameter is already present in the default <tt>axis2.xml</tt> file included in the
                         WAR distribution, but its value is set to <tt>false</tt>. Therefore it is enough to change
                         the parameter value.
                     </li>
                     <li>
                         After deployment, modify the application configuration to enable parent last class loading
                         for the Web module: in the WebSphere admin console, go the the configuration page for
                         the enterprise application, click on <em>Manage Modules</em> and locate the WAR containing
                         Axis2 (in the default WAR distribution, the module is called <em>Apache-Axis2</em>), then
                         change the <em>Class loader order</em> option to <em>Classes loaded with local class
                         loader first (parent last)</em>. Note that the class loader policy for the enterprise
                         application itself (which can be specified under <em>Class loading and update detection</em>)
                         is irrelevant, unless a custom EAR distribution is used that includes the Axis2 libraries
                         in the EAR instead of the WAR.
                     </li>
                 </ol>
             </subsection>
             <subsection name="Deploying services and modules">
                 <p>
                     By default (i.e. if the <em>Distribute application</em> option has not been disabled explicitly)
                     WebSphere will deploy the application in exploded form. The standard location for these files is
                     in the <tt>installedApps</tt> subdirectory in the WebSphere profile directory. This means that AAR
                     and MAR files can simply be deployed by dropping them into the corresponding folders. In this
                     scenario, hot deployment is supported and there is no need to update the <tt>services.list</tt>
                     and <tt>modules.list</tt> files.
                 </p>
                 <p>
                     However, the directory is still under control of WebSphere and manually deployed AAR and MAR files
                     will be removed e.g. when the application is upgraded. It may therefore be a good idea to configure
                     Axis2 to use a repository location outside of the <tt>installedApps</tt> directory.
                 </p>
             </subsection>
             <subsection name="Deploying older Axis2 versions">
                 <p>
                     The instructions given above apply to Axis2 1.5.5 or higher. Older versions don't support
                     the <tt>EnableChildFirstClassLoading</tt> parameter, and we don't provide any support for
                     deploying these versions on WAS 6.1 (with the Web Services feature pack installed) or 7.0.
                     However, IBM has published a <a href="https://www-304.ibm.com/support/docview.wss?uid=swg21315686">technote</a>
                     with an alternative approach that may work for older Axis2 versions.
                 </p>
             </subsection>
             <subsection name="Known issues">
                 <p>
                     On some WAS versions the following error may occur, e.g. when accessing a WSDL exposed by Axis2:
                 </p>
 <pre>java.lang.VerifyError: JVMVRFY013 class loading constraint violated;
 class=org/apache/xerces/dom/CoreDocumentImpl, method=getDomConfig()Lorg/w3c/dom/DOMConfiguration</pre>
                 <p>
                     This is caused by the XmlBeans library
                     packaged with Axis2. This library contains a set of interfaces in the <code>org.w3c.dom</code> package
                     and this may cause issues with class loaders that don't use a simple parent-first policy.
                     To avoid this issue, upgrade your WAS to a more recent fix pack level, remove the XmlBeans library
                     from the Axis2 WAR or remove the content of the <code>org.w3c.dom</code> package from the XmlBeans library.
                 </p>
             </subsection>
         </section>
     </body>
 </document>
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!--
	~ Licensed to the Apache Software Foundation (ASF) under one
	~ or more contributor license agreements. See the NOTICE file
	~ distributed with this work for additional information
	~ regarding copyright ownership. The ASF licenses this file
	~ to you under the Apache License, Version 2.0 (the
	~ "License"); you may not use this file except in compliance
	~ with the License. You may obtain a copy of the License at
	~
	~ http://www.apache.org/licenses/LICENSE-2.0
	~
	~ Unless required by applicable law or agreed to in writing,
	~ software distributed under the License is distributed on an
	~ "AS IS" BASIS, 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 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 http://maven.apache.org/xsd/xdoc-2.0.xsd">
	<properties>
	<title>Application Server Specific Configuration Guide</title>
	</properties>
	<body>
	<h1>Application Server Specific Configuration Guide</h1>
	<p>This document provides configuration information required for
	your Application Server to run Apache Axis2 to its fullest
	potential.</p>
	<section name="WebLogic">
	<subsection name="Use exploded configuration to deploy Axis2 WAR">
	<p>We recommend using the exploded configuration to deploy Axis2
	WAR in WebLogic application server to support the
	hotupdate/ hotdeployment features in Axis2. However, if you want to
	deploy custom WARs, say in a clustering environment, you need to
	add two additional files into the WEB-INF named "services.list" and
	"modules.list" under the modules and services directory
	respectively.</p>
	<ul>
	<li><b>WEB-INF/services/services.list</b> : should list all the
	services (aar files) that you want to expose.</li>
	<li><b>WEB-INF/modules/modules.list</b> : should list all the
	modules (mar files) that you want to use.</li>
	</ul>
	NOTE: In both cases, please list one entry per line.
	<p>WebLogic ships with JARs that conflict with JARs present in
	Axis2. Therefore use <prefer-web-inf-classes> to ensure that
	JARs packaged in Axis2 WAR are picked up from WEB-INF/lib. You can
	do this by setting the <prefer-web-inf-classes> element in
	WEB-INF/weblogic.xml to true. An example of weblogic.xml is shown
	below:</p>
	<pre>
	<weblogic-web-app>
	<container-descriptor>
	<prefer-web-inf-classes>true</prefer-web-inf-classes>
	</container-descriptor>
	</weblogic-web-app>
	</pre>
	<p>If set to true, the <prefer-web-inf-classes> element will
	force WebLogic's classloader to load classes located in the WEB-INF
	directory of a Web application in preference to application or
	system classes. This is a recommended approach since it only
	impacts a single Web module.</p>
	<p>Please refer to the following documents in WebLogic
	for more information:</p>
	<ul>
	<li><s><a href=
	"http://e-docs.bea.com/wls/docs81/programming/classloading.html">WebLogic
	ServerApplication Classloading</a></s> <em>(BEA docs may be inaccessible since Oracle acquisition)</em>- For more information on how
	WebLogic's class loader works</li>
	<li><s><a href=
	"http://e-docs.bea.com/wls/docs81/webapp/deployment.html">Redeploying
	a Web Application in Exploded Directory Format</a></s> <em>(BEA docs may be inaccessible since Oracle acquisition)</em></li>
	</ul>
	</subsection>
	<subsection name="Lack of namespacing on serialised items">
	<p>BEA WebLogic Server 9.0 comes with its own StAX implementation.
	This results in lack of namespacing on serialised items. In turn,
	WebLogic server (WLS) breaks with AXIOM on the WLS classpath. Hence
	a filtering classloader is required:</p>
	<p>Adding the following to weblogic-application.xml should resolve
	this issue:</p>
	<pre>
	<prefer-application-packages>
	<package-name>com.ctc.wstx.*</package-name>
	<package-name>javax.xml.*</package-name>
	<package-name>org.apache.*</package-name>
	</prefer-application-packages>
	</pre>
	<p>Note that the libraries listed--Xerces, StAX API, Woodstox--need
	to be on the application classpath.</p>
	</subsection>
	</section>
	<section name="WebSphere">
	<subsection name="Avoiding conflicts with WebSphere's JAX-WS runtime">
	<p>
	The JAX-WS runtime in WebSphere Application Server is based on a modified version of Axis2 and these
	classes are visible to application class loaders. This means that when deploying
	a standard version of Axis2 on WAS 7.0 (and WAS 6.1 with the Web Services feature pack installed),
	special configuration is required to avoid conflicts with the Axis2 classes used internally by WebSphere.
	In particular it is necessary to change the class loader policy of the Web module to parent last. However,
	this is not sufficient because Axis2 creates additional class loaders for modules and services, and
	these use parent first class loading by default. Therefore, two things must be done to make a standard
	Axis2 distribution work with WebSphere:
	</p>
	<ol>
	<li>
	Before deploying the Axis2 WAR, edit the <tt>axis2.xml</tt> file and set the
	<tt>EnableChildFirstClassLoading</tt> parameter to <tt>true</tt>.
	Please note that this parameter is only supported in Axis2 1.5.5 or higher.
	The parameter is already present in the default <tt>axis2.xml</tt> file included in the
	WAR distribution, but its value is set to <tt>false</tt>. Therefore it is enough to change
	the parameter value.
	</li>
	<li>
	After deployment, modify the application configuration to enable parent last class loading
	for the Web module: in the WebSphere admin console, go the the configuration page for
	the enterprise application, click on <em>Manage Modules</em> and locate the WAR containing
	Axis2 (in the default WAR distribution, the module is called <em>Apache-Axis2</em>), then
	change the <em>Class loader order</em> option to <em>Classes loaded with local class
	loader first (parent last)</em>. Note that the class loader policy for the enterprise
	application itself (which can be specified under <em>Class loading and update detection</em>)
	is irrelevant, unless a custom EAR distribution is used that includes the Axis2 libraries
	in the EAR instead of the WAR.
	</li>
	</ol>
	</subsection>
	<subsection name="Deploying services and modules">
	<p>
	By default (i.e. if the <em>Distribute application</em> option has not been disabled explicitly)
	WebSphere will deploy the application in exploded form. The standard location for these files is
	in the <tt>installedApps</tt> subdirectory in the WebSphere profile directory. This means that AAR
	and MAR files can simply be deployed by dropping them into the corresponding folders. In this
	scenario, hot deployment is supported and there is no need to update the <tt>services.list</tt>
	and <tt>modules.list</tt> files.
	</p>
	<p>
	However, the directory is still under control of WebSphere and manually deployed AAR and MAR files
	will be removed e.g. when the application is upgraded. It may therefore be a good idea to configure
	Axis2 to use a repository location outside of the <tt>installedApps</tt> directory.
	</p>
	</subsection>
	<subsection name="Deploying older Axis2 versions">
	<p>
	The instructions given above apply to Axis2 1.5.5 or higher. Older versions don't support
	the <tt>EnableChildFirstClassLoading</tt> parameter, and we don't provide any support for
	deploying these versions on WAS 6.1 (with the Web Services feature pack installed) or 7.0.
	However, IBM has published a <a href="https://www-304.ibm.com/support/docview.wss?uid=swg21315686">technote</a>
	with an alternative approach that may work for older Axis2 versions.
	</p>
	</subsection>
	<subsection name="Known issues">
	<p>
	On some WAS versions the following error may occur, e.g. when accessing a WSDL exposed by Axis2:
	</p>
	<pre>java.lang.VerifyError: JVMVRFY013 class loading constraint violated;
	class=org/apache/xerces/dom/CoreDocumentImpl, method=getDomConfig()Lorg/w3c/dom/DOMConfiguration</pre>
	<p>
	This is caused by the XmlBeans library
	packaged with Axis2. This library contains a set of interfaces in the <code>org.w3c.dom</code> package
	and this may cause issues with class loaders that don't use a simple parent-first policy.
	To avoid this issue, upgrade your WAS to a more recent fix pack level, remove the XmlBeans library
	from the Axis2 WAR or remove the content of the <code>org.w3c.dom</code> package from the XmlBeans library.
	</p>
	</subsection>
	</section>
	</body>
	</document>