<?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><a href= | |
"http://e-docs.bea.com/wls/docs81/programming/classloading.html">WebLogic | |
ServerApplication Classloading</a>- For more information on how | |
WebLogic's class loader works</li> | |
<li><a href= | |
"http://e-docs.bea.com/wls/docs81/webapp/deployment.html">Redeploying | |
a Web Application in Exploded Directory Format</a></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> |