<?xml version="1.0" encoding=""?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <meta http-equiv="content-type" content="" />
  <title>Apache Axis2 User's Guide- Introducing Axis2</title>
  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
  media="all" />
</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"></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="http://ws.apache.org/axis2/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"></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 the <a
    href="http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf">WS-Security</a>,
    <a
    href="http://xml.coverpages.org/ws-reliablemessaging20030313.pdf">WS-ReliableMessaging</a>,
    <a href="http://www.w3.org/2002/ws/addr/">WS-Addressing</a>, <a
    href="http://dev2dev.bea.com/pub/a/2004/03/ws-coordination.html">WS-Coordination</a>,
    and <a
    href="ftp://www6.software.ibm.com/software/developer/library/WS-AtomicTransaction.pdf">WS-Atomic
    Transaction</a> recommendations</li>
  <li>Use Axis2's modular structure to easily add support for new
    recommendations as they emerge</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"></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"></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, and Sandesha, which provides an implementation of
WS-ReliableMessaging, are the main extensibility mechanisms in Axis2.</p>
<a name="distributions"></a>

<h2>Axis2 Distributions</h2>

<p>Axis2 is released in several <a
href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi">distributions</a>.
Which one you need depends on what you'll be doing with it.</p>
<a name="sbd"></a>

<h3>The Axis2 Standard Binary Distribution</h3>

<p>If you're developing services and applications, you'll need the Axis2 <a
href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi#std-bin">Standard
Binary Distribution</a>. 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"></a>

<h2>axis2.war Distribution Directory Hierarchy</h2>

<p>axis2.war is available in <a
href="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi#war">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="http://ws.apache.org/axis2/download/@axis2_version_dir@/download.cgi#src">source
distribution</a>, which enables you to generate this .war file yourself.</p>
<a id="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="../../javadocs/index.html">API documentation</a> for the Axis2 API,
with other documentation (like this document) in the xdocs directory.</p>
<a name="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>