Google Git
Sign in
apache / axis-site / 89d475487d2f61e8cd102331a18503ad5e30bc96 / . / axis / site.html
blob: 61045b13148db00f4b4caf055a484002568f83b4 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<!--*** This is a generated file. Do not edit. ***-->
<link rel="stylesheet" href="skin/tigris.css" type="text/css">
<link rel="stylesheet" href="skin/mysite.css" type="text/css">
<link rel="stylesheet" href="skin/site.css" type="text/css">
<link media="print" rel="stylesheet" href="skin/print.css" type="text/css">
<title>The Apache Axis Project</title>
</head>
<body bgcolor="white" class="composite">
<!--================= start Banner ==================-->
<div id="banner">
<table width="100%" cellpadding="8" cellspacing="0" summary="banner" border="0">
<tbody>
<tr>
<!--================= start Group Logo ==================-->
<td align="left">
<div class="groupLogo">
<a href="http://ws.apache.org/"><img border="0" class="logoImage" alt="The Apache WebServices Project" src="images/project-logo.jpg"></a>
</div>
</td>
<!--================= end Group Logo ==================-->
<!--================= start Project Logo ==================--><td align="right">
<div class="projectLogo">
<a href="http://ws.apache.org/axis/"><img border="0" class="logoImage" alt="The Apache Axis Project" src="images/axis.jpg"></a>
</div>
</td>
<!--================= end Project Logo ==================-->
<!--================= start Search ==================--><td valign="top" rowspan="2" align="right" class="search">
<form target="_blank" action="http://www.google.com/search" method="get">
<table summary="search" border="0" cellspacing="0" cellpadding="0">
<tr>
<td bgcolor="#a5b6c6" colspan="3"><img height="10" width="1" alt="" src="skin/images/spacer.gif" class="spacer"></td>
</tr>
<tr>
<td colspan="3"><img height="8" width="1" alt="" src="skin/images/spacer.gif" class="spacer"></td>
</tr>
<tr>
<td><img height="1" width="1" alt="" src="skin/images/spacer.gif" class="spacer"></td><td nowrap="nowrap"><input value="ws.apache.org" name="sitesearch" type="hidden"><input size="10" name="q" id="query" type="text"><img height="1" width="5" alt="" src="skin/images/spacer.gif" class="spacer"><input name="Search" value="GO" type="submit">
<br>
Search WS</td><td><img height="1" width="1" alt="" src="skin/images/spacer.gif" class="spacer"></td>
</tr>
<tr>
<td colspan="3"><img height="7" width="1" alt="" src="skin/images/spacer.gif" class="spacer"></td>
</tr>
<tr>
<td class="bottom-left-thick"></td><td bgcolor="#a5b6c6"><img height="1" width="1" alt="" src="skin/images/spacer.gif" class="spacer"></td><td class="bottom-right-thick"></td>
</tr>
</table>
</form>
</td>
<!--================= end Search ==================-->
</tr>
</tbody>
</table>
</div>
<!--================= end Banner ==================-->
<!--================= start Main ==================-->
<table width="100%" cellpadding="0" cellspacing="0" border="0" summary="nav" id="breadcrumbs">
<tbody>
<!--================= start Status ==================-->
<tr class="status">
<td>
<!--================= start BreadCrumb ==================--><a href="http://www.apache.org/">Apache</a> | <a href="http://ws.apache.org/">WS</a><a href=""></a>
<!--================= end BreadCrumb ==================--></td><td id="tabs">
<!--================= start Tabs ==================-->
<div class="tab">
<span class="selectedTab"><a class="base-selected" href="index.html">WebServices-Axis</a></span>
</div>
<!--================= end Tabs ==================-->
</td>
</tr>
</tbody>
</table>
<!--================= end Status ==================-->
<table id="main" width="100%" cellpadding="8" cellspacing="0" summary="" border="0">
<tbody>
<tr valign="top">
<!--================= start Menu ==================-->
<td id="leftcol">
<div id="navcolumn">
<div class="menuBar">
<div class="menu">
<span class="menuLabel">Axis</span>
<div class="menuItem">
<a href="index.html">Introduction</a>
</div>
<div class="menuItem">
<a href="news.html">News</a>
</div>
<div class="menuItem">
<a href="http://wiki.apache.org/ws/FrontPage/Axis">FAQ/Wiki</a>
</div>
<div class="menu">
<span class="menuLabel">Get Involved</span>
<div class="menuItem">
<a href="overview.html">Overview</a>
</div>
<div class="menuItem">
<a href="cvs.html">CVS Repository</a>
</div>
<div class="menuItem">
<a href="mail.html">Mailing Lists</a>
</div>
<div class="menuItem">
<a href="ref.html">Reference Library</a>
</div>
<div class="menuItem">
<a href="bugs.html">Bugs</a>
</div>
<div class="menuItem">
<a href="howtobuild.html">HowToBuildSite</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Axis (Java)</span>
<div class="menuItem">
<a href="java/index.html">Documentation</a>
</div>
<div class="menuItem">
<a href="java/install.html">Installation</a>
</div>
<div class="menuItem">
<a href="java/user-guide.html">User's Guide</a>
</div>
<div class="menuItem">
<a href="java/developers-guide.html">Developer's Guide</a>
</div>
<div class="menuItem">
<a href="java/integration-guide.html">Integration Guide</a>
</div>
<div class="menuItem">
<a href="java/architecture-guide.html">Architecture Guide</a>
</div>
<div class="menuItem">
<a href="java/reference.html">Reference Guide</a>
</div>
<div class="menuItem">
<a href="java/reading.html">Reading Guide</a>
</div>
<div class="menuItem">
<a href="java/requirements.html">Requirements</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Axis (C++)</span>
<div class="menuItem">
<a href="cpp/index.html">Latest Axis C++ Release!</a>
</div>
<div class="menuItem">
<a href="cpp/documentation.html">Documentation</a>
</div>
<div class="menuItem">
<a href="cpp/download.html">Download</a>
</div>
<div class="menuItem">
<a href="http://wiki.apache.org/ws/FrontPage/AxisCPP">Wiki Pages</a>
</div>
<div class="menuItem">
<a href="cpp/who.html">Who we are</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Downloads</span>
<div class="menuItem">
<a href="releases.html">Releases</a>
</div>
<div class="menuItem">
<a href="interim.html">Interim Drops</a>
</div>
<div class="menuItem">
<a href="http://cvs.apache.org/viewcvs/ws-axis/">Source Code</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Translation</span>
<div class="menuItem">
<a href="http://ws.apache.org/axis/jp/">Japanese</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Related Projects</span>
<div class="menuItem">
<a href="http://ws.apache.org/wsif/">WSIF</a>
</div>
<div class="menuItem">
<a href="http://cvs.apache.org/viewcvs/*checkout*/ws-wsil/java/README.htm">WSIL</a>
</div>
<div class="menuItem">
<a href="http://www-124.ibm.com/developerworks/projects/wsdl4j/">WSDL4J</a>
</div>
<div class="menuItem">
<a href="http://www.uddi4j.org/">UDDI4J</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Misc</span>
<div class="menuItem">
<span class="menuSelected">Whole Site</span>
</div>
<div class="menuItem">
<a href="who.html">Who We Are</a>
</div>
<div class="menuItem">
<a href="contact.html">Contact</a>
</div>
<div class="menuItem">
<a href="legal.html">Legal</a>
</div>
<div class="menuItem">
<a href="docs.html">Notes/Docs</a>
</div>
</div>
</div>
</div>
</div>
</td>
<!--================= end Menu ==================-->
<!--================= start Content ==================--><td>
<div id="bodycol">
<div class="app">
<div align="center">
<h1>The Apache Axis Project</h1>
</div>
<div class="h3">
<div class="h3">
<h3>Axis</h3>
</div>
<div class="h4">
<h4>WebServices - Axis</h4>
</div>
<div class="h2">
<h2>WebServices - Axis - Introduction</h2>
</div>
<p>NEWS (April 09, 2005) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.5 Final
</a> is now available!
</p>
<p>NEWS ((March 01, 2005)) : Axis <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2RC2/">Axis 1.2 RC3 release</a> is now available!
</p>
<p>NEWS (February 08, 2005) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.5 Alpha
</a> is now available!
</p>
<p>NEWS (December 16, 2004) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.4 Final
</a> is now available!
</p>
<p>NEWS (December 03, 2004) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.4 Alpha
</a> is now available!
</p>
<p>NEWS (November 16, 2004) : Axis <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2RC2/">1.2 RC2 release</a> is now available!
</p>
<p>NEWS (October 29, 2004) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.3 Final
</a> is now available!
</p>
<p>NEWS (September 30, 2004) : Axis <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2RC1/">1.2 RC1 release</a> is now available!
</p>
<p>NEWS (September 15, 2004) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.3 Beta
</a> is now available!
</p>
<hr>
<p>NEWS (August 18, 2004) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.3 Alpha
</a> is now available!
</p>
<p>NEWS (August 17, 2004) : Axis <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2beta3/">1.2 beta 3 release</a> is now available!
</p>
<p>NEWS (July 14, 2004) : Axis <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2beta2/">1.2 beta 2 release</a> is now available!</p>
<p>NEWS (July 09, 2004) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.2
</a> is now available!
</p>
<p>NEWS (June 29, 2004) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.2 Beta
</a> is now available!
</p>
<p>NEWS (June 15, 2004) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.2 Alpha
</a> is now available!
</p>
<p>NEWS (May 07, 2004) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.1.1
</a> is now available!
</p>
<p>NEWS (April 16, 2004) : Axis C++<a href="http://ws.apache.org/axis/cpp/download.html">1.1
</a> is now available!
</p>
<p>NEWS (March 31, 2004) : Axis <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2beta/">1.2
Beta </a> is now available.
</p>
<p>NEWS (December 1, 2003) : Axis <a href="http://ws.apache.org/axis/download.cgi">1.2
Alpha </a> is now available.
</p>
<p>NEWS (June 16, 2003) : Axis <a href="http://ws.apache.org/axis/download.cgi">1.1
Final </a> is still the most recent stable release (read the <a href="http://cvs.apache.org/viewcvs/%7Echeckout%7E/ws-axis/java/release-notes.html">release
notes</a>)!
</p>
<hr>
<p>Apache Axis is an implementation of the SOAP ("Simple Object Access
Protocol") <a href="http://www.w3.org/TR/SOAP">submission</a>
to W3C.
</p>
<p>From the draft W3C specification:
<blockquote>SOAP is a lightweight protocol for exchange of information
in a decentralized, distributed environment. It is an XML based protocol
that consists of three parts: an envelope that defines a framework for
describing what is in a message and how to process it, a set of encoding
rules for expressing instances of application-defined datatypes, and a
convention for representing remote procedure calls and responses.</blockquote>
</p>
<p>
This project is a follow-on to the <a href="http://ws.apache.org/soap">Apache SOAP project</a>.
</p>
<p>Please see the <a href="#ref.html">Reference Library</a> for a list of
technical resources that should prove useful.
</p>
<div class="h2">
<h2>Axis 1.2 and beyond</h2>
</div>
<p>
Axis 1.1 has proven itself to be a reliable and stable base on which to
implement Java Web Services. There is a very active
<a href="http://ws.apache.org/axis/mail.html">user community</a>
and there a many companies who use Axis for Web Service
support in their products.
</p>
<p>
For Axis 1.2, we are focusing on our document/literal support to better address the
<a href="http://www.ws-i.org/Profiles/Basic/2003-08/BasicProfile-1.0a.html">WS-I Basic Profile 1.0</a>
and <a href="http://java.sun.com/xml/downloads/jaxrpc.html">JAX-RPC 1.1</a> specifications.
And we are fixing as many bug as possible.
</p>
<p>
We can always use <b>your</b> help. Here are some links to help you help us:
<ul>
<li>
<a href="http://ws.apache.org/axis/bugs.html">How do I report bugs?</a>
</li>
<li>
<a href="http://wiki.apache.org/ws/SubmitPatches">How do I submit patches to Axis?</a>
</li>
<li>
<a href="http://cvs.apache.org/snapshots/ws-axis/">Where can i get snapshots of latest CVS?</a>
</li>
</ul>
</p>
<div class="h2">
<h2>Credits</h2>
</div>
<p>
The Axis Development Team
</p>
<div class="h4">
<h4>WebServices - Axis</h4>
</div>
<div class="h2">
<h2>WebServices - Axis - News</h2>
</div>
<p>(April 09, 2005) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.5 Final is available!</b></a>
</p>
<p>(March 01, 2005) : Axis <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2RC2/">1.2 RC3 release</a> is now available!</p>
<p>(February 08, 2005) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.5 Alpha is available!</b></a>
</p>
<p>(December 16, 2004) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.4 Final is available!</b></a>
</p>
<p>(December 03, 2004) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.4 Alpha is available!</b></a>
</p>
<p>(November 16, 2004) : Axis <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2RC2/">1.2 RC2 release</a> is now available!</p>
<p>(October 29, 2004) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.3 Final is available!</b></a>
</p>
<p>(September 30, 2004) : Axis <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2RC1/">1.2 RC1 release</a> is now available!</p>
<p>(September 15, 2004) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.3 Beta is available!</b></a>
</p>
<p>(August 18, 2004) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.3 Alpha is available!</b></a>
</p>
<p>(August 17, 2004) : Axis <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2beta3/">1.2 beta 3 release</a> is now available!</p>
<p>(July 14, 2004) : Axis <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2beta2/">1.2 beta 2 release</a> is now available!</p>
<p>(July 09, 2004) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.2 is available!</b></a>
</p>
<p>(June 29, 2004) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.2 Beta is available!</b></a>
</p>
<p>(June 15, 2004) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.2 Alpha is available!</b></a>
</p>
<p>(May 07, 2004) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.1.1 is available!</b></a>
</p>
<p>(April 16, 2004) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.1 is available!</b></a>
</p>
<p>(December 29, 2003) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/"><b>1.0 is released!</b></a>
</p>
<p>(December 01, 2003) : Axis <a href="http://archive.apache.org/dist/ws/axis/1_2alpha/">1.2 Alpha</a> is available! </p>
<p>(December 01, 2003) : Axis C++ <a href="http://www.apache.org/dist/ws/axis-c/">Beta</a> is available! </p>
<p>(October 31, 2003) : Axis C++ alpha has been released! </p>
<p>(September 10, 2003) : Axis CVS Repository has moved from xml-axis to <a href="http://cvs.apache.org/viewcvs/ws-axis/">ws-axis</a>
</p>
<p>(June 16, 2003) : Axis <a href="http://ws.apache.org/axis/download.cgi">1.1</a> is now available!</p>
<p>(March 5, 2003) : Axis <a href="http://archive.apache.org/dist/ws/axis/1_1rc2/">1.1 RC2 release</a> is now available!</p>
<p>(February 9, 2003) : Axis <a href="http://archive.apache.org/dist/ws/axis/1_1RC1/">1.1 RC1 release</a> is now available!</p>
<p>(October 7, 2002) : Axis <a href="http://archive.apache.org/dist/ws/axis/1_0rc2/">1.0</a> is now available!</p>
<p>(September 30, 2002) : Axis <a href="http://archive.apache.org/dist/ws/axis/1_0rc2/">1.0 RC2 release</a> is now available!</p>
<p>(September 6, 2002) : Axis <a href="http://archive.apache.org/dist/ws/axis/1_0rc1/">1.0 RC1 release</a> is now available!</p>
<p>(July 9, 2002) : The Axis <a href="http://archive.apache.org/dist/ws/axis/beta3/">beta 3 release</a> is available!</p>
<p>See the <a href="#mail.html">Mailing Lists</a> for more information.
</p>
<p>
The Axis Development Team
</p>
<div class="h4">
<h4>Get Involved</h4>
</div>
<div class="h2">
<h2>WebServices - Axis</h2>
</div>
<div class="h5">
<h5>WebServices - Axis - Overview</h5>
</div>
<p>
Every volunteer project obtains its strength from the people involved in it.
We invite you to participate as much or as little as you choose. The roles
and responsibilities that people can assume in the project are based on
merit. Everybody's input matters!
</p>
<p>
There are a variety of ways to participate. Regardless of how you choose
to participate, we suggest you join some or all of our
<a href="#mail.html">mailing lists</a>.
</p>
<p>
<b>Use the Products and Give Us Feedback</b>
</p>
<p>
Using the products,reporting bugs, making feature requests, etc. is by
far the most important role. It's your feedback that allows the technology
to evolve.
<ul>
<li>
<a href="#mail.html">Join Mailing Lists </a>
</li>
<li>
<a href="#releases.html">Download Binary Builds </a>
</li>
<li>
<a href="#bugs.html">Report bugs/Request additional features </a>
</li>
</ul>
</p>
<p>
<b>Contribute Code or Documentation Patches</b>
</p>
<p>
In this role, you participate in the actual development of the code. If this
is the type of role you'd like to play, here are some steps (in addition to
the ones above) to get you started:
<ul>
<li>
<a href="#mailguide.html">Read Guidelines </a>
</li>
<li>
<a href="#ref.html">Review Reference Library </a>
</li>
<li>
<a href="http://cvs.apache.org/viewcvs/ws-axis/">Download the Source Code </a>
</li>
<li>
<a href="#cvs.html">Access CVS Repository </a>
</li>
</ul>
</p>
<div class="h2">
<h2>WebServices - Axis</h2>
</div>
<div class="h5">
<h5>WebServices - Axis - CVS Repositories</h5>
</div>
<p>
Most users of the source code probably don't need to have day
to day access to the source code as it changes. For these
users we provide easy to unpack source code downloads via our
<a href="#releases.html">download pages</a>.
</p>
<p>
<b><font size="+1">View the Source Tree</font></b>
<br>
</p>
<p> Latest CVS sources can be viewed at <a href="http://cvs.apache.org/viewcvs/ws-axis/">http://cvs.apache.org/viewcvs/ws-axis/</a>
</p>
<p>
<b><font size="+1">Access the Source Tree
(AnonCVS)</font></b>
<br>
So, you've decided that you need access to the source tree
to see the latest and greatest code. There's two different
forms of CVS access. The first is anonymous and anybody can
use it. The second is not and you must have a login to the
development server. If you don't know what this means, join
the <a href="#mail.html">mailing list</a> and find out.
</p>
<p>
Anyone can checkout source code from our anonymous CVS
server. To do so, simply use the following commands (if you
are using a GUI CVS client, configure it appropriately):
</p>
<blockquote>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td colspan="1" rowspan="1">
<pre>
cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
password: anoncvs
cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout ws-axis
</pre>
</td>
</tr>
</table>
</blockquote>
<b><font size="+1">Full Remote CVS
Access</font></b>
<br>
If you are a <i>Committer</i> and have a login on the Apache
development server, this section is for you. If you are not a
Committer, but you want to submit patches or even request
commit privileges, please see the <a href="http://jakarta.apache.org/site/guidelines.html">Jakarta
GuideLines</a> page (we follow the same rules) for more
information.
<p>
To have full access to the CVS server, you need to follow the
links depending on the operating system you are using:
</p>
<ul>
<li>
<a href="http://jakarta.apache.org/site/cvsonunix.html">Unix</a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsonwin32.html">Windows</a>
</li>
</ul>
<div class="h2">
<h2>WebServices - Axis</h2>
</div>
<div class="h5">
<h5>WebServices - Axis - Mailing List</h5>
</div>
<p>
<b>Before subscribing to any of the mailing lists, please make sure you have
read and understand the <a href="#mailguide.html">guidelines</a>.</b>
</p>
<p>While the mailing lists are not archived on Apache they are available
at other sites, for example <a href="http://marc.theaimsgroup.com">
http://marc.theaimsgroup.com</a> is pretty good and is used for searching below.
</p>
<div class="h5">
<h5>The Axis User List</h5>
</div>
<p>
<b>Medium Traffic</b>
<a href="#mailto:axis-user-subscribe@ws.apache.org">Subscribe</a>
<a href="#mailto:axis-user-unsubscribe@ws.apache.org">Unsubscribe</a>
<a href="#mailto:axis-user-digest-subscribe@ws.apache.org">Subscribe(Digest)</a>
<a href="#mailto:axis-user-digest-unsubscribe@ws.apache.org">Unsubscribe(Digest)</a>
<a href="#mailto:axis-user@ws.apache.org">Send mail to list</a>
<br>
This list is for developers that are using Axis in their own projects to
ask questions, share knowledge, and discuss issues related to using Axis.
<br>
<form action="http://marc.theaimsgroup.com/" method="get">
<input name="l" type="hidden" value="axis-user">
<input name="w" type="hidden" value="2">
<table class="ForrestTable" cellspacing="0" cellpadding="0" border="0">
<tr class="b">
<td align="left" colspan="1" rowspan="1"><input name="r" type="hidden" value="1">Search:&nbsp;<input maxlength="40" name="s" size="25" type="text" value=""><input type="submit" value="Search"><input type="reset" value="Reset">
<br>[<input name="q" type="radio" value="t">]&nbsp;Subjects&nbsp;[<input name="q" type="radio" value="a">]&nbsp;Authors&nbsp;[<input name="q" type="radio" value="b">]&nbsp;Bodies&nbsp;for&nbsp;list&nbsp;'axis-user'
<br>
</td>
</tr>
</table>
</form>
</p>
<div class="h5">
<h5>The Axis Developer List</h5>
</div>
<p>
<b>Medium Traffic</b>
<a href="#mailto:axis-dev-subscribe@ws.apache.org">Subscribe</a>
<a href="#mailto:axis-dev-unsubscribe@ws.apache.org">Unsubscribe</a>
<a href="#mailto:axis-dev-digest-subscribe@ws.apache.org">Subscribe(Digest)</a>
<a href="#mailto:axis-dev-digest-unsubscribe@ws.apache.org">Unsubscribe(Digest)</a>
<a href="#mailto:axis-dev@ws.apache.org">Send mail to list</a>
<br>
This is the list where participating developers of the Axis project meet
and discuss issues, code changes/additions, etc.
<form action="http://marc.theaimsgroup.com/" method="get">
<input name="l" type="hidden" value="axis-dev">
<input name="w" type="hidden" value="2">
<table class="ForrestTable" cellspacing="0" cellpadding="0" border="0">
<tr class="b">
<td align="left" colspan="1" rowspan="1"><input name="r" type="hidden" value="1">Search:&nbsp;<input maxlength="40" name="s" size="25" type="text" value=""><input type="submit" value="Search"><input type="reset" value="Reset">
<br>[<input name="q" type="radio" value="t">]&nbsp;Subjects&nbsp;[<input name="q" type="radio" value="a">]&nbsp;Authors&nbsp;[<input name="q" type="radio" value="b">]&nbsp;Bodies&nbsp;for&nbsp;list&nbsp;'axis-dev'
<br>
</td>
</tr>
</table>
</form>
</p>
<div class="h5">
<h5>The Axis C++ User List</h5>
</div>
<p>
<b>Medium Traffic</b>
<a href="#mailto:axis-c-user-subscribe@ws.apache.org">Subscribe</a>
<a href="#mailto:axis-c-user-unsubscribe@ws.apache.org">Unsubscribe</a>
<a href="#mailto:axis-c-user-digest-subscribe@ws.apache.org">Subscribe(Digest)</a>
<a href="#mailto:axis-c-user-digest-unsubscribe@ws.apache.org">Unsubscribe(Digest)</a>
<a href="#mailto:axis-c-user@ws.apache.org">Send mail to list</a>
<br>
This list is for developers that are using Axis C++ in their own projects to
ask questions, share knowledge, and discuss issues related to using Axis C++.
<form action="http://marc.theaimsgroup.com/" method="get">
<input name="l" type="hidden" value="axis-c-user">
<input name="w" type="hidden" value="2">
<table class="ForrestTable" cellspacing="0" cellpadding="0" border="0">
<tr class="b">
<td align="left" colspan="1" rowspan="1"><input name="r" type="hidden" value="1">Search:&nbsp;<input maxlength="40" name="s" size="25" type="text" value=""><input type="submit" value="Search"><input type="reset" value="Reset">
<br>[<input name="q" type="radio" value="t">]&nbsp;Subjects&nbsp;[<input name="q" type="radio" value="a">]&nbsp;Authors&nbsp;[<input name="q" type="radio" value="b">]&nbsp;Bodies&nbsp;for&nbsp;list&nbsp;'axis-c-user'
<br>
</td>
</tr>
</table>
</form>
</p>
<div class="h5">
<h5>The Axis C++ Developer List</h5>
</div>
<p>
<b>Medium Traffic</b>
<a href="#mailto:axis-c-dev-subscribe@ws.apache.org">Subscribe</a>
<a href="#mailto:axis-c-dev-unsubscribe@ws.apache.org">Unsubscribe</a>
<a href="#mailto:axis-c-dev-digest-subscribe@ws.apache.org">Subscribe(Digest)</a>
<a href="#mailto:axis-c-dev-digest-unsubscribe@ws.apache.org">Unsubscribe(Digest)</a>
<a href="#mailto:axis-c-dev@ws.apache.org">Send mail to list</a>
<br>
This is the list where participating developers of the Axis C++ project meet
and discuss issues, code changes/additions, etc.
<form action="http://marc.theaimsgroup.com/" method="get">
<input name="l" type="hidden" value="axis-c-dev">
<input name="w" type="hidden" value="2">
<table class="ForrestTable" cellspacing="0" cellpadding="0" border="0">
<tr class="b">
<td align="left" colspan="1" rowspan="1"><input name="r" type="hidden" value="1">Search:&nbsp;<input maxlength="40" name="s" size="25" type="text" value=""><input type="submit" value="Search"><input type="reset" value="Reset">
<br>[<input name="q" type="radio" value="t">]&nbsp;Subjects&nbsp;[<input name="q" type="radio" value="a">]&nbsp;Authors&nbsp;[<input name="q" type="radio" value="b">]&nbsp;Bodies&nbsp;for&nbsp;list&nbsp;'axis-c-dev'
<br>
</td>
</tr>
</table>
</form>
</p>
<div class="h2">
<h2>WebServices - Axis</h2>
</div>
<div class="h5">
<h5>WebServices - Axis - Reference Library</h5>
</div>
<p>The Axis Project lives or fails based on its human resources. Users
and contributors alike help the project with ideas and brainpower. A common
foundation of knowledge is required to effectively participate in this
virtual community. The following is a list of documents that we have found
helpful for us and may be helpful to you:</p>
<p>These resources are required reading for anybody contributing source
code to the project.</p>
<p>
<b><font>SOAP Specific Resources</font></b>
</p>
<p>
<b><a href="http://www.w3.org/TR/SOAP/">SOAP W3C Specification</a></b>
<br>Required reading.</p>
<p>
<b><a href="http://www.w3.org/TR/SOAP-attachments">SOAP
Messaging with Attachments W3C Specification</a></b>
<br>SOAP combined with MIME.</p>
<p>
<b><a href="http://www.w3.org/TR/SOAP-dsig/">SOAP Security
Extensions: Digital Signature Specification</a></b>
<br>Adding security to SOAP.</p>
<p>
<b><font>Other Specifications</font></b><b><font><a href="http://www.w3c.org/TR/wsdl.html"></a></font></b>
</p>
<p>
<a href="http://www.w3c.org/TR/wsdl.html">Web Services Description Language
(WSDL) 1.1</a>
</p>
<p>
<a href="http://www.ws-i.org/Profiles/BasicProfile-1.0.html">WS-I Basic Profile Version 1.0</a>
</p>
<p>
<a href="http://jcp.org/aboutJava/communityprocess/first/jsr101/index.html">Java
API for XML-based RPC (JAX-RPC)</a>
</p>
<p>
<b><font>Other Resources</font></b>
</p>
<p>
<b><a href="http://java.sun.com/docs/books/jls/index.html">The
Java Language Specification</a></b>
<br>Written by the creators of the Java Programming Language, this online
book is considered by many to be the bible for programming in Java. A must
read.</p>
<p>
<b><a href="http://java.sun.com/products/jdk/javadoc/index.html">Javadoc</a></b>
<br>Javadoc is the automatic software documentation generator used by Java
since it was first released. All code written for this project must be
documented using Javadoc conventions.</p>
<p>
<b><a href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">The
Java Code Conventions</a></b>
<br>This Sun document specifies the de-facto standard way of formatting
Java code. All code written for this project must follow these conventions.</p>
<p>
<b><a href="http://cvsbook.red-bean.com/">Open Source Development
with CVS</a></b>
<br>Written by Karl Fogel, this is an online version of many of the primary
chapters from the dead-tree version of his book.</p>
<p>
<b><a href="http://www.cvshome.org/docs/blandy.html">Introduction
to CVS</a></b>
<br>Written by Jim Blandy, this brief introduction gives a first look into
CVS. If you have never used CVS before, you'll want to start here.</p>
<p>
<b><a href="http://www.cvshome.org/docs/manual/cvs.html">Version
Management with CVS</a></b>
<br>Written by Per Cederqvist et al, this is the main manual for CVS. It
provides details on all documented CVS features.
</p>
<div class="h2">
<h2>WebServices - Axis</h2>
</div>
<div class="h5">
<h5>WebServices - Axis - </h5>
</div>
<p>
New Axis bugs should be reported using
<a href="http://issues.apache.org/jira">JIRA</a> (the Apache bug database).
</p>
<ul>
<li>
Please report bugs against the newest release.
</li>
<li>
If you're not sure whether the behavior in question is a
bug or a feature, please post a message to the
<a href="#mailto:axis-dev@ws.apache.org">axis-dev</a>
mailing list for clarification.
</li>
<li>
To avoid duplicate bug reports, please query JIRA to
see whether the bug has already been reported (and perhaps
fixed).
</li>
<li>
If you can't find your bug in the database, it would help
if you could check out Axis from CVS, and build it locally
to verify that the bug still exists.
</li>
<li>
If you have found a new bug, please enter an Axis bug
report in JIRA. Remember to include the following
information:
<ul>
<li>
Version number of Axis
</li>
<li>
Version number of JDK (enter "java -fullversion")
</li>
<li>
Instructions for how to reproduce the problem, ideally
including a small testcase.
</li>
</ul>
<p>
<i>Before you can enter your first bug report, you must
submit your email address to JIRA and receive a
password.</i>
</p>
</li>
</ul>
<p>
Bugs related to WSDL4J should be addressed to the Expert Group for JSR110 at
<a href="http://groups.yahoo.com/group/jsr110-eg-disc">http://groups.yahoo.com/group/jsr110-eg-disc</a>.
</p>
<p>
For more information visit the following links:
</p>
<ul>
<li>
<a href="http://issues.apache.org/jira/">Apache
JIRA</a>
</li>
</ul>
<p>
We also encourage you to write patches for problems you find
and submit them to the
<a href="#mailto:axis-dev@ws.apache.org">axis-dev</a> mailing
list. If we agree the problem is a bug and the patch fixes it
and does not break something else, we are likely to include
the patch in the next release.
</p>
<div class="h2">
<h2>How To Build Axis Project's Website</h2>
</div>
<div class="h5">
<h5>Installing Forrest</h5>
</div>
<p>
The Axis website build system requires two components to perform a build.<br>
<a href="http://ant.apache.org/">Ant</a> and
<a href="http://forrest.apache.org/">Forrest</a>.
</p>
<p>
Specifically the build has been tested to work with Ant version
1.6.1 and Forrest 0.5.1. To install these products download
the distributions and follow the instructions in their
documentation. Make sure you don't forget to set the
environment variables FORREST_HOME and ANT_HOME. The
ANT_HOME/bin directory should be in the path.
</p>
<div class="h5">
<h5>Checking out ws-axis and ws-site module</h5>
</div>
<p>
Check out <b>'ws-axis/site/src'</b> and <b>'ws-site/target/axis'</b>
module via your favorite CVS tools.<br>
Please follow the guildeline written <a href="#site:cvs">here</a>.
</p>
<div class="h5">
<h5>Running the Build</h5>
</div>
<p>
Here's a list of targets for the ant task. But, what you need to do is just "ant".
</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<th colspan="1" rowspan="1">Target</th>
<th colspan="1" rowspan="1">Description</th>
</tr>
<tr class="a">
<td colspan="1" rowspan="1">clean</td>
<td colspan="1" rowspan="1">Erase all build work products (ie, everything in the
build directory</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1">run-forrest</td>
<td colspan="1" rowspan="1">Run Forrest with Jetty server
to review the target</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1">run-browser</td>
<td colspan="1" rowspan="1">Invoke a web browser (ie, Internet Explorer)</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1">backcopy</td>
<td colspan="1" rowspan="1">Reflect the updates on the build directory to
the master source on 'ws-axis/site/src'</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1">forrest</td>
<td colspan="1" rowspan="1">Create the updated static contents</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1">replace</td>
<td colspan="1" rowspan="1">Copy the contents to ws-site/targets/axis directory</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1">build-site (default)</td>
<td colspan="1" rowspan="1">Do clean up and all tasks to the build site</td>
</tr>
</table>
<div class="h5">
<h5>For Committers (Highly recommended)</h5>
</div>
<p>
The procedure to make changes to http://ws.apache.org/axis/ is:
</p>
<ul>
<li>*cd* into the local <b>'ws-axis/site'</b> CVS dir</li>
<li>execute <b>"ant"</b>
</li>
<li>make changes to <b>'build/webapp/content/xdocs'</b>
</li>
<li>
<b>reload and review the contents</b> with the autostarted browser</li>
<li>
<b>close the browser and the forrest window</b> when you are ready to
finish editing the site</li>
<li>cvs commit (ie, <b>'ws-axis/site/src'</b> and
<b>'ws-site/target/axis'</b>)</li>
</ul>
<div class="h5">
<h5>Manual update (If you want to realize the value of ant tasks above ...)</h5>
</div>
<p>
If you just want to update the site step-by-step, the followings
are the instructions.
</p>
<PRE>
1. Installing Forrest
[Note] At this time, the version 0.5.1 of Forrest is tested version.
2. Checking out 'ws-axis/site' module
[ex]
'ws-axis/site/src/documentation/content/xdocs/java/user-guide.ihtml'
3. Make changes to the target
4. Confirming the change with "forrest run"
4-1) cd into the local "ws-axis/site" CVS dir
4-2) execute "forrest run"
4-3) have an access to http://localhost:8888/ to see the site
5. Generating a static content with "forrest"
5-1) execute "forrest" in the "ws-axis/site" dir
5-2) check the generated contents in "ws-axis/site/build/site/"
6. Make commitments
6-1) commit the original source (xml/ihtml/gif/jpg) to "ws-axis"
6-2) copy the generated contents into "ws-site/targets/axis"
6-3) commit the generated contents to "ws-site"
7. (Optional) If you are in a hurry to reflect the change to the site,
cd to /www/ws.apache.org, and execute "cvs update -P" on minotaur.
[Note] *** VERY IMPORTANT ***
YOU HAVE TO CHECK YOUR UMASK IS "002" BEFORE DOING THE COMMAND,
OR THE SITE WILL BECOME A NON-UPDATABLE SITE FROM THEN ON.
The site will be updated automatically twice a day 12 midnight and
12 noon PST by a cron job of dims.
</PRE>
<div class="h5">
<h5>F.A.Q.</h5>
</div>
<p>
<em>Q1.</em>
<br>
I encountered<br>
The &lt;xmlcatalog&gt; data type doesn't support the nested "catalogpath" element.<br>
error, during the build.
</p>
<p>
<em>A1.</em>
<br>
Please make sure that your Ant version is later than 1.6 alpha. You can check the Ant version, by running "ant -version".
</p>
<p>
<em>Q2.</em>
<br>
I see an error like this regarding mirrors.pdf<br>
[java] X [0] mirrors.pdf BROKEN ....
</p>
<p>
<em>A2.</em>
<br>
This is a known issue, but does not affect the site itself.
</p>
<p>
<strong>( more to be come )</strong>
</p>
<div class="h4">
<h4>Axis (Java)</h4>
</div>
<div class="h2">
<h2>Axis Documentation</h2>
</div>
<div class="h5">
<h5>Documentation</h5>
</div>
<p>This is the documentation for <a href="http://ws.apache.org/axis/">Apache Axis 1.2</a> If the version of Axis you are using is older or newer than this version, then this is the wrong documentation to be using. Read the version that came with your copy of Axis.</p>
<div class="h5">
<h5>Documentation for Axis Users</h5>
</div>
<ul>
<li>
<a href="#install.html">Installation Instructions</a>
</li>
<li>
<a href="#user-guide.html">User's Guide</a>
</li>
<li>
<a href="#client-side-axis.html">Client-side Axis</a>
</li>
<li>
<a href="#security.html">Securing an Axis-based Web Service</a>
</li>
<li>
<a href="#ant/ant.html">Axis Ant Tasks</a>
</li>
<li>
<a href="#reference.html">Reference Material</a>
</li>
<li>
<a href="#reading.html">Further Reading</a>
</li>
</ul>
<div class="h5">
<h5>Documentation for Axis Developers</h5>
</div>
<ul>
<li>
<a href="#apiDocs/index.html">API Documentation</a>
</li>
<li>
<a href="#building-axis.html">Building Axis</a> - Guidelines for building Axis with/without optional components.</li>
<li>
<a href="#developers-guide.html">Developer's Guide</a> - Collection of guidelines for developing code in Axis.</li>
<li>
<a href="#integration-guide.html">Integration Guide</a> - Description of APIs and development direction to allow integration into an existing web application server.</li>
<li>
<a href="#architecture-guide.html">Architecture Guide</a> - Axis design concepts and rationale.</li>
</ul>
<div class="h2">
<h2>Axis installation instructions</h2>
</div>
<div class="h5">
<h5>Axis installation instructions</h5>
</div>
<p>
<strong>Contents</strong>
</p>
<ul>
<li>
<a href="##intro">Introduction</a>
</li>
<li>
<a href="##webapp">Creating Webapps</a>
</li>
<li>
<a href="##depend">Installing Dependencies</a>
</li>
<li>
<a href="##websvc">Installing Web Services</a>
</li>
<li>
<a href="##start">Starting the web server</a>
</li>
<li>
<a href="##install-test">Installation testing</a>
</li>
<li>
<a href="##deploy">Deploying web services</a>
</li>
<li>
<a href="##test">Testing</a>
</li>
<li>
<a href="##advanced">Advanced Installation</a>
</li>
<li>
<a href="##broken">What if it doesn't work?</a>
</li>
<li>
<a href="##summary">Summary</a>
</li>
<li>
<a href="##soapmon">Appendix: Enabling the SOAP Monitor</a>
</li>
</ul>
<p>
<a name="java/install.html#intro"></a>
</p>
<div class="h5">
<h5>Introduction</h5>
</div>
<p>This document describes how to install Apache Axis. It assumes you already know how to write and run Java code and are not afraid of XML. You should also have an application server or servlet engine and be familiar with operating and deploying to it. If you need an application server, we recommend <a href="http://jakarta.apache.org/tomcat/">Jakarta Tomcat</a>. [If you are installing Tomcat, get the latest 4.1.x version, and the full distribution, not the LE version for Java 1.4, as that omits the Xerces XML parser]. Other servlet engines are supported, provided they implement version 2.2 or greater of the servlet API. Note also that Axis client and server requires Java 1.3 or later.</p>
<p>For more details on using Axis, please see the <a href="#user-guide.html">user guide</a>.</p>
<div class="h5">
<h5>Things you have to know</h5>
</div>
<p>A lot of problems with Axis are encountered by people who are new to Java, server-side Java and SOAP. While you can learn about SOAP as you go along, writing Axis clients and servers is not the right time to be learning foundational Java concepts, such as what an array is, or basic application server concepts such as how servlets work, and the basics of the HTTP protocol.</p>
<p>Things you need to know before writing a Web Service:</p>
<ol>
<li>Core Java datatypes, classes and programming concepts.</li>
<li>What threads are, race conditions, thread safety and sychronization.</li>
<li>What a classloader is, what hierarchical classloaders are, and the common causes of a "ClassNotFoundException".</li>
<li>How to diagnose trouble from exception traces, what a NullPointerException (NPE) and other common exceptions are, and how to fix them.</li>
<li>What a web application is; what a servlet is, where classes, libraries and data go in a web application.</li>
<li>How to start your application server and deploy a web application on it.</li>
<li>What a network is, the core concepts of the IP protocol suite and the sockets API. Specifically, what is TCP/IP.</li>
<li>What HTTP is. The core protocol and error codes, HTTP headers and perhaps the details of basic authentication.</li>
<li>What XML is. Not necessarily how to parse it or anything, just what constitutes well-formed and valid XML.</li>
</ol>
<p>Axis and SOAP depends on all these details. If you don't know them, Axis (or anyone else's Web Service middleware) is a dangerous place to learn. Sooner or later you will be forced to discover these details, and there are easier places to learn than Axis.</p>
<p>If you are completely new to Java, we recommend you start off with things like the Java Tutorials on Sun's web site, and perhaps a classic book like <a href="http://www.mindview.net/Books/TIJ/">Thinking in Java</a>, until you have enough of a foundation to be able to work with Axis. It is also useful to have written a simple web application, as this will give you some knowledge of how HTTP works, and how Java application servers integrate with HTTP. You may find the course notes from <a href="http://www.cs.indiana.edu/classes/a348-dger/fall2002/notes/">Mastering the World Wide Web</a> useful in this regard, even though Axis is only introduced in lecture 28.</p>
<p>Be aware that there is a lot more needed to be learned in order to use Axis and SOAP effectively than the listing above. The other big area is "how to write internet scale distributed applications". Nobody knows how to do that properly yet, so that you have to learn this by doing.</p>
<div class="h5">
<h5>Step 0: Concepts</h5>
</div>
<p>Apache Axis is an Open Source SOAP server and client. SOAP is a mechanism for inter-application communication between systems written in arbitrary languages, across the Internet. SOAP usually exchanges messages over HTTP: the client POSTs a SOAP request, and receives either an HTTP success code and a SOAP response or an HTTP error code. Open Source means that you get the source, but that there is no formal support organisation to help you when things go wrong.</p>
<p>SOAP messages are XML messages. These messages exchange structured information between SOAP systems. Messages consist of one or more SOAP elements inside an envelope, Headers and the SOAP Body. SOAP has two syntaxes for describing the data in these elements, <em>Section 5</em>, which is a clear descendant of the XML RPC system, and <em>XML Schema</em>, which is the newer (and usually better) system. Axis handles the magic of converting Java objects to SOAP data when it sends it over the wire or receives results. SOAP Faults are sent by the server when something goes wrong; Axis converts these to Java exceptions.</p>
<p>SOAP is intended to link disparate systems. It is not a mechanism to tightly bind Java programs written by the same team together. It can bind Java programs together, but not as tightly as RMI or Corba. If you try sending many Java objects that RMI would happily serialize, you will be disappointed at how badly Axis fails. This is by design: if Axis copied RMI and serialized Java objects to byte streams, you would be stuck to a particular version of Java everywhere.</p>
<p>Axis implements the JAX-RPC API, one of the standard ways to program Java services. If you look at the specification and tutorials on Sun's web site, you will understand the API. If you code to the API, your programs will work with other implementations of the API, such as those by Sun and BEA. Axis also provides extension features that in many ways extends the JAX-RPC API. You can use these to write better programs, but these will only work with the Axis implementation. But since Axis is free and you get the source, that should not matter.</p>
<p>Axis is compiled in the JAR file <em>axis.jar</em>; it implements the JAX-RPC API declared in the JAR files <em>jaxrpc.jar</em> and <em>saaj.jar</em>. It needs various helper libraries, for logging, WSDL processing and introspection. All these files can be packaged into a web application, <em>axis.war</em>, that can be dropped into a servlet container. Axis ships with some sample SOAP services. You can add your own by adding new compiled classes to the Axis webapp and registering them.</p>
<p>Before you can do that, you have to install it and get it working.</p>
<p>
<a name="java/install.html#webapp"></a>
</p>
<div class="h5">
<h5>Step 1: Preparing the webapp</h5>
</div>
<p>Here we assume that you have a web server up and running on the localhost at port 8080. If your server is on a different port, replace references to 8080 to your own port number.</p>
<p>In your Application Server installation, you should find a directory into which web applications ("webapps") are to be placed. Into this directory copy the webapps/axis directory from the xml-axis distribution. You can actually name this directory anything you want, just be aware that the name you choose will form the basis for the URL by which clients will access your service. The rest of this document assumes that the default webapp name, "axis" has been used; rename these references if appropriate.</p>
<p>
<a name="java/install.html#depend"></a>
</p>
<div class="h5">
<h5>Step 2: Setting up the libraries</h5>
</div>
<p>In the Axis directory, you will find a WEB-INF sub-directory. This directory contains some basic configuration information, but can also be used to contain the dependencies and web services you wish to deploy.</p>
<p>Axis needs to be able to find an XML parser. If your application server or Java runtime does not make one visible to web applications, you need to download and add it. Java 1.4 includes the Crimson parser, so you <em>can</em> omit this stage, though the Axis team prefer Xerces.</p>
<p>To add an XML parser, acquire the JAXP 1.1 XML compliant parser of your choice. We recommend Xerces jars from the <a href="http://xml.apache.org/dist/xerces-j/">xml-xerces distribution</a>, though others mostly work. Unless your JRE or app server has its own specific requirements, you can add the parser's libraries to axis/WEB-INF/lib.&nbsp; The examples in this guide use Xerces.&nbsp; This guide adds xml-apis.jar and xercesImpl.jar to the AXISCLASSPATH so that Axis can find the parser (<a href="##Classpath_setup">see below</a>).</p>
<p>If you get ClassNotFound errors relating to Xerces or DOM then you do not have an XML parser installed, or your CLASSPATH (or AXISCLASSPATH) variables are not correctly configured.</p>
<div class="h5">
<h5>Tomcat 4.x and Java 1.4</h5>
</div>
<p>Java 1.4 changed the rules as to how packages beginning in java.* and javax.* get loaded. Specifically, they only get loaded from <em>endorsed</em> directories. jaxrpc.jar and saaj.jar contain javax packages, so they may not get picked up. If happyaxis.jsp (see below) cannot find the relevant packages, copy them from axis/WEB-INF/lib to CATALINA_HOME/common/lib and restart Tomcat.</p>
<div class="h5">
<h5>WebLogic 8.1</h5>
</div>
<p>WebLogic 8.1 ships with <span class="codefrag">webservices.jar</span> that conflicts with Axis' <span class="codefrag">saaj.jar</span> and prevents Axis 1.2 from working right out of the box. This conflict exists because WebLogic uses an older definition of <span class="codefrag">javax.xml.soap.*</span> package from <a href="http://java.sun.com/webservices/docs/1.0/api/javax/xml/soap">Java Web Services Developer Pack Version 1.0</a>, whereas Axis uses a newer revision from J2EE 1.4.</p>
<p>However, there are two alternative configuration changes that enable Axis based web services to run on Weblogic 8.1.</p>
<ul>
<li>In a webapp containing Axis, set &lt;prefer-web-inf-classes&gt; element in <span class="codefrag">WEB-INF/weblogic.xml</span> to true. An example of <span class="codefrag">weblogic.xml</span> is shown below: <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 <span class="codefrag">true</span>, the <span class="codefrag">&lt;prefer-web-inf-classes&gt;</span> 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>
</li>
<li>In a script used to start WebLogic server, modify <span class="codefrag">CLASSPATH</span> property by placing Axis's <span class="codefrag">saaj.jar</span> library in front of WeLlogic's <span class="codefrag">webservices.jar</span>. <p>
<strong>NOTE:</strong> This approach impacts all applications deployed on a particular WebLogic instance and may prevent them from using WebLogic's webservices.</p>
</li>
</ul>
<p>For more information on how WebLogic's class loader works, see <a href="http://e-docs.bea.com/wls/docs81/programming/classloading.html">WebLogic Server Application Classloading</a>.</p>
<p>
<a name="java/install.html#start"></a>
</p>
<div class="h5">
<h5>Step 3: starting the web server</h5>
</div>
<p>This varies on a product-by-product basis. In many cases it is as simple as double clicking on a startup icon or running a command from the command line.</p>
<p>
<a name="java/install.html#install-test"></a>
</p>
<div class="h5">
<h5>Step 4: Validate the Installation</h5>
</div>
<p>After installing the web application and dependencies, you should make sure that the server is running the web application.</p>
<div class="h5">
<h5>Look for the start page</h5>
</div>
<p>Navigate to the start page of the webapp, usually <a href="http://127.0.0.1:8080/axis/">http://127.0.0.1:8080/axis/</a>, though of course the port may differ.<br>
<br> You should now see an Apache-Axis start page. If you do not, then the webapp is not actually installed, or the appserver is not running.</p>
<div class="h5">
<h5>Validate Axis with happyaxis</h5>
</div>
<p>Follow the link <em>Validate the local installation's configuration</em>
<br> This will bring you to <em>happyaxis.jsp</em> a test page that verifies that needed and optional libraries are present. The URL for this will be something like <a href="http://localhost:8080/axis/happyaxis.jsp">http://localhost:8080/axis/happyaxis.jsp</a>
</p>
<p>If any of the needed libraries are missing, Axis will not work.<br>
<strong>You must not proceed until all needed libraries can be found, and this validation page is happy.</strong>
<br> Optional components are optional; install them as your need arises. If you see nothing but an internal server error and an exception trace, then you probably have multiple XML parsers on the CLASSPATH (or AXISCLASSPATH), and this is causing version confusion. Eliminate the extra parsers, restart the app server and try again.</p>
<div class="h5">
<h5>Look for some services</h5>
</div>
<p>From the start page, select <em>View the list of deployed Web services</em>. This will list all registered Web Services, unless the servlet is configured not to do so. On this page, you should be able to click on <em>(wsdl)</em> for each deployed Web service to make sure that your web service is up and running.</p>
<p>Note that the 'instant' JWS Web Services that Axis supports are not listed in this listing here.&nbsp; The install guide covers this topic in detail.</p>
<div class="h5">
<h5>Test a SOAP Endpoint</h5>
</div>
<p>Now it's time to test a service. Although SOAP 1.1 uses HTTP POST to submit an XML request to the <em>endpoint</em>, Axis also supports a crude HTTP GET access mechanism, which is useful for testing. First let's retrieve the version of Axis from the version endpoint, calling the <span class="codefrag">getVersion</span> method:<br>
<br>
<a href="http://localhost:8080/axis/services/Version?method=getVersion">http://localhost:8080/axis/services/Version?method=getVersion</a>
<br>
<br> This should return something like:</p>
<pre class="xml"> &lt;?xml version="1.0" encoding="UTF-8" ?&gt;<br> &lt;soapenv:Envelope<br> xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"<br> xmlns:xsd="http://www.w3.org/2001/XMLSchema"<br> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;<br> &lt;soapenv:Body&gt;<br> &lt;getVersionResponse<br> soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&gt;<br> &lt;getVersionReturn<br> xsi:type="xsd:string"&gt;<br> Apache Axis version: 1.1 Built on Apr 04, 2003 (01:30:37 PST)<br> &lt;/getVersionReturn&gt;<br> &lt;/getVersionResponse&gt;<br> &lt;/soapenv:Body&gt;<br> &lt;/soapenv:Envelope&gt;
</pre>
<p>The Axis version and build date may of course be different.</p>
<div class="h5">
<h5>Test a JWS Endpoint</h5>
</div>
<p>Now let's test a JWS web service. Axis' JWS Web Services are java files you save into the Axis webapp <em>anywhere but the WEB-INF tree</em>, giving them the .jws extension. When someone requests the .jws file by giving its URL, it is compiled and executed. The user guide covers JWS pages in detail.</p>
<p>To test the JWS service, we make a request against a built-in example, EchoHeaders.jws (look for this in the axis/ directory).</p>
<p>Point your browser at <a href="http://localhost:8080/axis/EchoHeaders.jws?method=list">http://localhost:8080/axis/EchoHeaders.jws?method=list</a>.</p>
<p>This should return an XML listing of your application headers, such as</p>
<pre class="xml">&lt;?xml version="1.0" encoding="UTF-8" ?&gt;<br>&lt;soapenv:Envelope<br> xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"<br> xmlns:xsd="http://www.w3.org/2001/XMLSchema"<br> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;<br> &lt;soapenv:Body&gt;<br> &lt;listResponse<br> soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&gt;<br> &lt;listReturn xsi:type="soapenc:Array"<br> soapenc:arrayType="xsd:string[6]"<br> xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"&gt;<br> &lt;item&gt;accept:image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*&lt;/item&gt;<br> &lt;item&gt;accept-language:en-us&lt;/item&gt;<br> &lt;item&gt;accept-encoding:gzip, deflate&lt;/item&gt;<br> &lt;item&gt;user-agent:Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)&lt;/item&gt;<br> &lt;item&gt;host:localhost:8080&lt;/item&gt;<br> &lt;item&gt;connection:Keep-Alive&lt;/item&gt;<br> &lt;/listReturn&gt;<br> &lt;/listResponse&gt;<br> &lt;/soapenv:Body&gt;<br>&lt;/soapenv:Envelope&gt;
</pre>
<br>
<p>Again, the exact return values will be different, and you may need to change URLs to correct any host, port and webapp specifics.</p>
<p>
<a name="java/install.html#websvc"></a>
</p>
<div class="h5">
<h5>Step 5: Installing new Web Services</h5>
</div>
<p>So far you have got Axis installed and working--now it is time to add your own Web Service.</p>
<p>The process here boils down to (1) get the classes and libraries of your new service into the Axis WAR directory tree, and (2) tell the AxisEngine about the new file. The latter is done by submitting an XML deployment descriptor to the service via the Admin web service, which is usually done with the AdminClient program or the &lt;axis-admin&gt; Ant task. Both of these do the same thing: they run the Axis SOAP client to talk to the Axis administration service, which is a SOAP service in its own right. It's also a special SOAP service in one regard--it is restricted to local callers only (not remote access) and is password protected to stop random people from administrating your service. There is a default password that the client knows; if you change it then you need to pass the new password to the client.</p>
<p>The first step is to add your code to the server.</p>
<p>In the WEB-INF directory, look for (or create) a "classes" directory (i.e. axis/WEB-INF/classes ). In this directory, copy the compiled Java classes you wish to install, being careful to preserve the directory structure of the Java packages.</p>
<p>If your classes services are already packaged into JAR files, feel free to drop them into the WEB-INF/lib directory instead. Also add any third party libraries you depend on into the same directory.</p>
<p>After adding new classes or libraries to the Axis webapp, you must restart the webapp. This can be done by restarting your application server, or by using a server-specific mechanism to restart a specific webapp.</p>
<p>Note: If your web service uses the simple authorization handlers provided with xml-axis (this is actually <u>not</u> recommended as these are merely illustrations of how to write a handler than intended for production use), then you will need to copy the corresponding users.lst file into the WEB-INF directory.</p>
<p>
<a name="java/install.html#deploy"></a>
</p>
<div class="h5">
<h5>Step 6: Deploying your Web Service</h5>
</div>
<p>The various classes and JARs you have just set up implement your new Web Service. What remains to be done is to tell Axis how to expose this web service. Axis takes a Web Service Deployment Descriptor (WSDD) file that describes in XML what the service is, what methods it exports and other aspects of the SOAP endpoint.</p>
<p>The users guide and reference guide cover these WSDD files; here we are going to use one from the Axis samples: the stock quote service.</p>
<p>
<a name="java/install.html#Classpath_setup"></a>
</p>
<div class="h5">
<h5>Classpath setup</h5>
</div>
<p>In order for these examples to work, java must be able to find axis.jar, commons-discovery.jar, commons-logging.jar, jaxrpc.jar, saaj.jar, log4j-1.2.8.jar (or whatever is appropriate for your chosen logging implementation), and the XML parser jar file or files (e.g., xerces.jar). These examples do this by adding these files to AXISCLASSPATH and then specifying the AXISCLASSPATH when you run them. Also for these examples, we have copied the xml-apis.jar and xercesImpl.jar files into the AXIS_LIB directory. An alternative would be to add your XML parser's jar file directly to the AXISCLASSPATH variable or to add all these files to your CLASSPATH variable.<br>
<br> On Windows, this can be done via the following. For this document we assume that you have installed Axis in C:\axis. To store this information permanently in WinNT/2000/XP you will need to right click on "My Computer" and select "Properties". Click the "Advanced" tab and create the new environmental variables. It is often better to use WordPad to create the variable string and then paste it into the appropriate text field.</p>
<pre class="xml"> set AXIS_HOME=c:\axis<br> set AXIS_LIB=%AXIS_HOME%\lib<br> set AXISCLASSPATH=%AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery.jar;<br> %AXIS_LIB%\commons-logging.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;<br> %AXIS_LIB%\log4j-1.2.8.jar;%AXIS_LIB%\xml-apis.jar;%AXIS_LIB%\xercesImpl.jar
</pre>
<p>Unix users have to do something similar. Below we have installed AXIS into /usr/axis and are using the bash shell. See your shell's documentation for differences. To make variables permeate you will need to add them to your shell's startup (dot) files. Again, see your shell's documentation.</p>
<pre class="xml"> set AXIS_HOME=/usr/axis<br> set AXIS_LIB=$AXIS_HOME/lib<br> set AXISCLASSPATH=$AXIS_LIB/axis.jar:$AXIS_LIB/commons-discovery.jar:<br> $AXIS_LIB/commons-logging.jar:$AXIS_LIB/jaxrpc.jar:$AXIS_LIB/saaj.jar:<br> $AXIS_LIB/log4j-1.2.8.jar:$AXIS_LIB/xml-apis.jar:$AXIS_LIB/xercesImpl.jar<br> export AXIS_HOME; export AXIS_LIB; export AXISCLASSPATH
</pre>
<p>To use Axis client code, you can select AXISCLASSPATH when invoking Java by entering</p>
<pre class="xml">java -cp %AXISCLASSPATH% ...
</pre>
<p>or</p>
<pre class="xml">java -cp "$AXISCLASSPATH" ...
</pre>
<p>depending on the platform. You may omit the quotes if your CLASSPATH doesn't have spaces in it.<br>
<br> Also, it is probably a good time to add the AXISCLASSPATH variable to your CLASSPATH variable. This will enable you to not include the AXISCLASSPATH variable when launching the examples in this guide. This document assumes that you have NOT done this.</p>
<div class="h5">
<h5>Find the deployment descriptor</h5>
</div>
<p>Look in axis/samples/stock for the file deploy.wsdd. This is the deployment descriptor we want to tell Axis about. Deployment descriptors are an Axis-specific XML file that tells Axis how to deploy (or undeploy) a Web Service, and how to configure Axis itself. The Axis Administration Web Service lets the AdminClient program and its Ant task counterpart submit a new WSDD file for interpretation. The Axis 'engine' will update its configuration, then save its state.</p>
<p>By default Axis saves it state into the global configuration file axis/WEB-INF/server-config.wsdd. Sometimes you see a warning message about such a file not being found--don't worry about this, because Axis auto-creates the file after you deploy something to it. You can check in the webapp to see what this file looks like--and even copy it to other systems if you want to give them identical configurations. Note that Axis needs an expanded web application <em>and</em> write access to the WEB-INF dir to save its state in this location.</p>
<div class="h5">
<h5>Run the admin client</h5>
</div>
<p>Execute the following command from the samples/stock directory. If you are not in this directory you will get a "java.io.FileNotFoundException: deploy.wsdd (The system cannot find the file specified)" exception.</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td><strong>On Windows</strong>
<br>
<pre>java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient
-lhttp://localhost:8080/axis/services/AdminService deploy.wsdd<br>
</pre>
<br>
<strong>On UNIX</strong>
<br>
<pre>java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient
-lhttp://localhost:8080/axis/services/AdminService deploy.wsdd</pre>
</td>
</tr>
</table>
<p>If you get some java client error (like ClassNotFoundException), then you haven't set up your AXISCLASSPATH (or CLASSPATH) variable right, mistyped the classname, or did some other standard error. Tracking down such problems are foundational Java development skills--if you don't know how to do these things, learn them now!</p>
<p>Note: You may need to replace localhost with your host name, and 8080 with the port number used by your web server. If you have renamed the web application to something other than "axis" change the URL appropriately.</p>
<p>If you get some AxisFault listing, then the client is working, but the deployment was unsuccessful. This is where the knowledge of the sockets API to TCP and the basics of the HTTP that Web Service development requires begins to be needed. If you got some socket error like connection refused, the computer at the far end isn't talking to you, so find the cause of that and fix it. If you get an HTTP error code back find out what the error means and correct the problem. These skills are fundamental to using web services.</p>
<p>The <a href="#user-guide.html">user's guide</a> covers the AdminClient in more detail, and there is also an <a href="#ant/axis-admin.html">Ant task</a> to automate the use of Axis in your Ant build scripts.</p>
<p>
<a name="java/install.html#test"></a>
</p>
<div class="h5">
<h5>Step 7: Testing</h5>
</div>
<p>This step is optional, but highly recommended. For illustrative purposes, it is presumed that you have installed and deployed the stock quote demo.</p>
<ul>
<li>Change directory to the distribution directory for xml-axis and execute the following command (or its Unix equivalent): <table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td><strong>On Windows</strong>
<br>
<pre>java -cp .;%AXISCLASSPATH% samples.stock.GetQuote
-lhttp://localhost:8080/axis/servlet/AxisServlet
-uuser1 -wpass1 XXX
</pre>
<strong>On UNIX</strong>
<br>
<pre>java -cp $AXISCLASSPATH samples.stock.GetQuote
-lhttp://localhost:8080/axis/servlet/AxisServlet
-uuser1 -wpass1 XXX
</pre>
</td>
</tr>
</table>
</li>
<li>You should get back "55.25" as a result.</li>
</ul>
<p>Note: Again, you may need to replace localhost with your host name, and 8080 with the port number used by your web server. If you have renamed the web application to something other than "axis" change the URL appropriately.</p>
<p>
<a name="java/install.html#advanced"></a>
</p>
<div class="h5">
<h5>Advanced Installation: adding Axis to your own Webapp</h5>
</div>
<p>If you are experienced in web application development, and especially if you wish to add web services to an existing or complex webapp, you can take an alternate approach to running Axis. Instead of adding your classes to the Axis webapp, you can add Axis to your application.</p>
<p>The core concepts are</p>
<ol>
<li>Add axis.jar, wsdl.jar, saaj.jar, jaxrpc.jar and the other dependent libraries to your WAR file.</li>
<li>Copy all the Axis Servlet declarations and mappings from axis/WEB-INF/web.xml and add them to your own web.xml</li>
<li>Build and deploy your webapp.</li>
<li>Run the Axis AdminClient against your own webapp, instead of Axis, by changing the URL you invoke it with.</li>
</ol>
<p>The process is also covered in Chapter 15 of <a href="http://manning.com/antbook">Java Development with Ant</a>, which can be downloaded as a <a href="http://www.manning.com/hatcher/chap15.pdf">PDF file</a>.</p>
<p>
<a name="java/install.html#broken"></a>
</p>
<div class="h5">
<h5>What if it doesn't work?</h5>
</div>
<p>Axis is a complicated system to install. This is because it depends on the underlying functionality of your app server, has a fairly complex configuration, and, like all distributed applications, depends upon the network too.</p>
<p>We see a lot of people posting their problems on the axis-user mailing list, and other Axis users as well as the Axis developers do their best to help when they can. But before you rush to post your own problems to the mailing list, a word of caution:</p>
<p>Axis is free. This means nobody gets paid to man the support lines. All the help you get from the community is voluntary and comes from the kindness of their hearts. They may be other users, willing to help you get past the same hurdles they had to be helped over, or they may be the developers themselves. But it is all voluntary, so you may need to keep your expectations low!</p>
<ol>
<li>Post to the <a href="#mailto:axis-user@ws.apache.org">user mail</a> list, not the developer list. You may think the developer mail list is a short cut to higher quality answers. But the developers are also on the user list along with many other skilled users--so more people will be able to answer your questions. Also, it is helpful for all user issues to be on one list to help build the searchable mailing list archive.</li>
<li>Don't ask non-Axis-related questions. The list is not the place to ask about non-Axis, non-SOAP, problems. Even questions about the MS Soap toolkit or .NET client side, don't get many positive answers--we avoid them. That also goes for the Sun Java Web Services Developer Pack, or the Jboss.net stuff that they've done with Axis.</li>
<li>Never bother posting to the soapbuilders mailing list either, that is only for people developing SOAP toolkits, not using them--all off-topic messages are pointedly ignored.</li>
<li>There is no guarantee that anyone will be able to solve your problem. The usual response in such a situation is silence, for a good reason: if everybody who didn't know the answer to a question said "I don't know", the list would be overflowed with noise. Don't take silence personally.</li>
<li>Never expect an immediate answer. Even if someone knows the answer, it can take a day or two before they read their mail. So if you don't get an answer in an hour or two, don't panic and resend. Be patient. And put the time to use by trying to solve your problems yourself.</li>
<li>Do your homework first. This document lists the foundational stuff you need to understand. It has also warned you that it can take a day to get a reply. Now imagine you get a HTTP Error '404' on a SOAP call. Should you rush to post a 'help' request, or should you try and find out what an HTTP error code is, what #404 usually means and how to use a Java debugger. We provide the source to make that debugging easier :)</li>
<li>Post meaningful subject lines. You want your message read, not deleted unread. A subject line of 'Axis problem', 'Help with Axis', etc. is not meaningful, and is not likely to get many readers.</li>
<li>Search the <a href="http://mail-archives.apache.org/eyebrowse/SummarizeList?listId=209">mailing list archives</a> FIRST to see if someone had the same problem. This list is searchable--and may save you much time in getting an answer to your problem.</li>
<li>Use the <a href="http://issues.apache.org/jira/">jira</a> database to search for Axis bugs, both open and closed.</li>
<li>Consult the <a href="http://wiki.apache.org/ws/FrontPage/Axis">Axis Wiki</a> for its Frequently Asked Questions (FAQ), installation notes, interoperability issues lists, and other useful information.</li>
<li>Don't email people for help directly, unless you know them. It's rude and presumptuous. Messages sent over the mail list benefit the whole community--both the original posters and people who search the list. Personal messages just take up the recipients time, and are unwelcome. Usually, if not ignored outright, recipients of personal requests will just respond 'ask the mail list' anyway!</li>
<li>Know that configuration problems are hard to replicate, and so can be difficult to get help on. We have tried with the happyaxis.jsp demo to automate the diagnostics gathering for you, but it can be hard for people to be of help here, especially for obscure platforms.</li>
<li>Keep up to date with Axis releases, even the beta copies of forthcoming releases. You wouldn't want your problem to be a bug that was already known and fixed in a more recent release. Often the common response to any question is 'have you tried the latest release'.</li>
<li>Study and use the source, and fix it when you find defects. Even fix the documentation when you find defects. It is only through the participation of Axis' users that it will ever get better.</li>
</ol>
<p>Has this put you off joining and participating in the Axis user mail list? We hope not--this list belongs to the people who use Axis and so will be your peers as your project proceeds. We just need for you to be aware that it is not a 24x7 support line for people new to server side Java development, and that you will need to be somewhat self sufficient in this regard. It is not a silver bullet. However, knowing how to make effective use of the list will help you develop better with Axis.</p>
<p>
<a name="java/install.html#summary"></a>
</p>
<div class="h5">
<h5>Summary</h5>
</div>
<p>Axis is simply an implementation of SOAP which can be added to your own webapp, and a webapp which can host your own web services. Installing it can be a bit fiddly, especially given Java 1.4's stricter requirements. If you follow a methodical process, including testing along the way, using happyaxis and the bundled test services, you will find it easier to get started with Axis.</p>
<p>
<a name="java/install.html#soapmon"></a>
</p>
<div class="h5">
<h5>Appendix: Enabling the SOAP Monitor</h5>
</div>
<p>SOAP Monitor allows for the monitoring of SOAP requests and responses via a web browser with Java plug-in 1.3 or higher. For a more comprehensive explanation of its usage, read <a href="#user-guide.html#soapmon">Using the SOAP Monitor</a> in the User's Guide.</p>
<p>By default, the SOAP Monitor is not enabled. The basic steps for enabling it are compiling the SOAP Monitor java applet, deploying the SOAP Monitor web service and adding request and response flow definitions for each monitored web service. In more detail:</p>
<ol>
<li>Go to $AXIS_HOME/webapps/axis (or %AXIS_HOME%\webapps\axis) and compile SOAPMonitorApplet.java.<br>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td><strong>On Windows</strong>
<br>
<span class="codefrag">javac -classpath %AXIS_HOME%\lib\axis.jar SOAPMonitorApplet.java</span>
<br>
<br>
<strong>On Unix</strong>
<br>
<span class="codefrag">javac -classpath $AXIS_HOME/lib/axis.jar SOAPMonitorApplet.java</span>
<br>
</td>
</tr>
</table>
<p>Copy all resulting class files (i.e. SOAPMonitorApplet*.class) to the root directory of the web application using the SOAP Monitor (e.g. .../tomcat/webapps/axis)</p>
</li>
<li>Deploy the SOAPMonitorService web service with the admin client and the deploy-monitor.wsdd file (shown below).<br>
<pre> Go to the directory deploy-monitor.wsdd is located and execute
the command below. The command assume that /axis is the intended
web application and it is available on port 8080.<br>
</pre>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td><strong>On Windows</strong>
<br>
<pre>
<span class="codefrag">java -cp %AXISCLASSPATH% org.apache.axis.client.AdminClient
-lhttp://localhost:8080/axis/services/AdminService deploy-monitor.wsdd</span>
</pre>
<br>
<strong>On UNIX</strong>
<br>
<pre>
<span class="codefrag">java -cp $AXISCLASSPATH org.apache.axis.client.AdminClient
-lhttp://localhost:8080/axis/services/AdminService deploy-monitor.wsdd</span>
</pre>
</td>
</tr>
</table>
<pre>
<strong>SOAPMonitorService Deployment Descriptor (deploy-monitor.wsdd)</strong>
</pre>
<pre class="xml">&lt;deployment xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"&gt;
&lt;handler name="soapmonitor"
type="java:org.apache.axis.handlers.SOAPMonitorHandler"&gt;
&lt;parameter name="wsdlURL"
value="/axis/SOAPMonitorService-impl.wsdl"/&gt;
&lt;parameter name="namespace"
value="http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl"/&gt;
&lt;parameter name="serviceName" value="SOAPMonitorService"/&gt;
&lt;parameter name="portName" value="Demo"/&gt;
&lt;/handler&gt;
&lt;service name="SOAPMonitorService" provider="java:RPC"&gt;
&lt;parameter name="allowedMethods" value="publishMessage"/&gt;
&lt;parameter name="className"
value="org.apache.axis.monitor.SOAPMonitorService"/&gt;
&lt;parameter name="scope" value="Application"/&gt;
&lt;/service&gt;
&lt;/deployment&gt;
</pre>
<pre>
</pre>
</li>
<li>For each service that is to be monitored, add request and response flow definitions to the service's deployment descriptor and deploy (or redeploy) the service. The <strong>requestFlow</strong>requestFlow and <strong>responseFlow</strong>responseFlow definitions follow the start tag of the <strong>&lt;service&gt;</strong>&lt;service&gt; element. If a service is already deployed, undeploy it and deploy it with the modified deployment descriptor. An example is shown below: <pre class="xml">...
&lt;service name="xmltoday-delayed-quotes" provider="java:RPC"&gt;
&lt;requestFlow&gt;
&lt;handler type="soapmonitor"/&gt;
&lt;/requestFlow&gt;
&lt;responseFlow&gt;
&lt;handler type="soapmonitor"/&gt;
&lt;/responseFlow&gt;
...</pre>
</li>
<li>With a web browser, go to http[s]://host[:port][/webapp]/SOAPMonitor (e.g. http://localhost:8080/axis/SOAPMonitor) substituting the correct values for your web application. This will show the SOAP Monitor applet for viewing service requests and responses. Any requests to services that have been configured and deployed correctly should show up in the applet.</li>
<li style="list-style: none">
<hr noshade="noshade" size="1">Copyright &copy; 2001-2003, Apache Software Foundation</li>
</ol>
<div class="h2">
<h2>Axis User's Guide</h2>
</div>
<div class="h5">
<h5>Axis User's Guide</h5>
</div>
<p>
<em>1.2 Version</em>
<br>
<em>Feedback: axis-dev@ws.apache.org</em>
</p>
<div class="h5">
<h5>Table of Contents</h5>
</div>
<ul>
<li>
<a href="##Introduction">Introduction</a>
</li>
<li>
<a href="##Installation">Installing Axis</a>
</li>
<li>
<a href="##ConsumingServices">Consuming Web Services with Axis</a>
</li>
<li>
<a href="##PublishingServices">Publishing Web Services with Axis</a>
</li>
<li>
<a href="##DataMapping">XML &lt;-&gt; Java Data Mapping in Axis</a>
</li>
<li>
<a href="##WSDL">Using WSDL with Axis</a>
</li>
<li style="list-style: none">
<ul>
<li>
<a href="##WSDLObtaining">?WSDL: Obtaining WSDL for deployed services</a>
</li>
<li>
<a href="##WSDL2Java">WSDL2Java: Building stubs, skeletons, and data</a>
</li>
<li>
<a href="##Java2WSDL">Java2WSDL: Building WSDL from Java</a>
</li>
</ul>
</li>
<li>
<a href="##publishedinterfaces">Published Interfaces</a>
</li>
<li>
<a href="##newbie">Newbie Tips: Finding Your Way Around</a>
</li>
<li>
<a href="##tcpmon">Appendix : Using TCPMon</a>
</li>
<li>
<a href="##soapmon">Appendix : Using SOAP Monitor</a>
</li>
<li>
<a href="##Glossary">Glossary</a>
</li>
</ul>
<p>
<a name="java/user-guide.html#Introduction"></a>
</p>
<div class="h5">
<h5>Introduction</h5>
</div>
<p>Welcome to Axis, the third generation of Apache SOAP!</p>
<div class="h5">
<h5>What is SOAP?</h5>
</div>
<p>SOAP is an XML<em>-</em>based communication protocol and encoding format for inter-application communication. Originally conceived by Microsoft and Userland software, it has evolved through several generations; the current spec is version, <a href="http://w3.org/TR/soap">SOAP 1.2</a>, though version 1.1 is more widespread. The W3C's <a href="http://www.w3.org/2000/xp/Group/">XML Protocol working group</a> is in charge of the specification.</p>
<p>SOAP is widely viewed as the backbone to a new generation of cross-platform cross-language distributed computing applications, termed Web Services.</p>
<div class="h5">
<h5>What is Axis?</h5>
</div>
<p>Axis is essentially a <em>SOAP engine</em> -- a framework for constructing SOAP processors such as clients, servers, gateways, etc. The current version of Axis is written in Java, but a C++ implementation of the client side of Axis is being developed.</p>
<p>But Axis isn't just a SOAP engine -- it also includes:</p>
<ul>
<li>a simple stand-alone server,</li>
<li>a server which plugs into servlet engines such as Tomcat,</li>
<li>extensive support for the <em>Web Service Description Language (WSDL)</em>,</li>
<li>emitter tooling that generates Java classes from WSDL.</li>
<li>some sample programs, and</li>
<li>a tool for monitoring TCP/IP packets.</li>
</ul>
<p>Axis is the third generation of Apache SOAP (which began at IBM as "SOAP4J"). In late 2000, the committers of Apache SOAP v2 began discussing how to make the engine much more flexible, configurable, and able to handle both SOAP and the upcoming XML Protocol specification from the W3C.</p>
<p>After a little while, it became clear that a ground-up rearchitecture was required. Several of the v2 committers proposed very similar designs, all based around configurable "chains" of message "handlers" which would implement small bits of functionality in a very flexible and composable manner.</p>
<p>After months of continued discussion and coding effort in this direction, Axis now delivers the following key features:</p>
<ul>
<li>
<strong>Speed.</strong> Axis uses SAX (event-based) parsing to acheive significantly greater speed than earlier versions of Apache SOAP.</li>
<li style="list-style: none">
<p></p>
</li>
<li>
<strong>Flexibility.</strong> The Axis architecture gives the developer complete freedom to insert extensions into the engine for custom header processing, system management, or anything else you can imagine.</li>
<li style="list-style: none">
<p>
<a name="java/user-guide.html#publishedinterfaces"></a>
</p>
</li>
<li>
<strong>Stability.</strong> Axis defines a set of <strong>published interfaces</strong> which change relatively slowly compared to the rest of Axis.</li>
<li style="list-style: none">
<p></p>
</li>
<li>
<strong>Component-oriented deployment.</strong> You can easily define reusable networks of Handlers to implement common patterns of processing for your applications, or to distribute to partners.</li>
<li style="list-style: none">
<p></p>
</li>
<li>
<strong>Transport framework.</strong> We have a clean and simple abstraction for designing transports (i.e., senders and listeners for SOAP over various protocols such as SMTP, FTP, message-oriented middleware, etc), and the core of the engine is completely transport-independent.</li>
<li style="list-style: none">
<p></p>
</li>
<li>
<strong>WSDL support.</strong> Axis supports the <a href="http://www.w3.org/TR/wsdl">Web Service Description Language</a>, version 1.1, which allows you to easily build stubs to access remote services, and also to automatically export machine-readable descriptions of your deployed services from Axis.</li>
</ul>
<p>We hope you enjoy using Axis. Please note that this is an open-source effort - if you feel the code could use some new features or fixes, please get involved and lend a hand! The Axis developer community welcomes your participation. And in case you're wondering what <em>Axis</em> stands for, it's <strong>A</strong>pache E<strong>X</strong>tensible <strong>I</strong>nteraction <strong>S</strong>ystem - a fancy way of implying it's a very configurable SOAP engine.</p>
<div class="h5">
<h5>Let us know what you think!</h5>
</div>
<p>Please send feedback about the package to "<a href="#mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a>". Also, Axis is registered in <a href="http://issues.apache.org/jira">jira</a>, the Apache bug tracking and feature-request database.</p>
<div class="h5">
<h5>What's in this release?</h5>
</div>
<p>This release includes the following features:</p>
<ul>
<li>SOAP 1.1/1.2 compliant engine</li>
<li>Flexible configuration / deployment system</li>
<li>Support for "drop-in" deployment of SOAP services (JWS)</li>
<li>Support for all basic types, and a type mapping system for defining new serializers/deserializers</li>
<li>Automatic serialization/deserialization of Java Beans, including customizable mapping of fields to XML elements/attributes</li>
<li>Automatic two-way conversions between Java Collections and SOAP Arrays</li>
<li>Providers for RPC and message based SOAP services</li>
<li>Automatic WSDL generation from deployed services</li>
<li>WSDL2Java tool for building Java proxies and skeletons from WSDL documents</li>
<li>Java2WSDL tool for building WSDL from Java classes.</li>
<li>Preliminary security extensions, which can integrate with Servlet 2.2 security/roles</li>
<li>Support for session-oriented services, via HTTP cookies or transport-independent SOAP headers</li>
<li>Preliminary support for the <strong>SOAP with Attachments</strong> specification</li>
<li>An EJB provider for accessing EJB's as Web Services</li>
<li>HTTP servlet-based transport</li>
<li>JMS based transport</li>
<li>Standalone version of the server (with HTTP support)</li>
<li>Examples, including a client and server for the SoapBuilders community interoperability tests and experimental TCP, JMS, and file-based transports.</li>
</ul>
<div class="h5">
<h5>What's still to do?</h5>
</div>
<p>Please click for <a href="#to-do.html">a list of what we think needs doing</a> - and please consider helping out if you're interested &amp; able!</p>
<p>
<a name="java/user-guide.html#Installation"></a>
</p>
<div class="h5">
<h5>Installing Axis and Using this Guide</h5>
</div>
<p>See the <a href="#install.html">Axis Installation Guide</a> for instructions on installing Axis as a web application on your J2EE server.</p>
<p>Before running the examples in this guide, you'll need to make sure that your CLASSPATH includes (Note: If you build Axis from a CVS checkout, these will be in xml-axis/java/build/lib instead of axis-1_2/lib):</p>
<ul>
<li>axis-1_2/lib/axis.jar</li>
<li>axis-1_2/lib/jaxrpc.jar</li>
<li>axis-1_2/lib/saaj.jar</li>
<li>axis-1_2/lib/commons-logging.jar</li>
<li>axis-1_2/lib/commons-discovery.jar</li>
<li>axis-1_2/lib/wsdl4j.jar</li>
<li>axis-1_2/ <em>(for the sample code)</em>
</li>
<li>A JAXP-1.1 compliant XML parser such as Xerces or Crimson. We recommend <a href="http://xml.apache.org/xerces2-j/">Xerces</a>, as it is the one that the product has been tested against.</li>
</ul>
<p>
<a name="java/user-guide.html#ConsumingServices"></a>
</p>
<div class="h5">
<h5>Consuming Web Services with Axis</h5>
</div>
<div class="h5">
<h5>Basics - Getting Started</h5>
</div>
<p>Let's take a look at an example Web Service client that will call the <strong>echoString</strong> method on the public Axis server at Apache.</p>
<pre class="example">1 import org.apache.axis.client.Call;
2 import org.apache.axis.client.Service;
3 import javax.xml.namespace.QName;
4
5 public class TestClient {
6 public static void main(String [] args) {
7 try {
8 String endpoint =
9 "http://ws.apache.org:5049/axis/services/echo";
10
11 Service service = new Service();
12 Call call = (Call) service.createCall();
13
14 call.setTargetEndpointAddress( new java.net.URL(endpoint) );
15 call.setOperationName(new QName("http://soapinterop.org/", echoString"));
16
17 String ret = (String) call.invoke( new Object[] { "Hello!" } );
18
19 System.out.println("Sent 'Hello!', got '" + ret + "'");
20 } catch (Exception e) {
21 System.err.println(e.toString());
22 }
23 }
24 }</pre>
<p>(You'll find this file in <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/ws-axis/java/samples/userguide/example1/TestClient.java">samples/userguide/example1/TestClient.java</a>)</p>
<p>Assuming you have a network connection active, this program can be run as follows:</p>
<pre class="example">% java samples.userguide.example1.TestClient
Sent 'Hello!', got 'Hello!'
%
</pre>
<p>So what's happening here? On lines 11 and 12 we create new Service and Call objects. These are the standard JAX-RPC objects that are used to store metadata about the service to invoke. On line 14, we set up our endpoint URL - this is the destination for our SOAP message. On line 15 we define the operation (method) name of the Web Service. And on line 17 we actually invoke the desired service, passing in an array of parameters - in this case just one String.</p>
<p>You can see what happens to the arguments by looking at the SOAP request that goes out on the wire (look at the colored sections, and notice they match the values in the call above):</p>
<pre class="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
&lt;SOAP-ENV:Body&gt;
&lt;ns1:<strong>echoString</strong> xmlns:ns1="<strong>http://soapinterop.org/</strong>"&gt;
&lt;arg0 xsi:type="xsd:string"&gt;<strong>Hello!</strong>&lt;/arg0&gt;
&lt;/ns1:echoString&gt;
&lt;/SOAP-ENV:Body&gt;
&lt;/SOAP-ENV:Envelope&gt;
</pre>
<p>The String argument is automatically serialized into XML, and the server responds with an identical String, which we deserialize and print.</p>
<p>
<em>Note: To actually watch the XML flowing back and forth between a SOAP client and server, you can use the included tcpmon tool or SOAP monitor tool. See the appendix for an overview.</em>
</p>
<div class="h5">
<h5>Naming Parameters</h5>
</div>
<p>In the above example, you can see that Axis automatically names the XML-encoded arguments in the SOAP message "arg0", "arg1", etc. (In this case there's just "arg0") If you want to change this, it's easy! Before calling <tt>invoke()</tt> you need to call <tt>addParameter</tt> for each parameter and <tt>setReturnType</tt> for the return, like so:</p>
<pre class="example"> call.addParameter("testParam",
org.apache.axis.Constants.XSD_STRING,
javax.xml.rpc.ParameterMode.IN);
call.setReturnType(org.apache.axis.Constants.XSD_STRING);
</pre>
<p>This will assign the name <strong>testParam</strong> to the 1st (and only) parameter on the invoke call. This will also define the type of the parameter (<tt>org.apache.axis.Constants.XSD_STRING</tt>) and whether it is an input, output or inout parameter - in this case its an input parameter. Now when you run the program you'll get a message that looks like this:</p>
<pre class="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
&lt;SOAP-ENV:Body&gt;
&lt;ns1:echoString xmlns:ns1="http://soapinterop.org/"&gt;
&lt;testParam xsi:type="xsd:string"&gt;Hello!&lt;/testParam&gt;
&lt;/ns1:echoString&gt;
&lt;/SOAP-ENV:Body&gt;
&lt;/SOAP-ENV:Envelope&gt;
</pre>
<p>Note that the param is now named "testParam" as expected.</p>
<div class="h5">
<h5>Interoperating with "untyped" servers</h5>
</div>
<p>In the above examples, we've been casting the return type of invoke(), which is Object, to the appropriate "real" type - for instance, we know that the echoString method returns a String, so we expect to get one back from client.invoke(). Let's take a moment and investigate how this happens, which sheds light on a potential problem (to which, of course, we have a solution - so don't fret :)).</p>
<p>Here's what a typical response might look like to the echoString method:</p>
<pre class="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;<br> &lt;SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
&lt;SOAP-ENV:Body&gt;
&lt;ns1:echoStringResponse xmlns:ns1="http://soapinterop.org/"&gt;
&lt;result xsi:type="xsd:string"&gt;Hello!&lt;/result&gt;
&lt;/ns1:echoStringResponse&gt;
&lt;/SOAP-ENV:Body&gt;
&lt;/SOAP-ENV:Envelope&gt;
</pre>
<p>Take a look at the section which we've highlighted in red - that attribute is a schema <strong>type declaration</strong>, which Axis uses to figure out that the contents of that element are, in this case, deserializable into a Java String object. Many toolkits put this kind of explicit typing information in the XML to make the message "self-describing". On the other hand, some toolkits return responses that look like this:</p>
<pre class="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
&lt;SOAP-ENV:Body&gt;
&lt;ns1:echoStringResponse xmlns:ns1="http://soapinterop.org/"&gt;
&lt;result&gt;Hello, I'm a string!&lt;/result&gt;
&lt;/ns1:echoStringResponse&gt;
&lt;/SOAP-ENV:Body&gt;
&lt;/SOAP-ENV:Envelope&gt;
</pre>
<p>There's no type in the message, so how do we know what Java object we should deserialize the &lt;result&gt; element into? The answer is <strong>metadata</strong> - data about data. In this case, we need a <strong>description</strong> of the service that tells us what to expect as the return type. Here's how to do it on the client side in Axis:</p>
<pre class="example"> call.setReturnType( org.apache.axis.Constants.XSD_STRING );
</pre>
<p>This method will tell the Axis client that if the return element is not typed then it should act as if the return value has an xsi:type attribute set to the predefined SOAP String type. (You can see an example of this in action in the interop echo-test client - samples/echo/TestClient.java.)</p>
<p>There is also a similar method which allows you to specify the Java class of the expected return type:</p>
<pre class="example">call.setReturnClass(String.class);
</pre>
<p>OK - so now you know the basics of accessing SOAP services as a client. But how do you publish your own services?</p>
<p>
<a name="java/user-guide.html#PublishingServices"></a>
</p>
<div class="h5">
<h5>Publishing Web Services with Axis</h5>
</div>
<p>Let's say we have a simple class like the following:</p>
<pre class="example">public class Calculator {
public int add(int i1, int i2)
{
return i1 + i2;
}
public int subtract(int i1, int i2)
{
return i1 - i2;
}
}
</pre>
<p>(You'll find this very class in <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/ws-axis/java/samples/userguide/example2/Calculator.java">samples/userguide/example2/Calculator.java</a>.)</p>
<p>How do we go about making this class available via SOAP? There are a couple of answers to that question, but we'll start with the easiest way Axis provides to do this, which takes almost no effort at all!</p>
<div class="h5">
<h5>JWS (Java Web Service) Files - Instant Deployment</h5>
</div>
<p>OK, here's step 1 : copy the above .java file into your webapp directory, and rename it "Calculator.jws". So you might do something like this:</p>
<pre>% copy Calculator.java <em>&lt;your-webapp-root&gt;</em>/axis/Calculator.jws
</pre>
<p>Now for step 2... hm, wait a minute. You're done! You should now be able to access the service at the following URL (assuming your Axis web application is on port 8080):</p>
<p>
<a href="http://localhost:8080/axis/Calculator.jws">http://localhost:8080/axis/Calculator.jws</a>
</p>
<p>Axis automatically locates the file, compiles the class, and converts SOAP calls correctly into Java invocations of your service class. Try it out - there's a calculator client in samples/userguide/example2/CalcClient.java, which you can use like this:</p>
<pre class="example">% java samples.userguide.example2.CalcClient -p8080 add 2 5
Got result : 7
% java samples.userguide.example2.CalcClient -p8080 subtract 10 9
Got result : 1
%
</pre>
<p>(Note that you may need to replace the "-p8080" with whatever port your J2EE server is running on)</p>
<p>
<em>Important:</em> JWS web services are intended for simple web services. You cannot use packages in the pages, and as the code is compiled at run time you can not find out about errors until after deployment. Production quality web services should use Java classes with custom deployment.</p>
<div class="h5">
<h5>Custom Deployment - Introducing WSDD</h5>
</div>
<p>JWS files are great quick ways to get your classes out there as Web Services, but they're not always the best choice. For one thing, you need the source code - there might be times when you want to expose a pre-existing class on your system without source. Also, the amount of configuration you can do as to how the service gets accessed is pretty limited - you can't specify custom type mappings, or control which Handlers get invoked when people are using your service. <em>(Note for the future : the Axis team, and the Java SOAP community at large, are thinking about ways to be able to embed this sort of metadata into your source files if desired - stay tuned!)</em>
</p>
<p>
<a name="java/user-guide.html#descriptors"></a>
</p>
<div class="h5">
<h5>Deploying via descriptors</h5>
</div>
<p>To really use the flexibility available to you in Axis, you should get familiar with the Axis <strong>Web Service Deployment Descriptor (WSDD)</strong> format. A deployment descriptor contains a bunch of things you want to "deploy" into Axis - i.e. make available to the Axis engine. The most common thing to deploy is a Web Service, so let's start by taking a look at a deployment descriptor for a basic service (this file is <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/ws-axis/java/samples/userguide/example3/deploy.wsdd">samples/userguide/example3/deploy.wsdd</a>):</p>
<pre class="example">&lt;deployment xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"&gt;
&lt;service name="MyService" provider="java:RPC"&gt;
&lt;parameter name="className" value="samples.userguide.example3.MyService"/&gt;
&lt;parameter name="allowedMethods" value="*"/&gt;
&lt;/service&gt;
&lt;/deployment&gt;
</pre>
<p>Pretty simple, really - the outermost element tells the engine that this is a WSDD deployment, and defines the "java" namespace. Then the service element actually defines the service for us. A service is a <strong>targeted chain</strong> (see the <a href="#architecture-guide.html">Architecture Guide</a>), which means it may have any/all of: a request flow, a pivot Handler (which for a service is called a "provider"), and a response flow. In this case, our provider is "java:RPC", which is built into Axis, and indicates a Java RPC service. The actual class which handles this is <strong>org.apache.axis.providers.java.RPCProvider</strong>. We'll go into more detail later on the different styles of services and their providers.</p>
<p>We need to tell the RPCProvider that it should instantiate and call the correct class (e.g. samples.userguide.example3.MyService), and we do so by including &lt;parameter&gt; tags, giving the service one parameter to configure the class name, and another to tell the engine that any public method on that class may be called via SOAP (that's what the "*" means; we could also have restricted the SOAP-accessible methods by using a space or comma separated list of available method names).</p>
<div class="h5">
<h5>Advanced WSDD - specifying more options</h5>
</div>
<p>WSDD descriptors can also contain other information about services, and also other pieces of Axis called "Handlers" which we'll cover in a later section.</p>
<div class="h5">
<h5>Scoped Services</h5>
</div>
<p>Axis supports scoping service objects (the actual Java objects which implement your methods) three ways. "Request" scope, the default, will create a new object each time a SOAP request comes in for your service. "Application" scope will create a singleton shared object to service <strong>all</strong> requests. "Session" scope will create a new object for each session-enabled client who accesses your service. To specify the scope option, you add a &lt;parameter&gt; to your service like this (where "<em>value</em>" is request, session, or application):</p>
<pre class="xml">&lt;service name="MyService"...&gt;
&lt;parameter name="scope" value="<em>value</em>"/&gt;
...
&lt;/service&gt;
</pre>
<div class="h5">
<h5>Using the AdminClient</h5>
</div>
<p>Once we have this file, we need to send it to an Axis server in order to actually deploy the described service. We do this with the AdminClient, or the "org.apache.axis.client.AdminClient" class. If you have deployed Axis on a server other than Tomcat, you may need to use the -p <em>&lt;port&gt;</em> argument. The default port is 8080. A typical invocation of the AdminClient looks like this:</p>
<pre class="example">% java org.apache.axis.client.AdminClient deploy.wsdd
&lt;Admin&gt;Done processing&lt;/Admin&gt;
</pre>
<p>This command has now made our service accessible via SOAP. Check it out by running the Client class - it should look like this:</p>
<pre class="example">% java samples.userguide.example3.Client
-lhttp://localhost:8080/axis/services/MyService "test me!"
You typed : test me!
%
</pre>
<p>If you want to prove to yourself that the deployment really worked, try undeploying the service and calling it again. There's an "undeploy.wsdd" file in the example3/ directory which you can use just as you did the deploy.wsdd file above. Run the AdminClient on that file, then try the service Client again and see what happens.</p>
<p>You can also use the AdminClient to get a listing of all the deployed components in the server:</p>
<pre class="example">% java org.apache.axis.client.AdminClient list
&lt;big XML document returned here&gt;
</pre>
<p>In there you'll see services, handlers, transports, etc. Note that this listing is an exact copy of the server's "server-config.wsdd" file, which we'll talk about in more detail a little later.</p>
<div class="h5">
<h5>More deployment - Handlers and Chains</h5>
</div>
<p>Now let's start to explore some of the more powerful features of the Axis engine. Let's say you want to track how many times your service has been called. We've included a sample handler in the samples/log directory to do just this. To use a handler class like this, you first need to deploy the Handler itself, and then use the name that you give it in deploying a service. Here's a sample deploy.wsdd file (this is example 4 in samples/userguide):</p>
<pre class="example">&lt;deployment xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"&gt;
&lt;!-- define the logging handler configuration --&gt;
&lt;handler name="track" type="java:samples.userguide.example4.LogHandler"&gt;
&lt;parameter name="filename" value="MyService.log"/&gt;
&lt;/handler&gt;
&lt;!-- define the service, using the log handler we just defined --&gt;
&lt;service name="LogTestService" <strong></strong>provider="java:RPC"&gt;
&lt;requestFlow&gt;
&lt;handler type="track"/&gt;
&lt;/requestFlow&gt;
&lt;parameter name="className" value="samples.userguide.example4.Service"/&gt;
&lt;parameter name="allowedMethods" value="*"/&gt;
&lt;/service&gt;
&lt;/deployment&gt;
</pre>
<p>The first section defines a Handler called "track" that is implemented by the class samples.userguide.example4.LogHandler. We give this Handler an option to let it know which file to write its messages into.</p>
<p>Then we define a service, LogTestService, which is an RPC service just like we saw above in our first example. The difference is the &lt;requestFlow&gt; element inside the &lt;service&gt; - this indicates a set of Handlers that should be invoked when the service is invoked, before the provider. By inserting a reference to "track", we ensure that the message will be logged each time this service is invoked.</p>
<div class="h5">
<h5>Remote Administration</h5>
</div>
<p>Note that by default, the Axis server is configured to only accept administration requests from the machine on which it resides - if you wish to enable remote administration, you must set the "enableRemoteAdmin" property of the AdminService to <strong>true</strong>. To do this, find the "server-config.wsdd" file in your webapp's WEB-INF directory. In it, you'll see a deployment for the AdminService. Add an option as follows:</p>
<pre class="xml">&lt;service name="AdminService" provider="java:MSG"&gt;
&lt;parameter name="className" value="org.apache.axis.util.Admin"/&gt;
&lt;parameter name="allowedMethods" value="*"/&gt;
<strong>&lt;parameter name="enableRemoteAdmin" value="true"/&gt;
</strong>&lt;/service&gt;
</pre>
<p>
<strong>WARNING: enabling remote administration may give unauthorized parties access to your machine. If you do this, please make sure to add security to your configuration!</strong>
</p>
<div class="h5">
<h5>Service Styles - RPC, Document, Wrapped, and Message</h5>
</div>
<p>There are four "styles" of service in Axis. <strong>RPC</strong> services use the SOAP RPC conventions, and also the SOAP "section 5" encoding. <strong>Document</strong> services do not use any encoding (so in particular, you won't see multiref object serialization or SOAP-style arrays on the wire) but DO still do XML&lt;-&gt;Java databinding. <strong>Wrapped</strong> services are just like document services, except that rather than binding the entire SOAP body into one big structure, they "unwrap" it into individual parameters. <strong>Message</strong> services receive and return arbitrary XML in the SOAP Envelope without any type mapping / data binding. If you want to work with the raw XML of the incoming and outgoing SOAP Envelopes, write a message service.</p>
<div class="h5">
<h5>RPC services</h5>
</div>
<p>RPC services are the default in Axis. They are what you get when you deploy services with &lt;service ... provider="java:RPC"&gt; or &lt;service ... style="RPC"&gt;. RPC services follow the SOAP RPC and encoding rules, which means that the XML for an RPC service will look like the "echoString" example above - each RPC invocation is modeled as an outer element which matches the operation name, containing inner elements each of which maps to a parameter of the operation. Axis will deserialize XML into Java objects which can be fed to your service, and will serialize the returned Java object(s) from your service back into XML. Since RPC services default to the soap section 5 encoding rules, objects will be encoded via "multi-ref" serialization, which allows object graphs to be encoded. (See the SOAP spec for more on multi-ref serialization.)</p>
<div class="h5">
<h5>Document / Wrapped services</h5>
</div>
<p>Document services and wrapped services are similar in that neither uses the SOAP encoding for data; it's just plain old XML schema. In both cases, however, Axis still "binds" Java representations to the XML (see the <a href="##DataMapping">databinding</a> section for more), so you end up dealing with Java objects, not directly with XML constructs.</p>
<p>A good place to start in describing the difference between document and wrapped services is with a sample SOAP message containing a purchase order:</p>
<pre class="xml">&lt;soap:Envelope xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"&gt;
&lt;soap:Body&gt;
&lt;myNS:PurchaseOrder xmlns:myNS="http://commerce.com/PO"&gt;
&lt;item&gt;SK001&lt;/item&gt;
&lt;quantity&gt;1&lt;/quantity&gt;
&lt;description&gt;Sushi Knife&lt;/description&gt;
&lt;/myNS:PurchaseOrder&gt;
&lt;/soap:Body&gt;
&lt;/soap:Envelope&gt;
</pre>
<p>The relevant schema for the PurchaseOrder looks like this:</p>
<pre class="xml">&lt;schema targetNamespace="http://commerce.com/PO"&gt;
&lt;complexType name="POType"&gt;
&lt;sequence&gt;
&lt;element name="item" type="xsd:string"/&gt;
&lt;element name="quantity" type="xsd:int"/&gt;
&lt;element name="description" type="xsd:string"/&gt;
&lt;/sequence&gt;
&lt;/complexType&gt;
&lt;element name="PurchaseOrder" type="POType"/&gt;
&lt;/schema&gt;
</pre>
<p>For a <strong>document</strong> style service, this would map to a method like this:</p>
<p>public void method(PurchaseOrder po)</p>
<p>In other words, the ENTIRE &lt;PurchaseOrder&gt; element would be handed to your method as a single bean with three fields inside it. On the other hand, for a <strong>wrapped</strong> style service, it would map to a method like this:</p>
<p>public void purchaseOrder(String item, int quantity, String description)</p>
<p>Note that in the "wrapped" case, the &lt;PurchaseOrder&gt; element is a "wrapper" (hence the name) which only serves to indicate the correct operation. The arguments to our method are what we find when we "unwrap" the outer element and take each of the inner ones as a parameter.</p>
<p>The document or wrapped style is indicated in WSDD as follows:</p>
<p>&lt;service ... style="document"&gt;&lt;service ... style="document"&gt; for document style<br> &lt;service ... style="wrapped"&gt;&lt;service ... style="wrapped"&gt; for wrapped style</p>
<p>In most cases you won't need to worry about document or wrapped services if you are starting from a WSDL document (<a href="##WSDL">see below</a>).</p>
<div class="h5">
<h5>Message services</h5>
</div>
<p>Finally, we arrive at "Message" style services, which should be used when you want Axis to step back and let your code at the actual XML instead of turning it into Java objects. There are four valid signatures for your message-style service methods:</p>
<p>
<span class="codefrag">public Element [] method(Element [] bodies);</span><span class="codefrag"> public SOAPBodyElement [] method (SOAPBodyElement [] bodies);</span><span class="codefrag"> public Document method(Document body); public void method(SOAPEnvelope req, SOAPEnvelope resp);</span>
</p>
<p>The first two will pass your method arrays of either DOM Elements or SOAPBodyElements - the arrays will contain one element for each XML element inside the &lt;soap:body&gt; in the envelope.</p>
<p>The third signature will pass you a DOM Document representing the &lt;soap:body&gt;, and expects the same in return.</p>
<p>The fourth signature passes you two SOAPEnvelope objects representing the request and response messages. This is the signature to use if you need to look at or modify headers in your service method. Whatever you put into the response envelope will automatically be sent back to the caller when you return. Note that the response envelope may already contain headers which have been inserted by other Handlers.</p>
<p>
<strong>Message Example</strong>
</p>
<p>A sample message service can be found in <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/ws-axis/java/samples/message/MessageService.java">samples/message/MessageService.java</a>. The service class, <span class="codefrag">MessageService</span>, has one public method, <span class="codefrag">echoElements</span>, which matches the first of the three method signatures above:</p>
<pre class="example">public Element[] echoElements(Element [] elems)
</pre>
<p>The <span class="codefrag">MsgProvider</span> handler calls the method with an array of <span class="codefrag">org.w3c.dom.Element</span> objects that correspond to the immediate children of the incoming message's SOAP Body. Often, this array will contain a single Element (perhaps the root element of some XML document conforming to some agreed-upon schema), but the SOAP Body can handle any number of children. The method returns an <span class="codefrag">Element[]</span> array to be returned in the SOAP body of the response message.</p>
<p>Message services must be deployed with a WSDD file. Here is the full WSDD for the <span class="codefrag">MessageService</span> class:</p>
<pre class="XML">&lt;deployment name="test" xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"&gt;
&lt;service name="MessageService" style="message"&gt;
&lt;parameter name="className" value="samples.message.MessageService"/&gt;
&lt;parameter name="allowedMethods" value="echoElements"/&gt;
&lt;/service&gt;<br>&lt;/deployment&gt;
</pre>
<p>Note that the "style" attribute is different from the RPC deployment example. The "message" style tells Axis that this service is to be handled by <span class="codefrag">org.apache.axis.providers.java.MsgProvider</span> rather than <span class="codefrag">org.apache.axis.providers.java.RPCProvider</span>.</p>
<p>You can test this service by deploying it, then running samples.message.TestMsg (look at the source to see what the test driver does).</p>
<p>
<a name="java/user-guide.html#DataMapping"></a>
</p>
<div class="h5">
<h5>XML &lt;-&gt; Java Data Mapping in Axis</h5>
</div>
<div class="h5">
<h5>How your Java types map to SOAP/XML types</h5>
</div>
<p>Interoperability, <em>interop</em>, is an ongoing challenge between SOAP implementations. If you want your service to work with other platforms and implementations, you do need to understand the issues. There are some <a href="#reading.html#interop">external articles</a> on the subject that act as a good starting place. The basic mapping between Java types and WSDL/XSD/SOAP in Axis is determined by the JAX-RPC specification. Read chapters 4 and 5 of the <a href="http://java.sun.com/xml/jaxrpc/">specification</a> to fully understand how things are converted. Here are some of the salient points.</p>
<div class="h5">
<h5>Standard mappings from WSDL to Java</h5>
</div>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td>xsd:base64Binary</td><td><tt>byte[]</tt></td>
</tr>
<tr class="a">
<td>xsd:boolean</td><td><tt>boolean</tt></td>
</tr>
<tr class="b">
<td>xsd:byte</td><td><tt>byte</tt></td>
</tr>
<tr class="a">
<td>xsd:dateTime</td><td><tt>java.util.Calendar</tt></td>
</tr>
<tr class="b">
<td>xsd:decimal</td><td><tt>java.math.BigDecimal</tt></td>
</tr>
<tr class="a">
<td>xsd:double</td><td><tt>double</tt></td>
</tr>
<tr class="b">
<td>xsd:float</td><td><tt>float</tt></td>
</tr>
<tr class="a">
<td>xsd:hexBinary</td><td><tt>byte[]</tt></td>
</tr>
<tr class="b">
<td>xsd:int</td><td><tt>int</tt></td>
</tr>
<tr class="a">
<td>xsd:integer</td><td><tt>java.math.BigInteger</tt></td>
</tr>
<tr class="b">
<td>xsd:long</td><td><tt>long</tt></td>
</tr>
<tr class="a">
<td>xsd:QName</td><td><tt>javax.xml.namespace.QName</tt></td>
</tr>
<tr class="b">
<td>xsd:short</td><td><tt>short</tt></td>
</tr>
<tr class="a">
<td>xsd:string</td><td><tt>java.lang.String</tt></td>
</tr>
</table>
<p>If the WSDL says that an object can be <tt>nillable</tt>, that is the caller may choose to return a value of <tt>nil</tt>, then the primitive data types are replaced by their wrapper classes, such as Byte, Double, Boolean, etc.</p>
<div class="h5">
<h5>SOAP Encoding Datatypes</h5>
</div>
<p>Alongside the XSD datatypes are the SOAP 'Section 5' datatypes that are all nillable, and so only ever map to the wrapper classes. These types exist because they all support the "ID" and "HREF" attributes, and so will be used when in an RPC-encoded context to support multi-ref serialization.</p>
<div class="h5">
<h5>Exceptions</h5>
</div>
<p>This is an area which causes plenty of confusion, and indeed, the author of this section is not entirely sure how everything works, especially from an interop perspective. This means treat this section as incomplete and potentially inaccurate. See also section 5.5.5 and chapter 14 in the JAX-RPC specification</p>
<div class="h5">
<h5>RemoteExceptions map to SOAP Faults</h5>
</div>
<p>If the server method throws a <tt>java.rmi.RemoteException</tt> then this will be mapped into a SOAP Fault. The <tt>faultcode</tt> of this will contain the classname of the fault. The recipient is expected to deserialize the body of the fault against the classname.</p>
<p>Obviously, if the recipient does not know how to create an instance of the received fault, this mechanism does not work. Unless you include information about the exception class in the WSDL description of the service, or sender and receiver share the implementation, you can only reliably throw <tt>java.rmi.RemoteException</tt> instances, rather than subclasses.</p>
<p>When an implementation in another language receives such an exception, it should see the name of the class as the faultCode, but still be left to parse the body of the exception. You need to experiment to find out what happens there.</p>
<div class="h5">
<h5>Exceptions are represented as wsdl:fault elements</h5>
</div>
<p>If a method is marked as throwing an <tt>Exception</tt> that is not an instance or a subclass of <tt>java.rmi.RemoteException</tt>, then things are subtly different. The exception is no longer a SOAP Fault, but described as a <tt>wsdl:fault</tt> in the WSDL of the method. According to the JAX-RPC specification, your subclass of Exception must have accessor methods to access all the fields in the object to be marshalled <em>and</em> a constructor that takes as parameters all the same fields (i.e, arguments of the same name and type). This is a kind of immutable variant of a normal <a href="http://java.sun.com/products/javabeans">JavaBean</a>. The fields in the object must be of the datatypes that can be reliably mapped into WSDL.</p>
<p>If your exception meets this specification, then the WSDL describing the method will describe the exception too, enabling callers to create stub implementations of the exception, regardless of platform.</p>
<p>Again, to be sure of interoperability, you need to be experiment a bit. Remember, the calling language may not have the notion of Exceptions, or at least not be as rigorous as Java in the rules as to how exceptions must be handled.</p>
<div class="h5">
<h5>Java Collections</h5>
</div>
<p>Some of the Collection classes, such as <tt>Hashtable</tt>, do have serializers, but there is no formal interoperability with other SOAP implementations, and nothing in the SOAP specifications which covers complex objects. The most reliable way to send aggregate objects is to use arrays. In particular, .NET cannot handle them, though many Java SOAP implementations can marshall and unmarshall hash tables.</p>
<div class="h5">
<h5>Arbitrary Objects without Pre-Registration</h5>
</div>
<p>You cannot send arbitrary Java objects over the wire and expect them to be understood at the far end. With RMI you can send and receive <tt>Serializable</tt> Java objects, but that is because you are running Java at both ends. <strong>Axis will only send objects for which there is a registered Axis serializer.</strong> This document shows below how to use the BeanSerializer to serialize any class that follows the JavaBean pattern of accessor and mutator. To serve up objects you must either register your classes with this BeanSerializer, or there must be serialization support built in to Axis.</p>
<div class="h5">
<h5>Remote References</h5>
</div>
<p>Remote references are neither part of the SOAP specification, nor the JAX-RPC specification. You cannot return some object reference and expect the caller to be able to use it as an endpoint for SOAP calls or as a parameter in other calls. Instead you must use some other reference mechanism, such as storing them in a <tt>HashMap</tt> with numeric or string keys that can be passed over the wire.</p>
<div class="h5">
<h5>What Axis can send via SOAP with restricted Interoperability</h5>
</div>
<div class="h5">
<h5>What Axis can not send via SOAP</h5>
</div>
<div class="h5">
<h5>Encoding Your Beans - the BeanSerializer</h5>
</div>
<p>Axis includes the ability to serialize/deserialize, without writing any code, arbitrary Java classes which follow the standard <a href="http://java.sun.com/products/javabeans">JavaBean</a> pattern of get/set accessors. All you need to do is tell Axis which Java classes map to which XML Schema types. Configuring a bean mapping looks like this:</p>
<pre class="xml">&lt;beanMapping qname="ns:local" xmlns:ns="someNamespace"
languageSpecificType="java:my.java.thingy"/&gt;
</pre>
<p>The &lt;beanMapping&gt; tag maps a Java class (presumably a bean) to an XML QName. You'll note that it has two important attributes, <strong>qname</strong> and <strong>languageSpecificType</strong>. So in this case, we'd be mapping the "my.java.thingy" class to the XML QName [someNamespace]:[local].</p>
<p>Let's take a look at how this works in practice. Go look at <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/ws-axis/java/samples/userguide/example5/BeanService.java">samples/userguide/example5/BeanService.java</a>. The key thing to notice is that the argument to the service method is an Order object. Since Order is not a basic type which Axis understands by default, trying to run this service without a type mapping will result in a fault. (If you want to try this for yourself, you can use the bad-deploy.wsdd file in the example5 directory.) But if we put a beanMapping into our deployment, all will be well. Here's how to run this example (from the example5 directory):</p>
<pre class="example">% java org.apache.axis.client.AdminClient -llocal:///AdminService deploy.wsdd
&lt;Admin&gt;Done processing&lt;/Admin&gt;
% java samples.userguide.example5.Client -llocal://
Hi, Glen Daniels!
You seem to have ordered the following:
1 of item : mp3jukebox
4 of item : 1600mahBattery
If this had been a real order processing system, we'd probably have charged
you about now.
%
</pre>
<div class="h5">
<h5>When Beans Are Not Enough - Custom Serialization</h5>
</div>
<p>Just as JWS deployment is sometimes not flexible enough to meet all needs, the default bean serialization model isn't robust enough to handle every case either. At times there will be non-bean Java classes (especially in the case of pre-existing assets) which you need to map to/from XML, and there also may be some custom XML schema types which you want to map into Java in particular ways. Axis gives you the ability to write custom serializers/deserializers, and some tools to help make your life easier when you do so.</p>
<p>
<em>TBD - this section will be expanded in a future version! For now look at the DataSer/DataDeser classes (in samples/encoding). Also look at the BeanSerializer, BeanDeserializer, ArraySerializer, ArrayDeserializer and other classes in the org.apache.axis.encoding.ser package.</em>
</p>
<div class="h5">
<h5>Deploying custom mappings - the &lt;typeMapping&gt; tag</h5>
</div>
<p>Now that you've built your serializers and deserializers, you need to tell Axis which types they should be used for. You do this with a typeMapping tag in WSDD, which looks like this:</p>
<pre class="xml">&lt;typeMapping qname="ns:local" xmlns:ns="someNamespace"
languageSpecificType="java:my.java.thingy"
serializer="my.java.Serializer"
deserializer="my.java.DeserializerFactory"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/&gt;
</pre>
<p>This looks a lot like the &lt;beanMapping&gt; tag we saw earlier, but there are three extra attributes. One, <strong>serializer</strong>, is the Java class name of the Serializer <em>factory</em> which gets the serializer to be used to marshal an object of the specified Java class (i.e., my.java.thingy) into XML. Another, <strong>deserializer</strong>, is the class name of a Deserializer <em>factory</em> that gets the deserializer to be used to unmarshall XML into the correct Java class. The final attribute, the <strong>encodingStyle</strong>, which is SOAP encoding.</p>
<p>(The &lt;beanMapping&gt; tag is really just shorthand for a &lt;typeMapping&gt; tag with <tt>serializer="org.apache.axis.encoding.ser.BeanSerializerFactory"</tt>, <tt>deserializer="org.apache.axis.encoding.ser.BeanDeserializerFactory"</tt>, and <tt>encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"</tt>, but clearly it can save a lot of typing!)</p>
<p>
<a name="java/user-guide.html#WSDL"></a>
</p>
<div class="h5">
<h5>Using WSDL with Axis</h5>
</div>
<p>The <a href="http://www.w3.org/TR/wsdl">Web Service Description Language</a> is a specification authored by IBM and Microsoft, and supported by many other organizations. WSDL serves to describe Web Services in a structured way. A WSDL description of a service tells us, in a machine-understandable way, the interface to the service, the data types it uses, and where the service is located. Please see the spec (follow the link in the first sentence) for details about WSDL's format and options.</p>
<p>Axis supports WSDL in three ways:</p>
<ol>
<li>When you deploy a service in Axis, users may then access your service's URL with a standard web browser and by appending "?WSDL" to the end of the URL, they will obtain an automatically-generated WSDL document which describes your service.</li>
<li>We provide a "WSDL2Java" tool which will build Java proxies and skeletons for services with WSDL descriptions.</li>
<li>We provide a "Java2WSDL" tool which will build WSDL from Java classes.</li>
</ol>
<p>
<a name="java/user-guide.html#WSDLObtaining"></a>
</p>
<div class="h5">
<h5>?WSDL: Obtaining WSDL for deployed services</h5>
</div>
<p>When you make a service available using Axis, there is typically a unique URL associated with that service. For JWS files, that URL is simply the path to the JWS file itself. For non-JWS services, this is usually the URL "http://&lt;host&gt;/axis/services/&lt;service-name&gt;".</p>
<p>If you access the service URL in a browser, you'll see a message indicating that the endpoint is an Axis service, and that you should usually access it using SOAP. However, if you tack on "?wsdl" to the end of the URL, Axis will automatically generate a service description for the deployed service, and return it as XML in your browser (try it!). The resulting description may be saved or used as input to proxy-generation, described next. You can give the WSDL-generation URL to your online partners, and they'll be able to use it to access your service with toolkits like .NET, SOAP::Lite, or any other software which supports using WSDL.</p>
<p>You can also generate WSDL files from existing Java classes (see <a href="##Java2WSDL">Java2WSDL: Building WSDL from Java</a> ).<br>
</p>
<p>
<a name="java/user-guide.html#WSDL2Java"></a>
</p>
<div class="h5">
<h5>WSDL2Java: Building stubs, skeletons, and data types from WSDL</h5>
</div>
<div class="h5">
<h5>Client-side bindings</h5>
</div>
<p>You'll find the Axis WSDL-to-Java tool in "org.apache.axis.wsdl.WSDL2Java". The basic invocation form looks like this:</p>
<pre class="example">% java org.apache.axis.wsdl.WSDL2Java (WSDL-file-URL)
</pre>
<p>This will generate only those bindings necessary for the client. Axis follows the JAX-RPC specification when generating Java client bindings from WSDL. For this discussion, assume we executed the following:</p>
<pre class="example">% cd samples/addr
% java org.apache.axis.wsdl.WSDL2Java AddressBook.wsdl
</pre>
<p>The generated files will reside in the directory "AddressFetcher2". They are put here because that is the target namespace from the WSDL and namespaces map to Java packages. Namespaces will be discussed in detail later.</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td><strong>WSDL clause</strong></td><td><strong>Java class(es) generated</strong></td>
</tr>
<tr class="a">
<td>For each entry in the type section</td><td>A java class</td>
</tr>
<tr class="b">
<td></td><td>A holder if this type is used as an inout/out parameter</td>
</tr>
<tr class="a">
<td>For each portType</td><td>A java interface</td>
</tr>
<tr class="b">
<td>For each binding</td><td>A stub class</td>
</tr>
<tr class="a">
<td>For each service</td><td>A service interface</td>
</tr>
<tr class="b">
<td></td><td>A service implementation (the locator)</td>
</tr>
</table>
<p>There is an <a href="#ant/axis-wsdl2java.html">Ant Task</a> to integrate this action with an Ant based build process.</p>
<div class="h5">
<h5>Types</h5>
</div>
<p>The Java class generated from a WSDL type will be named from the WSDL type. This class will typically, though not always, be a bean. For example, given the WSDL (the WSDL used throughout the WSDL2Java discussion is from the <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/ws-axis/java/samples/addr/AddressBook.wsdl">Address Book sample</a>):</p>
<pre class="example">&lt;xsd:complexType name="phone"&gt;
&lt;xsd:all&gt;
&lt;xsd:element name="areaCode" type="xsd:int"/&gt;
&lt;xsd:element name="exchange" type="xsd:string"/&gt;
&lt;xsd:element name="number" type="xsd:string"/&gt;
&lt;/xsd:all&gt;
&lt;/xsd:complexType&gt;
</pre>
<p>WSDL2Java will generate:</p>
<pre class="example">public class Phone implements java.io.Serializable {
public Phone() {...}
public int getAreaCode() {...}
public void setAreaCode(int areaCode) {...}
public java.lang.String getExchange() {...}
public void setExchange(java.lang.String exchange) {...}
public java.lang.String getNumber() {...}
public void setNumber(java.lang.String number) {...}
public boolean equals(Object obj) {...}
public int hashCode() {...}
}
</pre>
<div class="h5">
<h5>Mapping XML to Java types : Metadata</h5>
</div>
<p>Notice in the mapping above, the XML type name is "phone" and the generated Java class is "Phone" - the capitalization of the first letter has changed to match the Java coding convention that classes begin with an uppercase letter. This sort of thing happens a lot, because the rules for expressing XML names/identifiers are much less restrictive than those for Java. For example, if one of the sub-elements in the "phone" type above was named "new", we couldn't just generate a Java field called "new", since that is a reserved word and the resultant source code would fail to compile.</p>
<p>To support this kind of mapping, and also to enable the serialization/deserialization of XML attributes, we have a <strong>type metadata</strong> system which allows us to associate Java data classes with descriptors which control these things.</p>
<p>When the WSDL2Java tool creates a data bean like the Phone class above, it notices if the schema contains any attributes, or any names which do not map directly to Java field/property names. If it finds any of these things, it will generate a static piece of code to supply a <strong>type descriptor</strong> for the class. The type descriptor is essentially a collection of <strong>field descriptors</strong>, each of which maps a Java field/property to an XML element or attribute.</p>
<p>To see an example of this kind of metadata, look at the "test.encoding.AttributeBean" class in the Axis source, or generate your own bean from XML which uses attributes or names which would be illegal in Java.</p>
<div class="h5">
<h5>Holders</h5>
</div>
<p>This type may be used as an inout or out parameter. Java does not have the concept of inout/out parameters. In order to achieve this behavior, JAX-RPC specifies the use of holder classes. A holder class is simply a class that contains an instance of its type. For example, the holder for the Phone class would be:</p>
<pre class="example">package samples.addr.holders;
public final class PhoneHolder implements javax.xml.rpc.holders.Holder {
public samples.addr.Phone value;
public PhoneHolder()
{
}
public PhoneHolder(samples.addr.Phone value) {
this.value = value;
}
}
</pre>
<p>A holder class is <strong>only</strong> generated for a type if that type is used as an inout or out parameter. Note that the holder class has the suffix "Holder" appended to the class name, and it is generated in a sub-package with the "holders".</p>
<p>The holder classes for the primitive types can be found in javax.xml.rpc.holders.</p>
<div class="h5">
<h5>PortTypes</h5>
</div>
<p>The Service Definition Interface (SDI) is the interface that's derived from a WSDL's portType. This is the interface you use to access the operations on the service. For example, given the WSDL:</p>
<pre class="example">&lt;message name="empty"&gt;
&lt;message name="AddEntryRequest"&gt;
&lt;part name="name" type="xsd:string"/&gt;
&lt;part name="address" type="typens:address"/&gt;
&lt;/message&gt;
&lt;portType name="AddressBook"&gt;
&lt;operation name="addEntry"&gt;
&lt;input message="tns:AddEntryRequest"/&gt;
&lt;output message="tns:empty"/&gt;
&lt;/operation&gt;
&lt;/portType&gt;
</pre>
<p>WSDL2Java will generate:</p>
<pre class="example">public interface AddressBook extends java.rmi.Remote {
public void addEntry(String name, Address address) throws
java.rmi.RemoteException;
}
</pre>
<p>A note about the name of the SDI. The name of the SDI is typically the name of the portType. However, to construct the SDI, WSDL2Java needs information from both the portType <strong>and</strong> the binding. (This is unfortunate and is a topic of discussion for WSDL version 2.)</p>
<p>JAX-RPC says (section 4.3.3): "The name of the Java interface is mapped from the name attribute of the wsdl:portType element. ... If the mapping to a service definition interface uses elements of the wsdl:binding ..., then the name of the service definition interface is mapped from the name of the wsdl:binding element."</p>
<p>Note the name of the spec. It contains the string "RPC". So this spec, and WSDL2Java, assumes that the interface generated from the portType is an RPC interface. If information from the binding tells us otherwise (in other words, we use elements of the wsdl:binding), then the name of the interface is derived instead from the binding.</p>
<p>Why? We could have one portType - pt - and two bindings - bRPC and bDoc. Since document/literal changes what the interface looks like, we cannot use a single interface for both of these bindings, so we end up with two interfaces - one named pt and another named bDoc - and two stubs - bRPCStub (which implements pt) and bDocStub (which implements bDoc).</p>
<p>Ugly, isn't it? But you can see why it's necessary. Since document/literal changes what the interface looks like, and we could have more than one binding referring to a single portType, we have to create more than one interface, and each interface must have a unique name.<br>
</p>
<div class="h5">
<h5>Bindings</h5>
</div>
<p>A Stub class implements the SDI. Its name is the binding name with the suffix "Stub". It contains the code which turns the method invocations into SOAP calls using the Axis Service and Call objects. It stands in as a <strong>proxy</strong> (another term for the same idea) for the remote service, letting you call it exactly as if it were a local object. In other words, you don't need to deal with the endpoint URL, namespace, or parameter arrays which are involved in dynamic invocation via the Service and Call objects. The stub hides all that work for you.</p>
<p>Given the following WSDL snippet:</p>
<pre class="example">&lt;binding name="AddressBookSOAPBinding" type="tns:AddressBook"&gt;
...
&lt;/binding&gt;
</pre>
<p>WSDL2Java will generate:</p>
<pre class="example">public class AddressBookSOAPBindingStub extends org.apache.axis.client.Stub
implements AddressBook {
public AddressBookSOAPBindingStub() throws org.apache.axis.AxisFault
{...}
public AddressBookSOAPBindingStub(URL endpointURL,
javax.xml.rpc.Service service)
throws org.apache.axis.AxisFault
{...}
<br> public AddressBookSOAPBindingStub(javax.xml.rpc.Service service)
throws org.apache.axis.AxisFault
{...}
<br> public void addEntry(String name, Address address) throws RemoteException
{...}<br>}
</pre>
<div class="h5">
<h5>Services</h5>
</div>
<p>Normally, a client program would not instantiate a stub directly. It would instead instantiate a service locator and call a get method which returns a stub. This locator is derived from the service clause in the WSDL. WSDL2Java generates two objects from a service clause. For example, given the WSDL:</p>
<pre class="example">&lt;service name="AddressBookService"&gt;
&lt;port name="AddressBook" binding="tns:AddressBookSOAPBinding"&gt;
&lt;soap:address location="http://localhost:8080/axis/services/AddressBook"/&gt;
&lt;/port&gt;
&lt;/service&gt;
</pre>
<p>WSDL2Java will generate the service interface:</p>
<pre class="example">public interface AddressBookService extends javax.xml.rpc.Service {
public String getAddressBookAddress();
<br> public AddressBook getAddressBook() throws javax.xml.rpc.ServiceException;
<br> public AddressBook getAddressBook(URL portAddress)
throws javax.xml.rpc.ServiceException;
}
</pre>
<p>WSDL2Java will also generate the locator which implements this interface:</p>
<pre class="example">public class AddressBookServiceLocator extends org.apache.axis.client.Service
implements AddressBookService {
...
}
</pre>
<p>The service interface defines a get method for each port listed in the service element of the WSDL. The locator is the implementation of this service interface. It implements these get methods. It serves as a locator for obtaining Stub instances. The Service class will by default make a Stub which points to the endpoint URL described in the WSDL file, but you may also specify a different URL when you ask for the PortType.</p>
<p>A typical usage of the stub classes would be as follows:</p>
<pre class="example">public class Tester
{
public static void main(String [] args) throws Exception {
// Make a service
AddressBookService service = new AddressBookServiceLocator();
// Now use the service to get a stub which implements the SDI.
AddressBook port = service.getAddressBook();
// Make the actual call
Address address = new Address(...);
port.addEntry("Russell Butek", address);
}<br>}
</pre>
<div class="h5">
<h5>Server-side bindings</h5>
</div>
<p>Just as a stub is the client side of a Web Service represented in Java, a <strong>skeleton</strong> is a Java framework for the server side. To make skeleton classes, you just specify the "--server-side --skeletonDeploy true" options to WSDL2Java. For instance, using the AddressBook.wsdl as we had above:</p>
<pre class="example">% java org.apache.axis.wsdl.WSDL2Java --server-side
--skeletonDeploy true AddressBook.wsdl
</pre>
<p>You will see that WSDL2Java generates all the classes that were generated before for the client, but it generates a few new files:<br>
<br>
</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td><strong>WSDL clause</strong></td><td><strong>Java class(es) generated</strong></td>
</tr>
<tr class="a">
<td>For each binding</td><td>A skeleton class</td>
</tr>
<tr class="b">
<td></td><td>An implementation template class</td>
</tr>
<tr class="a">
<td>For all services</td><td>One deploy.wsdd file</td>
</tr>
<tr class="b">
<td></td><td>One undeploy.wsdd file</td>
</tr>
</table>
<p>If you don't specify the "--skeletonDeploy true" option, a skeleton will not be generated. Instead, the generated deploy.wsdd will indicate that the implementation class is deployed directly. In such cases, the deploy.wsdd contains extra meta data describing the operations and parameters of the implementation class. Here is how you run WSDL2Java to deploy directly to the implementation:</p>
<pre class="example">% java org.apache.axis.wsdl.WSDL2Java --server-side AddressBook.wsdl
</pre>
<p>And here are the server side files that are generated:<br>
<br>
</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td><strong>WSDL clause</strong></td><td><strong>Java class(es) generated</strong></td>
</tr>
<tr class="a">
<td>For each binding</td><td>An implementation template class</td>
</tr>
<tr class="b">
<td>For all services</td><td>One deploy.wsdd file with operation meta data</td>
</tr>
<tr class="a">
<td></td><td>One undeploy.wsdd file</td>
</tr>
</table>
<div class="h5">
<h5>Bindings</h5>
</div>
<div class="h5">
<h5>Skeleton Description (for Skeleton Deployment)</h5>
</div>
<p>The skeleton class is the class that sits between the Axis engine and the actual service implementation. Its name is the binding name with suffix "Skeleton". For example, for the AddressBook binding, WSDL2Java will generate:</p>
<pre class="example">public class AddressBookSOAPBindingSkeleton implements AddressBook,
org.apache.axis.wsdl.Skeleton {
private AddressBook impl;
public AddressBookSOAPBindingSkeleton() {
this.impl = new AddressBookSOAPBindingImpl();
}
public AddressBookSOAPBindingSkeleton(AddressBook impl) {
this.impl = impl;
}
public void addEntry(java.lang.String name, Address address)
throws java.rmi.RemoteException
{
impl.addEntry(name, address);
}
}
</pre>
<p>(The real skeleton is actually much richer. For brevity we just show you the basic skeleton.)</p>
<p>The skeleton contains an implementation of the AddressBook service. This implementation is either passed into the skeleton on construction, or an instance of the generated implementation is created. When the Axis engine calls the skeleton's addEntry method, it simply delegates the invocation to the real implementation's addEntry method.</p>
<div class="h5">
<h5>Implementation Template Description</h5>
</div>
<p>WSDL2Java also generates an implementation template from the binding:</p>
<pre class="example">public class AddressBookSOAPBindingImpl implements AddressBook {
<br> public void addEntry(String name, Address address)
throws java.rmi.RemoteException {
}
}
</pre>
<p>This template could actually be used as a test implementation but, as you can see, it doesn't do anything. It is intended that the service writer fill out the implementation from this template.</p>
<p>When WSDL2Java is asked to generate the implementation template (via the --server-side flag), it will ONLY generate it if it does not already exist. If this implementation already exists, it will not be overwritten.</p>
<div class="h5">
<h5>Services</h5>
</div>
<p>The tool also builds you a "deploy.wsdd" and an "undeploy.wsdd" for each service for use with the AdminClient. These files may be used to deploy the service once you've filled in the methods of the Implementation class, compiled the code, and made the classes available to your Axis engine.</p>
<p>
<a name="java/user-guide.html#Java2WSDL"></a>
</p>
<div class="h5">
<h5>Java2WSDL: Building WSDL from Java</h5>
</div>
<p>The Java2WSDL and WSDL2Java emitters make it easy to develop a new web service. The following sections describe the steps in building a web service from a Java interface.<br>
</p>
<div class="h5">
<h5>Step 1: Provide a Java interface or class</h5>
</div>
<p>Write and compile a Java interface (or class) that describes the web service interface. Here is an example interface that describes a web services that can be used to set/query the price of widgets (<a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/ws-axis/java/samples/userguide/example6/WidgetPrice.java">samples/userguide/example6/WidgetPrice.java</a>):</p>
<pre class="example">package samples.userguide.example6;
<br>/**
* Interface describing a web service to set and get Widget prices.
**/
public interface WidgetPrice {
public void setWidgetPrice(String widgetName, String price);
public String getWidgetPrice(String widgetName);
}
</pre>
<p>
<strong>Note:</strong> If you compile your class with debug information, Java2WSDL will use the debug information to obtain the method parameter names.</p>
<div class="h5">
<h5>Step 2: Create WSDL using Java2WSDL</h5>
</div>
<p>Use the Java2WSDL tool to create a WSDL file from the interface above.</p>
<p>Here is an example invocation that produces the wsdl file (<tt>wp.wsdl</tt>) from the interface described in the previous section:</p>
<pre class="example">% java org.apache.axis.wsdl.Java2WSDL -o wp.wsdl
-l"http://localhost:8080/axis/services/WidgetPrice"
-n "urn:Example6" -p"samples.userguide.example6" "urn:Example6"
samples.userguide.example6.WidgetPrice
</pre>
<p>Where:</p>
<ul>
<li>-o indicates the name of the <strong>output WSDL</strong> file</li>
<li>-l indicates the<strong>location of the service</strong>
</li>
<li>-n is the target <strong>namespace</strong> of the WSDL file</li>
<li>-p indicates a mapping from the <strong>package to a namespace</strong>. There may be multiple mappings.</li>
<li>the class specified contains the interface of the webservice.</li>
</ul>
<p>The output WSDL document will contain the appropriate WSDL types, messages, portType, bindings and service descriptions to support a SOAP rpc, encoding web service. If your specified interface methods reference other classes, the Java2WSDL tool will generate the appropriate xml types to represent the classes and any nested/inherited types. The tool supports JAX-RPC complex types (bean classes), extension classes, enumeration classes, arrays and Holder classes.</p>
<p>The Java2WSDL tool has many additional options which are detailed in the <a href="#reference.html#Java2WSDL">reference guide</a>. There is an <a href="#ant/axis-java2wsdl.html">Ant Task</a> to integrate this action with an Ant based build process.</p>
<div class="h5">
<h5>Step 3: Create Bindings using WSDL2Java</h5>
</div>
<p>Use the generated WSDL file to build the appropriate client/server bindings for the web service (see <a href="##WSDL2Java:Buildingstubs,skeletons,anddata">WSDL2Java</a>):</p>
<pre class="example">% java org.apache.axis.wsdl.WSDL2Java -o . -d Session -s -S true
-Nurn:Example6 samples.userguide.example6 wp.wsdl
</pre>
<p>This will generate the following files:</p>
<ul>
<li>
<strong>WidgetPriceSoapBindingImpl.java</strong> : Java file containing the default server implementation of the WidgetPrice web service.</li>
<li style="list-style: none">
<br> You will need to modify the *SoapBindingImpl file to add your implementation (see <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/ws-axis/java//samples/userguide/example6/WidgetPriceSoapBindingImpl.java">samples/userguide/example6/WidgetPriceSoapBindingImpl.java</a> ).</li>
<li>
<strong>WidgetPrice.java</strong>: New interface file that contains the appropriate <strong>java.rmi.Remote</strong> usages.</li>
<li>
<strong>WidgetPriceService.java</strong>: Java file containing the client side service interface.</li>
<li>
<strong>WidgetPriceServiceLocator.java</strong>: Java file containing the client side service implementation class.</li>
<li>
<strong>WidgetPriceSoapBindingSkeleton.java</strong>: Server side skeleton.</li>
<li>
<strong>WidgetPriceSoapBindingStub.java</strong>: Client side stub.</li>
<li>
<strong>deploy.wsdd</strong>: Deployment descriptor</li>
<li>
<strong>undeploy.wsdd</strong>: Undeployment descriptor</li>
<li>(data types): Java files will be produced for all of the other types and holders necessary for the web service. There are no additional files for the WidgetPrice web service.</li>
</ul>
<p>Now you have all of the necessary files to build your client/server side code and deploy the web service!</p>
<p>
<a name="java/user-guide.html#published_interfaces"></a>
</p>
<div class="h5">
<h5>Published Axis Interfaces</h5>
</div>
<p>Although you may use any of the interfaces and classes present in Axis, you need to be aware that some are more stable than others since there is a continuing need to refactor Axis to maintain and improve its modularity.</p>
<p>Hence certain interfaces are designated as <em>published</em>, which means that they are relatively stable. As Axis is refactored, the Axis developers will try to avoid changing published interfaces unnecessarily and will certainly consider the impact on users of any modifications.</p>
<p>So if you stick to using only published interfaces, you'll minimise the pain of migrating between releases of Axis. On the other hand, if you decide to use unpublished interfaces, migrating between releases could be an interesting exercise! If you would like an interface to be published, you should make the case for this on the <a href="#mailto:axis-user@ws.apache.org">axis-user</a> mailing list.</p>
<p>The current list of published interfaces is as follows:</p>
<ul>
<li>JAX-RPC interfaces. These interfaces are from JAX-RPC 1.0 specification, and will change only when new versions of the specification are released. <ul>
<li>javax.xml.messaging.Endpoint</li>
<li>javax.xml.messaging.URLEndpoint</li>
<li>javax.xml.rpc.Call</li>
<li>javax.xml.rpc.FaultException</li>
<li>javax.xml.rpc.JAXRPCException</li>
<li>javax.xml.rpc.ParameterMode</li>
<li>javax.xml.rpc.Service</li>
<li>javax.xml.rpc.ServiceException</li>
<li>javax.xml.rpc.ServiceFactory</li>
<li>javax.xml.rpc.Stub</li>
<li>javax.xml.rpc.encoding.DeserializationContext</li>
<li>javax.xml.rpc.encoding.Deserializer</li>
<li>javax.xml.rpc.encoding.DeserializerFactory</li>
<li>javax.xml.rpc.encoding.SerializationContext</li>
<li>javax.xml.rpc.encoding.Serializer</li>
<li>javax.xml.rpc.encoding.SerializerFactory</li>
<li>javax.xml.rpc.encoding.TypeMapping</li>
<li>javax.xml.rpc.encoding.TypeMappingRegistry</li>
<li>javax.xml.rpc.handler.Handler</li>
<li>javax.xml.rpc.handler.HandlerChain</li>
<li>javax.xml.rpc.handler.HandlerInfo</li>
<li>javax.xml.rpc.handler.HandlerRegistry</li>
<li>javax.xml.rpc.handler.MessageContext</li>
<li>javax.xml.rpc.handler.soap.SOAPMessageContext</li>
<li>javax.xml.rpc.holders.BigDecimalHolder</li>
<li>javax.xml.rpc.holders.BigIntegerHolder</li>
<li>javax.xml.rpc.holders.BooleanHolder</li>
<li>javax.xml.rpc.holders.BooleanWrapperHolder</li>
<li>javax.xml.rpc.holders.ByteArrayHolder</li>
<li>javax.xml.rpc.holders.ByteHolder</li>
<li>javax.xml.rpc.holders.ByteWrapperArrayHolder</li>
<li>javax.xml.rpc.holders.ByteWrapperHolder</li>
<li>javax.xml.rpc.holders.CalendarHolder</li>
<li>javax.xml.rpc.holders.DateHolder</li>
<li>javax.xml.rpc.holders.DoubleHolder</li>
<li>javax.xml.rpc.holders.DoubleWrapperHolder</li>
<li>javax.xml.rpc.holders.FloatHolder</li>
<li>javax.xml.rpc.holders.FloatWrapperHolder</li>
<li>javax.xml.rpc.holders.Holder</li>
<li>javax.xml.rpc.holders.IntHolder</li>
<li>javax.xml.rpc.holders.IntegerWrapperHolder</li>
<li>javax.xml.rpc.holders.LongHolder</li>
<li>javax.xml.rpc.holders.LongWrapperHolder</li>
<li>javax.xml.rpc.holders.ObjectHolder</li>
<li>javax.xml.rpc.holders.QNameHolder</li>
<li>javax.xml.rpc.holders.ShortHolder</li>
<li>javax.xml.rpc.holders.ShortWrapperHolder</li>
<li>javax.xml.rpc.holders.StringHolder</li>
<li>javax.xml.rpc.namespace.QName</li>
<li>javax.xml.rpc.server.ServiceLifecycle</li>
<li>javax.xml.rpc.soap.SOAPFault</li>
<li>javax.xml.rpc.soap.SOAPHeaderFault</li>
<li>javax.xml.transform.Source</li>
</ul>
</li>
<li>Axis interfaces. These have less guarantees of stability: <ul>
<li>org.apache.axis.AxisFault</li>
<li>org.apache.axis.Handler</li>
<li>org.apache.axis.DefaultEngineConfigurationFactory</li>
<li>org.apache.axis.EngineConfiguration</li>
<li>org.apache.axis.EngineConfigurationFactory</li>
<li>org.apache.axis.Message</li>
<li>org.apache.axis.MessageContext</li>
<li>org.apache.axis.SOAPPart</li>
<li>org.apache.axis.client.Call</li>
<li>org.apache.axis.client.Service</li>
<li>org.apache.axis.client.ServiceFactory</li>
<li>org.apache.axis.client.Stub</li>
<li>org.apache.axis.client.Transport</li>
<li>org.apache.axis.description.TypeDesc</li>
<li>org.apache.axis.description.AttributeDesc</li>
<li>org.apache.aixs.description.ElementDesc</li>
<li>org.apache.axis.encoding.DeserializationContext</li>
<li>org.apache.axis.encoding.Deserializer</li>
<li>org.apache.axis.encoding.DeserializerFactory</li>
<li>org.apache.axis.encoding.DeserializerTarget</li>
<li>org.apache.axis.encoding.FieldTarget</li>
<li>org.apache.axis.encoding.MethodTarget</li>
<li>org.apache.axis.encoding.SerializationContext</li>
<li>org.apache.axis.encoding.Serializer</li>
<li>org.apache.axis.encoding.SerializerFactory</li>
<li>org.apache.axis.encoding.SimpleType</li>
<li>org.apache.axis.encoding.Target</li>
<li>org.apache.axis.encoding.TypeMapping</li>
<li>org.apache.axis.encoding.TypeMappingRegistry</li>
<li>org.apache.axis.encoding.ser.BaseDeserializerFactory</li>
<li>org.apache.axis.encoding.ser.BaseSerializerFactory</li>
<li>org.apache.axis.encoding.ser.BeanPropertyTarget</li>
<li>org.apache.axis.encoding.ser.SimpleSerializer</li>
<li>org.apache.axis.encoding.ser.SimpleDeserializer</li>
<li>org.apache.axis.session.Session</li>
<li>org.apache.axis.transport.http.SimpleAxisServer</li>
<li>org.apache.axis.transport.jms.SimpleJMSListener</li>
<li>org.apache.axis.utils.BeanProperty</li>
<li>org.apache.axis.wsdl.WSDL2Java</li>
<li>org.apache.axis.wsdl.Java2WSDL</li>
</ul>
</li>
</ul>
<p>
<a name="java/user-guide.html#newbie"></a>
</p>
<div class="h5">
<h5>Newbie Tips: Finding Your Way Around</h5>
</div>
<p>So you've skimmed the User's Guide and written your first .jws service, and everything went perfectly! Now it's time to get to work on a real project, and you have something specific you need to do that the User's Guide didn't cover. It's a simple thing, and you know it must be in Axis <em>somewhere</em>, but you don't know what it's called or how to get at it. This section is meant to give you some starting points for your search.</p>
<div class="h5">
<h5>Places to Look for Clues</h5>
</div>
<p>Here are the big categories.</p>
<ul>
<li>
<a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/ws-axis/java/samples/"><strong>The samples.</strong></a> These examples are complete with deployment descriptors and often contain both client and server code.</li>
<li>
<strong>The Javadocs.</strong> Full Javadocs are included with the binary distribution. The Javadocs can be intimidating at first, but once you know the major user classes, they are one of the fastest ways to an answer.</li>
<li>
<strong>The mailing list archives.</strong> If you know what you want but don't know what it's called in Axis, this is the best place to look. Chances are someone has wanted the same thing and someone else has used (or developed) Axis long enough know the name.</li>
<li>Consult the <a href="http://ws.apache.org/axis">Axis web site</a> for updated documentation and the <a href="http://wiki.apache.org/ws/FrontPage/Axis">Axis Wiki</a> for its Frequently Asked Questions (FAQ), installation notes, interoperability issues lists, and other useful information.</li>
<li>
<strong>WSDL2Java.</strong> Point WSDL2Java at a known webservice that does some of the things you want to do. See what comes out. This is useful even if you will be writing the actual service or client from scratch. If you want nice, human-readable descriptions of existing web services, try <a href="http://www.xmethods.net">http://www.xmethods.net</a>.</li>
</ul>
<div class="h5">
<h5>Classes to Know</h5>
</div>
<div class="h5">
<h5>org.apache.axis.MessageContext</h5>
</div>
<p>The answer to most "where do I find..." questions for an Axis web service is "in the MessageContext." Essentially everything Axis knows about a given request/response can be retrieved via the MessageContext. Here Axis stores:</p>
<ul>
<li>A reference to the AxisEngine</li>
<li>The request and response messages (<span class="codefrag">org.apache.axis.Message</span> objects available via getter and setter methods)</li>
<li>Information about statefulness and service scope (whether the service is maintaining session information, etc.)</li>
<li>The current status of processing (whether or not the "pivot" has been passed, which determines whether the request or response is the current message)</li>
<li>Authentication information (username and password, which can be provided by a servlet container or other means)</li>
<li>Properties galore. Almost anything you would want to know about the message can be retrieved via <span class="codefrag">MessageContext.getProperty()</span>. You only need to know the name of the property. This can be tricky, but it is usually a constant, like those defined in <span class="codefrag">org.apache.axis.transport.http.HTTPConstants</span>. So, for example, to retrieve the ServletContext for the Axis Servlet, you would want: <span class="codefrag">((HttpServlet)msgC.getProperty(HTTPConstants.MC_HTTP_SERVLET)).getServletContext();</span>
<br>
</li>
</ul>
<p>From within your service, the current MessageContext object is always available via the static method <span class="codefrag">MessageContext.getCurrentContext()</span>. This allows you to do any needed customization of the request and response methods, even from within an RPC service that has no explicit reference to the MessageContext.</p>
<div class="h5">
<h5>org.apache.axis.Message</h5>
</div>
<p>An <span class="codefrag">org.apache.axis.Message</span> object is Axis's representation of a SOAP message. The request and response messages can be retrieved from the MessageContext as described above. A Message has:</p>
<ul>
<li>MIME headers (if the message itself has MIME information)</li>
<li>Attachments (if the message itself has attachments)</li>
<li>A SOAPPart (and a convenience method for quick retrieval of the SOAPPart's SOAPEnvelope). The SOAPPart gives you access to the SOAP "guts" of the message (everything inside the &lt;soap:Envelope&gt; tags)</li>
</ul>
<div class="h5">
<h5>org.apache.axis.SOAPEnvelope</h5>
</div>
<p>As you can see, starting with the MessageContext lets you work your way down through the API, discovering all the information available to you about a single request/response exchange. A MessageContext has two Messages, which each have a SOAPPart that contains a SOAPEnvelope. The SOAPEnvelope, in turn, holds a full representation of the SOAP Envelope that is sent over the wire. From here you can get and set the contents of the SOAP Header and the SOAP Body. See the Javadocs for a full list of the properties available.</p>
<p>
<a name="java/user-guide.html#tcpmon"></a>
</p>
<div class="h5">
<h5>Appendix : Using the Axis TCP Monitor (tcpmon)</h5>
</div>
<p>The included "tcpmon" utility can be found in the org.apache.axis.utils package. To run it from the command line:</p>
<pre>% java org.apache.axis.utils.tcpmon [listenPort targetHost targetPort]
</pre>
<p>Without any of the optional arguments, you will get a gui which looks like this:</p>
<p>
<p>
<img alt="" src="images/tcpmon1.jpg"></p>
</p>
<p>To use the program, you should select a local port which tcpmon will monitor for incoming connections, a target host where it will forward such connections, and the port number on the target machine which should be "tunneled" to. Then click "add". You should then notice another tab appearing in the window for your new tunneled connection. Looking at that panel, you'll see something like this:</p>
<p>
<p>
<img alt="" src="images/tcpmon2.jpg"></p>
</p>
<p>Now each time a SOAP connection is made to the local port, you will see the request appear in the "Request" panel, and the response from the server in the "Response" panel. Tcpmon keeps a log of all request/response pairs, and allows you to view any particular pair by selecting an entry in the top panel. You may also remove selected entries, or all of them, or choose to save to a file for later viewing.</p>
<p>The "resend" button will resend the request you are currently viewing, and record a new response. This is particularly handy in that you can edit the XML in the request window before resending - so you can use this as a great tool for testing the effects of different XML on SOAP servers. Note that you may need to change the content-length HTTP header value before resending an edited request.</p>
<p>
<a name="java/user-guide.html#soapmon"></a>
</p>
<div class="h5">
<h5>Appendix: Using the SOAP Monitor</h5>
</div>
<p>Web service developers often have the need to see the SOAP messages being used to invoke web services along with the results of those messages. The goal of the SOAP Monitor utility is to provide a way for these developers to monitor the SOAP messages being used without requiring any special configuration or restarting of the server.</p>
<p>In this utility, a handler has been written and added to the global handler chain. As SOAP requests and responses are received, the SOAP message information is forwarded to a SOAP monitor service where it can be displayed using a web browser interface.</p>
<p>The SOAP message information is accessed with a web browser by going to http://localhost:&lt;port&gt;/axis/SOAPMonitor (where &lt;port&gt; is the port number where the application server is running).</p>
<p>The SOAP message information is displayed through a web browser by using an applet that opens a socket connection to the SOAP monitor service. This applet requires a Java plug-in 1.3 or higher to be installed in your browser. If you do not have a correct plug-in, the browser should prompt you to install one.</p>
<p>The port used by the SOAP monitor service to comminicate with applets is configurable. Edit the web.xml file for the Axis web application to change the port to be used.<br>
<strong>Note: The SOAP Monitor is NOT enabled by default for security reasons.</strong> To enable it, read <a href="#install.html#soapmon">Enabling the SOAP Monitor</a> in the Installation instructions.</p>
<p>
<a name="java/user-guide.html#Glossary"></a>
</p>
<div class="h5">
<h5>Glossary</h5>
</div>
<dl>
<dt>
<em>Handler</em>
</dt>
<dd>A reusable class which is responsible for processing a MessageContext in some custom way. The Axis engine invokes a series of Handlers whenever a request comes in from a client or a transport listener.</dd>
<dt>
<em>SOAP</em>
</dt>
<dd>The Simple Object Access Protocol (yes, despite the fact that it sometimes doesn't seem so simple, and doesn't have anything to do with objects... :)). You can read the SOAP 1.1 specification at <a href="http://www.w3.org/TR/SOAP">http://www.w3.org/TR/SOAP</a>. The W3C is currently in the midst of work on SOAP 1.2, under the auspices of the <a href="http://www.w3.org/2000/xp/Group/">XML Protocol Group</a>.</dd>
<dt>
<em>Provider</em>
</dt>
<dd>A provider is the "back-end" Handler which is responsible for actually performing the "meat" of the desired SOAP operation. Typically this means calling a method on some back-end service object. The two commonly used providers are RPCProvider and MsgProvider, both in the org.apache.axis.providers.java package.</dd>
</dl>
<div class="h2">
<h2>Axis Developer's Guide</h2>
</div>
<div class="h5">
<h5>Axis Developer's Guide</h5>
</div>
<p>
<em>1.2 Version</em>
<br>
<em>Feedback: axis-dev@ws.apache.org</em>
</p>
<div class="h5">
<h5>Introduction</h5>
</div>
<p>This guide is a collection of topics related to developing code for Axis.</p>
<div class="h5">
<h5>General Guidelines</h5>
</div>
<ul>
<li>Axis specific information (cvs repository access, mailing list info, etc.) can be found on the <a href="http://ws.apache.org/axis/index.html">Axis Home Page</a>.</li>
<li>Axis uses the <a href="http://jakarta.apache.org/site/guidelines.html">Jakarta Project Guidelines.</a>
</li>
<li>Code changes should comply with <a href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">"Code Conventions for the Java Programming Language"</a>
</li>
<li>When fixing a bug, please include the href of the bug in the cvs commit message.</li>
<li>Incompatible changes to <a href="#user-guide.html#published%20interfaces">published Axis interfaces</a> should be avoided where possible. When changes are necessary, for example to maintain or improve the overall modularity of Axis, the impact on users must be considered and, preferably, documented.</li>
<li>If you are making a big change that may affect interoperability, please run the <a href="http://xml.apache.org/~rubys/echotest.pl">echotest2 round 2 interop test</a> to ensure that your change does not result in any new interop failures. You will also need the <a href="http://xml.apache.org/~rubys/client_deploy.wsdd">client_deploy.wsdd</a>. Here are the <a href="http://xml.apache.org/~rubys/ApacheClientInterop.html">nightly interop test results</a>.</li>
</ul>
<div class="h5">
<h5>Development Environment</h5>
</div>
<p>The following packages are required for axis development:</p>
<ul>
<li>
<a href="http://jakarta.apache.org/ant/index.html">ant</a> - Java based build tool. <strong>Please Note: Version 1.5 OR HIGHER is required</strong>
</li>
<li>
<a href="http://www.junit.org">junit</a> - testing package</li>
<li>
<a href="http://xml.apache.org/dist/xerces-j">xerces</a> - xml processor</li>
<li>Install Java 1.3.1 JDK (or later).</li>
</ul>
<p>
<br> The Axis jar files are built in the <tt>xml-axis/java/build/lib</tt> directory.&nbsp;&nbsp; Here is an example CLASSPATH, which I use when developing code:</p>
<pre class="code">G:\xerces\xerces-1_4_2\xerces.jar
G:\junit3.7\junit.jar
G:\xml-axis\java\build\lib\commons-discovery.jar
G:\xml-axis\java\build\lib\commons-logging.jar
G:\xml-axis\java\build\lib\wsdl4j.jar
G:\xml-axis\java\build\lib\axis.jar
G:\xml-axis\java\build\lib\log4j-1.2.8.jar
G:\xml-axis\java\build\classes
</pre>
<p>If you access the internet via a proxy server, you'll need to set an environment variable so that the Axis tests do the same. Set ANT_OPTS to, for example:</p>
<pre class="code"> -Dhttp.proxyHost=proxy.somewhere.com
-Dhttp.proxyPort=80
-Dhttp.nonProxyHosts="localhost"</pre>
<div class="h5">
<h5>Pluggable-Components</h5>
</div>
<p>The <a href="#architecture-guide.html">Axis Architecture Guide</a> explains the requirements for pluggable components.</p>
<div class="h5">
<h5>Discovery</h5>
</div>
<p>An Axis-specific component factory should be created of the form:</p>org.apache.axis.components.&lt;componentType&gt;.&lt;factoryClassName&gt;<p>For example, <span class="codefrag">org.apache.axis.components.logger.LogFactory</span> is the factory, or discovery mechanism, for the logger component/service.</p>
<p>The <span class="codefrag">org.apache.axis.components.image</span> package demonstrates both a factory, and supporting classes for different image tools used by Axis. This is representative of a pluggable component that uses external tooling, isolating it behind a 'thin' wrapper to Axis that provides only a limited interface to meet Axis minimal requirements. This allows future designers and implementors to gain an explicit understanding of the Axis's specific requirements on these tools.</p>
<div class="h5">
<h5>Logging/Tracing</h5>
</div>
<p>Axis logging and tracing is based on the Logging component of the <a href="http://jakarta.apache.org/commons/index.html">Jakarta Commons</a> project, or the Jakarta Commons Logging (JCL) SPI. The JCL provides a Log interface with thin-wrapper implementations for other logging tools, including <a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a>, <a href="http://jakarta.apache.org/avalon/logkit/index.html">Avalon LogKit</a>, and JDK 1.4. The interface maps closely to Log4J and LogKit.</p>
<div class="h5">
<h5>Using the Logger SPI</h5>
</div>
<p>To use the JCL SPI from a Java class, include the following import statements:</p>
<pre>import org.apache.commons.logging.Log;
import org.apache.axis.components.logger.LogFactory;
</pre>
<p>For each class definition, declare and initialize a <span class="codefrag">log</span> attribute as follows:</p>
<pre>public class CLASS
{
private static Log log =
LogFactory.getLog(CLASS.class);
...
</pre>
<p>Messages are logged to a <em>logger</em>, such as <span class="codefrag">log</span> by invoking a method corresponding to <em>priority</em>: The <span class="codefrag">Log</span> interface defines the following methods for use in writing log/trace messages to the log:</p>
<pre>log.fatal(Object message);
log.fatal(Object message, Throwable t);
log.error(Object message);
log.error(Object message, Throwable t);
log.warn(Object message);
log.warn(Object message, Throwable t);
log.info(Object message);
log.info(Object message, Throwable t);
log.debug(Object message);
log.debug(Object message, Throwable t);
log.trace(Object message);
log.trace(Object message, Throwable t);</pre>
<p>While semantics for these methods are ultimately defined by the implementation of the Log interface, it is expected that the severity of messages is ordered as shown in the above list.</p>
<p>In addition to the logging methods, the following are provided:</p>
<pre>log.isFatalEnabled();
log.isErrorEnabled();
log.isWarnEnabled();
log.isInfoEnabled();
log.isDebugEnabled();
log.isTraceEnabled();</pre>
<p>These are typically used to guard code that only needs to execute in support of logging, and that introduces undesirable runtime overhead in the general case (logging disabled).</p>
<div class="h5">
<h5>Guidelines</h5>
</div>
<div class="h5">
<h5>Message Priorities</h5>
</div>
<p>It is important to ensure that log message are appropriate in content and severity. The following guidelines are suggested:</p>
<ul>
<li>fatal - Severe errors that cause the Axis server to terminate prematurely. Expect these to be immediately visible on a console, and MUST be internationalized.</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>error - Other runtime errors or unexpected conditions. Expect these to be immediately visible on a console, and MUST be internationalized.</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>warn - Use of deprecated APIs, poor use of API, almost errors, other runtime situations that are undesirable or unexpected, but not necessarily "wrong". Expect these to be immediately visible on a console, and MUST be internationalized.</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>info - Interesting runtime events (startup/shutdown). Expect these to be immediately visible on a console, so be conservative and keep to a minimum. These MUST be internationalized.</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>debug - detailed information on flow of through the system. Expect these to be written to logs only. These NEED NOT be internationalized, but it never hurts...</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>trace - more detailed information. Expect these to be written to logs only. These NEED NOT be internationalized, but it never hurts...</li>
</ul>
<div class="h5">
<h5>Configuring the Logger</h5>
</div>
<p>The Jakarta Commons Logging (JCL) SPI can be configured to use different logging toolkits. To configure which logger is used by the JCL, see the <a href="#integration-guide.html">Axis System Integration Guide</a>.</p>
<p>Configuration of the behavior of the JCL ultimately depends upon the logging toolkit being used. The JCL SPI (and hence Axis) uses <a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a> by default if it is available (in the CLASSPATH).</p>
<div class="h5">
<h5>Log4J</h5>
</div>
<p>As <a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a> is the prefered/default logger for Axis, a <em>few</em> details are presented herein to get the developer going.</p>
<p>Configure Log4J using system properties and/or a properties file:</p>
<ul>
<li>
<strong>log4j.configuration=<em>log4j.properties</em></strong>
<p>Use this system property to specify the name of a Log4J configuration file. If not specified, the default configuration file is <em>log4j.properties</em>. A <em>log4j.properties</em> file is provided in <span class="codefrag">axis.jar</span>.</p>
<p>This properties file can sometimes be overridden by placing a file of the same name so as to appear before <span class="codefrag">axis.jar</span> in the CLASSPATH. However, the precise behaviour depends on the classloader that is in use at the time, so we don't recommend this technique.</p>
<p>A safe way of overriding the properties file is to replace it in axis.jar. However, this isn't very convenient, especially if you want to tweak the properties during a debug session to filter out unwanted log entries. A more convenient alternative is to use an absolute file path to specify the properties file. This will even ignore web app's and their classloaders. So, for example on Linux, you could specify the system property:</p>
<pre>log4j.configuration=file:/home/fred/log4j.props
</pre>
</li>
<li>
<strong>log4j.debug</strong> A good way of telling where log4j is getting its configuration from is to set this system property and look at the messages on standard output.<br> &nbsp;</li>
<li>
<strong>log4j.rootCategory=<em>priority</em> [, <em>appender</em>]*</strong> Set the default (root) logger priority.<br> &nbsp;</li>
<li>
<strong>log4j.logger.<em>logger.name</em>=<em>priority</em></strong> Set the priority for the named logger and all loggers hierarchically lower than, or below, the named logger. <em>logger.name</em> corresponds to the parameter of <span class="codefrag">LogFactory.getLog(logger.name)</span>, used to create the logger instance. Priorities are: <span class="codefrag">DEBUG</span>, <span class="codefrag">INFO</span>, <span class="codefrag">WARN</span>, <span class="codefrag">ERROR</span>, or <span class="codefrag">FATAL</span>. <p>Log4J understands hierarchical names, enabling control by package or high-level qualifiers: <span class="codefrag">log4j.logger.org.apache.axis.encoding=DEBUG</span> will enable debug messages for all classes in both <span class="codefrag">org.apache.axis.encoding</span> and <span class="codefrag">org.apache.axis.encoding.ser</span>. Likewise, setting <span class="codefrag">log4j.logger.org.apache.axis=DEBUG</span> will enable debug message for all Axis classes, but not for other Jakarta projects.</p>
<p>A combination of settings will enable you to see the log events that you are interested in and omit the others. For example, the combination:</p>
<pre>log4j.logger.org.apache.axis=DEBUG
log4j.logger.org.apache.axis.encoding=INFO
log4j.logger.org.apache.axis.utils=INFO
log4j.logger.org.apache.axis.message=INFO
</pre>cuts down the number of a log entries produced by a single request to a manageable number.<br>
</li>
<li>
<strong>log4j.appender.<em>appender</em>.Threshold=<em>priority</em></strong> Log4J <em>appenders</em> correspond to different output devices: console, files, sockets, and others. If appender's <em>threshold</em> is less than or equal to the message priority then the message is written by that appender. This allows different levels of detail to be appear at different log destinations. <p>For example: one can capture DEBUG (and higher) level information in a logfile, while limiting console output to INFO (and higher).</p>
</li>
</ul>
<div class="h5">
<h5>Axis Servlet Query String Plug-ins</h5>
</div>
<p>Any servlet that is derived from the <span class="codefrag">org.apache.axis.transport.http.AxisServlet</span> class supports a number of standard query strings (<em>?list</em>, <em>?method</em>, and <em>?wsdl</em>) that provide information from or perform operations on a web service (for instance, <em>?method</em> is used to invoke a method on a web service and <em>?wsdl</em> is used to retrieve the WSDL document for a web service). Axis servlets are not limited to these three query strings and developers may create their own "plug-ins" by implementing the <span class="codefrag">org.apache.axis.transport.http.QSHandler</span> interface. There is one method in this interface that must be implemented, with the following signature:</p>
<pre>public void invoke (MessageContext msgContext) throws AxisFault;
</pre>
<p>The <span class="codefrag">org.apache.axis.MessageContext</span> instance provides the developer with a number of useful objects (such as the Axis engine instance, and HTTP servlet objects) that are accessible by its <span class="codefrag">getProperty</span> method. The following constants can be used to retrieve various objects provided by the Axis servlet invoking the query string plug-in:</p>
<ul>
<li>
<strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_NAME</strong>
<br> A <span class="codefrag">String</span> containing the name of the query string plug-in. For instance, if the query string <em>?wsdl</em> is provided, the name of the plugin is <em>wsdl</em>.<br>
<br>
</li>
<li>
<strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_SERVICE_NAME</strong>
<br> A <span class="codefrag">String</span> containing the name of the Axis servlet that inovked the query string plug-in.<br>
<br>
</li>
<li>
<strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_IS_DEVELOPMENT</strong>
<br> A <span class="codefrag">Boolean</span> containing <span class="codefrag">true</span> if this version of Axis is considered to be in development mode, <span class="codefrag">false</span> otherwise.<br>
<br>
</li>
<li>
<strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_ENABLE_LIST</strong>
<br> A <span class="codefrag">Boolean</span> containing <span class="codefrag">true</span> if listing of the Axis server configuration is allowed, <span class="codefrag">false</span> otherwise.<br>
<br>
</li>
<li>
<strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_ENGINE</strong>
<br> A <span class="codefrag">org.apache.axis.server.AxisServer</span> object containing the engine for the Axis server.<br>
<br>
</li>
<li>
<strong>org.apache.axis.transport.http.HTTPConstants.MC_HTTP_SERVLETREQUEST</strong>
<br> The <span class="codefrag">javax.servlet.http.HttpServletRequest</span> object from the Axis servlet that invoked the query string plug-in<br>
<br>
</li>
<li>
<strong>org.apache.axis.transport.http.HTTPConstants.MC_HTTP_SERVLETRESPONSE</strong>
<br> The <span class="codefrag">javax.servlet.http.HttpServletResponse</span> object from the Axis servlet that invoked the query string plug-in<br>
<br>
</li>
<li>
<strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_WRITER</strong>
<br> The <span class="codefrag">java.io.PrintWriter</span> object from the Axis servlet that invoked the query string plug-in<br>
<br>
</li>
<li>
<strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_LOG</strong>
<br> The <span class="codefrag">org.apache.commons.logging.Log</span> object from the Axis servlet that invoked the query string plug-in, which is used to log messages.<br>
<br>
</li>
<li>
<strong>org.apache.axis.transport.http.HTTPConstants.PLUGIN_EXCEPTION_LOG</strong>
<br> The <span class="codefrag">org.apache.commons.logging.Log</span> object from the Axis servlet that invoked the query string plug-in, which is used to log exceptions.<br>
<br>
</li>
</ul>
<p>Query string plug-in development is much like normal servlet development since the same basic information and methods of output are available to the developer. Below is an example query string plug-in which simply displays the value of the system clock (<span class="codefrag">import</span> statements have been omitted for brevity):</p>
<pre>public class QSClockHandler implements QSHandler {
public void invoke (MessageContext msgContext) throws AxisFault {
PrintWriter out = (PrintWriter) msgContext.getProperty (HTTPConstants.PLUGIN_WRITER);
HttpServletResponse response = (HttpServletResponse)
msgContext.getProperty (HTTPConstants.MC_HTTP_SERVLETRESPONSE);
response.setContentType ("text/html");
out.println ("&lt;HTML&gt;&lt;BODY&gt;&lt;H1&gt;" + System.currentTimeMillis()
+ "&lt;/H1&gt;&lt;/BODY&gt;&lt;/HTML&gt;");
}
}
</pre>
<p>Once a query string plug-in class has been created, the Axis server must be set up to recognize the query string which invokes it. See the section <a href="#reference.html#Deployment">Deployment (WSDD) Reference</a> in the <a href="#reference.html">Axis Reference Guide</a> for information on how the HTTP transport section of the Axis server configuration file must be set up.</p>
<div class="h5">
<h5>Configuration Properties</h5>
</div>
<p>Axis is in the process of moving away from using system properties as the primary point of internal configuration. Avoid calling <span class="codefrag">System.getProperty()</span>, and instead call <span class="codefrag">AxisProperties.getProperty</span>. <span class="codefrag">AxisProperties.getProperty</span> will call <span class="codefrag">System.getProperty</span>, and will (eventually) query other sources of configuration information.</p>
<p>Using this central point of access will allow the global configuration system to be redesigned to better support multiple Axis engines in a single JVM.</p>
<div class="h5">
<h5>Exception Handling</h5>
</div>
<p>Guidelines for Axis exception handling are based on best-practices for exception handling. While there are details specific to Axis in these guidelines, they apply in principle to any project; they are included here for two reasons. First, because they are not listed elsewhere in the Apache/Jakarta guidelines (or haven't been found). Second, because adherence to these guidelines is considered crucial to enterprise ready middleware.</p>
<p>These guidelines are fundamentally independent of programming language. They are based on experience, but proper credit must be given to <em>More Effective C++</em>, by Scott Meyers, for opening the eyes of the innocent(?) many years ago.</p>
<p>Finally, these are guidelines. There will always be exceptions to these guidelines, in which case all that can be asked (as per these guidelines) is that they be logged in the form of comments in the code.</p>
<ul>
<li>
<h3>Primary Rule: Only Catch An Exception If You Know What To Do With It</h3>
</li>
<li style="list-style: none">If code catches an exception, it should know what to do with it at that point in the program. Any exception to this rule must be documented with a GOOD reason. Code reviewers are invited to put on their vulture beaks and peck away... <p>There are a few corollaries to this rule.</p>
<ul>
<li>
<h4>Handle Specific Exceptions in Inner Code</h4>
</li>
<li style="list-style: none">Inner code is code <em>deep</em> within the program. Such code should catch specific exceptions, or categories of exceptions (parents in exception hierarchies), <u>if and only if</u> the exception can be resolved and normal flow restored to the code. Note that behaviour of this sort may be significantly different between non-interactive code versus an interactive tool.</li>
<li>
<h4>Catch All Exceptions in Outermost Flow of Control</h4>
</li>
<li style="list-style: none">Ultimately, all exceptions must be dealt with at one level or another. For command-line tools, this means the <span class="codefrag">main</span> method or program. For a middleware component, this is the entry point(s) into the component. For Axis this is <span class="codefrag">AxisServlet</span> or equivalent. <p>After catching specific exceptions which can be resolved internally, the outermost code must ensure that all internally generated exceptions are caught and handled. While there is generally not much that can be done, at a minimum the code should <u>log the exception</u>. In addition to logging, the Axis Server wraps all such exceptions in AxisFaults and returns them to the client code.</p>
<p>This may seem contrary to the primary rule, but in fact we are claiming that Axis does know what to do with this type of exception: exit gracefully.</p>
</li>
</ul>
</li>
<li>
<h3>Catching and Logging Exceptions</h3>
</li>
<li style="list-style: none">When an Exception is going to cross a component boundry (client/server, or system/business logic), the exception must be caught and logged by the throwing component. It may then be rethrown, or wrapped, as described below. <p>When in doubt, log the exception.</p>
<ul>
<li>
<h4>Catch and Throw</h4>
</li>
<li style="list-style: none">If an exception is caught and rethrown (unresolved), logging of the exception is at the discretion of the coder and reviewers. If any comments are logged, the exception should also be logged. <p>When in doubt, log the exception and any related local information that can help to identify the complete context of the exception.</p>
<p>Log the exception as an <em>error</em> (<span class="codefrag">log.error()</span>) if it is known to be an unresolved or unresolvable error, otherwise log it at the <em>informative</em> level (<span class="codefrag">log.info()</span>).</p>
</li>
<li>
<h4>Catch and Wrap</h4>
</li>
<li style="list-style: none">When exception <span class="codefrag">e</span> is caught and wrapped by a new exception <span class="codefrag">w</span>, log exception <span class="codefrag">e</span> before throwing <span class="codefrag">w</span>. <p>Log the exception as an <em>error</em> (<span class="codefrag">log.error()</span>) if it is known to be an unresolved or unresolvable error, otherwise log it at the <em>informative</em> level (<span class="codefrag">log.info()</span>).</p>
</li>
<li>
<h4>Catch and Resolve</h4>
</li>
<li style="list-style: none">When exception <span class="codefrag">e</span> is caught and resolved, logging of the exception is at the discretion of the coder and reviewers. If any comments are logged, the exception should also be logged (<span class="codefrag">log.info()</span>). Issues that must be balanced are performance and problem resolvability. <p>Note that in many cases, ignoring the exception may be appropriate.</p>
</li>
</ul>
</li>
<li>
<h3>Respect Component Boundries</h3>
</li>
<li style="list-style: none">There are multiple aspects of this guideline. On one hand, this means that business logic should be isolated from system logic. On the other hand, this means that client's should have limited exposure/visibility to implementation details of a server - particularly when the server is published to outside parties. This implies a well designed server interface. <ul>
<li>
<h4>Isolate System Logic from Business Logic</h4>
</li>
<li style="list-style: none">Exceptions generated by the Axis runtime should be handled, where possible, within the Axis runtime. In the worst case the details of an exception are to be logged by the Axis runtime, and a generally descriptive Exception raised to the Business Logic. <p>Exceptions raised in the business logic (this includes the server and Axis handlers) must be delivered to the client code.</p>
</li>
<li>
<h4>Protect System Code from User Code</h4>
</li>
<li style="list-style: none">Protect the Axis runtime from uncontrolled user business logic. For Axis, this means that dynamically configurable <span class="codefrag">handlers</span>, <span class="codefrag">providers</span> and other user controllable hook-points must be guarded by <span class="codefrag">catch(Exception ...)</span>. Exceptions generated by user code and caught by system code should be: <ul>
<li>Logged, and</li>
<li>Delivered to the client program</li>
</ul>
</li>
<li>
<h4>Isolate Visibility into Server from Client</h4>
</li>
<li style="list-style: none">Specific exceptions should be logged at the server side, and a more general exception thrown to the client. This prevents clues as to the nature of the server (such as handlers, providers, etc) from being revealed to client code. The Axis component boundries that should be respected are: <ul>
<li>Client Code &lt;--&gt; AxisClient</li>
<li>AxisClient &lt;--&gt; AxisServlet (AxisServer/AxisEngine)</li>
<li>AxisServer/AxisEngine &lt;--&gt; Web Service</li>
</ul>
</li>
</ul>
</li>
<li>
<h3>Throwing Exceptions in Constructors</h3>
</li>
<li style="list-style: none">Before throwing an exception in a constructor, ensure that any resources owned by the object are cleaned up. For objects holding resources, this requires catching <u>all</u> exceptions thrown by methods called within the constructor, cleaning up, and rethrowing the exceptions.</li>
</ul>
<div class="h5">
<h5>Compile and Run</h5>
</div>
<p>The <tt>xml-axis/java/build.xml</tt> file is the primary 'make' file used by ant to build the application and run the tests. The <tt>build.xml</tt> file defines ant build <em>targets</em>. Read the build.xml file for more information. Here are some of the useful targets:<br>
</p>
<ul>
<li>
<tt>compile -&gt; compiles the source and creates xml-axis/java/build/lib/axis.jar</tt>
</li>
<li>
<tt>javadocs -&gt; creates the javadocs in xml-axis/java/build/javadocs</tt>
</li>
<li>
<tt>functional-tests -&gt; compiles and runs the functional tests</tt>
</li>
<li>
<tt>all-tests -&gt; compiles and runs all of the tests</tt>
</li>
<li style="list-style: none">
<br>
</li>
</ul>
<p>To compile the source code:</p>
<pre class="code">cd xml-axis/java ant compile</pre>
<p>To run the tests:</p>
<pre class="code">cd xml-axis/java ant functional-tests</pre>
<p>
<strong>Note:</strong> these tests start a server on port 8080. If this clashes with the port used by your web application server (such as Tomcat), you'll need to change one of the ports or stop your web application server when running the tests.</p>
<p>
<strong>Please run ant functional-tests and ant all-tests before checking in new code.</strong>
</p>
<div class="h5">
<h5>Internationalization</h5>
</div>
<p>If you make changes to the source code that results in the generation of text (error messages or debug information), you must follow the following guidelines to ensure that your text is properly translated.</p>
<div class="h5">
<h5>Developer Guidelines</h5>
</div>
<ol>
<li>Your text string should be added as a property to the resource.properties file (xml-axis/java/src/org/apache/axis/i18n/resource.properties). Note that some of the utility applications (i.e. tcpmon) have their own resource property files (tcpmon.properties).</li>
<li style="list-style: none">
<br>
</li>
<li>The resource.properties file contains translation and usage instructions. Entries in a message resource file are of the form &lt;key&gt;=&lt;message&gt;. Here is an example message:</li>
<li style="list-style: none">
<p>sample00=My name is {0}, and my title is {1}.<br>
</p>
<ol>
<li>sample00 is the key that the code will use to access this message.</li>
<li>The text after the = is the message text.</li>
<li>The {<em>number</em>} syntax defines the location for inserts.</li>
</ol>
</li>
<li>The code should use the static method org.apache.axis.i18n.Messages.getMessage to obtain the text and add inserts. Here is an example usage:</li>
<li style="list-style: none">
<p>Messages.getMessage("sample00", "Rich Scheuerle", "Software Developer");<br>
</p>
</li>
<li>All keys in the properties file should use the syntax &lt;string&gt;&lt;2-digit-suffix&gt;.</li>
<li style="list-style: none">
<br>
<ol>
<li>
<strong>Never change the message text in the properties file.</strong> The message may be used in multiple places in the code. Plus translation is only done on new keys.</li>
<li style="list-style: none">
<br>
</li>
<li>If a code change requires a change to a message, create a new entry with an incremented 2-digit suffix.</li>
<li style="list-style: none">
<br>
</li>
<li>All new entries should be placed at the bottom of the file to ease translation.</li>
<li style="list-style: none">
<br>
</li>
<li>We may occasionally want to trim the properties file of old data, but this should only be done on major releases.</li>
</ol>
</li>
</ol>
<div class="h5">
<h5>Example</h5>
</div>
<p>Consider the following statement:</p>
<p>
<span class="codefrag">if ( operationName == null )</span>
<br>
<span class="codefrag">throw new AxisFault( "No operation name specified" );</span>
</p>
<p>We will add an entry into org/apache/axis/i18n/resource.properties:</p>
<p>
<span class="codefrag">noOperation=No operation name specified.</span>
</p>
<p>And change the code to read:</p>
<p>
<span class="codefrag">if ( operationName == null )</span>
<br>
<span class="codefrag">throw new AxisFault(Messages.getMessage("noOperation"));</span>
</p>
<div class="h5">
<h5>Interface</h5>
</div>
<p>Axis uses the standard Java internationalization class <span class="codefrag">java.util.ResourceBundle</span> to access property files and message strings, and uses <span class="codefrag">java.text.MessageFormat</span> to format the strings using variables. Axis provides a single class <span class="codefrag">org.apache.axis.i18n.Messages</span> that manages both ResourceBundle and MessageFormat classes. Messages methods are:</p>
<p>
<span class="codefrag">public static java.util.ResourceBundle getResourceBundle();</span>
</p>
<p>
<span class="codefrag">public static String getMessage(String key) throws java.util.MissingResourceException;</span>
</p>
<p>
<span class="codefrag">public static String getMessage(String key, String var) throws java.util.MissingResourceException;</span>
</p>
<p>
<span class="codefrag">public static String getMessage(String key, String var1, String var2) throws java.util.MissingResourceException;</span>
</p>
<p>
<span class="codefrag">public static String getMessage(String key, String[] vars) throws java.util.MissingResourceException;</span>
</p>
<p>Axis programmers can work with the resource bundle directly via a call to <span class="codefrag">Messages.getResourceBundle()</span>, but the <span class="codefrag">getMessage()</span> methods should be used instead for two reasons:</p>
<ol>
<li>It's a shortcut. It is cleaner to call</li>
<li style="list-style: none">
<span class="codefrag">Messages.getMessage("myMsg00");</span>than <span class="codefrag">Messages.getResourceBundle().getString("myMsg00");</span>
<br>
</li>
<li>The <span class="codefrag">getMessage</span> methods enable messages with variables.</li>
</ol>
<div class="h5">
<h5>The getMessage methods</h5>
</div>
<p>If you have a message with no variables</p>
<span class="codefrag">myMsg00=This is a string.</span>
<p>then simply call</p>
<span class="codefrag">Messages.getMessage("myMsg00");</span>
<p>
<br> If you have a message with variables, use the syntax "{X}" where <span class="codefrag">X</span> is the number of the variable, starting at 0. For example:</p>
<span class="codefrag">myMsg00=My {0} is {1}.</span>
<p>then call:</p>
<span class="codefrag">Messages.getMessage("myMsg00","name", "Russell");</span>
<p>and the resulting string will be: "My name is Russell."</p>
<p>You could also call the String array version of getMessage:</p>
<span class="codefrag">Messages.getMessage("myMsg00", new String[] {"name", "Russell"});</span>
<p>
<br> The String array version of getMessage is all that is necessary, but the vast majority of messages will have 0, 1 or 2 variables, so the other getMessage methods are provided as a convenience to avoid the complexity of the String array version.</p>
<p>Note that the getMessage methods throw MissingResourceException if the resource cannot be found. And ParseException if there are more {X} entries than arguments. These exceptions are RuntimeException's, so the caller doesn't have to explicitly catch them.</p>
<p>The resource bundle properties file is org/apache/axis/i18n/resource.properties.</p>
<div class="h5">
<h5>Extending Message Files</h5>
</div>
<p>Generally, within Axis all messages are placed in org.apache.axis.i18n.resource.properties. There are facilities for extending the messages without modifying this file for integration or 3rd party extensions to Axis. See the <a href="#integration-guide.html#Extending%20Message%20Files">Integration Guide for details.</a>
</p>
<div class="h5">
<h5>Creating a WSDL Test</h5>
</div>
<p>Here are the steps that I used to create the <tt>sequence</tt> test, which generates code from a wsdl file and runs a sequence validation test:<br>
</p>
<ol>
<li>Created a <tt>xml-axis/java/test/wsdl/sequence</tt> directory.</li>
<li style="list-style: none">
<br>
</li>
<li>Created a <tt>SequenceTest.wsdl</tt> file defining the webservice.</li>
<li style="list-style: none">
<br>
</li>
<li>Ran the Wsdl2java emitter to create Java files:</li>
<li style="list-style: none">
<p>
<tt>java org.apache.axis.wsdl.Wsdl2java -t -s SequenceTest.wsdl</tt>
</p>
<ol>
<li>The -t option causes the emitter to generate a *TestCase.java file that hooks into the test harness. This file is operational without any additional changes. Copy the *TestCase.java file into the same directory as your wsdl file. (Ideally only the Java files that are changed need to be in your directory.) So this file is not needed, but please make sure to modify your &lt;wsdl2java ...&gt; clause (described below) to emit a testcase.</li>
<li>The -s option causes the emitter to generate a *SOAPBindingImpl.java file. The Java file contains empty methods for the service. You probably want to fill them in with your own logic. Copy the *SOAPBindingImpl.java file into the same directory as your wsdl file. (If no changes are needed in the Java file, you don't need to save it. But you will need to make sure that your &lt;wsdl2java ...&gt; clause generates a skeleton).</li>
<li>Remove all of the Java files that don't require modification. So you should have three files in your directory (wsdl file, *TestCase.java, and *SOAPBindingImpl.java). My sequence test has an another file due to some additional logic that I needed.</li>
</ol>
<br>
</li>
<li>The <tt>test/wsdl/sequence/build.xml</tt> file controls the building of this test. Locate the "compile" target. Add a clause that runs the Wsdl2java code. I would recommend stealing something from the test/wsdl/roundtrip/build.xml file (it does a LOT of wsdl2java and java2wsdl calls). Here is the one for SequenceTest:</li>
<li style="list-style: none">
<p>
<tt> &lt;!-- Sequence Test --&gt;</tt>
<br>
<tt>&lt;wsdl2java url="${axis.home}/test/wsdl/sequence/SequenceTest.wsdl"</tt>
<br>
<tt>output="${axis.home}/build/work"</tt>
<br>
<tt>deployscope="session"</tt>
<br>
<tt>skeleton="yes"</tt>
<br>
<tt>messagecontext="no"</tt>
<br>
<tt>noimports="no"</tt>
<br>
<tt>verbose="no"</tt>
<br>
<tt>testcase="no"&gt;</tt>
<br>
<tt>&lt;mapping namespace="urn:SequenceTest2" package="test.wsdl.sequence"/&gt;</tt>
<br>
<tt>&lt;/wsdl2java&gt;</tt>
</p>
</li>
<li>Enable the run target in the new build.xml file. You need to choose from the execute-Component and the (soon to be introduced) execute-Simple-Test target. These control HOW the test is invoked when run as a single component. The execute-Component sets up the tcp-server and http-server prior to running the test, as well as handles deploying and services that may be needed. The execute-Simple-test simply invokes the raw test class file.<br>
<br>
</li>
<li>Done. Run <tt>ant functional-tests</tt> to verify. Check in your test.</li>
<li style="list-style: none">
<br>
</li>
</ol>
<div class="h5">
<h5>Using tcpmon to Monitor Functional Tests.</h5>
</div>
<p>Here is an easy way to monitor the messages while running <span class="codefrag">functional-tests</span> (or <span class="codefrag">all-tests</span>).<br> Start up tcpmon listening on 8080 and forwarding to a different port:</p>
<pre class="code">java org.apache.axis.utils.tcpmon 8080 localhost 8011</pre>
<p>Run your tests, but use the forwarded port for the SimpleAxisServer, and indicate that functional-tests should continue if a failure occurs.</p>
<pre class="code">ant functional-tests -Dtest.functional.SimpleAxisPort=8011 -Dtest.functional.fail=no</pre>
<p>The SOAP messages for all of the tests should appear in the tcpmon window.</p>
<p>
<span class="codefrag">tcpmon</span> is described in more detail in the <a href="#user-guide.html#tcpmon">Axis User's Guide</a>.</p>
<div class="h5">
<h5>Using SOAP Monitor to Monitor Functional Tests.</h5>
</div>
<p>If you are debugging code that is running as a web application using a web application server (such as Tomcat) then you may also use the SOAP Monitor utility to view the SOAP request and response messages.<br> Start up the SOAP monitor utility by loading the SOAP monitor applet in your web browser window:</p>
<pre class="code">http://localhost:&lt;port&gt;/axis/SOAPMonitor</pre>
<p>As you run your tests, the SOAP messages should appear in the SOAP monitor window.</p>
<p>
<span class="codefrag">SOAP Monitor</span> is described in more detail in the <a href="#user-guide.html#soapmon">Axis User's Guide</a>.</p>
<div class="h5">
<h5>Running a Single Functional Test</h5>
</div>
<p>In one window start the server:</p>
<pre class="code">java org.apache.axis.transport.http.SimpleAxisServer -p 8080</pre>
<p>In another window, first deploy the service you're testing:</p>
<pre class="code">java org.apache.axis.client.AdminClient deploy.wsdd</pre>
<p>Then bring up the JUnit user interface with your test. For example, to run the the multithread test case:</p>
<pre class="code">java junit.swingui.TestRunner -noloading test.wsdl.multithread.MultithreadTestCase</pre>
<div class="h5">
<h5>Turning on Debug Output</h5>
</div>
<p>This section is oriented to the Axis default logger: Log4J. For additional information on Log4J, see the section <a href="##Configuring%20the%20Logger">Configuring the Logger</a>.</p>
<ul>
<li>
<h5>Overriding Log4J properties</h5>
</li>
<li style="list-style: none">The <span class="codefrag">log4j.properties</span> file is packaged in <span class="codefrag">axis.jar</span> with reasonable default settings. Subsequent items presume changes to these settings. There are multiple options open to the developer, most of which involve extracting <span class="codefrag">log4j.properties</span> from <span class="codefrag">axis.jar</span> and modifying as appropriate. <ul>
<li>If you are building and executing <span class="codefrag">Java</span> programs from a command line or script file, include the JVM option <span class="codefrag">-Dlog4j.configuration=yourConfigFile</span>.</li>
<li>Set <span class="codefrag">CLASSPATH</span> such that your version of <span class="codefrag">log4j.properties</span> appears prior to <span class="codefrag">axis.jar</span> in the <span class="codefrag">CLASSPATH</span>.</li>
<li>If you are building and executing your programs using <span class="codefrag">ant</span> (this includes building Axis and running it's tests), set the environment variable <span class="codefrag">ANT_OPTS</span> to <span class="codefrag">-Dlog4j.configuration=yourConfigFile</span>.</li>
<li>If you are building Axis, you can change <span class="codefrag">src/log4j.properties</span> directly. Be sure NOT to commit your change(s).</li>
</ul>
<br>
</li>
<li>
<h5>Turning on ALL DEBUG Output</h5>
</li>
<li style="list-style: none">
<ul>
<li>Set the <span class="codefrag">log4j.rootCategory</span> <em>priority</em> to <span class="codefrag">DEBUG</span>.</li>
<li>Set the <em>priority</em> threshold for an appender to <span class="codefrag">DEBUG</span> (The <span class="codefrag">log4j.properties</span> file in Axis defines two appenders: <span class="codefrag">CONSOLE</span> and <span class="codefrag">LOGFILE</span>).</li>
</ul>
<br>
</li>
<li>
<h5>Selective DEBUG Output</h5>
</li>
<li style="list-style: none">
<ul>
<li>Set the <span class="codefrag">log4j.rootCategory</span> <em>priority</em> to <span class="codefrag">INFO</span> or higher.</li>
<li>Set the <span class="codefrag">log4j.logger.logger.name</span> <em>priority</em> to <span class="codefrag">DEBUG</span> for the loggers that you are interested in.</li>
<li>Set the <em>priority</em> threshold for an appender to <span class="codefrag">DEBUG</span> (The <span class="codefrag">log4j.properties</span> file in Axis defines two appenders: <span class="codefrag">CONSOLE</span> and <span class="codefrag">LOGFILE</span>).</li>
<li>If you are still seeing more than you want to see, you will need to use other tools to extract the information you are interested in from the log output. Use appropriate key words in log messages and use tools such as <span class="codefrag">grep</span> to search for them in log messages.</li>
</ul>
</li>
</ul>
<div class="h5">
<h5>Writing Temporary Output</h5>
</div>
<p>Remember that Axis is targeted for use in a number of open-source and other web applications, and so it needs to be a good citizen. Writing output using <span class="codefrag">System.out.println</span> or <span class="codefrag">System.err.println</span> should be avoided.</p>
<p>Developers may be tempted to use <span class="codefrag">System.out.println</span> while debugging or analyzing a system. If you choose to do this, you will need to disable the <span class="codefrag">util/TestSrcContent</span> test, which enforces avoidance of <span class="codefrag">System.out.println</span> and <span class="codefrag">System.err.println</span>. It follows that you will need to remove your statements before checking the code back in.</p>
<p>As an alternative, we strongly encourage you to take a few moments and introduce debug statements: <span class="codefrag">log.debug("reasonably terse and meaningful message")</span>. If a debug message is useful for understanding a problem now, it may be useful again in the future to you or a peer.</p>
<div class="h5">
<h5>Adding Testcases</h5>
</div>
<p>See Also: <a href="##TestStructure">Test and Samples Structure</a>
</p>
<p>
<strong>Editor's Note:</strong> We need more effort to streamline and simplify the addition of tests. We also need to think about categorizing tests as the test bucket grows.<br>
</p>
<p>If you make changes to Axis, please add a test that uses your change. Why?</p>
<ul>
<li>The test validates that your new code works.</li>
<li>The test protects your change from bugs introduced by future code changes.</li>
<li>The test is an example to users of the features of Axis.</li>
<li>The test can be used as a starting point for new development.</li>
</ul>
<p>
<br> Some general principles:</p>
<ul>
<li>Tests should be self-explanatory.</li>
<li>Tests should not generate an abundance of output</li>
<li>Tests should hook into the existing junit framework.</li>
<li>Each test or group of related tests should have its own directory in the <tt>xml-axis/java/test</tt> directory</li>
</ul>
<p>
<br> One way to build a test is to "cut and paste" the existing tests, and then modify the test to suit your needs. This approach is becoming more complicated as the different kinds of tests grow.</p>
<p>A good "non-wsdl" test for reference is test/saaj.</p>
<div class="h5">
<h5>Test Structure</h5>
</div>
<p>
<a href="#AxisTestRedesign.html">The Test and Samples Redesign Document is here</a>
</p>
<p>As of Axis 1.0, RC1, we have moved to a "componentized" test structure. Instead of having one high-level large recursive function, there are smaller, simple "component" build.xml files in the leaf level of the test/** and samples/** trees.</p>
<p>These "component" files have a common layout. Their primary targets are:</p>
<ul>
<li>clean - reset the build destination(s)</li>
<li>compile - javac, wsdl2java, java2wsdl instructions</li>
<li>run - "executes" the test</li>
</ul>
<br>
<p>A "sample" test xml file can be found in test/templateTest</p>
<div class="h5">
<h5>Adding Source Code Checks</h5>
</div>
<p>The Axis build performs certain automated checks of the files in the source directory (java/src) to make sure certain conventions are followed such as using internationalised strings when issuing messages.</p>
<p>If a convention can be reduced to a regular expression match, it can be enforced at build time by updating java/test/utils/TestSrcContent.java.</p>
<p>All that is necessary is to add a pattern to the static FileNameContentPattern array. Each pattern has three parameters:</p>
<ol>
<li>a pattern that matches filenames that are to be checked,</li>
<li>a pattern to be searched for in the chosen files, and</li>
<li>a boolean indicating whether the pattern is to be allowed (typically false indicating not allowed).</li>
</ol>
<p>A reasonable summary of the regular expression notation is provided in the <a href="http://jakarta.apache.org/oro/api/org/apache/oro/text/regex/package-summary.html">Jakarta ORO javadocs</a>.</p>
<div class="h5">
<h5>JUnit and Axis</h5>
</div>
<p>You try to run some JUnit tests on an Axis client that invokes a web service, and you always get this exception:</p>
<pre>
java.lang.ExceptionInInitializerError
at org.apache.axis.client.Service.&lt;init&gt;(Service.java:108)
...
Caused by: org.apache.commons.logging.LogConfigurationException: ...
org.apache.commons.logging.impl.Jdk14Logger does not implement Log
at org.apache.commons.logging.impl.LogFactoryImpl.newInstance
(LogFactoryImpl.java:555)
...
</pre>
<p>Actually, the Jdk14Logger does implement Log. What you have is a JUnit classloading issue. JUnit's graphical TestRunner has a feature where it will dynamically reload modified classes every time the user presses the "Run" button. This way, the user doesn't need to relaunch the TestRunner after every edit. For this, JUnit uses its own classloader, junit.runner.TestCaseClassLoader. As of JUnit 3.8.1, confusion can arise between TestCaseClassLoader and the system class loader as to which loader did or should load which classes.</p>
<p>There are two ways to avoid this problem.</p>
<ul>
<li>Sure and simple fix. Turn off dynamic class reloading by running junit.swingui.TestRunner with the -noloading argument.</li>
<li>Finicky and fancy fix, only necessary if you want dynamic class reloading. Tell TestCaseClassLoader to ignore certain packages and their sub-packages, deferring them to the system classloader. You can do this using a file located in junit.jar, junit/runner/excluded.properties. Its content appears as follows: <pre>#
# The list of excluded package paths for the TestCaseClassLoader
#
excluded.0=sun.*
excluded.1=com.sun.*
excluded.2=org.omg.*
excluded.3=javax.*
excluded.4=sunw.*
excluded.5=java.*
excluded.6=org.w3c.dom.*
excluded.7=org.xml.sax.*
excluded.8=net.jini.*
</pre>
</li>
</ul>
<p>Copy this file, preserving the directory path, into another location, e.g. deployDir. So the copied properties file's path will be deployDir/junit/runner/excluded.properties. Add an extra entry to the end of this file:</p>
<pre>excluded.9=org.apache.*
</pre>
<p>Edit your classpath so that deployDir appears before junit.jar. This way, the modified excluded.properties will be used, rather than the default. (Don't add the path to excluded.properties itself to the classpath.)</p>
<p>This fix will prevent the commons-logging exception. However, other classloading problems might still arise. For example:</p>
<pre>Dec 10, 2002 7:16:16 PM org.apache.axis.encoding.ser.BeanPropertyTarget set
SEVERE: Could not convert [Lfoo.bar.Child; to bean field 'childrenAsArray',
type [Lfoo.bar.Child;
Dec 10, 2002 7:16:16 PM org.apache.axis.client.Call invoke
SEVERE: Exception:
java.lang.IllegalArgumentException: argument type mismatch
at org.apache.axis.encoding.ser.BeanPropertyTarget.set
(BeanPropertyTarget.java:182)
at org.apache.axis.encoding.DeserializerImpl.valueComplete
(DeserializerImpl.java:284)
...
</pre>
<p>In this case, you have no choice but to give up on dynamic class reloading and use the -noloading argument.</p>
<p>One other heads-up about JUnit testing of an Axis web service. Suppose you have run JUnit tests locally on the component that you want to expose as a web service. You press the "Run" button to initiate a series of tests. Between each test, all your data structures are re-initialized. Your tests produce a long green bar. Good.</p>
<p>Suppose you now want to run JUnit tests on an Axis client that is connecting to an application server running the Axis web application and with it your web service. Between each test, JUnit will automatically re-initialize your client.</p>
<p>Your server-side data structures are a different matter. If you're checking your server data at the end of each test (as you should be) and you run more than one test at a time, the second and later tests will fail because they are generating cumulative data on the Axis server based on preceding tests rather than fresh data based only on the current one.</p>
<p>This means that, for each test, you must manually re-initialize your web service. One way to accomplish this is to add to your web service interface a re-initialize operation. Then have the client call that operation at the start of each test.</p>
<div class="h5">
<h5>Debugging</h5>
</div>
<div class="h5">
<h5>Running the JAX-RPC Compatibility Tests</h5>
</div>
<p>As well as a specification, JAX-RPC has a Technology Compatibility Kit (TCK) which is available to members of the JAX-RPC Expert Group (and others?).</p>
<p>The kit comes as a zip file which you should unzip into a directory of your choosing. The installation instructions are in the JAX-RPC Release Notes document which is stored in the docs directory. If you open the index.html file in the docs directory using a web browser, you'll see a list of all the documents supplied with the kit.</p>
<p>Note that the kit includes the JavaTest test harness which is used for running the compatibility tests.</p>
<p>If any more information is needed about running these tests, please add it here!</p>
<div class="h2">
<h2>Axis System Integration Guide</h2>
</div>
<div class="h5">
<h5>Axis System Integration Guide</h5>
</div>
<p>
<em>1.2 Version</em>
<br>
<em>Feedback: axis-dev@ws.apache.org</em>
</p>
<div class="h5">
<h5>Introduction</h5>
</div>
<p>The primary purpose of this guide is to present how Axis can be integrated into an existing web application server, such as Tomcat or WebSphere, for example.&nbsp; Axis has a number of Pluggable APIs that are necessary for such an integration.</p>
<p>The reader may find useful background information in the <a href="#architecture-guide.html">Architecture Guide</a>.</p>
<div class="h5">
<h5>Pluggable APIs</h5>
</div>
<p>The following are the points that are pluggable in order to integrate Axis into a web application server. The first subsection details a number of pluggable components in general. More details are provided for other components in the remaining subsections.</p>
<div class="h5">
<h5>Components</h5>
</div>
<p>This section describes in general how to plug specializations of various components into Axis.</p>
<div class="h5">
<h5>General Strategy</h5>
</div>
<p>To override the default behavior for a pluggable component:</p>
<ul>
<li>Develop implementation of components interface</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>Define the implementation class to Axis by either creating a service definition file (prefered) or by setting a system property. <ul>
<li style="list-style: none">
<br>
</li>
<li>
<strong>PREFERED:</strong> To create a service definition file:</li>
<li style="list-style: none">
<ul>
<li>The name of the service definition file is derived from the interface or abstract class which the service implements/extends:<br> &nbsp;&nbsp; <span class="codefrag">/META-INF/services/&lt;componentPackage&gt;.&lt;interfaceName&gt;</span>.</li>
<li>Put the fully qualified class name of the implementation class on a line by itself in the service definition file.</li>
</ul>
<br>
</li>
<li>Set system property: <ul>
<li>The name of the system property is the name of the interface.</li>
<li>The value of the system property is the name of the implementation.</li>
<li>The optional system property name (in table, below) may be also be used.</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>Setting a system property is not prefered, particularly in a J2EE or other application hosting environment, because it imposes a directive across all applications. This may or may not be appropriate behavior. If it is to be done, it should never be done from within a Web Application at runtime.</li>
</ul>
</li>
</ul>
<br>
</li>
<li>Package the implementation class and, if used, the service definition file in a JAR file and/or place it where it can be picked up by a class loader (CLASSPATH).</li>
</ul>
<div class="h5">
<h5>Example 1</h5>
</div>
<p>To override the default behavior for the Java Compiler:</p>
<ul>
<li>An implementation of the <span class="codefrag">Compiler</span> interface is already provided for the <span class="codefrag">Jikes</span> compiler.</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>Create the service definition file named:<br> &nbsp;&nbsp; <span class="codefrag">/META-INF/services/org.apache.axis.components.compiler.Compiler</span>
</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>Add the following line to the service definition file:<br> &nbsp;&nbsp; <span class="codefrag">org.apache.axis.components.compiler.Jikes</span>
</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>Since <span class="codefrag">org.apache.axis.components.compiler.Jikes</span> is packaged with Axis, all that needs to be done is to ensure that the service definition file is loadable by a class loader.</li>
</ul>
<div class="h5">
<h5>Example 2</h5>
</div>
<p>To override the default behavior for the SocketFactory in an environment that does not allow resources to be located/loaded appropriately, or where the behavior needs to be forced to a specific implementation:</p>
<ul>
<li>Provide an implementation of the <span class="codefrag">SocketFactory</span> interface, for example <span class="codefrag">your.package.YourSocketFactory</span>
</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>Set the system property named<br> &nbsp;&nbsp; <span class="codefrag">org.apache.axis.components.net.SocketFactory</span>
<br> to the value<br> &nbsp;&nbsp; <span class="codefrag">your.package.YourSocketFactory</span>
<br>
<p>This can be done by using the JVM commandline<br> &nbsp;&nbsp; <span class="codefrag">-Dorg.apache.axis.components.net.SocketFactory=your.package.YourSocketFactory</span>
<br> &nbsp;</p>
</li>
<li>Ensure that the implementation class is loadable by a class loader.</li>
</ul>
<div class="h5">
<h5>Reference</h5>
</div>
<p>(Component/Package: org.apache.axis.components.*)</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<th>Component Package</th><th>Factory</th><th>Interface</th><th>Optional System Property</th><th>Default Implementation</th>
</tr>
<tr class="a">
<td><tt>compiler</tt></td><td><tt>CompilerFactory getCompiler()</tt></td><td><tt>Compiler</tt></td><td><tt>axis.Compiler</tt></td><td><tt>Javac</tt></td>
</tr>
<tr class="b">
<td><tt>image</tt></td><td><tt>ImageIOFactory getImageIO()</tt></td><td><tt>ImageIO</tt></td><td><tt>axis.ImageIO</tt></td><td><tt>MerlinIO, JimiIO, JDK13IO</tt></td>
</tr>
<tr class="a">
<td><tt>jms</tt></td><td><tt>JMSVendorAdapterFactory getJMSVendorAdapter()</tt></td><td><tt>JMSVendorAdapter</tt></td><td></td><td><tt>JNDIVendorAdapter</tt></td>
</tr>
<tr class="b">
<td><tt>net</tt></td><td><tt>SocketFactoryFactory getFactory()</tt></td><td><tt>SocketFactory</tt></td><td><tt>axis.socketFactory</tt></td><td><tt>DefaultSocketFactory</tt></td>
</tr>
<tr class="a">
<td><tt>net</tt></td><td><tt>SocketFactoryFactory getSecureFactory()</tt></td><td><tt>SecureSocketFactory</tt></td><td><tt>axis.socketSecureFactory</tt></td><td><tt>JSSESocketFactory</tt></td>
</tr>
</table>
<div class="h5">
<h5>Logging/Tracing</h5>
</div>
<p>Axis logging and tracing is based on the Logging component of the <a href="http://jakarta.apache.org/commons/index.html">Jakarta Commons</a> project, or the Jakarta Commons Logging (JCL) SPI. The JCL provides a Log interface with thin-wrapper implementations for other logging tools, including <a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a>, <a href="http://jakarta.apache.org/avalon/logkit/index.html">Avalon LogKit</a>, and JDK 1.4. The interface maps closely to Log4J and LogKit.</p>
<div class="h5">
<h5>Justification/Rationale</h5>
</div>
<p>A pluggable logging/trace facility enables Axis to direct logging/trace messages to a host web application server's logging facility. A central logging facility with a single point of configuration/control is superior to distinct logging mechanisms for each of a multitude of middleware components that are to be integrated into a web application server.</p>
<div class="h5">
<h5>Integration</h5>
</div>
<p>The minimum requirement to integrate with another logger is to provide an implementation of the <span class="codefrag">org.apache.commons.logging.Log</span> interface. In addition, an implementation of the <span class="codefrag">org.apache.commons.logging.LogFactory</span> interface can be provided to meet specific requirements for connecting to, or instantiating, a logger.</p>
<ul>
<li>
<h5>org.apache.commons.logging.Log</h5>
</li>
<li style="list-style: none">The <span class="codefrag">Log</span> interface defines the following methods for use in writing log/trace messages to the log: <pre> log.fatal(Object message);
log.fatal(Object message, Throwable t);
log.error(Object message);
log.error(Object message, Throwable t);
log.warn(Object message);
log.warn(Object message, Throwable t);
log.info(Object message);
log.info(Object message, Throwable t);
log.debug(Object message);
log.debug(Object message, Throwable t);
log.trace(Object message);
log.trace(Object message, Throwable t);
log.isFatalEnabled();
log.isErrorEnabled();
log.isWarnEnabled();
log.isInfoEnabled();
log.isDebugEnabled();
log.isTraceEnabled();
</pre>
<p>Semantics for these methods are such that it is expected that the severity of messages is ordered, from highest to lowest:</p>
<ul>
<li>fatal - Consider logging to console and system log.</li>
<li>error - Consider logging to console and system log.</li>
<li>warn - Consider logging to console and system log.</li>
<li>info - Consider logging to console and system log.</li>
<li>debug - Log to system log, if enabled.</li>
<li>trace - Log to system log, if enabled.</li>
</ul>
<br> &nbsp;</li>
<li>
<h5>org.apache.commons.logging.LogFactory</h5>
</li>
<li style="list-style: none">If desired, the default implementation of the <span class="codefrag">org.apache.commons.logging.LogFactory</span> interface can be overridden, allowing the JDK 1.3 Service Provider discovery process to locate and create a LogFactory specific to the needs of the application. Review the Javadoc for the <span class="codefrag">LogFactoryImpl.java</span> for details.</li>
</ul>
<div class="h5">
<h5>Mechanism</h5>
</div>
<ul>
<li>
<h5>Life cycle</h5>
</li>
<li style="list-style: none">The JCL LogFactory implementation must assume responsibility for either connecting/disconnecting to a logging toolkit, or instantiating/initializing/destroying a logging toolkit.<br> &nbsp;</li>
<li>
<h5>Exception handling</h5>
</li>
<li style="list-style: none">The JCL Log interface doesn't specify any exceptions to be handled, the implementation must catch any exceptions.<br> &nbsp;</li>
<li>
<h5>Multiple threads</h5>
</li>
<li style="list-style: none">The JCL Log and LogFactory implementations must ensure that any synchronization required by the logging toolkit is met.</li>
</ul>
<div class="h5">
<h5>Logger Configuration</h5>
</div>
<ul>
<li>
<h5>Log</h5>
</li>
<li style="list-style: none">The default <span class="codefrag">LogFactory</span> provided by JCL can be configured to instantiate a specific implementation of the <span class="codefrag">org.apache.commons.logging.Log</span> interface by setting the property <span class="codefrag">org.apache.commons.logging.Log</span>. This property can be specified as a system property, or in the <span class="codefrag">commons-logging.properties</span> file, which must exist in the CLASSPATH.<br> &nbsp;</li>
<li>
<h5>Default logger if not plugged</h5>
</li>
<li style="list-style: none">The Jakarta Commons Logging SPI uses the implementation of the <span class="codefrag">org.apache.commons.logging.Log</span> interface specified by the system property <span class="codefrag">org.apache.commons.logging.Log</span>. If the property is not specified or the class is not available then the JCL provides access to a default logging toolkit by searching the CLASSPATH for the following toolkits, in order of preference: <ul>
<li>
<a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a>
</li>
<li>JDK 1.4</li>
<li>JCL SimpleLog</li>
</ul>
</li>
</ul>
<div class="h5">
<h5>Configuration</h5>
</div>
<p>
<br> The internal data model used by Axis is based on an Axis specific data model: Web Services Deployment Descriptor (WSDD). Axis initially obtains the WSDD information for a service from an instance of <span class="codefrag">org.apache.axis.EngineConfiguration</span>.</p>
<p>The EngineConfiguration is provided by an implementation of the interface <span class="codefrag">org.apache.axis.EngineConfigurationFactory</span>, which currently provides methods that return client and server configurations.</p>
<p>Our focus will be how to define the implementation class for <span class="codefrag">EngineConfigurationFactory</span>.</p>
<ul>
<li>Justification/Rationale</li>
<li style="list-style: none">
<br> While the default behaviour is sufficient for general use of Axis, integrating Axis into an existing application server may require an alternate deployment model. A customized implementation of the EngineConfigurationFactory would map from the hosts deployment model to Axis's internal deployment model.<br> &nbsp;</li>
<li>Mechanism</li>
<li style="list-style: none">
<br> The relevant sequence of instructions used to obtain configuration information and initialize Axis is as follows: <br>
<span class="codefrag">EngineConfigurationFactory factory = EngineConfigurationFactoryFinder(someContext);</span>
<br>
<span class="codefrag">EngineCongfiguration config = factory.getClientEngineConfig();</span>
<br>
<span class="codefrag">AxisClient = new AxisClient(config);</span>
<br> The details may vary (server versus client, whether other factories are involved, etc). Regardless, the point is that integration code is responsible for calling <span class="codefrag">EngineConfigurationFactoryFinder(someContext)</span> and ensuring that the results are handed to Axis.&nbsp; <span class="codefrag">someContext</span> is key to how the factory finder locates the appropriate implementation of EngineConfigurationFactory to be used, if any. <p>EngineConfigurationFactoryFinder works as follows:<br> &nbsp;</p>
<ul>
<li>Obtain a list of classes that implement <span class="codefrag">org.apache.axis.EngineConfigurationFactory</span>, in the following order: <ul>
<li>The value of the system property <span class="codefrag">axis.EngineConfigFactory</span>.</li>
<li>The value of the system property <span class="codefrag">org.apache.axis.EngineConfigurationFactory</span>.</li>
<li>Locate all resources named <span class="codefrag">META-INF/services/org.apache.axis.EngineConfigurationFactory</span>. Each line of such a resource identifies the name of a class implementing the interface ('#' comments, through end-of-line).</li>
<li>
<span class="codefrag">org.apache.axis.configuration.EngineConfigurationFactoryServlet</span>
</li>
<li>
<span class="codefrag">org.apache.axis.configuration.EngineConfigurationFactoryDefault</span>
</li>
</ul>
</li>
<li style="list-style: none">
<br>
</li>
<li>Classes implementing EngineConfigurationFactory are required to provide the method<br> &nbsp; <span class="codefrag">public static EngineConfigurationFactory newFactory(Object)</span>
<br> This method is called, passing <span class="codefrag">someContext</span> as the parameter.</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>The <span class="codefrag">newFactory</span> method is required to check the <span class="codefrag">someContext</span> parameter to determine if it is meaningfull to the class (at a minimum, verify that it is of an expected type, or class) and may, in addition, examine the overall runtime environment. If the environment can provide information required by an EngineConfigurationFactory, then the <span class="codefrag">newFactory()</span> may return in instance of that factory. Otherwise, <span class="codefrag">newFactory()</span> must return null.</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>EngineConfigurationFactoryFinder returns the first non-null factory it obtains.</li>
</ul>
<br> &nbsp;</li>
<li>Default behavior</li>
<li style="list-style: none">
<br> The default behaviour is provided by the last two elements of the list of implementing classes, as described above: <ul>
<li>
<span class="codefrag">org.apache.axis.configuration.EngineConfigurationFactoryServlet</span>
<br>
<span class="codefrag">newFactory(obj)</span> is called. If <span class="codefrag">obj instanceof javax.servlet.ServletContext</span> is true, then an instance of this class is returned. <p>The default Servlet factory is expected to function as a server (as a client it will incorrectly attempt to load the WSDD file <span class="codefrag">client-config.wsdd</span> from the current working directory!).</p>
<p>The default Servlet factory will open the Web Application resource <span class="codefrag">/WEB-INF/server-config.wsdd</span> (The name of this file may be changed using the system property <span class="codefrag">axis.ServerConfigFile</span>):</p>
<ul>
<li>If it exists as an accessible file (i.e. not in a JAR/WAR file), then it opens it as a file. This allows changes to be saved, if changes are allowed &amp; made using the Admin tools.</li>
<li>If it does not exist as a file, then an attempt is made to access it as a resource stream (getResourceAsStream), which works for JAR/WAR file contents.</li>
<li>If the resource is simply not available, an attempt is made to create it as a file.</li>
<li>If all above attempts fail, a final attempt is made to access <span class="codefrag">org.apache.axis.server.server-config.wsdd</span> as a data stream.</li>
</ul>
</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>
<span class="codefrag">org.apache.axis.configuration.EngineConfigurationFactoryDefault</span>
<br>
<span class="codefrag">newFactory(obj)</span> is called. If <span class="codefrag">obj</span> is null then an instance of this class is returned. A non-null <span class="codefrag">obj</span> is presumed to require a non-default factory. <p>The default factory will load the WSDD files <span class="codefrag">client-config.wsdd</span> or <span class="codefrag">server-config.wsdd</span>, as appropriate, from the current working directory. The names of these files may be changed using the system properties <span class="codefrag">axis.ClientConfigFile</span> and <span class="codefrag">axis.ServerConfigFile</span>, respectively.</p>
</li>
</ul>
</li>
</ul>
<div class="h5">
<h5>Handlers</h5>
</div>
<p>See the <a href="#architecture-guide.html">Architecture Guide</a> for current information on Handlers.</p>
<div class="h5">
<h5>Internationalization</h5>
</div>
<p>Axis supports internationalization by providing both a property file of the strings used in Axis, and an extension mechanism that facilitates accessing internal Axis messages and extending the messages available to integration code based on existing Axis code.</p>
<div class="h5">
<h5>Translation</h5>
</div>
<ul>
<li>Justification/Rationale</li>
<li style="list-style: none">
<br> In order for readers of languages other than English to be comfortable with Axis, we provide a mechanism for the strings used in Axis to be translated. We do not provide any translations in Axis; we merely provide a means by which translators can easily plug in their translations.<br> &nbsp;</li>
<li>Mechanism</li>
<li style="list-style: none">
<br> Axis provides english messages in the Java resource named org.apache.axis.i18n.resource.properties (in the source tree, the file is named xml-axis/java/src/org/apache/axis/i18n/resource.properties). <p>Axis makes use of the Java internationalization mechanism - i.e., a java.util.ResourceBundle backed by a properties file - and the java.text.MessageFormat class to substitute parameters into the message text.</p>
<ul>
<li style="list-style: none">
<br>
</li>
<li>java.util.ResourceBundle retrieves message text from a property file using a key provided by the program. Entries in a message resource file are of the form &lt;key&gt;=&lt;message&gt;.</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>java.text.MessageFormat substitutes variables for markers in the message text. Markers use the syntax "{X}" where <span class="codefrag">X</span> is the number of the variable, starting at 0.</li>
</ul>
<p>For example: <span class="codefrag">myMsg00=My {0} is {1}.</span>
</p>
<p>Translation requires creating an alternate version of the property file provided by Axis for a target language. The JavaDoc for <span class="codefrag">java.utils.ResourceBundle</span> provides details on how to identify different property files for different locales.</p>
<p>For details on using Axis's internationalization tools, see the <a href="#developers-guide.html">Developer's Guide</a>.<br> &nbsp;</p>
</li>
<li>Default behavior</li>
<li style="list-style: none">
<br> The default behavior, meaning what happens when a translated file doesn't exist for a given locale, is to fall back on the English-language properties file.&nbsp; If that file doesn't exist (unlikely unless something is seriously wrong), Axis will throw an exception with an English-language reason message.<br> &nbsp;</li>
</ul>
<div class="h5">
<h5>Extending Message Files</h5>
</div>
<p>Axis provides a Message file extension mechanism that allows Axis-based code to use Axis message keys, as well as new message keys unique to the extended code.</p>
<ul>
<li>Justification/Rationale</li>
<li style="list-style: none">
<br> Axis provides pluggable interfaces for various Axis entities, including EngineConfigurationFactory's, Provides, and Handlers. Axis also provides a variety of implementations of these entities. It is convenient to use Axis source code for such implementations as starting points for developing extentions and customizations that fulfill the unique needs of the end user.<br> &nbsp;</li>
<li>Procedure</li>
<li style="list-style: none">
<br> To extend the Axis message file:<br> &nbsp; <ul>
<li>Copy the Axis source file <span class="codefrag">java/src/org/apache/axis/i18n/Messages.java</span> to your project/package, say <span class="codefrag">my/project/package/path/Messages.java</span>.</li>
<li style="list-style: none">
<ul>
<li>Set the <span class="codefrag">package</span> declaration in the copied file to the correct package name.</li>
<li>Set the private attribute <span class="codefrag">projectName</span> to <span class="codefrag">"my.project"</span>: the portion of the package name that is common to your project. <span class="codefrag">projectName</span> must be equal to or be a prefix of the copied Messages package name.</li>
</ul>
<br> &nbsp;</li>
<li>Create the file <span class="codefrag">my/project/package/path/resource.properties</span>. Add new message key/value pairs to this file.</li>
<li style="list-style: none">
<br> &nbsp;</li>
<li>As you copy Axis source files over to your project, change the <span class="codefrag">import org.apache.axis.i18n.Messages</span> statement to <span class="codefrag">import my.project.package.path.Messages</span>.</li>
<li>Use the methods provided by the class Messages, as discussed in the <a href="#developers-guide.html">Developer's Guide</a>, to access the new messages.</li>
</ul>
<br>
</li>
<li>Behavior</li>
<li style="list-style: none">
<ul>
<li>Local Search</li>
<li style="list-style: none">
<br>
<span class="codefrag">Messages</span> begins looking for a key's value in the <span class="codefrag">resources.properties</span> resource in it's (Messages) package.<br> &nbsp;</li>
<li>Hierarchical Search</li>
<li style="list-style: none">
<br> If <span class="codefrag">Messages</span> cannot locate either the key, or the resource file, it walks up the package hierarchy until it finds it. The top of the hierarchy, above which it will not search, is defined by the <span class="codefrag">projectName</span> attribute, set above.<br> &nbsp;</li>
<li>Default behavior</li>
<li style="list-style: none">
<br> If the key cannot be found in the package hierarchy then a default resource is used. The default behaviour is determined by the <span class="codefrag">parent</span> attribute of the <span class="codefrag">Messages</span> class copied to your extensions directory. <p>Unless changed, the default behavior, meaning what happens when a key isn't defined in the new properties file, is to fall back to the Axis properties file (org.apache.axis.i18n.resource.properties).<br> &nbsp;</p>
</li>
</ul>
</li>
</ul>
<div class="h5">
<h5>Performance Monitoring</h5>
</div>
<p>Axis does not yet include specific Performance Monitoring Plugs. <!--
<ul>
<li>
Justification/Rationale - why is this plug point necessary?&nbsp; Spec
compliance?</li>
<li>
Interfaces</li>
<li>
Mechanism</li>
<ul>
<li>
Life cycle</li>
<li>
Exception handling - in general; plug-in shouldn't throw any exceptions
- does runtime ignore? Log?)</li>
<li>
Multiple thread support?&nbsp; Ie., is synchronization required?</li>
</ul>
<li>
Configuration/reconfiguration</li>
<li>
Default behavior if not plugged.</li>
<li>
Example</li>
</ul>
--></p>
<div class="h5">
<h5>Encoding</h5>
</div>
<p>Axis does not yet include an Encoding Plug. <!--
How can a system integrator plug in other encoding mechanisms such as SOAP
1.2 or optimized XML-based encoding?
<ul>
<li>
Justification/Rationale - why is this plug point necessary?&nbsp; Spec
compliance?</li>
<li>
Interfaces</li>
<li>
Mechanism</li>
<ul>
<li>
Life cycle</li>
<li>
Exception handling - in general; plug-in shouldn't throw any exceptions
- does runtime ignore? Log?)</li>
<li>
Multiple thread support?&nbsp; Ie., is synchronization required?</li>
</ul>
<li>
Configuration/reconfiguration</li>
<li>
Default behavior if not plugged.</li>
<li>
Example</li>
</ul>
--></p>
<div class="h5">
<h5>WSDL Parser and Code Generator Framework</h5>
</div>
<p>WSDL2Java is Axis's tool to generate Java artifacts from WSDL.&nbsp; This tool is extensible.&nbsp; If users of Axis wish to extend Axis, then they may also need to extend or change the generated artifacts.&nbsp; For example, if Axis is inserted into some product which has an existing deployment model that's different than Axis's deployment model, then that product's version of WSDL2Java will be required to generate deployment descriptors other than Axis's deploy.wsdd.</p>
<p>What follows immediately is a description of the framework.&nbsp; If you would rather dive down into the dirt of <a href="##WSDL%20Examples">examples</a>, you could learn a good deal just from them.&nbsp; Then you could come back up here and learn the gory details.</p>
<p>There are three parts to WSDL2Java:</p>
<ol>
<li>The symbol table</li>
<li>The parser front end with a generator framework</li>
<li>The code generator back end (WSDL2Java itself)</li>
</ol>
<div class="h5">
<h5>Symbol Table</h5>
</div>
<p>The symbol table, found in org.apache.axis.wsdl.symbolTable, will contain all the symbols from a WSDL document, both the symbols from the WSDL constructs themselves (portType, binding, etc), and also the XML schema types that the WSDL refers to.</p>
<p>NOTE:&nbsp; Needs lots of description here.</p>
<p>The symbol table is not extensible, but you <strong>can</strong> add fields to it by using the Dynamic Variables construct:</p>
<ul>
<li>You must have some constant object for a dynamic variable key.&nbsp; For example:&nbsp; public static final String MY_KEY = "my key";</li>
<li>You set the value of the variable in your GeneratorFactory.generatorPass:&nbsp; entry.setDynamicVar(MY_KEY, myValue);</li>
<li>You get the value of the variable in your generators:&nbsp; Object myValue = entry.getDynamicVar(MY_KEY);</li>
</ul>
<div class="h5">
<h5>Parser Front End and Generator Framework</h5>
</div>
<p>The parser front end and generator framework is located in org.apache.axis.wsdl.gen.&nbsp; The parser front end consists of two files:</p>
<ul>
<li>Parser</li>
<li style="list-style: none">
<br>
<tt>public class Parser {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public Parser();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public boolean isDebug();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void setDebug(boolean);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public boolean isImports();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void setImports(boolean);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public boolean isVerbose();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void setVerbose(boolean);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public long getTimeout();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void setTimeout(long);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public java.lang.String getUsername();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void setUsername(java.lang.String);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public java.lang.String getPassword();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void setPassword(java.lang.String);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public GeneratorFactory getFactory();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void setFactory(GeneratorFactory);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public org.apache.axis.wsdl.symbolTable.SymbolTable getSymbolTable();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public javax.wsdl.Definition getCurrentDefinition();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public java.lang.String getWSDLURI();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void run(String wsdl) throws java.lang.Exception;</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void run(String context, org.w3c.dom.Document wsdlDoc) throws java.io.IOException, javax.wsdl.WSDLException;</tt>
<br>
<tt>}</tt>
<p>The basic behavior of this class is simple:&nbsp; you instantiate a Parser, then you run it.</p>
<tt>Parser parser = new Parser();</tt>
<br>
<tt>parser.run("myfile.wsdl");</tt>
<p>
<br> There are various options on the parser that have accessor methods:</p>
<ul>
<li>debug - default is false - dump the symbol table after the WSDL file has been parsed</li>
<li>imports - default is true - should imported files be visited?</li>
<li>verbose - default is false - list each file as it is being parsed</li>
<li>timeout - default is 45 - the number of seconds to wait before halting the parse</li>
<li>username - no default - needed for protected URI's</li>
<li>password - no default - needed for protected URI's</li>
</ul>
<p>
<br> Other miscellaneous methods on the parser:</p>
<ul>
<li>get/setFactory - get or set the GeneratorFactory on this parser - see below for details.&nbsp; The default generator factory is NoopFactory, which generates nothing.</li>
<li>getSymbolTable - once a run method is called, the symbol table will be populated and can get queried.</li>
<li>getCurrentDefinition - once a run method is called, the parser will contain a Definition object which represents the given wsdl file.&nbsp; Definition is a WSDL4J object.</li>
<li>getWSDLURI - once the run method which takes a string is called, the parser will contain the string representing the location of the WSDL file.&nbsp; Note that the other run method - run(String context, Document wsdlDoc) - does not provide a location for the wsdl file.&nbsp; If this run method is used, getWSDLURI will be null.</li>
<li>There are two run methods.&nbsp; The first, as shown above, takes a URI string which represents the location of the WSDL file.&nbsp; If you've already parsed the WSDL file into an XML Document, then you can use the second run method, which takes a context and the WSDL Document.</li>
</ul>
<p>
<br> An extension of this class would ...<br>
<br> NOTE:&nbsp; continue this sentiment...<br> &nbsp;</p>
</li>
<li>WSDL2</li>
<li style="list-style: none">
<br> Parser is the programmatic interface into the WSDL parser.&nbsp; WSDL2 is the command line tool for the parser.&nbsp; It provides an extensible framework for calling the Parser from the command line.&nbsp; It is named WSDL2 because extensions of it will likely begin with WSDL2:&nbsp; <strong>WSDL2</strong>Java, <strong>WSDL2</strong>Lisp, <strong>WSDL2</strong>XXX. <p>
<tt>public class WSDL2 {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected WSDL2();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected Parser createParser();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected Parser getParser();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected void addOptions(org.apache.axis.utils.CLOptionDescriptor[]);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected void parseOption(org.apache.axis.utils.CLOption);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected void validateOptions();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected void printUsage();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected void run(String[]);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public static void main(String[]);</tt>
<br>
<tt>}</tt>
</p>
<p>Like all good command line tools, it has a main method.&nbsp; Unlike some command line tools, however, its methods are not static.&nbsp; Static methods are not extensible.&nbsp; WSDL2's main method constructs an instance of itself and calls methods on that instance rather than calling static methods.&nbsp; These methods follow a behavior pattern.&nbsp; The main method is very simple:<br> &nbsp;</p>
<tt>&nbsp;&nbsp;&nbsp; public static void main(String[] args) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; WSDL2 wsdl2 = new WSDL2();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; wsdl2.run(args);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<p>
<br> The constructor calls createParser to construct a Parser or an extension of Parser.</p>
<p>run calls:</p>
<ul>
<li>parseOption to parse each command line option and call the appropriate Parser accessor.&nbsp; For example, when this method parses --verbose, it calls parser.setVerbose(true)</li>
<li>validateOptions to make sure all the option values are consistent</li>
<li>printUsage if the usage of the tool is in error</li>
<li>parser.run(args);</li>
</ul>
<p>
<br> If an extension has additional options, then it is expected to call addOptions before calling run.&nbsp; So extensions will call, as necessary, getParser, addOptions, run.&nbsp; Extensions will override, as necessary, createParser, parseOption, validateOptions, printUsage.<br> &nbsp;</p>
<p>The generator framework consists of 2 files:</p>
<ul>
<li>Generator</li>
<li style="list-style: none">
<br> The Generator interface is very simple.&nbsp; It just defines a generate method. <p>
<tt>public interface Generator</tt>
<br>
<tt>{</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void generate() throws java.io.IOException;</tt>
<br>
<tt>}</tt>
<br> &nbsp;</p>
</li>
<li>GeneratorFactory</li>
<li style="list-style: none">
<p>
<br>
<tt>public interface GeneratorFactory</tt>
<br>
<tt>{</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void generatorPass(javax.wsdl.Definition, SymbolTable);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public Generator getGenerator(javax.wsdl.Message, SymbolTable);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public Generator getGenerator(javax.wsdl.PortType, SymbolTable);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public Generator getGenerator(javax.wsdl.Binding, SymbolTable);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public Generator getGenerator(javax.wsdl.Service, SymbolTable);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public Generator getGenerator(TypeEntry, SymbolTable);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public Generator getGenerator(javax.wsdl.Definition, SymbolTable);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void setBaseTypeMapping(BaseTypeMapping);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public BaseTypeMapping getBaseTypeMapping();</tt>
<br>
<tt>}</tt>
</p>
<p>The GeneratorFactory interface defines a set of methods that the parser uses to get generators.&nbsp; There should be a generator for each of the WSDL constructs (message, portType, etc - note that these depend on the WSDL4J classes:&nbsp; javax.xml.Message, javax.xml.PortType, etc); a generator for schema types; and a generator for the WSDL Definition itself.&nbsp; This last generator is used to generate anything that doesn't fit into the previous categories.</p>
<p>In addition to the getGeneratorMethods, the GeneratorFactory defines a generatorPass method which provides the factory implementation a chance to walk through the symbol table to do any preprocessing before the actual generation begins.</p>
<p>Accessors for the base type mapping are also defined.&nbsp; These are used to translate QNames to base types in the given target mapping.<br> &nbsp;</p>
</li>
</ul>In addition to Parser, WSDL2, Generator, and GeneratorFactory, the org.apache.axis.wsdl.gen package also contains a couple of no-op classes:&nbsp; NoopGenerator and NoopFactory.&nbsp; NoopGenerator is a convenience class for extensions that do not need to generate artifacts for every WSDL construct.&nbsp; For example, WSDL2Java does not generate anything for messages, therefore its factory's getGenerator(Message, SymbolTable) method returns an instance of NoopGenerator.&nbsp; NoopFactory returns a NoopGenerator for all getGenerator methods.&nbsp; The default factory for Parser is the NoopFactory.</li>
</ul>
<div class="h5">
<h5>Code Generator Back End</h5>
</div>
<p>The meat of the WSDL2Java back end generators is in org.apache.axis.wsdl.toJava.&nbsp; Emitter extends Parser.&nbsp; org.apache.axis.wsdl.WSDL2Java extends WSDL2.&nbsp; JavaGeneratorFactory implements GeneratorFactory.&nbsp; And the various JavaXXXWriter classes implement the Generator interface.</p>
<p>NOTE:&nbsp; Need lots more description here...</p>
<div class="h5">
<h5>WSDL Framework Extension Examples</h5>
</div>
<p>Everything above sounds rather complex.&nbsp; It is, but that doesn't mean your extension has to be.</p>
<div class="h5">
<h5>Example 1 - Simple extension of WSDL2Java - additional artifact</h5>
</div>
<p>The simplest extension of the framework is one which generates everything that WSDL2Java already generates, plus something new.&nbsp; Example 1 is such an extension.&nbsp; It's extra artifact is a file for each service that lists that service's ports.&nbsp; I don't know why you'd want to do this, but it makes for a good, simple example.&nbsp; See samples/integrationGuide/example1 for the complete implementation of this example.<br> &nbsp;</p>
<ul>
<li>First you must create your writer that writes the new artifact.&nbsp; This new class extends org.apache.axis.wsdl.toJava.JavaWriter.&nbsp; JavaWriter dictates behavior to its extensions; it calls writeFileHeader and writeFileBody.&nbsp; Since we don't care about a file header for this example, writeFileHeader is a no-op method.&nbsp; writeFileBody does the real work of this writer.</li>
<li style="list-style: none">
<p>
<br>
<tt>public class MyListPortsWriter extends JavaWriter {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; private Service service;</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public MyListPortsWriter(</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Emitter emitter,</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ServiceEntry sEntry,</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; SymbolTable symbolTable) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; super(emitter,</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; new QName(</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sEntry.getQName().getNamespaceURI(),</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sEntry.getQName().getLocalPart() + "Lst"),</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "", "lst", "Generating service port list file", "service list");</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; this.service = sEntry.getService();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected void writeFileHeader() throws IOException {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected void writeFileBody() throws IOException {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; Map portMap = service.getPorts();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; Iterator portIterator = portMap.values().iterator();</tt>
</p>
<p>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; while (portIterator.hasNext()) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Port p = (Port) portIterator.next();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; pw.println(p.getName());</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; pw.close();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>}</tt>
<br> &nbsp;</p>
</li>
<li>Then you need a main program.&nbsp; This main program extends WSDL2Java so that it gets all the functionality of that tool.&nbsp; The main of this tool does 3 things:</li>
<li style="list-style: none">
<ul>
<li>instantiates itself</li>
<li>adds MyListPortsWriter to the list of generators for a WSDL service</li>
<li>calls the run method.</li>
</ul>That's it!&nbsp; The base tool does all the rest of the work. <p>
<tt>public class MyWSDL2Java extends WSDL2Java {</tt>
</p>
<p>
<tt>&nbsp;&nbsp;&nbsp; public static void main(String args[]) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; MyWSDL2Java myWSDL2Java = new MyWSDL2Java();</tt>
</p>
<p>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; JavaGeneratorFactory factory =</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (JavaGeneratorFactory) myWSDL2Java.getParser().getFactory();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; factory.addGenerator(Service.class, MyListPortsWriter.class);</tt>
</p>
<p>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; myWSDL2Java.run(args);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>}</tt>
</p>
</li>
</ul>
<div class="h5">
<h5>Example 2 - Not quite as simple an extension of WSDL2Java - change an artifact</h5>
</div>
<p>In this example, we'll replace deploy.wsdd with mydeploy.useless.&nbsp; For brevity, mydeploy.useless is rather useless.&nbsp; Making it useful is an exercise left to the reader.&nbsp; See samples/integrationGuide/example2 for the complete implementation of this example.</p>
<ul>
<li>First, here is the writer for the mydeploy.useless.&nbsp; This new class extends org.apache.axis.wsdl.toJava.JavaWriter.&nbsp; JavaWriter dictates behavior to its extensions; it calls writeFileHeader and writeFileBody.&nbsp; Since we don't care about a file header for this example, writeFileHeader is a no-op method.&nbsp; writeFileBody does the real work of this writer.&nbsp; It simply writes a bit of a song, depending on user input.</li>
<li style="list-style: none">
<p>
<br> Note that we've also overridden the generate method.&nbsp; The parser always calls generate, but since this is a server-side artifact, we don't want to generate it unless we are generating server-side artifacts (in other words, in terms of the command line options, we've specified the --serverSide option).</p>
<p>
<tt>public class MyDeployWriter extends JavaWriter {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public MyDeployWriter(Emitter emitter, Definition definition,</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; SymbolTable symbolTable) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; super(emitter,</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; new QName(definition.getTargetNamespace(), "deploy"),</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "", "useless", "Generating deploy.useless", "deploy");</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void generate() throws IOException {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; if (emitter.isServerSide()) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; super.generate();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected void writeFileHeader() throws IOException {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected void writeFileBody() throws IOException {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; MyEmitter myEmitter = (MyEmitter) emitter;</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; if (myEmitter.getSong() == MyEmitter.RUM) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; pw.println("Yo!&nbsp; Ho!&nbsp; Ho!&nbsp; And a bottle of rum.");</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; else if (myEmitter.getSong() == MyEmitter.WORK) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; pw.println("Hi ho!&nbsp; Hi ho!&nbsp; It's off to work we go.");</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; else {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; pw.println("Feelings...&nbsp; Nothing more than feelings...");</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; pw.close();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>}</tt>
<br> &nbsp;</p>
</li>
<li>Since we're changing what WSDL2Java generates, rather than simply adding to it like the previous example did, calling addGenerator isn't good enough.&nbsp; In order to change what WSDL2Java generates, you have to create a generator factory and provide your own generators.&nbsp; Since we want to keep most of WSDL2Java's artifacts, we can simply extend WSDL2Java's factory - JavaGeneratorFactory - and override the addDefinitionGenerators method.</li>
<li style="list-style: none">
<p>
<br>
<tt>public class MyGeneratorFactory extends JavaGeneratorFactory {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected void addDefinitionGenerators() {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; addGenerator(Definition.class, JavaDefinitionWriter.class); // WSDL2Java's JavaDefinitionWriter</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; addGenerator(Definition.class, MyDeployWriter.class); // our DeployWriter</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; addGenerator(Definition.class, JavaUndeployWriter.class); // WSDL2Java's JavaUndeployWriter</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>}</tt>
<br> &nbsp;</p>
</li>
<li>Now we must write the API's to our tool.&nbsp; Since we've added an option - song - we need both the programmatic API - an extension of Parser (actually Emitter in this case since we're extending WSDL2Java and Emitter is WSDL2Java's parser extension) - and the command line API.</li>
<li style="list-style: none">
<p>
<br> Here is our programmatic API.&nbsp; It adds song accessors to Emitter.&nbsp; It also, in the constructor, lets the factory know about the emitter and the emitter know about the factory.</p>
<p>
<tt>public class MyEmitter extends Emitter {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public static final int RUM&nbsp; = 0;</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public static final int WORK = 1;</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; private int song = -1;</tt>
</p>
<p>
<tt>&nbsp;&nbsp;&nbsp; public MyEmitter() {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; MyGeneratorFactory factory = new MyGeneratorFactory();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; setFactory(factory);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; factory.setEmitter(this);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public int getSong() {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; return song;</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public void setSong(int song) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; this.song = song;</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>}</tt>
</p>
<p>And here is our command line API.&nbsp; It's a bit more complex that our previous example's main program, but it does 2 extra things:</p>
<ol>
<li>accept a new command line option:&nbsp; --song rum|work (this is the biggest chunk of the new work).</li>
<li>create a new subclass of Parser</li>
</ol>
<p>
<br>
<tt>public class WSDL2Useless extends WSDL2Java {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected static final int SONG_OPT = 'g';</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected static final CLOptionDescriptor[] options = new CLOptionDescriptor[]{</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; new CLOptionDescriptor("song",</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; CLOptionDescriptor.ARGUMENT_REQUIRED,</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; SONG_OPT,</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Choose a song for deploy.useless:&nbsp; work or rum")</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; };</tt>
</p>
<p>
<tt>&nbsp;&nbsp;&nbsp; public WSDL2Useless() {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; addOptions(options);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected Parser createParser() {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; return new MyEmitter();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; protected void parseOption(CLOption option) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; if (option.getId() == SONG_OPT) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; String arg = option.getArgument();</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if (arg.equals("rum")) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ((MyEmitter) parser).setSong(MyEmitter.RUM);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; else if (arg.equals("work")) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ((MyEmitter) parser).setSong(MyEmitter.WORK);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; else {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; super.parseOption(option);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; public static void main(String args[]) {</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; WSDL2Useless useless = new WSDL2Useless();</tt>
</p>
<p>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; useless.run(args);</tt>
<br>
<tt>&nbsp;&nbsp;&nbsp; }</tt>
<br>
<tt>}</tt>
</p>
<p>Let's go through this one method at a time.</p>
<ul>
<li>constructor - this constructor adds the new option --song rum|work.&nbsp; (the abbreviated version of this option is "-g", rather an odd abbreviation, but "-s" is the abbreviation for --serverSide and "-S" is the abbreviation for --skeletonDeploy.&nbsp; Bummer.&nbsp; I just picked some other letter.)</li>
<li>createParser - we've got to provide a means by which the parent class can get our Parser extension.</li>
<li>parseOption - this method processes our new option.&nbsp; If the given option isn't ours, just let super.parseOption do its work.</li>
<li>main - this main is actually simpler than the first example's main.&nbsp; The first main had to add our generator to the list of generators.&nbsp; In this example, the factory already did that, so all that this main must do is instantiate itself and run itself.</li>
</ul>
</li>
</ul>
<div class="h5">
<h5>Client SSL</h5>
</div>
<p>The default pluggable secure socket factory module (see <a href="##Pluggable%20APIs">Pluggable APIs</a>) uses JSSE security. Review the JSSE documentation for details on installing, registering, and configuring JSSE for your runtime environment.</p>
<div class="h2">
<h2>Axis Architecture Guide</h2>
</div>
<div class="h5">
<h5>Axis Architecture Guide</h5>
</div>
<p>
<br>
<em>1.2 Version</em>
<br>
<em>Feedback: axis-dev@ws.apache.org</em>
</p>
<div class="h5">
<h5>Introduction</h5>
</div>
<p>This guide records some of the rationale of the architecture and design of Axis.</p>
<div class="h5">
<h5>Architectural Overview</h5>
</div>
<p>Axis consists of several subsystems working together, as we shall see later. In this section we'll give you an overview of how the core of Axis works.</p>
<div class="h5">
<h5>Handlers and the Message Path in Axis</h5>
</div>
<p>Put simply, Axis is all about processing Messages. When the central Axis processing logic runs, a series of <strong>Handlers</strong> are each invoked in order. The particular order is determined by two factors - deployment configuration and whether the engine is a client or a server. The object which is passed to each Handler invocation is a <strong>MessageContext</strong>. A MessageContext is a structure which contains several important parts: 1) a "request" message, 2) a "response" message, and 3) a bag of properties. More on this in a bit.</p>
<p>There are two basic ways in which Axis is invoked:</p>
<ol>
<li>As a <strong>server</strong>, a <strong>Transport Listener</strong> will create a MessageContext and invoke the Axis processing framework.</li>
<li>As a <strong>client</strong>, application code (usually aided by the client programming model of Axis) will generate a MessageContext and invoke the Axis processing framework.</li>
</ol>
<p>In either case, the Axis framework's job is simply to pass the resulting MessageContext through the configured set of Handlers, each of which has an opportunity to do whatever it is designed to do with the MessageContext.</p>
<div class="h5">
<h5>Message Path on the Server</h5>
</div>
<p>The server side message path is shown in the following diagram. The small cylinders represent Handlers and the larger, enclosing cylinders represent <strong>Chains</strong> (ordered collections of Handlers which will be described shortly).<br>
<img alt="" src="images/ServerMessagePath.jpg"><br> A message arrives (in some protocol-specific manner) at a Transport Listener. In this case, let's assume the Listener is a HTTP servlet. It's the Listener's job to package the protocol-specific data into a <strong>Message</strong> object (org.apache.axis.Message), and put the Message into a <strong>MessageContext</strong>. The MessageContext is also loaded with various <strong>properties</strong> by the Listener -&nbsp; in this example the property "http.SOAPAction" would be set to the value of the SOAPAction HTTP header. The Transport Listener also sets the <strong>transportName</strong> String on the MessageContext , in this case to "http". Once the MessageContext is ready to go, the Listener hands it to the AxisEngine.</p>
<p>The AxisEngine's first job is to look up the transport by name. The transport is an object which contains a <strong>request</strong> Chain, a <strong>response</strong> Chain, or perhaps both. A <strong>Chain</strong> is a Handler consisting of a sequence of Handlers which are invoked in turn -- more on Chains later. If a transport request Chain exists, it will be invoked, passing the MessageContext into the invoke() method. This will result in calling all the Handlers specified in the request Chain configuration.</p>
<p>After the transport request Handler, the engine locates a global request Chain, if configured, and then invokes any Handlers specified therein.</p>
<p>At some point during the processing up until now, some Handler has hopefully set the <strong>serviceHandler</strong> field of the MessageContext (this is usually done in the HTTP transport by the "URLMapper" Handler, which maps a URL like "http://localhost/axis/services/AdminService" to the "AdminService" service). This field determines the Handler we'll invoke to execute service-specific functionality, such as making an RPC call on a back-end object. Services in Axis are typically instances of the "SOAPService" class (org.apache.axis.handlers.soap.SOAPService), which may contain <strong>request</strong> and <strong>response</strong> Chains (similar to what we saw at the transport and global levels), and must contain a <strong>provider</strong>, which is simply a Handler responsible for implementing the actual back end logic of the service.</p>
<p>For RPC-style requests, the provider is the org.apache.axis.providers.java.RPCProvider class. This is just another Handler that, when invoked, attempts to call a backend Java object whose class is determined by the "className" parameter specified at deployment time. It uses the SOAP RPC convention for determining the method to call, and makes sure the types of the incoming XML-encoded arguments match the types of the required parameters of the resulting method.</p>
<div class="h5">
<h5>The Message Path on the Client</h5>
</div>
<p>The Message Path on the client side is similar to that on the server side, except the order of scoping is reversed, as shown below.<br>
<img alt="" src="images/ClientMessagePath.jpg"><br> The <strong>service</strong> Handler, if any, is called first - on the client side, there is no "provider" since the service is being provided by a remote node, but there is still the possibility of request and response Chains. The service request and response Chains perform any service-specific processing of the request message on its way out of the system, and also of the response message on its way back to the caller.</p>
<p>After the service request Chain, the global request Chain, if any, is invoked, followed by the transport. The <strong>Transport Sender</strong>, a special Handler whose job it is to actually perform whatever protocol-specific operations are necessary to get the message to and from the target SOAP server, is invoked to send the message. The response (if any) is placed into the responseMessage field of the MessageContext, and the MessageContext then propagates through the response Chains - first the transport, then the global, and finally the service.</p>
<div class="h5">
<h5>Subsystems</h5>
</div>
<p>Axis comprises several subsystems working together with the aim of separating responsibilities cleanly and making Axis modular. Subsystems which are properly layered enable parts of a system to be used without having to use the whole of it (or hack the code).</p>
<p>The following diagram shows the layering of subsystems. The lower layers are independent of the higher layers. The 'stacked' boxes represent mutually independent, although not necessary mutually exclusive, alternatives. For example, the HTTP, SMTP, and JMS transports are independent of each other but may be used together.</p>
<p>
<img alt="" src="images/subsystems.jpg"></p>
<p>In fact, the Axis source code is not as cleanly separated into subsystems as the above diagram might imply. Some subsystems are spread over several packages and some packages overlap more than one subsystem. Proposals to improve the code structure and make it conform more accurately to the notional Axis subsystems will be considered when we get a chance.</p>
<div class="h5">
<h5>Message Flow Subsystem</h5>
</div>
<div class="h5">
<h5>Handlers and Chains</h5>
</div>
<p>Handlers are invoked in sequence to process messages. At some point in the sequence a Handler may send a request and receive a response or else process a request and produce a response. Such a Handler is known as the <em>pivot point</em> of the sequence. As described above, Handlers are either transport-specific, service-specific, or global. The Handlers of each of these three different kinds are combined together into Chains. So the overall sequence of Handlers comprises three Chains: transport, global, and service. The following diagram shows two sequences of handlers: the client-side sequence on the left and the server-side sequence on the right.<br>
<img alt="" src="images/pivots.jpg"></p>
<p>A web service does not necessarily send a response message to each request message, although many do. However, response Handlers are still useful in the message path even when there isn't a response message, e.g. to stop timers, clean up resources, etc.</p>
<p>A Chain is a composite Handler, i.e. it aggregates a collection of Handlers as well as implementing the Handler interface as shown in the following UML diagram:<br>
<img alt="" src="images/chainclasses.jpg"></p>
<p>A Chain also has similarities to the Chain of Responsibility design pattern in which a request flows along a sequence of Handlers until it is processed. Although an Axis Chain may process a request in stages over a succession of Handlers, it has the same advantages as Chain of Responsibility: flexibility and the ease with which new function can be added.</p>
<p>Back to message processing -- a message is processed by passing through the appropriate Chains. A message context is used to pass the message and associated environment through the sequence of Handlers. The model is that Axis Chains are constructed offline by having Handlers added to them one at a time. Then they are turned online and message contexts start to flow through the Chains. Multiple message contexts may flow through a single Chain concurrently. Handlers are never added to a Chain once it goes online. If a Handler needs to be added or removed, the Chain must be 'cloned', the modifications made to the clone, and then the clone made online and the old Chain retired when it is no longer in use. Message contexts that were using the old Chain continue to use it until they are finished. This means that Chains do not need to cope with the addition and removal of Handlers while the Chains are processing message contexts -- an important simplification.</p>
<p>The deployment registry has factories for Handlers and Chains. Handlers and Chains can be defined to have 'per-access', 'per-request', or 'singleton' scope although the registry currently only distinguishes between these by constructing non-singleton scope objects when requested and constructing singleton scope objects once and holding on to them for use on subsequent creation requests.</p>
<div class="h5">
<h5>Targeted Chains</h5>
</div>
<p>A <strong>Targeted Chain</strong> is a special kind of chain which may have any or all of: a request Handler, a pivot Handler, and a response Handler. The following class diagram shows how Targeted Chains relate to Chains. Note that a Targeted Chain is an aggregation of Handlers by virtue of extending the Chain interface which is an aggregation of Handlers.</p>
<p>
<img alt="" src="images/targetedchainclasses.jpg"></p>
<p>A service is a special kind of Targeted Chain in which the pivot Handler is known as a "provider".</p>
<div class="h5">
<h5>Fault Processing</h5>
</div>
<p>Now let's consider what happens when a fault occurs. The Handlers prior to the Handler that raised the fault are driven, in reverse order, for onFault (previously misnamed 'undo'). The scope of this backwards scan is interesting: all Handlers previously invoked for the current Message Context are driven.</p>
<p>
<em>Need to explain how "FaultableHandlers" and "WSDD Fault Flows" fit in.</em>
</p>
<div class="h5">
<h5>Message Contexts</h5>
</div>
<p>The current structure of a MessageContext is shown below. Each message context may be associated with a request Message and/or a response Message. Each Message has a SOAPPart and an Attachments object, both of which implement the Part interface.<br>
<img alt="" src="images/messagecontext.jpg"><br> The typing of Message Contexts needs to be carefully considered in relation to the Axis architecture. Since a Message Context appears on the Handler interface, it should not be tied to or biassed in favour of&nbsp; SOAP. The current implementation is marginally biassed towards SOAP in that the setServiceHandler method narrows the specified Handler to a SOAPService.</p>
<div class="h5">
<h5>Engine</h5>
</div>
<p>Axis has an abstract AxisEngine class with two concrete subclasses: AxisClient drives the client side handler chains and AxisServer drives the server side handler chains. The relationships between these classes is fairly simple:<br>
<img alt="" src="images/engineclasses.jpg"></p>
<div class="h5">
<h5>Engine Configuration</h5>
</div>
<p>The EngineConfiguration interface is the means of configuring the Handler factories and global options of an engine instance. An instance of a concrete implementation of EngineConfiguration must be passed to the engine when it is created and the engine must be notified if the EngineConfiguration contents are modified. The engine keeps a reference to the EngineConfiguration and then uses it to obtain Handler factories and global options.</p>
<p>The EngineConfiguration interface belongs to the Message Flow subsystem which means that the Message Flow subsystem does not depend on the Administration subsystem.</p>
<div class="h5">
<h5>Administration Subsystem</h5>
</div>
<p>The Administration subsystem provides a way of configuring Axis engines. The configuration information an engine needs is a collection of factories for runtime artefacts such as Chains and SOAPServices and a set of global configuration options for the engine.</p>
<p>The Message Flow subsystem's EngineConfiguration interface is implemented by the Administration subsystem. FileProvider enables an engine to be configured statically from a file containing a deployment descriptor which is understood by the WSDDDeployment class. SimpleProvider, on the other hand, enables an engine to be configured dynamically.<br>
<img alt="" src="images/engineconfig.jpg"></p>
<div class="h5">
<h5>WSDD-Based Administration</h5>
</div>
<p>WSDD is an XML grammer for deployment descriptors which are used to statically configure Axis engines. Each Handler needs configuration in terms of the concrete class name of a factory for the Handler, a set of options for the handler, and a lifecycle scope value which determines the scope of sharing of instances of the Handler.</p>
<p>The structure of the WSDD grammar is mirrored by a class hierarchy of factories for runtime artefacts. The following diagram shows the classes and the types of runtime artefacts they produce (a dotted arrow means "instantiates").<br>
<img alt="" src="images/wsddclasses.jpg"></p>
<div class="h5">
<h5>Message Model Subsystem</h5>
</div>
<div class="h5">
<h5>SOAP Message Model</h5>
</div>
<p>The XML syntax of a SOAP message is fairly simple. A SOAP message consists of an <em>envelope</em> containing:</p>
<ul>
<li>an optional <em>header</em> containing zero or more <em>header entries</em> (sometimes ambiguously referred to as <em>headers</em>),</li>
<li>a <em>body</em> containing zero or more <em>body entries</em>, and</li>
<li>zero or more additional, non-standard elements.</li>
</ul>
<p>The only body entry defined by SOAP is a <em>SOAP fault</em> which is used for reporting errors.</p>
<p>Some of the XML elements of a SOAP message define namespaces, each in terms of a URI and a local name, and encoding styles, a standard one of which is defined by SOAP.</p>
<p>Header entries may be tagged with the following optional SOAP attributes:</p>
<ul>
<li>
<em>actor</em> which specifies the intended recipient of the header entry in terms of a URI, and</li>
<li>
<em>mustUnderstand</em> which specifies whether or not the intended recipient of the header entry is required to process the header entry.</li>
</ul>
<p>So the SOAP message model looks like this:<br>
<img alt="" src="images/soapmessagemodel.jpg"></p>
<div class="h5">
<h5>Message Elements</h5>
</div>
<p>The classes which represent SOAP messages form a class hierarchy based on the MessageElement class which takes care of namespaces and encodings. The SOAPHeaderElement class looks after the actor and mustUnderstand attributes.<br>
<img alt="" src="images/messagemodelclasses.jpg"> During deserialization, a parse tree is constructed consisting of instances of the above classes in parent-child relationships as shown below.<br>
<img alt="" src="images/messagetree.jpg"></p>
<div class="h5">
<h5>Deserialization</h5>
</div>
<p>The class mainly responsible for XML parsing, i.e. deserialization, is DeserializationContext ('DC'). DC manages the construction of the parse tree and maintains a stack of SAX handlers, a reference to the MessageElement that is currently being deserialized, a stack of namespace mappings, a mapping from IDs to elements, a set of type mappings for deserialization (see <a href="##Encoding Subsystem">Encoding Subsystem</a>) and a SAX event recorder.</p>
<p>Elements that we scan over, or ones for which we don't have a particular deserializer, are recorded - in other words, the SAX events are placed into a queue which may be 'played back' at a later time to any SAX ContentHandler.</p>
<p>Once a SOAPEnvelope has been built, either through a parse or manual construction by the user, it may be output using a SerializationContext (also see <a href="##Encoding%20Subsystem">Encoding Subsystem</a>). MessageElements all have an output() method which lets them write out their contents.</p>
<p>The SAX handlers form a class hierarchy:<br>
<img alt="" src="images/SAXHandlerClasses.jpg"></p>
<p>and stack up as shown in the following diagram:<br>
<img alt="" src="images/SAXhandlers.jpg"></p>
<p>Initially, the SAX handler stack just contains an instance of EnvelopeHandler which represents the fact that parsing of the SOAP envelope has not yet started. The EnvelopeHandler is constructed with a reference to an EnvelopeBuilder, which is the SAX handler responsible for parsing the SOAP envelope.</p>
<p>During parsing, DC receives the events from the SAX parser and notifies either the SAX handler on the top of its handler stack, the SAX event recorder, or both.</p>
<p>On the start of an element, DC calls the SAX handler on the top of its handler stack for onStartChild. This method returns a SAX handler to be used to parse the child, which DC pushes on its SAX handler stack and calls for startElement. startElement, amongst other things, typically creates a new MessageElement of the appropriate class and calls DC for pushNewElement. The latter action creates the parent-child relationships of the parse tree.</p>
<p>On the end of an element, DC pops the top SAX handler from its handler stack and calls it for endElement. It then drives SAX handler which is now on the top of the handler stack for onEndChild. Finally, it sets the MessageElement that is currently being deserialized to the parent of the current one.</p>
<p>Elements which are not defined by SOAP are treated using a SOAPHandler as a SAX event handler and a MessageElement as a node in the parse tree.</p>
<div class="h5">
<h5>Encoding Subsystem</h5>
</div>
<p>Encoding is most easily understood from the bottom up. The basic requirement is to transform between values of programming language datatypes and their XML representations. In Axis, this means encoding (or 'serializing') Java objects and primitives into XML and decoding (or 'deserializing') XML into Java objects and primitives. The basic classes that implement these steps are <em>serializers</em> and <em>deserializers</em>.<br>
<img alt="" src="images/serclasses.jpg"></p>
<p>Particular serializers and deserializers are written to support a specific XML processing mechanism such as DOM or SAX. So <em>serializer factories</em> and <em>deserializer factories</em> are introduced to construct serializers and deserializers for a XML processing mechanism which is specified as a parameter.<br>
<img alt="" src="images/serfactoryclasses.jpg"></p>
<p>As is apparent from the above class diagrams, each pair of Java type and XML data type which needs encoding and decoding requires specific serializers and deserializers (actually one of each per XML processing mechanism). So we need to maintain a mapping from a pair of Java type and XML data type, identified by a QName, to a serializer factory and a deserializer factory. Such a mapping is known as a <em>type mapping</em>. The type mapping class hierarchy is shown below. Notice how the default type mapping instantiates the various serializer and deserialiser factories.<br>
<img alt="" src="images/typemappingclasses.jpg"></p>
<p>There is one final level of indirection. How do we know which type mapping to use for a particular message? This is determined by the encoding which is specified in the message. A <em>type mapping registry</em> maintains a map from encoding name (URI) to type mapping. Note that the XML data type QNames are defined by the encoding.<br>
<img alt="" src="images/typemappingclasses.jpg"></p>
<p>So, in summary, to encode a Java object or primitive data value to a XML datatype or to decode the latter to the former, we need to know:</p>
<ul>
<li>the Java type we are dealing with,</li>
<li>the QName of the XML data type we want to encode it as,</li>
<li>the XML processing mechanism we are using, and</li>
<li>the encoding name.</li>
</ul>
<div class="h5">
<h5>WSDL Tools Subsystem</h5>
</div>
<p>The WSDL Tools subsystem contains WSDL2Java and Java2WSDL. The Axis runtime does not depend on these tools -- they are just there to make life easier for the user. </p>
<div class="h5">
<h5>WSDL2Java</h5>
</div>
<p>This tool takes a description of a web service written in WSDL and emits Java artefacts used to access the web service.</p>
<p>There are three layers inside the tool:</p>
<ul>
<li>framework: SymbolTable, Emitter, WriterFactory</li>
<li>WSDL2Java plugin to the framework: WSDL2Java (the main), JavaWriterFactory, and all the WSDL-relative writers: JavaPortTypeWriter, JavaBindingWriter, etc.</li>
<li>The actual WSDL2Java emitters, one for each file generated: JavaInterfaceWriter, JavaStubWriter, etc.</li>
</ul>
<p>
<a name="java/architecture-guide.html#Java2WSDL"></a>
</p>
<div class="h5">
<h5>Java2WSDL</h5>
</div>
<p>tbd.</p>
<div class="h5">
<h5>Interaction Diagrams</h5>
</div>
<div class="h5">
<h5>Client Side Processing</h5>
</div>
<p>The client side Axis processing constructs a Call object with associated Service, MessageContext, and request Message as shown below before invoking the AxisClient engine.</p>
<p>
<img alt="" src="images/clientobjects.jpg"><br> An instance of&nbsp; Service and its related AxisClient instance are created before the Call object. The Call object is then created by invoking the Service.createCall <em>factory method</em>. Call.setOperation creates a Transport instance, if a suitable one is not already associated with the Call instance. Then Call.invoke creates a MessageContext and associated request Message, drives AxisClient.invoke, and processes the resultant MessageContext. This significant method calls in this sequence are shown in the following interaction diagram.<br>
<img alt="" src="images/clientinteraction.jpg"></p>
<div class="h5">
<h5>Pluggable-Component Discovery</h5>
</div>
<p>While most pluggable components infrastructures (jaxp/xerces, commons-logging, etc) provide discovery features, it is foreseen that there are situations where these may evolve over time. For example, as leading-edge technologies are reworked and adopted as standards, discovery mechanisms are likely to change.</p>
<p>Therefore, component discovery must be relegated to a <strong>single</strong> point of control within AXIS, typically an AXIS-specific factory method. These factory methods should conform to current standards, when available. As technologies evolve and/or are standardized, the factory methods should be kept up-to-date with appropriate discovery mechanisms.</p>
<div class="h5">
<h5>Open Issues</h5>
</div>
<ol>
<li>The relationship between the Axis subsystems needs to be documented and somewhat cleaned up as there is leakage of responsibilities between some of the subsystems. For example, there is some SOAP and HTTP bias in the basic MessageContext type and associated classes.</li>
<li>What classes are included in the "encoding" subsystem? Are the encoding and message model subsystems independent of the other subsystems which depend on "message flow"?</li>
<li>(Possibly related to the previous issue) How should we distribute the classes in the above diagram between the Axis subsystems taking into account&nbsp; SOAP-specific and HTTP-specific features?</li>
<li>The Axis Engine currently knows about three layers of handlers: transport, global, and service. However, architecturally, this is rather odd. What "law" of web services ensures that there will always and only ever be <em>three</em> layers? It would be more natural to use Targeted Chains with their more primitive notion of request, pivot, and response Handlers. We would then implemented the Axis Engine as a Targeted Chain whose pivot Handler is itself a Targeted Chain with global request and response Handlers and a service pivot Handler (which is itself a Targeted Chain as we have just described). Such an Axis Engine architecture is shown in the diagram below.</li>
<li style="list-style: none">
<br>
<img alt="" src="images/stcengine.jpg"></li>
<li>WSDDService.faultFlows is initialised to an empty Vector and there is no way of adding a fault flow to it. Is this dead code or is something else missing?</li>
<li>If a fault occurs after the pivot Handler, should the backwards scan notify Handlers which were invoked prior to the pivot Handler? The current implementation does notify such Handlers. However, this is not consistent with the processing of faults raised in a downstream system and stored in the message context by the pivot Handler. These faults are passed through any response Handlers, but do not cause onFault to be driven in the local engine.</li>
<li style="list-style: none">
<br> &nbsp; <p>&nbsp;<br> &nbsp;<br> &nbsp;</p>
<p>We need to consider what's going on here. If you take a sequence of Handlers and then introduce a distribution boundary into the sequence, what effect should that have on the semantics of the sequence in terms of its effects on message contexts? The following diagram shows a client-side Handler sequence invoking a server-side Handler sequence. We need to consider how the semantics of this combined sequence compares with the sequence formed by omitting the transport-related Handlers.<br>
<img alt="" src="images/pivots2.jpg"></p>
</li>
</ol>
<div class="h2">
<h2>Axis Reference Guide</h2>
</div>
<div class="h5">
<h5>Axis Reference Guide</h5>
</div>
<p>
<em>1.2 Version</em>
<br>
<em>Feedback: axis-dev@ws.apache.org</em>
</p>
<div class="h5">
<h5>Tools Reference</h5>
</div>
<div class="h5">
<h5>WSDL2Java Reference</h5>
</div>
<p>Usage:&nbsp; java org.apache.axis.wsdl.WSDL2Java [options] WSDL-URI<br> Options:<br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp; -h, --help<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; print this message and exit<br> &nbsp;&nbsp;&nbsp;&nbsp; -v, --verbose<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; print informational messages<br> &nbsp;&nbsp;&nbsp;&nbsp; -n, --noImports<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; only generate code for the immediate WSDL document<br> &nbsp;&nbsp;&nbsp;&nbsp; -O, --timeout &lt;argument&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; timeout in seconds (default is 45, specify -1 to disable)<br> &nbsp;&nbsp;&nbsp;&nbsp; -D, --Debug<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; print debug information<br> &nbsp;&nbsp;&nbsp; -W, --noWrapped<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; turn off support for "wrapped" document/literal<br> &nbsp;&nbsp;&nbsp;&nbsp; -s, --server-side<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; emit server-side bindings for web service<br> &nbsp;&nbsp;&nbsp;&nbsp; -S, --skeletonDeploy &lt;argument&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; deploy skeleton (true) or implementation (false) in deploy.wsdd.<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Default is false.&nbsp; Assumes --server-side.<br> &nbsp;&nbsp;&nbsp;&nbsp; -N, --NStoPkg &lt;argument&gt;=&lt;value&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mapping of namespace to package<br> &nbsp;&nbsp;&nbsp;&nbsp; -f, --fileNStoPkg &lt;argument&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; file of NStoPkg mappings (default NStoPkg.properties)<br> &nbsp;&nbsp;&nbsp;&nbsp; -p, --package &lt;argument&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; override all namespace to package mappings, use this package<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name instead<br> &nbsp;&nbsp;&nbsp;&nbsp; -o, --output &lt;argument&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; output directory for emitted files<br> &nbsp;&nbsp;&nbsp;&nbsp; -d, --deployScope &lt;argument&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; add scope to deploy.xml: "Application", "Request", "Session"<br> &nbsp;&nbsp;&nbsp;&nbsp; -t, --testCase<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; emit junit testcase class for web service<br> &nbsp;&nbsp;&nbsp;&nbsp; -a, --all<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; generate code for all elements, even unreferenced ones<br> &nbsp;&nbsp;&nbsp;&nbsp; -T, --typeMappingVersion<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; indicate 1.1 or 1.2. The default is 1.1 (SOAP 1.1 JAX-RPC compliant.<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1.2 indicates SOAP 1.1 encoded.)<br> &nbsp;&nbsp;&nbsp;&nbsp; -F, --factory &lt;argument&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; name of a custom class that implements GeneratorFactory interface<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (for extending Java generation functions)<br> &nbsp;&nbsp;&nbsp;&nbsp; -i, --nsInclude &lt;namespace&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; namescape to specifically include in the generated code (defaults to<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; all namespaces unless specifically excluded with the -x option)<br> &nbsp;&nbsp;&nbsp;&nbsp; -x, --nsExclude &lt;namespace&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; namespace to specifically exclude from the generated code (defaults to<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; none excluded until first namespace included with -i option)<br> &nbsp;&nbsp;&nbsp;&nbsp; -p, --property &lt;name&gt;=&lt;value&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; name and value of a property for use by the custom GeneratorFactory<br> &nbsp;&nbsp;&nbsp;&nbsp; -H, --helperGen<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; emits separate Helper classes for meta data<br> &nbsp;&nbsp;&nbsp;&nbsp; -U, --user &lt;argument&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; username to access the WSDL-URI<br> &nbsp;&nbsp;&nbsp;&nbsp; -P, --password &lt;argument&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; password to access the WSDL-URI<br> &nbsp;&nbsp;&nbsp;&nbsp; -c, --implementationClassName &lt;argument&gt;<br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; use this as the implementation class<br>
</tt>
</p>
<tt></tt>
<div class="h5">
<h5>-h, --help</h5>
</div>
<p>
<tt>Print the usage statement and exit</tt>
</p>
<div class="h5">
<h5>-v, --verbose</h5>
</div>
<p>
<tt>See what the tool is generating as it is generating it.</tt>
</p>
<div class="h5">
<h5>-n, --noImports</h5>
</div>
<p>
<tt>Only generate code for the WSDL document that appears on the command line.&nbsp; The default behaviour is to generate files for all WSDL documents, the immediate one and all imported ones.</tt>
</p>
<div class="h5">
<h5>-O, --timeout</h5>
</div>
<p>
<tt>Timeout in seconds. The default is 45. Use -1 to disable the timeout.</tt>
</p>
<div class="h5">
<h5>-D, --Debug</h5>
</div>
<p>
<tt>Print debug information, which currently is WSDL2Java's symbol table. Note that this is only printed after the symbol table is complete, ie., after the WSDL is parsed successfully.</tt>
</p>
<div class="h5">
<h5>-W, --noWrapped</h5>
</div>
<p>
<tt>This turns off the special treatment of what is called "wrapped" document/literal style operations. &nbsp;By default, WSDL2Java will recognize the following conditions:</tt>
</p>
<ul>
<li>
<tt>If an input message has is a single part.</tt>
</li>
<li>
<tt>The part is an element.</tt>
</li>
<li>
<tt>The element has the same name as the operation</tt>
</li>
<li>
<tt>The element's complex type has no attributes<br>
</tt>
</li>
</ul>
<p>
<tt>When it sees this, WSDL2Java will 'unwrap' the top level element, and treat each of the components of the element as arguments to the operation. This type of WSDL is the default for Microsoft .NET web services, which wrap up RPC style arguments in this top level schema element.</tt>
</p>
<div class="h5">
<h5>-s, --server-side</h5>
</div>
<p>
<tt>Emit the server-side bindings for the web service:</tt>
</p>
<ul>
<li>
<tt>a skeleton class named &lt;bindingName&gt;Skeleton.&nbsp; This may or may not be emitted (see -S, --skeletonDeploy).</tt>
</li>
<li>
<tt>an implementation template class named &lt;bindingName&gt;Impl.&nbsp; Note that, if this class already exists, then it is not emitted.</tt>
</li>
<li>
<tt>deploy.wsdd</tt>
</li>
<li>
<tt>undeploy.wsdd</tt>
</li>
</ul>
<div class="h5">
<h5>-S, --skeletonDeploy &lt;argument&gt;</h5>
</div>
<p>
<tt>Deploy either the skeleton (true) or the implementation (false) in deploy.wsdd.&nbsp; In other words, for "true" the service clause in the deploy.wsdd file will look something like:</tt>
</p>
<pre class="example">
<tt>&lt;service name="AddressBook" provider="java:RPC"&gt;
&lt;parameter name="className" value="samples.addr.AddressBookSOAPBindingSkeleton"/&gt;
...
&lt;/service&gt;
</tt>
</pre>
<p>
<tt>and for "false" it would look like:</tt>
</p>
<pre class="example">
<tt>&lt;service name="AddressBook" provider="java:RPC"&gt;
&lt;parameter name="className" value="samples.addr.AddressBookSOAPBindingImpl"/&gt;
...
&lt;/service&gt;
</tt>
</pre>
<p>
<tt>The default for this option is false. When you use this option, the --server-side option is assumed, so you don't have to explicitly specify --server-side as well.</tt>
</p>
<div class="h5">
<h5>-N, --NStoPkg &lt;argument&gt;=&lt;value&gt;</h5>
</div>
<p>
<tt>By default, package names are generated from the namespace strings in the WSDL document in a magical manner (typically, if the namespace is of the form "http://x.y.com" or "urn:x.y.com" the corresponding package will be "com.y.x"). If this magic is not what you want, you can provide your own mapping using the --NStoPkg argument, which can be repeated as often as necessary, once for each unique namespace mapping. For example, if there is a namespace in the WSDL document called "urn:AddressFetcher2", and you want files generated from the objects within this namespace to reside in the package samples.addr, you would provide the following option to WSDL2Java:</tt>
</p>
<pre>
<tt>--NStoPkg urn:AddressFetcher2=samples.addr
</tt>
</pre>
<p>
<tt>(Note that if you use the short option tag, "-N", then there must not be a space between "-N" and the namespace.)<br>
</tt>
</p>
<div class="h5">
<h5>-f, --fileNStoPkg &lt;argument&gt;</h5>
</div>
<p>
<tt>If there are a number of namespaces in the WSDL document, listing a mapping for them all could become tedious. To help keep the command line terse, WSDL2Java will also look for mappings in a properties file. By default, this file is named "NStoPkg.properties" and it must reside in the default package (ie., no package). But you can explicitly provide your own file using the --fileNStoPkg option.</tt>
</p>
<p>
<tt>The entries in this file are of the same form as the arguments to the --NStoPkg command line option. For example, instead of providing the command line option as above, we could provide the same information in NStoPkg.properties:</tt>
</p>
<pre>
<tt>urn\:AddressFetcher2=samples.addr
</tt>
</pre>
<p>
<tt>(Note that the colon must be escaped in the properties file.)</tt>
</p>
<p>
<tt>If an entry for a given mapping exists both on the command line and in the properties file, the command line entry takes precedence.</tt>
</p>
<div class="h5">
<h5>-p, --package &lt;argument&gt;</h5>
</div>
<p>
<tt>This is a shorthand option to map all namespaces in a WSDL document to the same Java package name. This can be useful, but dangerous. You must make sure that you understand the effects of doing this. For instance there may be multiple types with the same name in different namespaces. It is an error to use the --NStoPkg switch and --package at the same time.</tt>
</p>
<div class="h5">
<h5>-o, --output &lt;argument&gt;</h5>
</div>
<p>
<tt>The root directory for all emitted files.</tt>
</p>
<div class="h5">
<h5>-d, --deployScope &lt;argument&gt;</h5>
</div>
<p>
<tt>Add scope to deploy.wsdd: "Application", "Request", or "Session". If this option does not appear, no scope tag appears in deploy.wsdd, which the Axis runtime defaults to "Request".</tt>
</p>
<div class="h5">
<h5>-t, --testCase</h5>
</div>
<p>
<tt>Generate a client-side JUnit test case. This test case can stand on its own, but it doesn't really do anything except pass default values (null for objects, 0 or false for primitive types). Like the generated implementation file, the generated test case file could be considered a template that you may fill in.</tt>
</p>
<div class="h5">
<h5>-a, --all</h5>
</div>
<p>
<tt>Generate code for all elements, even unreferenced ones. By default, WSDL2Java only generates code for those elements in the WSDL file that are referenced.</tt>
</p>
<p>
<tt>A note about what it means to be referenced. We cannot simply say: start with the services, generate all bindings referenced by the service, generate all portTypes referenced by the referenced bindings, etc. What if we're generating code from a WSDL file that only contains portTypes, messages, and types? If WSDL2Java used service as an anchor, and there's no service in the file, then nothing will be generated. So the anchor is the lowest element that exists in the WSDL file in the order:</tt>
</p>
<ol>
<li>
<tt>types</tt>
</li>
<li>
<tt>portTypes</tt>
</li>
<li>
<tt>bindings</tt>
</li>
<li>
<tt>services</tt>
</li>
</ol>
<p>
<tt>For example, if a WSDL file only contained types, then all the listed types would be generated. But if a WSDL file contained types and a portType, then that portType will be generated and only those types that are referenced by that portType.</tt>
</p>
<p>
<tt>Note that the anchor is searched for in the WSDL file appearing on the command line, <strong>not</strong> in imported WSDL files. This allows one WSDL file to import constructs defined in another WSDL file without the nuisance of having all the imported WSDL file's constructs generated.</tt>
</p>
<div class="h5">
<h5>-T, --typeMappingVersion &lt;argument&gt;</h5>
</div>
<p>
<tt>Indicate 1.1 or 1.2. The default is 1.2 (SOAP 1.2 JAX-RPC compliant).</tt>
</p>
<div class="h5">
<h5>-F, --factory &lt;argument&gt;</h5>
</div>
<p>
<tt>Used to extend the functionality of the WSDL2Java emitter. The argument is the name of a class which extends JavaWriterFactory.</tt>
</p>
<div class="h5">
<h5>-H, --helperGen</h5>
</div>
<p>
<tt>Emits separate Helper classes for meta data.</tt>
</p>
<div class="h5">
<h5>-U, --user &lt;argument&gt;</h5>
</div>
<p>
<tt>This username is used in resolving the WSDL-URI provided as the input to WSDL2Java. If the URI contains a username, this will override the command line switch. An example of a URL with a username and password is: <span class="codefrag">http://user:password@hostname:port/path/to/service?WSDL</span></tt>
</p>
<div class="h5">
<h5>-P, --password &lt;argument&gt;</h5>
</div>
<p>
<tt>This password is used in resolving the WSDL-URI provided as the input to WSDL2Java. If the URI contains a password, this will override the command line switch.<br>
</tt>
</p>
<div class="h5">
<h5>-c, --implementationClassName &lt;argument&gt;</h5>
</div>
<p>
<tt>Set the name of the implementation class.Especially useful when exporting an existing class as a web service using java2wsdl followed by wsdl2java.&nbsp;If you are using the skeleton deploy option you must make sure, after generation, that your implementation class implements the port type name interface generated by wsdl2java.&nbsp;You should also make sure that all your exported methods throws java.lang.RemoteException.</tt>
</p>
<div class="h5">
<h5>Java2WSDL Reference</h5>
</div>
<p>Here is the help message generated from the current tool:</p>
<pre>Java2WSDL emitter
Usage: java org.apache.axis.wsdl.Java2WSDL [options] class-of-portType
Options:
<tt> -h, --help
print this message and exit
-I, --input &lt;argument&gt;
input WSDL filename
-o, --output &lt;argument&gt;
output WSDL filename
-l, --location &lt;argument&gt;
service location url
-P, --portTypeName &lt;argument&gt;
portType name (obtained from class-of-portType if not specified)
-b, --bindingName &lt;argument&gt;
binding name (--servicePortName value + "SOAPBinding" if not specified)
-S, --serviceElementName &lt;argument&gt;
service element name (defaults to --servicePortName value + "Service")
-s, --servicePortName &lt;argument&gt;
service port name (obtained from --location if not specified)
-n, --namespace &lt;argument&gt;
target namespace
-p, --PkgtoNS &lt;argument&gt;=&lt;value&gt;
package=namespace, name value pairs
-m, --methods &lt;argument&gt;
space or comma separated list of methods to export
-a, --all
look for allowed methods in inherited class
-w, --outputWsdlMode &lt;argument&gt;
output WSDL mode: All, Interface, Implementation
-L, --locationImport &lt;argument&gt;
location of interface wsdl
-N, --namespaceImpl &lt;argument&gt;
target namespace for implementation wsdl
-O, --outputImpl &lt;argument&gt;
output Implementation WSDL filename, setting this causes
--outputWsdlMode to be ignored
-i, --implClass &lt;argument&gt;
optional class that contains implementation of methods in class-of-portType.
The debug information in the class is used
to obtain the method parameter names, which are used to set
the WSDL part names.
-x, --exclude &lt;argument&gt;
space or comma separated list of methods not to export
-c, --stopClasses &lt;argument&gt;
space or comma separated list of class names which will stop
inheritance search if --all switch is given
-T, --typeMappingVersion &lt;argument&gt;
indicate 1.1 or 1.2. The default is 1.1 (SOAP 1.1 JAX-RPC
compliant 1.2 indicates SOAP 1.1 encoded.)
-A, --soapAction &lt;argument&gt;
value of the operations soapAction field. Values are DEFAULT,
OPERATION or NONE. OPERATION forces soapAction to the name
of the operation. DEFAULT causes the soapAction to be set
according to the operations meta data (usually ""). NONE forces
the soapAction to "". The default is DEFAULT.
-y, --style &lt;argument&gt;
The style of binding in the WSDL, either DOCUMENT, RPC, or WRAPPED.
-u, --use &lt;argument&gt;
The use of items in the binding, either LITERAL or ENCODED
-e, --extraClasses &lt;argument&gt;
A space or comma separated list of class names to be added to
the type section.
-C, --importSchema
A file or URL to an XML Schema that should be physically
imported into the generated WSDL
-X, --classpath
additional classpath elements
Details:
portType element name= &lt;--portTypeName value&gt; OR &lt;class-of-portType name&gt;
binding element name= &lt;--bindingName value&gt; OR &lt;--servicePortName value&gt;Soap
Binding
service element name= &lt;--serviceElementName value&gt; OR &lt;--portTypeName value&gt;
Service
port element name= &lt;--servicePortName value&gt;
address location = &lt;--location value&gt;
</tt>
</pre>
<tt></tt>
<p>
<tt><strong>-h , --help</strong>
<br> Prints the help message.</tt>
</p>
<p>
<tt><strong>-I, --input &lt;WSDL file&gt;</strong>
<br> Optional parameter that indicates the name of the input wsdl file. The output wsdl file will contain everything from the input wsdl file plus the new constructs. If a new construct is already present in the input wsdl file, it is not added. This option is useful for constructing a wsdl file with multiple ports, bindings, or portTypes.</tt>
</p>
<p>
<tt><strong>-o, --output &lt;WSDL file&gt;</strong>
<br> Indicates the name of the output WSDL file. If not specified, a suitable default WSDL file is written into the current directory.</tt>
</p>
<p>
<tt><strong>-l, --location &lt;location&gt;</strong>
<br> Indicates the url of the location of the service. The name after the last slash or backslash is the name of the service port (unless overridden by the -s option). The service port address location attribute is assigned the specified value.</tt>
</p>
<p>
<tt><strong>-P, --portTypeName &lt;name&gt;</strong>
<br> Indicates the name to use for the portType element. If not specified, the class-of-portType name is used.</tt>
</p>
<p>
<tt><strong>-b, --bindingName &lt;name&gt;</strong>
<br> Indicates the name to use for the binding element. If not specified, the value of the --servicePortName + "SoapBinding" is used.</tt>
</p>
<p>
<tt><strong>-S, --serviceElementName &lt;name&gt;</strong>
<br> Indicates the name of the service element. If not specified, the service element is the &lt;portTypeName&gt;Service.</tt>
</p>
<p>
<tt><strong>-s, --servicePortName &lt;name&gt;</strong>
<br> Indicates the name of the service port. If not specified, the service port name is derived from the --location value.</tt>
</p>
<p>
<tt><strong>-n, --namespace &lt;target namespace&gt;</strong>
<br> Indicates the name of the target namespace of the WSDL.</tt>
</p>
<p>
<tt><strong>-p, --PkgToNS &lt;package&gt; &lt;namespace&gt;</strong>
<br> Indicates the mapping of a package to a namespace. If a package is encountered that does not have a namespace, the Java2WSDL emitter will generate a suitable namespace name. This option may be specified multiple times.</tt>
</p>
<p>
<tt><strong>-m, --methods &lt;arguments&gt;</strong>
<br> If this option is specified, only the indicated methods in your interface class will be exported into the WSDL file. The methods list must be comma separated. If not specified, all methods declared in the interface class will be exported into the WSDL file.</tt>
</p>
<p>
<tt><strong>-a, --all</strong>
<br> If this option is specified, the Java2WSDL parser will look into extended classes to determine the list of methods to export into the WSDL file.</tt>
</p>
<p>
<tt><strong>-w, --outputWSDLMode &lt;mode&gt;</strong>
<br> Indicates the kind of WSDL to generate. Accepted values are:</tt>
</p>
<ul>
<li>
<tt>All --- (default) Generates wsdl containing both interface and implementation WSDL constructs.</tt>
</li>
<li>
<tt>Interface --- Generates a WSDL containing the interface constructs (no service element).</tt>
</li>
<li>
<tt>Implementation -- Generates a WSDL containing the implementation. The interface WSDL is imported via the -L option.</tt>
</li>
</ul>
<p>
<tt><strong>-L, --locationImport &lt;url&gt;</strong>
<br> Used to indicate the location of the interface WSDL when generating an implementation WSDL.</tt>
</p>
<p>
<tt><strong>-N, --namespaceImpl &lt;namespace&gt;</strong>
<br> Namespace of the implementation WSDL.</tt>
</p>
<p>
<tt><strong>-O, --outputImpl &lt;WSDL file&gt;</strong>
<br> Use this option to indicate the name of the output implementation WSDL file. If specified, Java2WSDL will produce interface and implementation WSDL files. If this option is used, the -w option is ignored.</tt>
</p>
<p>
<tt><strong>-i, --implClass &lt;impl-class&gt;</strong>
<br> Sometimes extra information is available in the implementation class file. Use this option to specify the implementation class.</tt>
</p>
<p>
<tt><strong>-x, --exclude &lt;list&gt;</strong>
<br> List of methods to not exclude from the wsdl file.</tt>
</p>
<p>
<tt><strong>-c, --stopClasses &lt;list&gt;</strong>
<br> List of classes which stop the Java2WSDL inheritance search.</tt>
</p>
<p>
<tt><strong>-T, --typeMappingVersion &lt;version&gt;</strong>
<br> Choose the default type mapping registry to use. Either 1.1 or 1.2.</tt>
</p>
<p>
<tt><strong>-A, --soapAction &lt;argument&gt;</strong>
<br> The value of the operations soapAction field. Values are DEFAULT, OPERATION or NONE. OPERATION forces soapAction to the name of the operation. DEFAULT causes the soapAction to be set according to the operation's meta data (usually ""). NONE forces the soapAction to "". The default is DEFAULT.</tt>
</p>
<p>
<tt><strong>-y, --style &lt;argument&gt;</strong>
<br> The style of the WSDL document: RPC, DOCUMENT or WRAPPED. The default is RPC. If RPC is specified, an rpc wsdl is generated. If DOCUMENT is specified, a document wsdl is generated. If WRAPPED is specified, a document/literal wsdl is generated using the wrapped approach. Wrapped style forces the use attribute to be literal.</tt>
</p>
<p>
<tt><strong>-u, --use &lt;argument&gt;</strong>
<br> The use of the WSDL document: LITERAL or ENCODED. If LITERAL is specified, the XML Schema defines the representation of the XML for the request. If ENCODED is specified, SOAP encoding is specified in the generated WSDL.</tt>
</p>
<p>
<tt><strong>-e, --extraClasses &lt;argument&gt;</strong>
<br> Specify a space or comma seperated list of class names which should be included in the <strong>types</strong> section of the WSDL document. This is useful in the case where your service interface references a base class and you would like your WSDL to contain XML Schema type defintions for these other classes. The --extraClasses option can be specified duplicate times. Each specification results in the additional classes being added to the list.</tt>
</p>
<p>
<tt><strong>-C, --importSchema</strong>
<br> A file or URL to an XML Schema that should be physically imported into the generated WSDL</tt>
</p>
<p>
<tt>
<br>
<strong>-X, --classpath</strong>
<br> Additional classpath elements</tt>
</p>
<p>
<tt>&nbsp;</tt>
</p>
<div class="h5">
<h5>Deployment (WSDD) Reference</h5>
</div>
<p>Note : all the elements referred to in this section are in the WSDD namespace, namely "http://xml.apache.org/axis/wsdd/".</p>
<dl>
<dt>
<strong>&lt;deployment&gt;</strong>
</dt>
<dd>The root element of the deployment document which tells the Axis engine that this is a deployment. A deployment document may represent EITHER a complete engine configuration OR a set of components to deploy into an active engine.</dd>
<dt>
<br>
<strong>&lt;GlobalConfiguration&gt;</strong>
</dt>
<dd>This element is used to control the engine-wide configuration of Axis. It may contain several subelements: <ul>
<li>
<strong>&lt;parameter&gt;</strong> : This is used to set options on the Axis engine - see the <a href="##global_configuration">Global Axis Configuration</a> section below for more details. Any number of <strong>&lt;parameter&gt;</strong> elements may appear.</li>
<li>
<strong>&lt;role&gt;</strong> : This is used to set a SOAP actor/role URI which the engine will recognize. This allows SOAP headers targeted at that role to be successfully processed by the engine. Any number of <strong>&lt;role&gt;</strong> elements may appear.</li>
<li>
<strong>&lt;requestFlow&gt;</strong> : This is used to configure global request Handlers, which will be invoked before the actual service on every request. You may put any number of <strong>&lt;handler&gt;</strong> or <strong>&lt;chain&gt;</strong> elements (see below) inside the <strong>&lt;requestFlow&gt;</strong>, but there may only be one <strong>&lt;requestFlow&gt;</strong>.</li>
</ul>
</dd>
<dd>
<ul>
<li>
<strong>&lt;responseFlow&gt;</strong> : This is used to configure global response Handlers, which will be invoked after the actual service on every request. You may put any number of <strong>&lt;handler&gt;</strong> or <strong>&lt;chain&gt;</strong> elements (see below) inside the <strong>&lt;responseFlow&gt;</strong>, but there may only be one <strong>&lt;responseFlow&gt;</strong>.</li>
</ul>
</dd>
<dt></dt>
<dt>
<strong>&lt;undeployment&gt;</strong>
</dt>
<dd>The root element of the deployment document which tells Axis that this is an undeployment.</dd>
<dt></dt>
<dt>
<strong>&lt;handler [name="</strong><em>name</em><strong>"] type="</strong><em>type</em><strong>"/&gt;</strong>
</dt>
<dd>Belongs at the top level inside a <strong>&lt;deployment&gt;</strong> or <strong>&lt;undeployment&gt;</strong>, or inside a <strong>&lt;chain&gt;</strong>, <strong>&lt;requestFlow&gt;</strong>, or <strong>&lt;responseFlow&gt;</strong>. Defines a Handler, and indicates the type of the handler. "Type" is either the name of another previously defined Handler, or a QName of the form "<strong>java:class.name</strong>". The optional "name" attribute allows you to refer to this Handler definition in other parts of the deployment. May contain an arbitrary number of <strong>&lt;parameter name="</strong><em>name</em><strong>" value="</strong><em>value</em><strong>"&gt;</strong> elements, each of which will supply an option to the deployed Handler.</dd>
<dt></dt>
<dt>
<strong>&lt;service name="</strong><em>name</em><strong>" provider="</strong><em>provider</em><strong>" &gt;</strong>
</dt>
<dd>Deploys/undeploys an Axis Service. This is the most complex WSDD tag, so we're going to spend a little time on it.<br>
<br>
<strong>Options</strong> may be specified as follows : <span class="codefrag">&lt;parameter name="name" value="value"/&gt;</span>, and common ones include:<br>
<br>
<ul>
<li>
<strong>className</strong> : the backend implementation class<br>
</li>
<li>
<strong>allowedMethods</strong> : Each provider can determine which methods are allowed to be exposed as web services.<br> To summaries for Axis supplied providers:<br>
<p>
<u>Java RPC Provider</u> (provider="java:RPC") by default all public methods specified by the class in the className option, including any inherited methods are available as web services.<br> For more details regarding the Java Provider please see <strong>WHERE???</strong>.</p>
<p>
<u>Java MsgProvder</u> (provider="java:MSG") <!-- Glen to provide details --></p>
<p>In order to further restrict the above methods, the <strong>allowedMethods</strong> option may be used to specify in a space delimited list the names of only those methods which are allowed as web services. It is also possible to specify for this option the value <strong>"*"</strong> which is functionally equivalent to not specify the option at all. Also, it is worth mentioning that the <strong>operation</strong> element is used to further define the methods being offered, but it does not affect which methods are made available.</p>
<p>
<em>Note, while this is true for Axis supplied providers, it is implementation dependent on each individual provider. Please review your providers documentation on how or if it supports this option.</em>
</p>
<p>
<strong>Note, Exposing any web service has security implications.</strong>As a best practices guide it is <u>highly</u> recommend when offering a web service in un secure environment to restrict allowed methods to only those required for the service being offered. And, for those that are made available, to <strong>fully</strong> understand their function and how they may access and expose your systems's resources.</p>
</li>
<li>
<strong>allowedRoles</strong> : comma-separated list of roles allowed to access this service (Note that these are security roles, as opposed to SOAP roles. Security roles control access, SOAP roles control which SOAP headers are processed.)<br>
</li>
<li>
<strong>extraClasses</strong> : Specify a space or comma seperated list of class names which should be included in the <strong>types</strong> section of the WSDL document. This is useful in the case where your service interface references a base class and you would like your WSDL to contain XML Schema type defintions for these other classes.</li>
</ul>
<br> If you wish to define handlers which should be invoked either before or after the service's provider, you may do so with the <strong>&lt;requestFlow&gt;</strong> and the <strong>&lt;responseFlow&gt;</strong> subelements. Either of those elements may be specified inside the <strong>&lt;service&gt;</strong> element, and their semantics are identical to the <strong>&lt;chain&gt;</strong> element described below - in other words, they may contain <strong>&lt;handler&gt;</strong> and <strong>&lt;chain</strong>&gt; elements which will be invoked in the order they are specified.<br>
<p>To control the <a href="http://www.w3.org/TR/2003/REC-soap12-part1-20030624/#soaproles">roles</a> that should be recognized by your service Handlers, you can specify any number of <strong>&lt;role&gt;</strong> elements inside the service declaration.</p>
<br> Example:<br>
<pre>&lt;service name="test"&gt;
&lt;parameter name="className" value="test.Implementation"/&gt;
&lt;parameter name="allowedMethods" value="*"/&gt;
&lt;namespace&gt;http://testservice/&lt;/namespace&gt;
&lt;role&gt;http://testservice/MyRole&lt;/role&gt;
&lt;requestFlow&gt; &lt;!-- Run these before processing the request --&gt;
&lt;handler type="java:MyHandlerClass"/&gt;
&lt;handler type="somethingIDefinedPreviously"/&gt;
&lt;/requestFlow&gt;
&lt;/service&gt;
</pre>
<strong>Metadata</strong> may be specified about particular operations in your service by using the &lt;operation&gt; tag inside a service. This enables you to map the java parameter names of a method to particular XML names, to specify the parameter modes for your parameters, and to map particular XML names to particular operations.<br>
<br> &lt;operation name="method"&gt;<br> &lt;/operation&gt;<br>
</dd>
<dt></dt>
<dt>
<strong>&lt;chain name="</strong><em>name</em><strong>"</strong><strong>&gt; &lt;subelement/&gt;... &lt;/chain&gt;</strong>
</dt>
<dd>Defines a chain. Each <em>handler</em> (i.e. deployed handler name) in the list will be invoked() in turn when the chain is invoked. This enables you to build up "modules" of commonly used functionality. The subelements inside chains may be &lt;<strong>handler</strong>&gt;s or &lt;<strong>chain</strong>&gt;s. &lt;handler&gt;s inside a &lt;chain&gt; may either be defined in terms of their Java class:<br>
<pre>&lt;chain name="myChain"&gt;
&lt;handler type="java:org.apache.axis.handlers.LogHandler"/&gt;
&lt;/chain&gt;
</pre>or may refer to previously defined &lt;handlers&gt;, with the "type" of the handler referring to the name of the other handler definition:<br>
<pre>&lt;handler name="logger" type="java:org.apache.axis.handlers.LogHandler"/&gt;<br>&lt;chain name="myChain"/&gt;<br> &lt;handler type="logger"/&gt;<br>&lt;/chain&gt;
</pre>
</dd>
<dt></dt>
<dt>
<strong>&lt;transport name="</strong><em>name</em><strong>"&gt;</strong>
</dt>
<dd>Defines a transport on the server side. Server transports are invoked when an incoming request arrives. A server transport may define <strong>&lt;requestFlow&gt;</strong> and/or <strong>&lt;responseFlow&gt;</strong> elements to specify handlers/chains which should be invoked during the request (i.e. incoming message) or response (i.e. outgoing message) portion of processing (this function works just like the <strong>&lt;service&gt;</strong> element above). Typically handlers in the transport request/response flows implement transport-specific functionality, such as parsing protocol headers, etc.</dd>
<dd>
<br>
<br>
</dd>
<dd>For any kind of transport (though usually this relates to HTTP transports), users may allow Axis servlets to perform arbitrary actions (by means of a "plug-in") when specific query strings are passed to the servlet (see the section <a href="#developers-guide.html#Axis%20Servlet%20Query%20String%20Plug-ins">Axis Servlet Query String Plug-ins</a> in the <a href="#developers-guide.html">Axis Developer's Guide</a> for more information on what this means and how to create a plug-in). When the name of a query string handler class is known, users can enable it by adding an appropriate <strong>&lt;parameter&gt;</strong> element in the Axis server configuration's <strong>&lt;transport&gt;</strong> element. An example configuration might look like the following:<br>
<br>
<span class="codefrag">&lt;transport name="http"&gt; &lt;parameter name="useDefaultQueryStrings" value="false" /&gt; &lt;parameter name="qs.name" value="class.name" /&gt; &lt;/transport&gt;</span>
<br> In this example, the query string that the Axis servlet should respond to is <em>?name</em> and the class that it should invoke when this query string is encountered is named <span class="codefrag">class.name</span>. The <span class="codefrag">name</span> attribute of the <strong>&lt;parameter&gt;</strong> element must start with the string "qs." to indicate that this <strong>&lt;parameter&gt;</strong> element defines a query string handler. The <span class="codefrag">value</span> attribute must point to the name of a class implementing the <span class="codefrag">org.apache.axis.transport.http.QSHandler</span> interface. By default, Axis provides for three Axis servlet query string handlers (<em>?list</em>, <em>?method</em>, and <em>?wsdl</em>). See the Axis server configuration file for their definitions. If the user wishes not to use these default query string handlers (as in the example), a <strong>&lt;parameter&gt;</strong> element with a <span class="codefrag">name</span> attribute equal to "useDefaultQueryStrings" should have its <span class="codefrag">value</span> attribute set to <span class="codefrag">false</span>. By default it is set to <span class="codefrag">true</span> and the element is not necessary if the user wishes to have this default behavior.</dd>
<dt></dt>
<dt>
<strong>&lt;transport name="</strong><em>name</em><strong>" pivot="</strong><em>handler type</em><strong>"</strong><strong>&gt;</strong>
</dt>
<dd>Defines a transport on the client side, which is invoked when sending a SOAP message. The "pivot" attribute specifies a Handler to be used as the actual sender for this transport (for example, the HTTPSender). Request and response flows may be specified as in server-side transports to do processing on the request (i.e. outgoing message) or response (i.e. incoming message).</dd>
<dt></dt>
<dt>
<strong>&lt;typeMapping qname="</strong><em>ns:localName</em><strong>" classname="</strong><em>classname</em><strong>" serializer="</strong><em>classname</em><strong>" deserializer="</strong><em>classname</em><strong>"/&gt;</strong>
</dt>
<dd>Each typeMapping maps an XML qualified name to/from a Java class, using a specified Serializer and Deserializer.</dd>
<dt></dt>
<dt>
<strong>&lt;beanMapping qname="</strong><em>ns:localName</em><strong>" classname="</strong><em>classname</em><strong>"</strong><strong>&gt;</strong>
</dt>
<dd>A simplified type mapping, which uses pre-defined serializers/deserializers to encode/decode JavaBeans. The class named by "classname" must follow the JavaBean standard pattern of get/set accessors.</dd>
<dt>&nbsp;</dt>
<dt>
<strong>&lt;documentation&gt;</strong>
</dt>
<dd>Can be used inside a <strong>&lt;service&gt;</strong>, an <strong>&lt;operation&gt;</strong> or an operation <strong>&lt;parameter&gt;</strong>. The content of the element is arbitrary text which will be put in the generated wsdl inside a wsdl:document element.<br>
<br> Example:<br>
<span class="codefrag">&lt;operation name="echoString" &gt; &nbsp;&nbsp;&lt;documentation&gt;This operation echoes a string&lt;/documentation&gt; &nbsp;&nbsp;&lt;parameter name="param"&gt; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;documentation&gt;a string&lt;/documentation&gt; &nbsp;&nbsp;&lt;/parameter&gt; &lt;/operation&gt;</span>
</dd>
</dl>
<p>
<a name="java/reference.html#global_configuration"></a>
</p>
<div class="h5">
<h5>Global Axis Configuration</h5>
</div>
<p>The server is configured (by default) by values in the server-config.wsdd file, though a dedicated Axis user can write their own configuration handler, and so store configuration data in an LDAP server, database, remote web service, etc. Consult the source on details as to how to do that. You can also add options to the web.xml file and have them picked up automatically. We don't encourage that as it is nice to keep configuration stuff in one place.</p>
<p>In the server-config file, there is a global configuration section, which supports parameter name/value pairs as nested elements. Here are the options that we currently document, though there may be more (consult the source, as usual).</p>
<pre> &lt;globalConfiguration&gt;
&lt;parameter name="adminPassword" value="admin"/&gt;
&lt;parameter name="attachments.Directory" value="c:\temp\attachments"/&gt;
&lt;parameter name="sendMultiRefs" value="true"/&gt;
&lt;parameter name="sendXsiTypes" value="true"/&gt;
&lt;parameter name="attachments.implementation"
value="org.apache.axis.attachments.AttachmentsImpl"/&gt;
&lt;parameter name="sendXMLDeclaration" value="true"/&gt;
&lt;parameter name="enable2DArrayEncoding" value="true"/&gt;
&lt;/globalConfiguration&gt;
</pre>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tbody>
<tr class="b">
<td><strong>adminPassword</strong></td><td>Adminstrator password, as used by AdminService.</td>
</tr>
<tr class="a">
<td><strong>attachments.Directory</strong></td><td>The directory where attachments end up. This should be in the syntax appropriate for the target platform.</td>
</tr>
<tr class="b">
<td><strong>attachments.implementation</strong></td><td>Name of class that implements attachments support. Default is <tt>org.apache.axis.attachments.AttachmentsImpl</tt></td>
</tr>
<tr class="a">
<td><strong>axis.enableListQuery</strong></td><td>Flag to enable the "list the WSDD" feature. Set to false by default, because listing the current system config can expose information (such as the adminservice password) that one does not want widely avaialable.</td>
</tr>
<tr class="b">
<td><strong>axis.disableServiceList</strong></td><td>Flag to disable the list of services feature. Set to false by default, which enables the list of services by the AxisServlet when a GET request is performed on the servlet root.</td>
</tr>
<tr class="a">
<td><strong>axis.servicesPath</strong></td><td>Path to the Axis servlet. This should be the same as the services servlet-mapping defined in web.xml. Used for displaying the list of services. Default is "/services/".</td>
</tr>
<tr class="b">
<td><strong>axis.Compiler</strong></td><td>Compiler adapter classname for JWS compilation. Default is <tt>org.apache.axis.components.compiler.Javac</tt>; change this to <tt>org.apache.axis.components.compiler.Jikes</tt> to invoke jikes instead.</td>
</tr>
<tr class="a">
<td><strong>axis.development.system</strong></td><td>Flag to switch the system from <em>production</em> (false) to <em>development</em> (true). A development system gives out stack traces and other information that production boxes should not.</td>
</tr>
<tr class="b">
<td><strong>axis.xmlEncoding</strong></td><td>Encoding used for XML messages -either UTF-8 (default) or UTF-16</td>
</tr>
<tr class="a">
<td><strong>axis.engineConfigClass</strong></td><td>Name of a class that provides Axis configuration. Implement a new class implementing <tt>EngineConfiguration</tt> and name it here to use alternate configuration mechanisms.</td>
</tr>
<tr class="b">
<td><strong>axis.jws.servletClassDir</strong></td><td>Path to where compiled JWS pages are placed.</td>
</tr>
<tr class="a">
<td><strong>axis.sendMinimizedElements</strong></td><td>Flag to turn on support for a when .NET1.0 can't correctly handle some bits of XML <a href="http://issues.apache.org/jira/secure/ViewIssue.jspa?key=AXIS-667">that it should.</a> The flag defaults to true; if some .NET clients are failing to handle a Web Service returning an empty array inside another object, set this flag to <em>false</em>.</td>
</tr>
<tr class="b">
<td><strong>enable2DArrayEncoding</strong></td><td>Set this to "true" to turn 2D array encoding on; this encoding is incompatible with .NET 1.0: default="false".</td>
</tr>
<tr class="a">
<td><strong>sendMultiRefs</strong></td><td>true/false flag to control whether multirefs are sent or not.</td>
</tr>
<tr class="b">
<td><strong>sendXMLDeclaration</strong></td><td>true/false flag to control whether the &lt;?xml?&gt; declaration is sent in messages</td>
</tr>
<tr class="a">
<td><strong>sendXsiTypes</strong></td><td>true/false flag to enable/disable sending the type of every value sent over the wire. Defaults to true.</td>
</tr>
<tr class="b">
<td><strong>SingleSOAPVersion</strong></td><td>When set to either "1.1" or "1.2", this configures the engine to only accept the specified SOAP version. Attempts to connect to the engine using another version will result in a fault.</td>
</tr>
<tr class="a">
<td><strong>use-servlet-security</strong></td><td>Set this flag to hand authentication off to the servlet container.</td>
</tr>
<!-- end table -->
</tbody>
</table>
<p>
<a name="java/reference.html#individual_service"></a>
</p>
<div class="h5">
<h5>Individual Service Configuration</h5>
</div>
<p>
<em>TODO</em>
</p>
<p>Here are some of the per-service configuration options are available; these can be set in the wsdd file used to deploy a service, from where they will be picked up.</p>
<p>More may exist.</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td><strong>style</strong></td><td>whether to use RPC:enc or doc/lit encoding</td>
</tr>
<tr class="a">
<td><strong>SingleSOAPVersion</strong></td><td>When set to either "1.1" or "1.2", this configures a service to only accept the specified SOAP version. Attempts to connect to the service using another version will result in a fault.</td>
</tr>
<tr class="b">
<td><strong>wsdlFile</strong></td><td>The path to a WSDL File; can be an absolute path or a resource that axis.jar can load. Useful to export your custom WSDL file. When specify a path to a resource, place a forward slash to start at the beginning of the classpath (e.g "/org/someone/res/mywsdl.wsdl"). How does Axis know whether to return a file or resource? It looks for a file first, if that is missing a resource is returned.</td>
</tr>
<!-- TODO: what does this mean?
<tr><td><b>streaming</b></td>
<td>
</td>
</tr>
-->
</table>
<p>
<a name="java/reference.html#axis_logging"></a>
</p>
<div class="h5">
<h5>Axis Logging Configuration</h5>
</div>
<p>Axis uses the Jakarta Projects's <a href="http://jakarta.apache.org/commons/logging.html">commons-logging API</a>, as implemented in <tt>commons-logging.jar</tt> to implement logging throughout the code. Normally this library routes the logging to the Log4j library, provided that an implementation of log4j is on the classpath of the server or client. The commons-logging API can also bind to Avalon, <tt>System.out</tt> or the Java1.4 logger. The JavaDocs for the library explain the process for selecting a logger, which can be done via a system property or a properties file in the classpath.</p>
<p>Log4J can be configured using the file log4j.properties in the classpath; later versions also support an XML configuration. Axis includes a preconfigured log4j.properties file in <tt>axis.jar</tt>. While this is adequate for basic use, any complex project will want to modify their own version of the file. Here is what to do</p>
<ol>
<li>Open up axis.jar in a zipfile viewer and remove log4j.properties from the jar</li>
<li>Or, when building your own copy of axis.jar, set the Ant property <tt>exclude.log4j.configuration</tt> to keep the properties file out the JAR.</li>
<li>Create your own log4J.properties file, and include it in <tt>WEB-INF/classes</tt> (server-side), in your main application JAR file client side.</li>
<li>Edit this log4J properties file to your hearts content. Server side, setting up rolling logs with fancy html output is convenient, though once you start clustering the back end servers that ceases to be as usuable. Log4J power tools, such as 'chainsaw', are the secret here.</li>
</ol>
<div class="h5">
<h5>Log Categories</h5>
</div>
<p>Axis classes that log information create their own per-class log, each of which may output information at different levels. For example, the main entry point servlet has a log called <tt>org.apache.axis.transport.http.AxisServlet</tt>, the AxisEngine is <tt>org.apache.axis.AxisEngine</tt>, and so on. There are also special logs for special categories.</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td><tt>org.apache.axis.TIME</tt></td><td>A log that records the time to execute incoming messages, splitting up into preamble, invoke, post and send times. These are only logged at debug level.</td>
</tr>
<tr class="a">
<td><tt>org.apache.axis.EXCEPTIONS</tt></td><td>Exceptions that are sent back over the wire. AxisFaults, which are normally created in 'healthy' operation, are logged at debug level. Other Exceptions are logged at the Info level, as they are more indicative of server side trouble.</td>
</tr>
<tr class="b">
<td><tt>org.apache.axis.enterprise</tt></td><td>''Enterprise'' level stuff, which generally means stuff that an enterprise product might want to track, but in a simple environment (like the Axis build) would be nothing more than a nuisance.</td>
</tr>
</table>
<p>
<a name="java/reference.html#axis_components"></a>
</p>
<div class="h5">
<h5>Pre-Configured Axis Components Reference</h5>
</div>
<div class="h5">
<h5>On the server:</h5>
</div>
<dl>
<dt>
<strong>SimpleSessionHandler</strong>
</dt>
<dd>uses SOAP headers to do simple session management</dd>
<dt></dt>
<dt>
<strong>LogHandler</strong>
</dt>
<dd>The LogHandler will simply log a message to a logger when it gets invoked.</dd>
<dt>
<strong>SoapMonitorHandler</strong>
</dt>
<dd>Provides the hook into the message pipeline sending the SOAP request and response messages to the SoapMonitor utility.</dd>
<dt>
<strong>DebugHandler</strong>
</dt>
<dd>Example handler that demonstrates dynamically setting the debug level based on a the value of a soap header element.</dd>
<dt></dt>
<dt>
<strong>ErrorHandler</strong>
</dt>
<dd>Example handler that throws an AxisFault to stop request/response flow processing.</dd>
<dt></dt>
<dt>
<strong>EchoHandler</strong>
</dt>
<dd>The EchoHandler copies the request message into the response message.</dd>
<dt></dt>
<dt>
<strong>HTTPAuth</strong>
</dt>
<dd>The HTTPAuthHandler takes HTTP-specific authentication information (right now, just Basic authentication) and turns it into generic MessageContext properties for username and password</dd>
<dt>
<strong>SimpleAuthenticationHandler</strong>
</dt>
<dd>The SimpleAuthentication handler passes a MessageContext to a SecurityProvider (see org.apache.axis.security) to authenticate the user using whatever information the SecurityProvider wants (right now, just the username and password).</dd>
<dt>
<strong>SimpleAuthorizationHandler</strong>
</dt>
<dd>This handler, typically deployed alongside the SimpleAuthenticationHandler (a chain called "authChecks" is predefined for just this combination), checks to make sure that the currently authenticated user satisfies one of the allowed roles for the target service. Throws a Fault if access is denied.</dd>
<dt>
<strong>MD5AttachHandler</strong>
</dt>
<dd>Undocumented, uncalled, untested handler that generates an MD5 hash of attachment information and adds the value as an attribute in the soap body.</dd>
<dt></dt>
<dt>
<strong>URLMapper</strong>
</dt>
<dd>The URLMapper, an HTTP-specific handler, usually goes on HTTP transport chains (it is deployed by default). It serves to do service dispatch based on URL - for instance, this is the Handler which allows URLs like http://localhost:8080/axis/services/MyService?wsdl to work.</dd>
<dt></dt>
<dt>
<strong>RPCProvider</strong>
</dt>
<dd>The RPCProvider is the pivot point for all RPC services. It accepts the following options:<br>
<strong>className</strong> = the class of the backend object to invoke<br>
<strong>methodName</strong> = a space-separated list of methods which are exported as web services. The special value "*" matches all public methods in the class.</dd>
<dt>
<strong>MsgProvider</strong>
</dt>
<dd>The MsgProvider is the pivot point for all messaging services. It accepts the following options:<br>
</dd>
<dd>
<strong>className</strong> = the class of the backend object to invoke<br>
<strong>methodName</strong> = a space-separated list of methods which are exported as web services. The special value "*" matches all public methods in the class.</dd>
<dt>
<strong>JWSHandler</strong>
</dt>
<dd>Performs drop-in deployment magic.</dd>
<dt>
<strong>JAXRPCHandler</strong>
</dt>
<dd>Wrapper around JAX-RPC compliant handlers that exposes an Axis handler interface to the engine.</dd>
<dt></dt>
<dt>
<strong>LocalResponder</strong>
</dt>
<dd>The LocalResponder is a Handler whose job in life is to serialize the response message coming back from a local invocation into a String. It is by default on the server's local transport response chain, and it ensures that serializing the message into String form happens in the context of the server's type mappings.</dd>
</dl>
<div class="h5">
<h5>On the client:</h5>
</div>
<dl>
<dt>
<strong>SimpleSessionHandler</strong>
</dt>
<dd>uses SOAP headers to do simple session management</dd>
<dt></dt>
<dt>
<strong>JAXRPCHandler</strong>
</dt>
<dd>Wrapper around JAX-RPC compliant handlers that exposes an Axis handler interface to the engine.</dd>
<dt></dt>
<dt>
<strong>HTTPSender</strong>
</dt>
<dd>A Handler which sends the request message to a remote server via HTTP, and collects the response message.</dd>
<dt>
<strong>LocalSender</strong>
</dt>
<dd>A Handler which sends the request message to a "local" AxisServer, which will process it and return a response message. This is extremely useful for testing, and is by default mapped to the "local:" transport. So, for instance, you can test the AdminClient by doing something like this:<br>
<pre>% java org.apache.axis.client.AdminClient -llocal:// list
</pre>
</dd>
</dl>
<div class="h2">
<h2>Axis: further reading</h2>
</div>
<div class="h5">
<h5>Recommended Reading</h5>
</div>
<p>Here are things you can read to understand and use Axis better. Remember, you also have access to all the source if you really want to find out how things work (or why they don't).</p>
<div class="h5">
<h5>Axis installation, use and internals</h5>
</div>
<ol>
<li>
<a href="http://www.tusc.com.au/tutorial/html/">Tutorial for building J2EE Applications using JBOSS and ECLIPSE</a>
<br> A good tutorial on open source Enterprise Java Dev, whose chapter nine covers Axis.</li>
<li>
<a href="http://www.pankaj-k.net/axis4tag/">Web Services with JAX-RPC and Apache Axis.</a>
<br> by Pankaj Kumar. Starting with a 10000 ft. view of Web Services, prior technologies, current and emerging standards, it quickly gets into the nitty-gritties of using JAX-RPC and Apache Axis for writing and executing programs. Has a nice coverage of different invocation styles - generated stubs, dynamic proxy and dynamic invocation interface. A good place to start if you are new to Web Services and Axis.<br>
<br> The author also maintains a <a href="http://www.pankaj-k.net/webservices/index.html">Web Services Resource Page</a>.</li>
<li>
<a href="http://www.sosnoski.com/presents/java-xml/axis/">Apache Axis SOAP for Java</a>
<br> Dennis Sosnoski covers Axis. This is another good introductory guide.</li>
<li>
<a href="http://www.sosnoski.com/presents/java-xml/axis/axis-monitor.html">Enabling SOAPMonitor in Axis 1.0</a>.<br> Dennis Sosnoski on how to turn the SOAP monitor on and off, and use it to log your application.</li>
<li>
<a href="http://macromedia.com/support/jrun/extend/using_web_services/">Axis in JRun</a>
<br> Macromedia authored coverage of using Axis from inside JRun.</li>
<li>
<a href="http://www-106.ibm.com/developerworks/webservices/library/ws-eight/">Ask the magic eight ball</a>
<br> Example of using an Axis service with various caller platforms/languages.</li>
<li>
<a href="http://www.fawcette.com/javapro/2003_02/online/WSDL_kjones_02_27_03/">Configure Axis Web Services</a>
<br> Kevin Jones talks a bit about configuring axis, showing how to return handwritten WSDL from the ?wsdl query.</li>
<li>
<a href="http://www.fawcette.com/javapro/2003_03/online/wsdl_kjones_03_10_03/">Different WSDL Styles in Axis</a>
<br> Kevin Jones looks at the document and wrapped styles of WSDL2Java bindings.</li>
</ol>
<div class="h5">
<h5>Specifications</h5>
</div>
<ol>
<li>
<a href="http://www.w3.org/TR/SOAP/">SOAP Version 1.1</a>
<br> Remember that SOAP1.1 is not an official W3C standard.</li>
<li>
<a href="http://www.w3.org/TR/soap12-part0/">SOAP Version 1.2 Part 0: Primer</a>
<br> This and the follow-on sections cover what the W3C think SOAP is and how it should be used.</li>
<li>
<a href="http://www.w3.org/TR/wsdl">Web Services Description Language (WSDL) 1.1</a>
<br>
</li>
<li>
<a href="http://ietf.org/rfc/rfc2616.txt">RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1</a>
<br> This is HTTP. You really do need to understand the basics of how this works, to work out why your web service doesn't :)</li>
<li>
<a href="http://java.sun.com/xml/saaj/index.html">SOAP with Attachments API for Java (SAAJ)</a>
<br> SAAJ enables developers to produce and consume messages conforming to the SOAP 1.1 specification and SOAP with Attachments note.</li>
<li>
<a href="http://java.sun.com/xml/jaxrpc/index.html">Java API for XML-Based RPC (JAX-RPC)</a>
<br> The public API for Web Services in Java. JAX-RPC enables Java technology developers to develop SOAP based interoperable and portable web services. JAX-RPC provides the core API for developing and deploying web services on the Java platform.</li>
<li>
<a href="http://www.w3.org/TR/xmlschema-0/">XML Schema Part 0: Primer</a>
<br> The W3C XML Schema, (WXS) is one of the two sets of datatype SOAP supports, the other being the SOAP Section 5 datatypes that predate WXS. Complicated as it is, it is useful to have a vague understanding of this specification.</li>
<li>
<a href="http://java.sun.com/xml/jaxm/index.html">Java API for XML Messaging (JAXM)</a>
<br> JAXM enables applications to send and receive document oriented XML messages using a pure Java API. JAXM implements Simple Object Access Protocol (SOAP) 1.1 with Attachments messaging so that developers can focus on building, sending, receiving, and decomposing messages for their applications instead of programming low level XML communications routines.</li>
</ol>
<div class="h5">
<h5>Explanations, articles and presentations</h5>
</div>
<ol>
<li>
<a href="http://www.intertwingly.net/stories/2002/03/16/aGentleIntroductionToSoap.html">A Gentle Introduction to SOAP</a>
<br> Sam Ruby tries not to scare people.</li>
<li>
<a href="http://www.intertwingly.net/stories/2002/02/15/aBusyDevelopersGuideToWsdl11.html">A Busy Developer's Guide to WSDL 1.1</a>
<br> Quick intro to WSDL by the eponymous Sam Ruby.</li>
<li>
<a href="http://www.ociweb.com/javasig/knowledgebase/2002Sep/">Axis - an open source web service toolkit for Java</a>
<br> by Mark Volkmann, Partner, Object Computing, Inc. A very good introduction to SOAP and Axis. Highly Recommended.</li>
<li>
<a href="http://www.iseran.com/Steve/papers/when_web_services_go_bad.html">When Web Services Go Bad</a>
<br> Steve Loughran tries to scare people. A painful demonstration how deployment and system management are trouble spots in a production service, followed by an espousal of a deployment-centric development process. Remember, it doesn't have to be that bad.</li>
<li>
<a href="http://servlet.java.sun.com/javaone/sf2002/conf/sessions/index.en.jsp">JavaOne 2002, Web Services Today and Tomorrow</a>
<br> (Java Developer connection login required)</li>
<li>
<a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/JAXRPC.html">The Java Web Services Tutorial: Java API for XML-based RPC</a>
<br> This is part of Sun's guide to their Java Web Services Developer Pack. The examples are all based on their JWSDP, but as Axis also implements JAX-RPC, they may all port to Axis.</li>
<li>
<a href="http://java.sun.com/blueprints/webservices/using/webservbp.html">Using Web Services Effectively.</a>
<br> Blissfully ignoring issues such as versioning, robustness and security and all the other details a production Web Service needs, instead pushing EJB as the only way to process requests, this is Sun's guide to using web services in Java. It also assumes Java is at both ends, so manages to skirt round the interop problem.</li>
<li>
<a href="http://www.hpl.hp.com/techreports/2002/HPL-2002-274.html">Making Web Services that Work</a>
<br> A practical but suspiciously code free paper on how to get web services into production. As well as coverage of topics such as interop, versioning, security, this (57 page) paper looks at the deployment problem, advocating a fully automated deployment process in which configuration problems are treated as defects for which automated test cases and regresssion testing are appropriate. Happyaxis.jsp is the canonical example of this. The author, Steve Loughran also looks a bit at what the component model of a federated web service world would really be like.</li>
</ol>
<div class="h5">
<h5>Interoperability</h5>
</div>
<ol>
<li>
<a href="http://www.intertwingly.net/stories/2002/02/01/toInfinityAndBeyondTheQuestForSoapInteroperability.html">To infinity and beyond - the quest for SOAP interoperability</a>
<br> Sam Ruby explains why Interop matters so much.</li>
<li>
<a href="http://www.iseran.com/Steve/papers/interop/">The Wondrous Curse of Interoperability</a>
<br> Steve Loughran on interop challenges (especially between .NET and Axis), and how to test for them.</li>
</ol>
<div class="h5">
<h5>Advanced topics</h5>
</div>
<ol>
<li>
<a href="http://www.extreme.indiana.edu/xgws/papers/sc00_paper/index.html">Requirements for and Evaluation of RMI Protocols for Scientific Computing</a>
</li>
<li>
<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Architectural Styles and the Design of Network-based Software Architectures</a>
<br> The theoretical basis of the REST architecture</li>
<li>
<a href="http://www.extreme.indiana.edu/xgws/papers/soap-hpdc2002/soap-hpdc2002.pdf">Investigating the Limits of SOAP Performance for Scientific Computing</a>
</li>
<li>
<a href="http://www.w3.org/TR/webarch/">Architectural Principles of the World Wide Web</a>
<br> The W3C architects say how things should be done.</li>
</ol>
<div class="h5">
<h5>Books</h5>
</div>
<ol>
<li>
<em>Beginning Java Web Services</em>
<br> Meeraj Kunnumpurath et al, Wrox Press, September 2002.<br> An introductory book, with the early chapters focusing on Axis.<br> The <a href="http://www.wrox.com/books/sample-chapters/SampleChapter_1861007531.pdf">sample chapter</a> shows how to install Axis with Tomcat 4.0: we do not believe that their approach is the best. It is easier to drop jaxrpc.jar and saaj.jar into the CATALINA_HOME/common/lib dir than it is to add all axis jars to the classpath by hand. The book is based on Axis Beta-3.</li>
<li>
<a href="http://manning.com/antbook"><em>Java development with Ant</em></a>
<br> by Erik Hatcher and Steve Loughran, Manning Press, July 2002.<br> A book on Ant development which covers Web Service development with Axis, along with other topics relevant to Java developers using Ant. The Web Service chapter, <a href="http://www.manning.com/hatcher/chap15.pdf">chapter 15</a>, is free to download, and was the birthplace of happyaxis.jar.<br> The book is based on Axis Beta-2; the web site contains updated documentation where appropriate.</li>
<li>
<a href="http://www.wrox.com/books/toc/1861007159_toc.htm"><em>AXIS: Next Generation Java SOAP</em>
<br>
</a> by Romin Irani and S Jeelani Bashna, Wrox Press, May 2002.<br> The first nothing-but-Axis book.<br> It is based on Beta-1. This is a reasonable book, despite is apparent thinness and relative age. If it has a major weakness it believes everything works as intended, which regular Axis users will know is not quite true yet. Maybe they didn't want to fault missing features and other gotchas, assuming they would be fixed by the time the product shipped, but the effective result is that you can get into minor trouble working from this book, trying to use bits that aren't there, or just don't work (yet).</li>
<li>
<a href="http://sams.com/catalog/product.asp?product_id={ABC81EE6-0D9F-4BD7-99DB-84F9C983ACF7}"><em>Building Web Services with Java: Making Sense of XML, SOAP, WSDL and UDDI</em></a>
<br> Steve Graham et al, December 2001.<br> Covering very early versions of Axis along with other aspects of Web Service technologies. One of the authors, Glen Daniels, is an Axis committer and active contributor, so the quality of the Axis coverage is high. Good explanations of SOAP, UDDI, and the like.</li>
</ol>
<p>Authors, publishers: we welcome additions to this section of any books which have some explicit coverage of Axis. Free paper/pdf copies and other forms of bribery accepted.</p>
<div class="h5">
<h5>External Sites covering Web Services</h5>
</div>
<ol>
<li>
<a href="http://www-106.ibm.com/developerworks/webservices/">IBM developerWorks Web Services corner</a>
<br> There are lots of interesting articles on Web Services here, many of which are Axis related. There is also a <a href="http://www-106.ibm.com/developerworks/webservices/library/ws-spec.html">listing of</a> "all current open standards and specifications that define the Web services family of protocols", though Soap with Attachments is mysteriously absent.</li>
</ol>
<div class="h2">
<h2>Axis requirements &amp; status</h2>
</div>
<div class="h5">
<h5>Requirements</h5>
</div>
<p>There is a <a href="##nonreq">non-requirements</a> section below.<br>
<a href="##releases">Release cycles</a> are explained below.</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tbody>
<tr class="b">
<th>No.</th><th>Description [Priority]</th><th>
<br>
<br>
</th><td><strong>status</strong> - worker(s)<br>
</td><th>a1</th><th>a2</th><th>
<p>beta/</p>
<p>3.0</p>
</th><th>later</th>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">XML Protocol compliance</th>
</tr>
<tr class="b">
<td>10</td><td>We will diligently track the XP protocol as it evolves, and support it when it's ready.</td><td>
<br>
<br>
</td><td>n/a<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">Error and fault handling</th>
</tr>
<tr class="b">
<td>20</td><td>Specify an extensible Java Exception mapping into SOAP faults</td><td>
<br>
<br>
</td><td>?<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>21</td><td>Specify an extensible SOAP fault mapping into Java exceptions</td><td>
<br>
<br>
</td><td>?<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<th>
<br>
</th><th colspan="7">Service and Operation Identification</th>
</tr>
<tr class="a">
<td>30</td><td>Dispatch by transport URL</td><td>
<br>
</td><td>done<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>31</td><td>Dispatch by SOAPAction</td><td>
<br>
</td><td>done<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>32</td><td>Dispatch by QName of the first body entry</td><td>
<br>
</td><td>done<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>33</td><td>Dispatch by a custom handler <em>(to use any information available)</em></td><td>
<br>
</td><td>done (can do it already)<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">Message exchange patterns supported at the client API level</th>
</tr>
<tr class="b">
<td>
<br>
</td><td colspan="7"><em>Motivation: we believe the following message exchange patterns are in common use and important to implement (e.g. WSDL uses them)</em></td>
</tr>
<tr class="a">
<td>40</td><td>Synchronous request/response</td><td>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>41</td><td>One-way messaging</td><td>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>42</td><td>[??] Asynchronous request/response (non-blocking) <em>(the question marks mean we don't know whether to provide this)</em></td><td>
<br>
<br>
</td><td><strong>NYI -</strong> ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>
<br>
</td>
</tr>
<tr class="b">
<th>
<br>
</th><th colspan="7">SOAP 1.1 compliance</th>
</tr>
<tr class="a">
<td>50</td><td>All aspects of SOAP 1.1 supported by Apache SOAP 2.x</td><td>
<br>
<br>
</td><td>what is missing?<br> (actor, full sec-5)</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>51</td><td>Support intermediaries</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - RobJ<br>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="a">
<td>52</td><td>Transparency should be provided when we place intermediaries (hosts) between requestor and provider (creating a proxy server)</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - RobJ<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="b">
<td>53</td><td>Support the SOAP concept of mustUnderstand headers</td><td>
<br>
</td><td>done<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>54</td><td>Support the SOAP actor header attributes</td><td>
<br>
</td><td><strong>NYI - Glen</strong>
<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<th>
<br>
</th><th colspan="7">Performance</th>
</tr>
<tr class="a">
<td>60</td><td>The architecture must not require the whole message to be in memory at the same time</td><td>
<br>
<br>
</td><td>not for 1.0 - no incremental 1.0 parse; architecture still allows this, later<br>
<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>61</td><td>Scalable</td><td>
<br>
</td><td>? - Sam<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>62</td><td>Faster than Apache SOAP 2.x</td><td>
<br>
</td><td>done!<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>63</td><td>Must not be significantly slower than comparable alternative implementations</td><td>
<br>
<br>
</td><td>done?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">Administration and monitoring</th>
</tr>
<tr class="b">
<td>70</td><td>Logging API</td><td>
<br>
</td><td><strong>NYI (all)</strong></td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>71</td><td>Metrics API</td><td>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>72</td><td>Management (JMX) API</td><td>
<br>
</td><td><strong>n/a?</strong></td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="a">
<td>73</td><td>Run-time (un)deployment API</td><td>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<th>
<br>
</th><th colspan="7">Deployment</th>
</tr>
<tr class="a">
<td>80</td><td>Installation and deployment of both the engine, components, and services should be simple</td><td>
<br>
<br>
</td><td>done! (what more?)<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>81</td><td>Support a WebServiceArchive format which associates the executable and the description files</td><td>
<br>
<br>
</td><td>NYI (does JWS count?) - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>82</td><td>Support .asmx-like drop-in service deployment</td><td>
<br>
</td><td>done - this is JWS<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="b">
<td>83</td><td>A single SUPER TINY .jar file must be enough for a client to communicate via SOAP</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - what is best way to build it?<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>84</td><td>Defaults packaged with both client and server must be sane, secure and ready to go</td><td>
<br>
<br>
</td><td><strong>NYI</strong> but getting there!<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>85</td><td>Intermediaries (hosts) should be easy to configure</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - RobJ<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="a">
<td>86<br>
</td><td>WSDD implementation<br>
</td><td>
<br>
</td><td><strong>NYI</strong> - Carl W / Glen</td><td>
<br>
</td><td>
<br>
</td><td>?<br>
</td><td>
<br>
</td>
</tr>
<tr class="b">
<th>
<br>
</th><th colspan="7">Providers</th>
</tr>
<tr class="a">
<td>90</td><td>Pluggable provider API</td><td>
<br>
</td><td><strong>done? (handler API)</strong></td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>91</td><td>Java provider</td><td>
<br>
</td><td>done?<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>92</td><td>BSF provider</td><td>
<br>
</td><td><strong>NYI -</strong>?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>93</td><td>EJB provider</td><td>
<br>
</td><td><strong>NYI -</strong> ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="a">
<td>94</td><td>COM provider</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="b">
<td>95new<br>
</td><td>App server provider / connectivity layer <strong>[High]</strong>
<br>
</td><td>
<br>
</td><td><strong>NYI</strong> - Glen?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X<br>
</td><td>
<br>
</td>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">Pluggable XML protocol support</th>
</tr>
<tr class="b">
<td>100</td><td>SOAP 1.1</td><td>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>101</td><td>SOAP 1.2</td><td>
<br>
<br>
</td><td><strong>Partial -</strong> doesn't yet do envelope versioning or namespaces</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="b">
<td>102</td><td>Must not name general classes as SOAPWhateverDoer</td><td>
<br>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>103</td><td>Simultaneous support for multiple message protocols</td><td>
<br>
<br>
</td><td>NYI<br>
</td><td>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td>
</tr>
<tr class="b">
<th>
<br>
</th><th colspan="7">Message processing</th>
</tr>
<tr class="a">
<td>110</td><td>Support a flexible and extensible system allowing message handlers (extensions, applications) to build up orthogonal pieces of a message</td><td>
<br>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>111</td><td>Handler invocation order is always deterministic for a given server configuration and message</td><td>
<br>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>112</td><td>Some information should be shared between all the handlers in the "chain" on one host - MessageContext</td><td>
<br>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>112a</td><td>Have the ability to specify application-specific parameters (like username or other thing) in the context</td><td>
<br>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>112b</td><td>Some encapsulation of the idea of a session that's transport-independent (cookies in the HTTPRequest/HTTPResponse for http)</td><td>
<br>
<br>
</td><td>done<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>112b.1</td><td>An example/sample for a SOAP session header/handler/supplier</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - RobJ<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="a">
<td>112b.2</td><td>Client code needs to support this as well - need to pass session back across if necessary...</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - RobJ<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>113</td><td>Handlers need to be allowed to reach raw message data</td><td>
<br>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">Transport</th>
</tr>
<tr class="b">
<td>120</td><td>Pluggable transport API</td><td>
<br>
</td><td>done - needs doc!</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>121</td><td>HTTP listener and sender</td><td>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>122</td><td>HTTPS listener and sender</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>123</td><td>SMTP sender</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>124</td><td>POP3 poller</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>125</td><td>JMS listener and sender</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="b">
<td>126</td><td>Support for "SOAP messages with attachments"<strong>[High]</strong> &nbsp; &nbsp;</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - Glen / RobJ<br>
</td><td>
<br>
<br>
</td><td>X<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>127</td><td>The transport can insert arbitrary transport-specific stuff into the Context</td><td>
<br>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>128</td><td>The transport-specific stuff should be encapsulated, most of the engine should work on a canonical form of the message</td><td>
<br>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">Security</th>
</tr>
<tr class="b">
<td>130</td><td>Support transport-level security <strong>[High]</strong></td><td>
<br>
</td><td><strong>NY</strong><strong>I</strong> - per-transport issue?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>130b<br>
</td><td>Support SOAP-level security <strong>[High]</strong>
<br>
</td><td>
<br>
<br>
</td><td>what, specifically? - Yuhichi?<br>
</td><td>
<br>
<br>
</td><td>
<br>
<br>
</td><td>
<br>
<br>
</td><td>
<br>
<br>
</td>
</tr>
<tr class="b">
<td>131</td><td>HTTP Basic auth</td><td>
<br>
</td><td>done?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>132</td><td>Support for existing security SOAP-level standards</td><td>
<br>
</td><td>what, specifically?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="b">
<td>133</td><td>An example/sample for a SOAP Basic Authentication header/handler</td><td>
<br>
</td><td>done?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">Service Description and Discovery (for instance, WSDL, DISCO)</th>
</tr>
<tr class="b">
<td>140</td><td>Support the ability to query a service's description at runtime (e.g. GET ...?wsdl)</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - Jim's contribution? or is this something simpler?<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>140a</td><td>If deployment params have altered the service description, the updated version must be returned</td><td>
<br>
<br>
</td><td><strong>NYI</strong>?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>141</td><td>Support a basic html page describing the service (via an HTTP GET)</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - James? Doug?<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>142</td><td>Support a pretty html page describing the service (via an HTTP GET)</td><td>
<br>
<br>
</td><td><strong>NYI -</strong> James? Doug?</td><td>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td>
</tr>
<tr class="b">
<td>143</td><td>Services can be deployed and used without service descriptions</td><td>
<br>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>144</td><td>Should abstract the SD layer, at least by keeping the interfaces clean <strong>[High]</strong></td><td>
<br>
<br>
</td><td>?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>144a</td><td>The abstract SD layer must support run-time determination of xsi:types of parts of the message</td><td>
<br>
<br>
</td><td><strong>NYI?</strong> - Sam?<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>144b</td><td>Include a WSDL implementation of the SD layer <strong>[High]</strong> &nbsp; &nbsp;</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - Lance &amp; HP contribution?<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>144c</td><td>Extend WSDL with information on where to get components for stuff</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - James?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td>
</tr>
<tr class="a">
<td>144d</td><td>Tools and/or run-time support for proxy generation from WSDL and/or WSDD</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - Lance &amp; HP?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td>
</tr>
<tr class="b">
<td>145</td><td>HTTP GET on the Axis node returns an appropriate DISCO document</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">Platforms</th>
</tr>
<tr class="b">
<td>150</td><td>Java implementation</td><td>
<br>
</td><td>underway :-)<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>151</td><td>C++ implementation</td><td>
<br>
</td><td>n/a for 1.0<br>
</td><td>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td>
</tr>
<tr class="b">
<td>151a</td><td>C++ impl core should be cross platform with platform-specific extensions (like COM)</td><td>
<br>
<br>
</td><td>n/a for 1.0<br>
</td><td>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td>
</tr>
<tr class="a">
<td>152</td><td>All implementations should have as much in common as possible</td><td>
<br>
<br>
</td><td>n/a for 1.0<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>153</td><td>Use standard APIs wherever possible</td><td>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">Data Encoding</th>
</tr>
<tr class="b">
<td>160</td><td>Extensible support for encodings</td><td>
<br>
</td><td>NYI<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>161</td><td>Implement basic SOAP encoding (the level of current Apache SOAP 2.x)</td><td>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>162</td><td>Support for sparse and partially-transmitted arrays</td><td>
<br>
</td><td>NYI<br>
</td><td>
<br>
</td><td>X<br>
</td><td>X</td><td>&nbsp;</td>
</tr>
<tr class="a">
<td>163</td><td>Support for multidimensional arrays</td><td>
<br>
</td><td>NYI<br>
</td><td>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td>
</tr>
<tr class="b">
<td>164</td><td>Support literal XML encoding</td><td>
<br>
</td><td>NYI<br>
</td><td>
<br>
</td><td>X<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>165</td><td>It should be relatively easy to write a "Serializer"</td><td>
<br>
</td><td>done (depending on feedback from users)<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>166</td><td>Include some general (de)serializers (that handle multiple types), so that there needn't exist a (de)serializer for every type that could possibly travel over the wire (needs further discussion - isomorphism (roundtrip) issues)</td><td>
<br>
<br>
</td><td>Is this the beanserializer / basicDeserializer, or something else?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="a">
<td>167</td><td>(De)serialization may occur at any time on demand</td><td>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>168</td><td>(De)serialization should be available to the application</td><td>
<br>
</td><td>done<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">Release</th>
</tr>
<tr class="b">
<td>
<br>
</td><td colspan="7"><em>Although these are a 1.0 requirements, significant progress must be made on these items during interim releases.</em></td>
</tr>
<tr class="a">
<td>170</td><td>Product-level code</td><td>
<br>
</td><td>getting there....<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>171</td><td>Product-level docs <strong>[High]</strong></td><td>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>172</td><td>Product-level examples</td><td>
<br>
</td><td><strong>NYI</strong> but getting there - everyone<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>173</td><td>Product-level performance</td><td>
<br>
</td><td><strong>NYI</strong> - Sam?</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>174</td><td>Product-level testing</td><td>
<br>
</td><td>getting there, with functional &amp; unit tests<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<th>
<br>
</th><th colspan="7">Migration from Apache SOAP 2.x</th>
</tr>
<tr class="a">
<td>180</td><td>Documentation</td><td>
<br>
</td><td><strong>NYI -</strong> ?<br>
</td><td>
<br>
</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>181</td><td>The legacy Call object</td><td>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>182</td><td>Serialization, custom serializers - maybe wrappers</td><td>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>?</td><td>?</td>
</tr>
<tr class="b">
<td>183</td><td>Support for legacy messaging services</td><td>
<br>
</td><td><strong>NYI</strong> - which?<br>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>184</td><td>Support for legacy providers <strong>[Medium]</strong> &nbsp; &nbsp;</td><td>
<br>
</td><td><strong>NYI</strong> - ?<br>
</td><td>
<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td>
</tr>
<tr class="b">
<td>185new<br>
</td><td>Support for legacy deployment<br>
</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - James?<br>
</td><td>
<br>
<br>
</td><td>
<br>
<br>
</td><td>X<br>
<br>
</td><td>
<br>
<br>
</td>
</tr>
<tr class="a">
<th>
<br>
</th><th colspan="7">Coding</th>
</tr>
<tr class="b">
<td>190</td><td>Follow the <a href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Java Coding Style</a> with <strong>no</strong> tab characters.</td><td>
<br>
</td><td>done<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>191</td><td>Use javadoc style to document all non-private methods in commits.</td><td>
<br>
<br>
</td><td>could be more...<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="b">
<td>192</td><td>Document packages.</td><td>
<br>
<br>
</td><td>could be MUCH more...<br>
</td><td>
<br>
</td><td>
<br>
</td><td>X</td><td>
<br>
</td>
</tr>
<tr class="a">
<td>193</td><td>Committing a new package, at least place in a placeholder for the package doc that says "this is to be done".</td><td>
<br>
<br>
</td><td><strong>NYI</strong> - everyone!!!<br>
</td><td>X</td><td>X</td><td>X</td><td>
<br>
</td>
</tr>
</tbody>
</table>
<p>
<a name="java/requirements.html#nonreq"></a>
</p>
<br>
<div class="h5">
<h5>Non-requirements (won't be supported)</h5>
</div>
<p>
<br>
<em>We find the SOAP spec. to be unclear on these issues so we decided not to support them.</em>
</p>
<ol>
<li>RPC calls in SOAP headers</li>
<li>Multiple RPC calls in a single SOAP message</li>
</ol>
<p>
<a name="java/requirements.html#releases"></a>
</p>
<div class="h5">
<h5>Releases and test cycles</h5>
</div>
<p>We're planning on releasing alpha1 (a1),&nbsp;alpha2 (a2), beta, and 3.0.<br> alpha&nbsp;is a preview.<br> subsequent alphas&nbsp;are to show the growing set of features and docs and test cases and all that.<br> Beta is functionally complete.</p>
<div class="h4">
<h4>Axis (C++)</h4>
</div>
<div class="h2">
<h2>Axis C++ 1.5 Final is Available!</h2>
</div>
<div class="h5">
<h5>Axis C++ 1.5 Final</h5>
</div>
<p>
<a href="#download.html">Download Axis C++</a>
</p>
<br>
<div class="h5">
<h5>Key features of Axis C++ 1.5 Final</h5>
</div>
<br>
<br>
<p>
<strong>New client side transport</strong>
<br> This is called Axis3 transport.This is a cleaner and extensible Transport compared to Axis2Transport.<br>
<br>
<br> WSDL tool fixes to handle nil types.<br>
<br>Supports Broader XSD types.<br>
<br>Supports Broader XSD Any types<br>
<br>Comprehensive test framework which includes client &amp; server side.<br>
<br>
</p>
<div class="h5">
<h5>The Bug Fixes</h5>
</div>
<p>AXISCPP-605<br>AXISCPP-602<br>AXISCPP-600<br>AXISCPP-596<br>AXISCPP-594<br>AXISCPP-593<br>AXISCPP-592<br>AXISCPP-591<br>AXISCPP-590<br>AXISCPP-589<br>AXISCPP-587<br>AXISCPP-586<br>AXISCPP-585<br>AXISCPP-584<br>AXISCPP-583<br>AXISCPP-582<br>AXISCPP-581<br>AXISCPP-579<br>AXISCPP-576<br>AXISCPP-575<br>AXISCPP-569<br>AXISCPP-568<br>AXISCPP-567<br>AXISCPP-566<br>AXISCPP-564<br>AXISCPP-562<br>AXISCPP-561<br>AXISCPP-560<br>AXISCPP-556<br>AXISCPP-555<br>AXISCPP-553<br>AXISCPP-550<br>AXISCPP-549<br>AXISCPP-545<br>AXISCPP-534<br>AXISCPP-532<br>AXISCPP-531<br>AXISCPP-530<br>AXISCPP-528<br>AXISCPP-525<br>AXISCPP-524<br>AXISCPP-523<br>AXISCPP-521<br>AXISCPP-520<br>AXISCPP-518<br>AXISCPP-517<br>AXISCPP-516<br>AXISCPP-514<br>AXISCPP-513<br>AXISCPP-511<br>AXISCPP-510<br>AXISCPP-509<br>AXISCPP-508<br>AXISCPP-507<br>AXISCPP-504<br>AXISCPP-503<br>AXISCPP-502<br>AXISCPP-501<br>AXISCPP-500<br>AXISCPP-499<br>AXISCPP-498<br>AXISCPP-497<br>AXISCPP-496<br>AXISCPP-495<br>AXISCPP-494<br>AXISCPP-493<br>AXISCPP-492<br>AXISCPP-491<br>AXISCPP-490<br>AXISCPP-489<br>AXISCPP-488<br>AXISCPP-487<br>AXISCPP-486<br>AXISCPP-485<br>AXISCPP-484<br>AXISCPP-483<br>AXISCPP-482<br>AXISCPP-481<br>AXISCPP-480<br>AXISCPP-479<br>AXISCPP-478<br>AXISCPP-477<br>AXISCPP-475<br>AXISCPP-474<br>AXISCPP-472<br>AXISCPP-470<br>AXISCPP-469<br>AXISCPP-468<br>AXISCPP-466<br>AXISCPP-465<br>AXISCPP-464<br>AXISCPP-463<br>AXISCPP-462<br>AXISCPP-459<br>AXISCPP-457<br>AXISCPP-456<br>AXISCPP-454<br>AXISCPP-453<br>AXISCPP-451<br>AXISCPP-450<br>AXISCPP-447<br>AXISCPP-446<br>AXISCPP-444<br>AXISCPP-443<br>AXISCPP-442<br>AXISCPP-441<br>AXISCPP-437<br>AXISCPP-436<br>AXISCPP-433<br>AXISCPP-431<br>AXISCPP-430<br>AXISCPP-428<br>AXISCPP-425<br>AXISCPP-420<br>AXISCPP-419<br>AXISCPP-418<br>AXISCPP-417<br>AXISCPP-415<br>AXISCPP-414<br>AXISCPP-413<br>AXISCPP-410<br>AXISCPP-409<br>AXISCPP-408<br>AXISCPP-407<br>AXISCPP-403<br>AXISCPP-400<br>AXISCPP-398<br>AXISCPP-392<br>AXISCPP-390<br>AXISCPP-389<br>AXISCPP-385<br>AXISCPP-383<br>AXISCPP-376<br>AXISCPP-375<br>AXISCPP-371<br>AXISCPP-364<br>AXISCPP-355<br>AXISCPP-348<br>AXISCPP-346<br>AXISCPP-344<br>AXISCPP-341<br>AXISCPP-340<br>AXISCPP-335<br>AXISCPP-331<br>AXISCPP-310<br>AXISCPP-306<br>AXISCPP-305<br>AXISCPP-303<br>AXISCPP-300<br>AXISCPP-293<br>AXISCPP-288<br>AXISCPP-270<br>AXISCPP-268<br>AXISCPP-242<br>AXISCPP-216<br>AXISCPP-207<br>AXISCPP-164<br>
</p>
<div class="h5">
<h5>Known Issues</h5>
</div>
<p>GNU make based build system is not working.<br>
<br>Out of the two parsers Expat and Xerces, only Xerces is supported.<br>
<br> C support is not complete.<br>
<br> There are no vc projects for samples<br>
<br> Pending bugs in Jira.<br>
<br>
</p>
<br>
<p>We hope you will enjoy using Axis C++.<br>
<br> Numerous efforts are currently underway to improve Axis C++ as a whole. Please have a look at the <a href="http://wiki.apache.org/ws/FrontPage/AxisC_2b_2b">TODO page</a> to learn about 1.5 plans for Axis C++.<br>
<br>We value your feed back very much.</p>
<br>
<p>Please report any bugs in <a href="http://issues.apache.org/jira/secure/Dashboard.jspa">Jira</a> and feel free to let us know your thoughts and/or problems in <a href="#mailto:axis-c-user@ws.apache.org">axis-c-user@ws.apache.org</a>
<br>
<br>We welcome you to contribute to Axis C++ and please join the discussions in <a href="#mailto:axis-c-dev@ws.apache.org">axis-c-dev@ws.apache.org</a>
</p>
<div class="h2">
<h2>Axis C++ Documentation</h2>
</div>
<div class="h5">
<h5>Documentation</h5>
</div>
<br>
<a href="#index.html">Apache Axis C++ 1.5 Final</a>
<div class="h5">
<h5>Installation Guides</h5>
</div>
<ul>
<li>
<a href="#lininstall-guide.html">Linux Installation Instructions</a>
</li>
<li>
<a href="#wininstall-guide.html">Windows Installation Instructions</a>
</li>
</ul>
<div class="h5">
<h5>User Guides</h5>
</div>
<ul>
<li>
<a href="#linuser-guide.html">Linux User Guide</a>
</li>
<li>
<a href="#winuser-guide.html">Windows User Guide</a>
</li>
</ul>
<div class="h5">
<h5>Developer Guides</h5>
</div>
<ul>
<li>
<a href="#windev-guide.html">Windows Developer's Guide</a>
</li>
<li>
<a href="#antbuild-guide.html">ANT Build Guide</a>
</li>
</ul>
<div class="h5">
<h5>Reference Material</h5>
</div>
<ul>
<li>
<a href="#arch/handler.html">Handler Tutorial</a>
</li>
<li>
<a href="#arch/ArchitectureGuide.html">Architecture Guide</a>
</li>
<li>
<a href="#arch/WSDL2Ws.html">WSDL2Ws Tool</a>
</li>
<li>
<a href="#arch/mem-management.html">Memory Management Guide</a>
</li>
</ul>
<div class="h2">
<h2>Axis C++ download page</h2>
</div>
<div class="h5">
<h5>Download Axis C++</h5>
</div>
<p>
<a href="http://www.apache.org/dist/ws/axis-c/">Direct Link</a>
</p>
<p>(Direct link to a Axis C++ distribution folder)</p>
<p>
<a href="http://www.apache.org/dyn/closer.cgi">Mirror Sites</a>
</p>
<p>(Click on the address of a mirror. Once you are presented with the contents of the dist folder, click on the "ws" folder.<br>Then click on "axis-c" to find the distribution)</p>
<div class="h2">
<h2>The Axis C++ team</h2>
</div>
<div class="h5">
<h5>The Axis C++ team</h5>
</div>
<div class="h5">
<h5>Active Contributors</h5>
</div>
<p>Susantha Kumara &lt;susantha@virtusa.com, susantha@opensource.lk&gt;,</p>
<p>Damitha Kumarage &lt;damitha@beyondm.net, damitha@opensource.lk&gt;,</p>
<p>Roshan Weerasuriya &lt;roshan@jkcsworld.com, roshan@opensource.lk&gt;,</p>
<p>Sanjaya Singharage &lt;sanjayas@jkcsworld.com,sanjayas@opensource.lk&gt;,</p>
<p>John Hawkins &lt;HAWKINSJ@uk.ibm.com&gt;,</p>
<p>Samisa Abeysinghe &lt;samisa_abeysinghe@yahoo.com&gt;,</p>
<p>Fred Preston &lt;PRESTONF@uk.ibm.com&gt;,</p>
<p>Mark Whitlock &lt;mark_whitlock@uk.ibm.com&gt;,</p>
<p>Andrew Perry &lt;PERRYAN@uk.ibm.com&gt;,</p>
<p>Adrian Dick &lt;adrian.dick@uk.ibm.com&gt;,</p>
<p>Sanjiva Weerawarana &lt;sanjiva@opensource.lk&gt;,</p>
<p>Farhaan Mohideen &lt;farhaan@opensource.lk&gt;,</p>
<p>Nithyakala Thangarajah &lt;nithya@opensource.lk&gt;,</p>
<p>Rangika Mendis &lt;rangika@opensource.lk&gt;,</p>
<p>Sharanka Perera &lt;sharanka@opensource.lk&gt;,</p>
<p>M.F.Rinzad Ahamed &lt;rinzad@opensource.lk&gt;,</p>
<br>
<div class="h5">
<h5>Additional Contributors</h5>
</div>
<p>Chaminda Divitotawela &lt;cdivitotawela@virtusa.com, chadiv@opensource.lk&gt;,</p>
<p>Nuwan Gurusinghe &lt;nuwan@beyondm.net, nuwan@opensource.lk&gt;,</p>
<p>Chamindra de Silva &lt;chamindra@virtusa.com&gt;,</p>
<p>Kanchana Welagedara &lt;kanchana@opensource.lk&gt;,</p>
<p>Srinath Perera &lt;hemapani@cse.mrt.ac.lk, hemapani@opensource.lk&gt;,</p>
<p>Thushantha Ravipriya De Alwis &lt;thushantha@beyondm.net, ravi@opensource.lk&gt;,</p>
<p>Dimuthu Leelarathne &lt;muthulee@cse.mrt.ac.lk, muthulee@opensource.lk&gt;,</p>
<p>Jeyakumaran.C &lt;jkumaran@opensource.lk&gt;,</p>
<p>Vairamuthu Thayapavan &lt;vtpavan@opensource.lk&gt;,</p>
<p>Satheesh Thurairajah</p>
<p>Piranavam ThiruChelvan &lt;chelvan@opensource.lk&gt;,</p>
<p>Dharmarajeswaran Dharmeehan &lt;dhar@opensource.lk&gt;,</p>
<p>Selvarajah Selvendra &lt;selva@opensource.lk&gt;,</p>
<p>Lilantha Darshana &lt;Lilantha@virtusa.com&gt;,</p>
<p>Nadika Ranasinghe &lt;nranasinghe@virtusa.com, nadika@opensource.lk&gt;,</p>
<div class="h4">
<h4>Downloads</h4>
</div>
<div class="h2">
<h2>WebServices - Axis</h2>
</div>
<div class="h5">
<h5>WebServices - Axis - Releases</h5>
</div>
<p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr class="b">
<td colspan="1" rowspan="1"><b>Name</b></td>
<td colspan="1" rowspan="1"><b>Date</b></td>
<td colspan="1" rowspan="1"><b>Description</b></td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_2RC2/">1.2RC2</a></td>
<td colspan="1" rowspan="1">November 17, 2004</td>
<td colspan="1" rowspan="1">Release Candidate #2 for version 1.2.</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_2RC1/">1.2RC1</a></td>
<td colspan="1" rowspan="1">September 30, 2004</td>
<td colspan="1" rowspan="1">Release Candidate #1 for version 1.2.</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_2beta3/">1.2beta3</a></td>
<td colspan="1" rowspan="1">August 17, 2004</td>
<td colspan="1" rowspan="1">Third beta release for version 1.2.</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_2beta2/">1.2beta2</a></td>
<td colspan="1" rowspan="1">July 14, 2004</td>
<td colspan="1" rowspan="1">Second beta release for version 1.2.</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_2beta/">1.2beta1</a></td>
<td colspan="1" rowspan="1">April 1, 2004</td>
<td colspan="1" rowspan="1">First beta release for version 1.2.</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_2alpha/">1.2alpha</a></td>
<td colspan="1" rowspan="1">December 1, 2003</td>
<td colspan="1" rowspan="1">Alpha Version 1.2.</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1"><a href="http://ws.apache.org/axis/download.cgi">1.1</a> (from mirror)</td>
<td colspan="1" rowspan="1">June 16, 2003</td>
<td colspan="1" rowspan="1">Final Version 1.1.</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_1rc2">1.1rc2</a></td>
<td colspan="1" rowspan="1">March 5, 2003</td>
<td colspan="1" rowspan="1">Release Candidate #2 for version 1.1.</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_1RC1">1.1rc1</a></td>
<td colspan="1" rowspan="1">February 9, 2003</td>
<td colspan="1" rowspan="1">Release Candidate #1 for version 1.1.</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_1beta">1.1beta</a></td>
<td colspan="1" rowspan="1">December 3, 2002</td>
<td colspan="1" rowspan="1">Beta for 1.1 release</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_0/">1.0</a></td>
<td colspan="1" rowspan="1">October 7, 2002</td>
<td colspan="1" rowspan="1">Release 1.0.</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_0rc2/">1.0rc2</a></td>
<td colspan="1" rowspan="1">September 30, 2002</td>
<td colspan="1" rowspan="1">Release Candidate #2 for version 1.0.</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/1_0rc1/">1.0rc1</a></td>
<td colspan="1" rowspan="1">September 6, 2002</td>
<td colspan="1" rowspan="1">Release Candidate #1 for version 1.0.</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/beta3/">Beta 3</a></td>
<td colspan="1" rowspan="1">July 9, 2002</td>
<td colspan="1" rowspan="1">Third beta release (<a href="#beta2-beta3.html">changes since beta 2</a>).</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/beta2/">Beta 2</a></td>
<td colspan="1" rowspan="1">April 29, 2002</td>
<td colspan="1" rowspan="1">Second beta release (<a href="#beta1-beta2.html">changes since beta 1</a>)</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/beta1/">Beta 1</a></td>
<td colspan="1" rowspan="1">March 15, 2002</td>
<td colspan="1" rowspan="1">First beta release.</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/alpha3">Alpha 3</a></td>
<td colspan="1" rowspan="1">December 14, 2001</td>
<td colspan="1" rowspan="1">Third Alpha - add JAX RPC, WSDD, more WSDL functionallity, etc.</td>
</tr>
<tr class="b">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/alpha2">Alpha 2</a></td>
<td colspan="1" rowspan="1">September 21, 2001</td>
<td colspan="1" rowspan="1">Second Alpha - add WSDL functionality, many bug fixes</td>
</tr>
<tr class="a">
<td colspan="1" rowspan="1"><a href="http://archive.apache.org/dist/ws/axis/alpha1">Alpha 1</a></td>
<td colspan="1" rowspan="1">August 15, 2001</td>
<td colspan="1" rowspan="1">First Alpha release</td>
</tr>
</table>
</p>
<p>For nightly builds, see the <a href="#interim.html">Interim Drops</a>
page.
</p>
<div class="h2">
<h2>WebServices - Axis</h2>
</div>
<div class="h5">
<h5>WebServices - Axis - Interim</h5>
</div>
<p>
Nightly builds are done of the current source in the
CVS repository. The source and binaries from these builds are available at:
<br>
<blockquote>
<a href="http://cvs.apache.org/dist/axis/nightly ">
http://cvs.apache.org/dist/axis/nightly
</a>
</blockquote>
</p>
<p>
Nightly Snapshots of the current CVS source tree are available at:
<br>
<blockquote>
<a href="http://cvs.apache.org/snapshots/ws-axis/">
http://cvs.apache.org/snapshots/ws-axis/
</a>
</blockquote>
</p>
<div class="h4">
<h4>Translation</h4>
</div>
<div class="h4">
<h4>Related Projects</h4>
</div>
<div class="h4">
<h4>Misc</h4>
</div>
<div class="h2">
<h2>WebServices - Axis</h2>
</div>
<div class="h5">
<h5>WebServices - Axis - Who We Are</h5>
</div>
<p>
The Axis Project operates on a meritocracy: the more you do,
the more responsibility you will obtain. This page lists all
of the people who have gone the extra mile and are
Committers. If you would like to get involved, the first step
is to join the mailing lists.
</p>
<p>
We ask that you please do not send us emails privately asking
for support. We are non-paid volunteers who help out with the
project and we do not necessarily have the time or energy to
help people on an individual basis. Instead, we have setup
mailing lists which often contain hundreds of individuals who
will help answer detailed requests for help. The benefit of
using mailing lists over private communication is that it is
a shared resource where others can also learn from common
mistakes and as a community we all grow together.
</p>
<div class="h5">
<h5>Active Committers (Java)</h5>
</div>
<p>
<ul class="noindent">
<li>
<b>Andras Avar</b>
&lt;<a href="mailto:Andras.Avar@nokia.com">andras.avar@nokia.com</a>&gt;
</li>
<li>
<b>David Chappell</b>
&lt;<a href="mailto:chappell@sonicsoftware.com">chappell@sonicsoftware.com</a>&gt;
</li>
<li>
<b>Glen Daniels</b>
&lt;<a href="mailto:gdaniels@apache.org">gdaniels@apache.org</a>&gt;
</li>
<li>
<b>Doug Davis</b>
&lt;<a href="mailto:dug@apache.org">dug@apache.org</a>&gt;
</li>
<li>
<b>Eric Friedman</b>
&lt;<a href="mailto:ericf@apache.org">ericf@apache.org</a>&gt;
</li>
<li>
<b>Chris Haddad</b>
&lt;<a href="mailto:haddadc@apache.org">haddadc@apache.org</a>&gt;
</li>
<li>
<b>Tom Jordahl</b>
&lt;<a href="mailto:tomj@macromedia.com">tomj@macromedia.com</a>&gt;
</li>
<li>
<b>Dominik Kacprzak</b>
&lt;<a href="mailto:dominik@apache.org">dominik@apache.org</a>&gt;
</li>
<li>
<b>Rick Kellogg
&lt;</b><a href="mailto:rmkellogg@comcast.net">rmkellogg@comcast.net</a>
<b>&gt;</b>
</li>
<li>
<b><a href="http://ws.apache.org/~toshi/">Toshiyuki Kimura (Toshi)</a></b>
&lt;<a href="mailto:kimuratsy@nttdata.co.jp">kimuratsy@nttdata.co.jp</a>&gt;
</li>
<li>
<b>Steve Loughran</b>
</li>
<li>
<b>Jaime Meritt</b>
&lt;<a href="mailto:jmeritt@sonicsoftware.com">jmeritt@sonicsoftware.com</a>&gt;
</li>
<li>
<b>Yuhichi Nakamura</b>
&lt;<a href="mailto:nakamury@apache.org">nakamury@apache.org</a>&gt;
</li>
<li>
<b>Thomas Sandholm</b>
&lt;<a href="mailto:sandholm@mcs.anl.gov">sandholm@mcs.anl.gov</a>&gt;
</li>
<li>
<b>Igor Sedukhin</b>
&lt;<a href="mailto:igors@apache.org">igors@apache.org</a>&gt;
</li>
<li>
<b><a href="http://ws.apache.org/~dims/">Davanum Srinivas</a></b>
&lt;<a href="mailto:dims@yahoo.com">dims@yahoo.com</a>&gt;
</li>
<li>
<b>Sanjiva Weerawarana</b>
&lt;<a href="mailto:sanjiva@watson.ibm.com">sanjiva@watson.ibm.com</a>&gt;
</li>
<li>
<b><a href="http://www.iasandcb.pe.kr">Changshin Lee (a.k.a. Ias)</a></b>
&lt;<a href="mailto:iasandcb@tmax.co.kr">iasandcb@tmax.co.kr</a>&gt;
</li>
<li>
<b>Srinath Perera</b>
&lt;<a href="mailto:hemapani@opensource.lk">hemapani@opensource.lk</a>&gt;
</li>
<li>
<b>Venkat Reddy</b>
&lt;<a href="mailto:venkat@apache.org">venkat@apache.org</a>&gt;
</li>
<li>
<b>Jarek Gawor</b>
&lt;<a href="mailto:gawor@apache.org">gawor@apache.org</a>&gt;
</li>
<li>
<b>Jongjin Choi</b>
&lt;<a href="mailto:jjchoe@tmax.co.kr">jjchoe@tmax.co.kr</a>&gt;
</li>
</ul>
</p>
<div class="h5">
<h5>Active Committers (C++)</h5>
</div>
<p>
<ul class="noindent">
<li>
<b>Chaminda Divitotawela</b>
&lt;<a href="mailto:chadiv@opensource.lk">chadiv@opensource.lk</a>&gt;
</li>
<li>
<b>Nuwan Gurusinghe</b>
&lt;<a href="mailto:nuwan@opensouce.lk">nuwan@opensouce.lk</a>&gt;
</li>
<li>
<b>Susantha Kumara</b>
&lt;<a href="mailto:susantha@opensource.lk">susantha@opensource.lk</a>&gt;
</li>
<li>
<b>Damitha Kumarage</b>
&lt;<a href="mailto:damitha@opensource.lk">damitha@opensource.lk</a>&gt;
</li>
<li>
<b>Nadika Ranasinghe</b>
&lt;<a href="mailto:nadika@opensource.lk">nadika@opensource.lk</a>&gt;
</li>
<li>
<b>Sanjaya Sinharage</b>
&lt;<a href="mailto:sanjayasing@opensource.lk">sanjayasing@opensource.lk</a>&gt;
</li>
<li>
<b>Roshan Weerasuriya</b>
&lt;<a href="mailto:roshan@opensource.lk">roshan@opensource.lk</a>&gt;
</li>
<li>
<b>Sanjiva Weerawarana</b>
&lt;<a href="mailto:sanjiva@watson.ibm.com">sanjiva@watson.ibm.com</a>&gt;
</li>
</ul>
</p>
<div class="h5">
<h5>Committers Emeriti (committers that have
been inactive for 3 months or more)</h5>
</div>
<p>
<ul class="noindent">
<li>
<b>Vahe Amirbekyan</b>
&lt;<a href="mailto:avahe@apache.org">avahe@apache.org</a>&gt;
</li>
<li>
<b>Russell Butek</b>
&lt;<a href="mailto:butek@us.ibm.com">butek@us.ibm.com</a>&gt;
</li>
<li>
<b>Wouter Cloetens</b>
&lt;<a href="mailto:wouter@mind.be">wouter@mind.be</a>&gt;
</li>
<li>
<b>Matt Duftler</b>
&lt;<a href="mailto:duftler@apache.org">duftler@apache.org</a>&gt;
</li>
<li>
<b>Steve Graham</b>
&lt;<a href="mailto:sggraham@us.ibm.com">sggraham@us.ibm.com</a>&gt;
</li>
<li>
<b>Rob Jellinghaus</b>
&lt;<a href="mailto:robj@helium.com">robj@helium.com</a>&gt;
</li>
<li>
<b>Jacek Kopecky</b>
&lt;<a href="mailto:jacek@idoox.com">jacek@idoox.com</a>&gt;
</li>
<li>
<b>Ravi Kumar</b>
&lt;<a href="mailto:rkumar@borland.com">rkumar@borland.com</a>&gt;
</li>
<li>
<b>Berin Loritsch</b>
&lt;<a href="mailto:bloritsch@apache.org">bloritsch@apache.org</a>&gt;
</li>
<li>
<b>George Matkovits</b>
&lt;<a href="mailto:matkovitsg@apache.org">matkovitsg@apache.org</a>&gt;
</li>
<li>
<b>Kevin Mitchell</b>
&lt;<a href="mailto:kmitchell@apache.org">kmitchell@apache.org</a>&gt;
</li>
<li>
<b>Vidyanand Murunikkara</b>
&lt;<a href="mailto:Vidyanand@infravio.com">vidyanand@infravio.com</a>&gt;
</li>
<li>
<b>Bill Nagy</b>
&lt;<a href="mailto:wnagy@us.ibm.com">wnagy@us.ibm.com</a>&gt;
</li>
<li>
<b>Christopher Nelson</b>
&lt;<a href="mailto:cnelson@synchrony.net">cnelson@synchrony.net</a>&gt;
</li>
<li>
<b>Ryo Neyama</b>
&lt;<a href="mailto:neyama@apache.org">neyama@apache.org</a>&gt;
</li>
<li>
<b>Glyn Normington</b>
&lt;<a href="mailto:glyn@apache.org">glyn@apache.org</a>&gt;
[<a href="http://cvs.apache.org/~glyn">Apache home
page</a>]
</li>
<li>
<b>Rick Rineholt
&lt;</b><a href="mailto:rineholt@us.ibm.com">rineholt@us.ibm.com</a>
<b>&gt;</b>
</li>
<li>
<b><a href="http://www.intertwingly.net/blog/">Sam
Ruby</a></b>
&lt;<a href="mailto:rubys@us.ibm.com">rubys@us.ibm.com</a>&gt;
</li>
<li>
<b>Rich Scheuerle</b>
&lt;<a href="mailto:scheu@us.ibm.com">scheu@us.ibm.com</a>&gt;
</li>
<li>
<b>Matt Seibert</b>
&lt;<a href="mailto:mseibert@us.ibm.com">mseibert@us.ibm.com</a>&gt;
</li>
<li>
<b>Richard Sitze</b>
&lt;<a href="mailto:rsitze@apache.org">rsitze@apache.org</a>&gt;
</li>
<li>
<b>James Snell</b>
&lt;<a href="mailto:jasnell@us.ibm.com">jasnell@us.ibm.com</a>&gt;
</li>
</ul>
</p>
<div class="h2">
<h2>WebServices - Axis</h2>
</div>
<div class="h5">
<h5>WebServices - Axis - Contact Us</h5>
</div>
<p>
If you have questions or comments <b>about this site</b>, please send email
to:<br>
<a href="#mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a>.
</p>
<p>
If you have questions or comments <b>about the software or documentations on
this site</b>, please subscribe to the <b>axis-user</b> mailing list:
</p>
<p>
<a href="#mail.html">Mailing lists</a>
</p>
<p>
The Axis project is an effort of the Apache Software Foundation. The address
for general ASF correspondence and licensing questions is:
</p>
<p>
<a href="#mailto:apache@apache.org">apache@apache.org</a>
</p>
<p>
You can find more contact information for the Apache Software Foundation
on the <a href="http://www.apache.org/foundation/contact.html">
contact page of the main Apache site</a>.
</p>
<div class="h2">
<h2>WebServices - Axis</h2>
</div>
<div class="h5">
<h5>WebServices - Axis - Legal Stuff</h5>
</div>
<p>
All material on this website is Copyright &copy; 1999-2003,
The Apache Software Foundation.
</p>
<p>
Sun, Sun Microsystems, Solaris, Java, JavaServer Web Development Kit, and
JavaServer Pages are trademarks or registered trademarks of Sun
Microsystems, Inc.
UNIX is a registered trademark in the United States and other countries,
exclusively licensed through X/Open Company, Ltd.
Windows, WindowsNT, and Win32 are registered trademarks of Microsoft Corp.
All other product names mentioned herein and throughout the entire web site
are trademarks of their respective owners.
</p>
<div class="h2">
<h2>WebServices - Axis</h2>
</div>
<div class="h5">
<h5>WebServices - Axis - Misc Notes</h5>
</div>
<p>
Misc notes and docs that might be of interest...
</p>
<p>
<ul>
<li>
<a href="http://cvs.apache.org/viewcvs/~checkout~/ws-axis/java/docs/requirements.html?content-type=text/html">
Current list of requirements</a>
</li>
<li> Notes from the 1st Face-2-Face </li>
<li>
<a href="#docs/F2F-2.html">
Notes from the 2nd Face-2-Face </a>
</li>
<li>
<a href="#docs/ms-interop.html">
Notes from the Interop meeting with Microsoft</a>
</li>
<li>
<a href="#docs/SOAPVerse.html">
Glen's note about SOAPVerse</a>
</li>
<li>
<a href="#docs/CachingEarlDraft2.html">
Toshi's note about Caching Mechanism</a>
</li>
<li>
<a href="#java/soapmonitor-user-guide.html">
SOAPMonitor User's Guide</a> [for nightly build]</li>
<li>
<a href="http://ws.apache.org/~toshi/jp-site/axis/index.html">
Axis site in Japanese</a> [translation]</li>
</ul>
</p>
<div id="pdf" align="right">
<a href="site.pdf"><img alt="PDF" src="skin/images/pdfdoc.gif" class="skin"><br>
PDF</a>
</div>
</div>
</div>
</div>
</td>
<!--================= end Content ==================-->
</tr>
</tbody>
</table>
<!--================= end Main ==================-->
<!--================= start Footer ==================-->
<div id="footer">
<table summary="footer" cellspacing="0" cellpadding="4" width="100%" border="0">
<tbody>
<tr>
<!--================= start Copyright ==================-->
<td colspan="2">
<div align="center">
<div class="copyright">
Copyright &copy; 2000-2004&nbsp;The Apache Software Foundation. All rights reserved.
</div>
</div>
</td>
<!--================= end Copyright ==================-->
</tr>
<tr>
<td align="left">
<!--================= start Host ==================-->
<!--================= end Host ==================--></td><td align="right">
<!--================= start Credits ==================-->
<div align="right">
<div class="credit"></div>
</div>
<!--================= end Credits ==================-->
</td>
</tr>
</tbody>
</table>
</div>
<!--================= end Footer ==================-->
</body>
</html>