<?xml version="1.0" encoding="UTF-8"?> | |
<!-- | |
~ Licensed to the Apache Software Foundation (ASF) under one | |
~ or more contributor license agreements. See the NOTICE file | |
~ distributed with this work for additional information | |
~ regarding copyright ownership. The ASF licenses this file | |
~ to you under the Apache License, Version 2.0 (the | |
~ "License"); you may not use this file except in compliance | |
~ with the License. You may obtain a copy of the License at | |
~ | |
~ http://www.apache.org/licenses/LICENSE-2.0 | |
~ | |
~ Unless required by applicable law or agreed to in writing, | |
~ software distributed under the License is distributed on an | |
~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
~ KIND, either express or implied. See the License for the | |
~ specific language governing permissions and limitations | |
~ under the License. | |
--> | |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" | |
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> | |
<head> | |
<meta name="generator" content= | |
"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" /> | |
<meta http-equiv="content-type" content="" /> | |
<title>Apache Axis2 User's Guide- Introducing Axis2</title> | |
</head> | |
<body xml:lang="en" lang="en"> | |
<h1>Apache Axis2 User's Guide</h1> | |
<p>This guide provides a starting place for users who are new to | |
Apache Axis2. It also covers some advanced topics, such as how to | |
use Axis2 to create and deploy Web services as well as how to use | |
WSDL to generate both clients and services.</p> | |
For experienced users of Apache Axis2, we recommend the <a href= | |
"adv-userguide.html">Advanced User's Guide.</a> <a name="intro" id= | |
"intro"></a> | |
<h1>Introducing Axis2</h1> | |
<p>This section introduces Axis2 and its structure, including an | |
explanation of various directories/files included in the latest | |
Axis2 <a href="../download.cgi">download</a>.</p> | |
<h2>Content</h2> | |
<ul> | |
<li><a href="userguide.html#intro"><strong>Introducing | |
Axis2</strong></a><br /> | |
<ul> | |
<li><a href="userguide.html#whatis"><strong>What is | |
Axis2?</strong></a></li> | |
<li><a href="userguide.html#underhood"><strong>What's under the | |
hood?</strong></a></li> | |
<li><a href="userguide.html#handlessoap"><strong>How Axis2 handles | |
SOAP messages</strong></a></li> | |
<li><a href="userguide.html#distributions"><strong>Axis2 | |
Distributions</strong></a></li> | |
<li><a href="userguide.html#sbd"><strong>The Axis2 Standard Binary | |
Distribution</strong></a></li> | |
<li><a href="userguide.html#hierarchy"><strong>Axis2.war Directory | |
Hierarchy</strong></a></li> | |
<li><a href="userguide.html#docs"><strong>Axis2 Documents | |
Distribution</strong></a></li> | |
<li><a href="userguide.html#clients"><strong>Axis2 and | |
Clients</strong></a></li> | |
</ul> | |
</li> | |
<li><a href= | |
"userguide-installingtesting.html#installingtesting">Installing and | |
Testing Client Code</a></li> | |
<li><a href= | |
"userguide-introtoservices.html#introservices">Introduction to | |
Services</a><br /> | |
<ul> | |
<li><a href= | |
"userguide-introtoservices.html#messageexchange">Message Exchange | |
Patterns</a></li> | |
</ul> | |
</li> | |
<li><a href="userguide-creatingclients.html#createclients">Creating | |
Clients</a><br /> | |
<ul> | |
<li><a href= | |
"userguide-creatingclients.html#choosingclient">Choosing a Client | |
Generation Method</a></li> | |
<li><a href="userguide-creatingclients.html#generating">Generating | |
Clients</a></li> | |
<li><a href="userguide-creatingclients.html#adb">Axis Data Binding | |
(ADB)</a></li> | |
</ul> | |
</li> | |
<li><a href= | |
"userguide-buildingservices.html#buildservices">Building | |
Services</a><br /> | |
<ul> | |
<li><a href= | |
"userguide-buildingservices.html#getcomfortable">Getting | |
Comfortable with Available Options</a></li> | |
<li><a href= | |
"userguide-buildingservices.html#createscratch">Creating a Service | |
from Scratch</a></li> | |
<li><a href="userguide-buildingservices.html#deploypojo">Deploying | |
Plain Old Java Objects</a></li> | |
<li><a href="userguide-buildingservices.html#deployrun">Deploying | |
and Running an Axis2 Service Created from WSDL</a></li> | |
</ul> | |
</li> | |
<li><a href="userguide-samples.html">Samples</a></li> | |
<li><a href="userguide-forfurtherstudy.html">For Further | |
Study</a></li> | |
</ul> | |
<a name="whatis" id="whatis"></a> | |
<h2>What is Axis2?</h2> | |
<p>The Apache Axis2 project is a Java-based implementation of both | |
the client and server sides of the Web services equation. Designed | |
to take advantage of the lessons learned from Apache Axis 1.0, | |
Apache Axis2 provides a complete object model and a modular | |
architecture that makes it easy to add functionality and support | |
for new Web services-related specifications and | |
recommendations.</p> | |
<p>Axis2 enables you to easily perform the following tasks:</p> | |
<ul> | |
<li>Send SOAP messages</li> | |
<li>Receive and process SOAP messages</li> | |
<li>Create a Web service out of a plain Java class</li> | |
<li>Create implementation classes for both the server and client | |
using WSDL</li> | |
<li>Easily retrieve the WSDL for a service</li> | |
<li>Send and receive SOAP messages with attachments</li> | |
<li>Create or utilize a REST-based Web service</li> | |
<li>Create or utilize services that take advantage of <a href= | |
"http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf"> | |
WS-Security</a> and <a href="http://www.w3.org/2002/ws/addr/">WS-Addressing</a></li> | |
</ul> | |
<p>Many more features exist as well, but this user guide | |
concentrates on showing you how to accomplish the first five tasks | |
on this list.</p> | |
<a name="underhood" id="underhood"></a> | |
<h2>What's Under the Hood?</h2> | |
<p>To understand Axis2 and what it does, you must have a good idea | |
of the life cycle of a Web services message. Typically, it looks | |
something like this:</p> | |
<p><img alt="Lifecycle of a Web services message" src= | |
"images/fig01.jpg" /><br clear="all" /></p> | |
<p>The sending application creates the original SOAP message, an | |
XML message that consists of headers and a body. (For more | |
information on SOAP, see "<a href= | |
"userguide-introtoservices.html">Introduction to Services</a>".) | |
If the system requires the use of WS* recommendations such as | |
WS-Addressing or WS-Security, the message may undergo additional | |
processing before it leaves the sender. Once the message is ready, | |
it is sent via a particular transport such as HTTP, JMS, and so | |
on.</p> | |
<p>The message works its way over to the receiver, which takes in | |
the message via the transport listener. (In other words, if the | |
application doesn't have an HTTP listener running, it's not going | |
to receive any HTTP messages.) Again, if the message is part of a | |
system that requires the use of WS-Security or other | |
recommendations, it may need additional processing for the purpose | |
of checking credentials or decrypting sensitive information. | |
Finally, a dispatcher determines the specific application (or other | |
component, such as a Java method) for which the message was | |
intended, and sends it to that component. That component is part of | |
an overall application designed to work with the data being sent | |
back and forth.</p> | |
<a name="handlessoap" id="handlessoap"></a> | |
<h2>How Axis2 Handles SOAP Messages</h2> | |
<p>Axis2 can handle processing for both the sender and the receiver | |
in a transaction. From the Axis2 perspective, the structure looks | |
like this:</p> | |
<p><img alt="Axis2 handles SOAP messages" src= | |
"images/fig02.jpg" /><br clear="all" /></p> | |
<p>On each end, you have an application designed to deal with the | |
(sent or received) messages. In the middle, you have Axis2, or | |
rather, you <em>can</em> have Axis2. The value of Web services is | |
that the sender and receiver (each of which can be either the | |
server or the client) don't even have to be on the same platform, | |
much less running the same application. Assuming that Axis2 is | |
running on both sides, the process looks like this:</p> | |
<ul> | |
<li>The sender creates the SOAP message.</li> | |
<li>Axis "handlers" perform any necessary actions on that message | |
such as encryption of WS-Security related messages.</li> | |
<li>The transport sender sends the message.</li> | |
<li>On the receiving end, the transport listener detects the | |
message.</li> | |
<li>The transport listener passes the message on to any handlers on | |
the receiving side.</li> | |
<li>Once the message has been processed in the "pre-dispatch" | |
phase, it is handed off to the dispatchers, which pass it on to the | |
appropriate application.</li> | |
</ul> | |
<p>In Axis2, these actions are broken down into "phases", with | |
several pre-defined phases, such as the "pre-dispatch", "dispatch," | |
and "message processing", being built into Axis2. Each phase is a | |
collection of "handlers". Axis2 enables you to control what | |
handlers go into which phases, and the order in which the handlers | |
are executed within the phases. You can also add your own phases | |
and handlers.</p> | |
<p>Handlers come from "modules" that can be plugged into a running | |
Axis2 system. These modules, such as Rampart, which provides an | |
implementation of WS-Security, are the main extensibility | |
mechanisms in Axis2.</p> | |
<a name="distributions" id="distributions"></a> | |
<h2>Axis2 Distributions</h2> | |
<p>Axis2 is released in several <a href="../download.cgi"> | |
distributions</a>. Which one you need depends on what you'll be | |
doing with it.</p> | |
<a name="sbd" id="sbd"></a> | |
<h3>The Axis2 Standard Binary Distribution</h3> | |
<p>If you're developing services and applications, you'll need the | |
Axis2 Standard Binary Distribution. The distribution includes all the | |
necessary *.jar files, as well as a variety of scripts that ease | |
development. It has the following structure.</p> | |
<p><b>Code Listing 1: Axis2 Standard Binary Distribution</b></p> | |
<pre> | |
bin | |
axis2.bat | |
axis2.sh | |
axis2server.bat | |
axis2server.sh | |
java2wsdl.bat | |
java2wsdl.sh | |
wsdl2java.bat | |
wsdl2java.sh | |
setenv.sh | |
lib | |
activation-1.1.jar | |
... | |
XmlSchema.jar | |
repository | |
modules | |
modules.list | |
addressing-1.1.mar | |
.. | |
services | |
services.list | |
version.aar | |
.. | |
samples | |
... | |
webapp | |
... | |
conf | |
axis2.xml | |
LICENSE.txt | |
README.txt | |
NOTICE.txt | |
INSTALL.txt | |
release-notes.html | |
</pre> | |
<p>The bin directory includes a number of useful scripts. They | |
include axis2.bat (or axis2.sh), which enables you to easily | |
execute a Java command without having to manually add all the Axis2 | |
jar files to the classpath, java2wsdl.bat (and .sh) and | |
wsdl2java.bat (and .sh), which enable you to easily generate Java | |
code from a WSDL file and vice versa, and axis2server.bat (and sh), | |
a simple Web server that enables you to build Axis2's capability to | |
send and receive messages into your own application.</p> | |
<p>As expected, the lib directory includes all the necessary .jar | |
files. Services and modules are added to the repository directory. | |
Axis2 comes with a standard module implementing WS-Addressing, and | |
you can add any other necessary module such as Rampart to the | |
repository/modules directory.</p> | |
<p>conf directory includes the axis2.xml which is the global | |
deployment descriptor.</p> | |
<p>Finally, the samples directory includes all the sample code | |
distributed with Axis2. See the list of <a href= | |
"userguide-samples.html">samples and their descriptions</a>.</p> | |
<a name="hierarchy" id="hierarchy"></a> | |
<h2>axis2.war Distribution Directory Hierarchy</h2> | |
<p>axis2.war is available in <a href="../download.cgi"> | |
WAR (Web Archive) Distribution</a>. The server side of Axis2 ships | |
as a J2EE application, and has the following structure shown in | |
Code Listing 2.</p> | |
<p><b>Code Listing 2: Server Side of Axis2</b></p> | |
<pre> | |
axis2-web | |
META-INF | |
WEB-INF | |
classes | |
conf | |
axis2.xml | |
lib | |
activation.jar | |
... | |
xmlSchema.jar | |
modules | |
modules.list | |
addressing.mar | |
... | |
soapmonitor.mar | |
services | |
services.list | |
aservice.aar | |
... | |
version.aar | |
web.xml | |
</pre> | |
<p>Starting at the top, axis2-web is a collection of JSPs that make | |
up the <a href="webadminguide.html">Axis2 administration | |
application</a>, through which you can perform any needed actions | |
such as adding services and engaging and dis-engaging modules. The | |
WEB-INF directory represents the actual Axis2 application, | |
including all the *.jar files, any included modules, and even the | |
deployed services themselves.</p> | |
<p>The classes directory holds any class or property files that are | |
needed by Axis2 itself, such as log4j.properties. Any actual | |
services to be handled by the system reside in the services | |
directory in the form of an axis archive, or *.aar file. This file | |
contains any classes related to the service, as well as the | |
services.xml file, which controls any additional requirements, such | |
as the definition of message senders and message receivers.</p> | |
<p>The main file in all this is axis2.xml, which controls how the | |
application deals with received messages. It defines message | |
receivers and transport receivers, as well as defining transport | |
senders and determining which modules are active. It also defines | |
the order of phases, and the handlers to be executed within each | |
phase.</p> | |
<p>You can control all of this information through the use of the | |
Web application, but if you restart the Axis2 application, these | |
changes are lost and the server goes back to the definitions in the | |
axis2.xml file.</p> | |
<p>Axis2 also provides a third distribution, the <a href="../download.cgi"> | |
source distribution</a>, which enables you to generate this .war | |
file yourself.</p> | |
<a id="docs" name="docs"></a> | |
<h2>Axis2 Documentation Distribution Directory Hierarchy</h2> | |
<p>The Documents distribution includes all Axis2 documentation | |
including the xdcos and javadocs. It has the following | |
structure:</p> | |
<p><b>Code Listing 3: Axis2 Documents Distribution</b></p> | |
<pre> | |
docs | |
javadocs | |
xdocs | |
LICENSE.txt | |
README.txt | |
release-notes.html | |
</pre> | |
<p>The javadocs directory includes all the standard <a href= | |
"../api/index.html">API documentation</a> for the Axis2 | |
API, with other documentation (like this document) in the xdocs | |
directory.</p> | |
<a name="clients" id="clients"></a> | |
<h2>Axis2 and Clients</h2> | |
<p>Now that explains how Axis2 behaves as part of a Web | |
application. What about a standalone client that is not part of a | |
J2EE application? In that case, a sender can use the Axis2 default | |
properties, in other words, no special handlers, and so on. But you | |
also have the option to tell the client to load its own copy of the | |
axis2.xml file and behave accordingly.</p> | |
<p><strong>See Next Section</strong> - <a href= | |
"userguide-installingtesting.html#installingtesting">Installing and | |
Testing Client Code</a></p> | |
</body> | |
</html> |