blob: 3a49621e5b6d888b85ffa49029f88c18b70ec5fd [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2017-05-06
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="Date-Revision-yyyymmdd" content="20170506" />
<meta http-equiv="Content-Language" content="en" />
<title>Apache Axis2 &#x2013; Application Server Specific Configuration Guide</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" />
<link rel="stylesheet" href="../css/site.css" />
<link rel="stylesheet" href="../css/print.css" media="print" />
<script type="text/javascript" src="../js/apache-maven-fluido-1.6.min.js"></script>
</head>
<body class="topBarDisabled">
<div class="container-fluid">
<div id="banner">
<div class="pull-left"><a href="http://www.apache.org/" id="bannerLeft"><img src="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Axis2"/></a></div>
<div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/axis.jpg" /></a></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="publishDate">Last Published: 2017-05-06<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.7.5<span class="divider">|</span></li>
<li class=""><a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li>
<li class=""><a href="../index.html" title="Axis2/Java">Axis2/Java</a><span class="divider">/</span></li>
<li class="active ">Application Server Specific Configuration Guide</li>
</ul>
</div>
<div class="row-fluid">
<div id="leftColumn" class="span2">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header">Axis2/Java</li>
<li><a href="../index.html" title="Home"><span class="none"></span>Home</a> </li>
<li><a href="../download.html" title="Downloads"><span class="none"></span>Downloads</a> </li>
<li><a href="javascript:void(0)" title="Release Notes"><span class="icon-chevron-down"></span>Release Notes</a>
<ul class="nav nav-list">
<li><a href="../release-notes/1.6.1.html" title="1.6.1"><span class="none"></span>1.6.1</a> </li>
<li><a href="../release-notes/1.6.2.html" title="1.6.2"><span class="none"></span>1.6.2</a> </li>
<li><a href="../release-notes/1.6.3.html" title="1.6.3"><span class="none"></span>1.6.3</a> </li>
<li><a href="../release-notes/1.6.4.html" title="1.6.4"><span class="none"></span>1.6.4</a> </li>
<li><a href="../release-notes/1.7.0.html" title="1.7.0"><span class="none"></span>1.7.0</a> </li>
<li><a href="../release-notes/1.7.1.html" title="1.7.1"><span class="none"></span>1.7.1</a> </li>
<li><a href="../release-notes/1.7.2.html" title="1.7.2"><span class="none"></span>1.7.2</a> </li>
<li><a href="../release-notes/1.7.3.html" title="1.7.3"><span class="none"></span>1.7.3</a> </li>
<li><a href="../release-notes/1.7.4.html" title="1.7.4"><span class="none"></span>1.7.4</a> </li>
<li><a href="../release-notes/1.7.5.html" title="1.7.5"><span class="none"></span>1.7.5</a> </li>
</ul>
</li>
<li><a href="../modules/index.html" title="Modules"><span class="none"></span>Modules</a> </li>
<li><a href="../tools/index.html" title="Tools"><span class="none"></span>Tools</a> </li>
<li class="nav-header">Documentation</li>
<li><a href="../docs/toc.html" title="Table of Contents"><span class="none"></span>Table of Contents</a> </li>
<li><a href="../docs/installationguide.html" title="Installation Guide"><span class="none"></span>Installation Guide</a> </li>
<li><a href="../docs/quickstartguide.html" title="QuickStart Guide"><span class="none"></span>QuickStart Guide</a> </li>
<li><a href="../docs/userguide.html" title="User Guide"><span class="none"></span>User Guide</a> </li>
<li><a href="../docs/jaxws-guide.html" title="JAXWS Guide"><span class="none"></span>JAXWS Guide</a> </li>
<li><a href="../docs/pojoguide.html" title="POJO Guide"><span class="none"></span>POJO Guide</a> </li>
<li><a href="../docs/spring.html" title="Spring Guide"><span class="none"></span>Spring Guide</a> </li>
<li><a href="../docs/webadminguide.html" title="Web Administrator's Guide"><span class="none"></span>Web Administrator's Guide</a> </li>
<li><a href="../docs/migration.html" title="Migration Guide (from Axis1)"><span class="none"></span>Migration Guide (from Axis1)</a> </li>
<li class="nav-header">Resources</li>
<li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a> </li>
<li><a href="../articles.html" title="Articles"><span class="none"></span>Articles</a> </li>
<li><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="Wiki"><span class="none"></span>Wiki</a> </li>
<li><a href="../refLib.html" title="Reference Library"><span class="none"></span>Reference Library</a> </li>
<li><a href="../apidocs/index.html" title="Online Java Docs"><span class="none"></span>Online Java Docs</a> </li>
<li class="nav-header">Get Involved</li>
<li><a href="../overview.html" title="Overview"><span class="none"></span>Overview</a> </li>
<li><a href="../svn.html" title="Checkout the Source"><span class="none"></span>Checkout the Source</a> </li>
<li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a> </li>
<li><a href="../release-process.html" title="Release Process"><span class="none"></span>Release Process</a> </li>
<li><a href="../guidelines.html" title="Developer Guidelines"><span class="none"></span>Developer Guidelines</a> </li>
<li><a href="../siteHowTo.html" title="Build the Site"><span class="none"></span>Build the Site</a> </li>
<li class="nav-header">Project Information</li>
<li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a> </li>
<li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a> </li>
<li><a href="http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/" class="externalLink" title="Source Code"><span class="none"></span>Source Code</a> </li>
<li><a href="../thanks.html" title="Acknowledgements"><span class="none"></span>Acknowledgements</a> </li>
<li class="nav-header">Apache</li>
<li><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License"><span class="none"></span>License</a> </li>
<li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a> </li>
<li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a> </li>
<li><a href="http://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a> </li>
</ul>
<hr />
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
</div>
</div>
</div>
<div id="bodyColumn" class="span10" >
<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>
<div class="section">
<h2><a name="WebLogic"></a>WebLogic</h2>
<div class="section">
<h3><a name="Use_exploded_configuration_to_deploy_Axis2_WAR"></a>Use exploded configuration to deploy Axis2 WAR</h3>
<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 &quot;services.list&quot; and
&quot;modules.list&quot; 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>
<div>
<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></div>
<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><a class="externalLink" 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 class="externalLink" href="http://e-docs.bea.com/wls/docs81/webapp/deployment.html">Redeploying
a Web Application in Exploded Directory Format</a></li>
</ul>
</div>
<div class="section">
<h3><a name="Lack_of_namespacing_on_serialised_items"></a>Lack of namespacing on serialised items</h3>
<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>
<div>
<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></div>
<p>Note that the libraries listed--Xerces, StAX API, Woodstox--need
to be on the application classpath.</p>
</div>
</div>
<div class="section">
<h2><a name="WebSphere"></a>WebSphere</h2>
<div class="section">
<h3><a name="Avoiding_conflicts_with_WebSpheres_JAX-WS_runtime"></a>Avoiding conflicts with WebSphere's JAX-WS runtime</h3>
<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 style="list-style-type: decimal">
<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 <i>Manage Modules</i> and locate the WAR containing
Axis2 (in the default WAR distribution, the module is called <i>Apache-Axis2</i>), then
change the <i>Class loader order</i> option to <i>Classes loaded with local class
loader first (parent last)</i>. Note that the class loader policy for the enterprise
application itself (which can be specified under <i>Class loading and update detection</i>)
is irrelevant, unless a custom EAR distribution is used that includes the Axis2 libraries
in the EAR instead of the WAR.
</li>
</ol>
</div>
<div class="section">
<h3><a name="Deploying_services_and_modules"></a>Deploying services and modules</h3>
<p>
By default (i.e. if the <i>Distribute application</i> 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>
</div>
<div class="section">
<h3><a name="Deploying_older_Axis2_versions"></a>Deploying older Axis2 versions</h3>
<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 class="externalLink" 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>
</div>
<div class="section">
<h3><a name="Known_issues"></a>Known issues</h3>
<p>
On some WAS versions the following error may occur, e.g. when accessing a WSDL exposed by Axis2:
</p>
<div>
<pre>java.lang.VerifyError: JVMVRFY013 class loading constraint violated;
class=org/apache/xerces/dom/CoreDocumentImpl, method=getDomConfig()Lorg/w3c/dom/DOMConfiguration</pre></div>
<p>
This is caused by the XmlBeans library
packaged with Axis2. This library contains a set of interfaces in the <tt>org.w3c.dom</tt> 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 <tt>org.w3c.dom</tt> package from the XmlBeans library.
</p>
</div>
</div>
</div>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p>Copyright &copy;2004&#x2013;2017
<a href="https://www.apache.org/">The Apache Software Foundation</a>.
All rights reserved.</p>
</div>
</div>
</footer>
</body>
</html>