Google Git
Sign in
apache / axis-site / ca5eb79b4221a7cc5a51274bfba81a17eb90567a / . / axis2 / java / core-staging / docs / userguide.html
blob: 11cae21cc41e80f8675c990f7eaf473555e04800 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.9.2 at 2021-08-01
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="Date-Revision-yyyymmdd" content="20210801" />
<meta http-equiv="Content-Language" content="en" />
<title>Apache Axis2 &#x2013; Apache Axis2 User's Guide- Introducing Axis2</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" />
<link rel="stylesheet" href="../css/site.css" />
<link rel="stylesheet" href="../css/print.css" media="print" />
<script type="text/javascript" src="../js/apache-maven-fluido-1.6.min.js"></script>
<meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" /><meta http-equiv="content-type" content="" /> </head>
<body class="topBarDisabled">
<div class="container-fluid">
<div id="banner">
<div class="pull-left"><a href="http://www.apache.org/" id="bannerLeft"><img src="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Axis2"/></a></div>
<div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/axis.jpg" /></a></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="publishDate">Last Published: 2021-08-01<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.8.0<span class="divider">|</span></li>
<li class=""><a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li>
<li class=""><a href="../index.html" title="Axis2/Java">Axis2/Java</a><span class="divider">/</span></li>
<li class="active ">Apache Axis2 User's Guide- Introducing Axis2</li>
</ul>
</div>
<div class="row-fluid">
<div id="leftColumn" class="span2">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header">Axis2/Java</li>
<li><a href="../index.html" title="Home"><span class="none"></span>Home</a> </li>
<li><a href="../download.html" title="Downloads"><span class="none"></span>Downloads</a> </li>
<li><a href="javascript:void(0)" title="Release Notes"><span class="icon-chevron-down"></span>Release Notes</a>
<ul class="nav nav-list">
<li><a href="../release-notes/1.6.1.html" title="1.6.1"><span class="none"></span>1.6.1</a> </li>
<li><a href="../release-notes/1.6.2.html" title="1.6.2"><span class="none"></span>1.6.2</a> </li>
<li><a href="../release-notes/1.6.3.html" title="1.6.3"><span class="none"></span>1.6.3</a> </li>
<li><a href="../release-notes/1.6.4.html" title="1.6.4"><span class="none"></span>1.6.4</a> </li>
<li><a href="../release-notes/1.7.0.html" title="1.7.0"><span class="none"></span>1.7.0</a> </li>
<li><a href="../release-notes/1.8.0.html" title="1.8.0"><span class="none"></span>1.8.0</a> </li>
</ul>
</li>
<li><a href="../modules/index.html" title="Modules"><span class="none"></span>Modules</a> </li>
<li><a href="../tools/index.html" title="Tools"><span class="none"></span>Tools</a> </li>
<li class="nav-header">Documentation</li>
<li><a href="../docs/toc.html" title="Table of Contents"><span class="none"></span>Table of Contents</a> </li>
<li><a href="../docs/installationguide.html" title="Installation Guide"><span class="none"></span>Installation Guide</a> </li>
<li><a href="../docs/quickstartguide.html" title="QuickStart Guide"><span class="none"></span>QuickStart Guide</a> </li>
<li class="active"><a href="#"><span class="none"></span>User Guide</a>
</li>
<li><a href="../docs/jaxws-guide.html" title="JAXWS Guide"><span class="none"></span>JAXWS Guide</a> </li>
<li><a href="../docs/pojoguide.html" title="POJO Guide"><span class="none"></span>POJO Guide</a> </li>
<li><a href="../docs/spring.html" title="Spring Guide"><span class="none"></span>Spring Guide</a> </li>
<li><a href="../docs/webadminguide.html" title="Web Administrator's Guide"><span class="none"></span>Web Administrator's Guide</a> </li>
<li><a href="../docs/migration.html" title="Migration Guide (from Axis1)"><span class="none"></span>Migration Guide (from Axis1)</a> </li>
<li class="nav-header">Resources</li>
<li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a> </li>
<li><a href="../articles.html" title="Articles"><span class="none"></span>Articles</a> </li>
<li><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="Wiki"><span class="none"></span>Wiki</a> </li>
<li><a href="../refLib.html" title="Reference Library"><span class="none"></span>Reference Library</a> </li>
<li><a href="../apidocs/index.html" title="Online Java Docs"><span class="none"></span>Online Java Docs</a> </li>
<li class="nav-header">Get Involved</li>
<li><a href="../overview.html" title="Overview"><span class="none"></span>Overview</a> </li>
<li><a href="../git.html" title="Checkout the Source"><span class="none"></span>Checkout the Source</a> </li>
<li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a> </li>
<li><a href="../release-process.html" title="Release Process"><span class="none"></span>Release Process</a> </li>
<li><a href="../guidelines.html" title="Developer Guidelines"><span class="none"></span>Developer Guidelines</a> </li>
<li><a href="../siteHowTo.html" title="Build the Site"><span class="none"></span>Build the Site</a> </li>
<li class="nav-header">Project Information</li>
<li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a> </li>
<li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a> </li>
<li><a href="https://github.com/apache/axis-axis2-java-core/java/core/trunk/" class="externalLink" title="Source Code"><span class="none"></span>Source Code</a> </li>
<li><a href="../thanks.html" title="Acknowledgements"><span class="none"></span>Acknowledgements</a> </li>
<li class="nav-header">Apache</li>
<li><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License"><span class="none"></span>License</a> </li>
<li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a> </li>
<li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a> </li>
<li><a href="http://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a> </li>
</ul>
<hr />
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
</div>
</div>
</div>
<div id="bodyColumn" class="span10" >
<html xmlns="http://www.w3.org/1999/xhtml" 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>
For users of JSON and Spring Boot, see the sample application in the <a href="json-springboot-userguide.html">JSON and Spring Boot 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>
<section>
<h2><a name="Content"></a>Content</h2>
<ul>
<li><a href="userguide.html#intro"><b>Introducing
Axis2</b></a><br />
<ul>
<li><a href="userguide.html#whatis"><b>What is
Axis2?</b></a></li>
<li><a href="userguide.html#underhood"><b>What's under the
hood?</b></a></li>
<li><a href="userguide.html#handlessoap"><b>How Axis2 handles
SOAP messages</b></a></li>
<li><a href="userguide.html#handlesjson">How Axis2 handles JSON
messages</a></li>
<li><a href="userguide.html#distributions"><b>Axis2
Distributions</b></a></li>
<li><a href="userguide.html#sbd"><b>The Axis2 Standard Binary
Distribution</b></a></li>
<li><a href="userguide.html#hierarchy"><b>Axis2.war Directory
Hierarchy</b></a></li>
<li><a href="userguide.html#docs"><b>Axis2 Documents
Distribution</b></a></li>
<li><a href="userguide.html#clients"><b>Axis2 and
Clients</b></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>
<section>
<h2><a name="What_is_Axis2.3F"></a>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>Receive and process JSON 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 class="externalLink" href="http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf">
WS-Security</a> and <a class="externalLink" 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>
<section>
<h2><a name="What.27s_Under_the_Hood.3F"></a>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 src="images/fig01.jpg" alt="Lifecycle of a Web services message" /><br /></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 &quot;<a href="userguide-introtoservices.html">Introduction to Services</a>&quot;.)
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>
<section>
<h2><a name="How_Axis2_Handles_SOAP_Messages"></a>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 src="images/fig02.jpg" alt="Axis2 handles SOAP messages" /><br /></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 <i>can</i> 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 &quot;handlers&quot; 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 &quot;pre-dispatch&quot;
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 &quot;phases&quot;, with
several pre-defined phases, such as the &quot;pre-dispatch&quot;, &quot;dispatch,&quot;
and &quot;message processing&quot;, being built into Axis2. Each phase is a
collection of &quot;handlers&quot;. 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 &quot;modules&quot; 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="handlesjson" id="handlesjson"></a>
<section>
<h2><a name="How_Axis2_Handles_JSON_Messages"></a>How Axis2 Handles JSON Messages</h2>
<p>Axis2 with REST provides GSON or the newer Moshi library as the JSON parser.
With the proper axis2.xml configuration, this support is triggered by the HTTP header
&quot;Content-Type: application/json&quot;. </p>
<p>More docs concerning Axis2 and JSON can be found in the <a href=" json_support_gson.html">Pure JSON Support</a> and <a href=" json_gson_user_guide.html">JSON User Guide.</a>
</p>
<p>
For users of JSON and Spring Boot - or anyone interesed in a complete JSON example that
includes Spring Security - see the sample application in the <a href="json-springboot-userguide.html">JSON and Spring Boot User's Guide.</a>
</p>
<a name="distributions" id="distributions"></a>
<section>
<h2><a name="Axis2_Distributions"></a>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>
<section>
<h3><a name="The_Axis2_Standard_Binary_Distribution"></a>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>
<div>
<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></div>
<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>
</section><section>
<h2><a name="axis2.war_Distribution_Directory_Hierarchy"></a>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>
<div>
<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></div>
<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 log4j2.xml. 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 name="docs" id="docs"></a>
<section>
<h2><a name="Axis2_Documentation_Distribution_Directory_Hierarchy"></a>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>
<div>
<pre>
docs
javadocs
xdocs
LICENSE.txt
README.txt
release-notes.html
</pre></div>
<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>
<section>
<h2><a name="Axis2_and_Clients"></a>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><b>See Next Section</b> - <a href="userguide-installingtesting.html#installingtesting">Installing and
Testing Client Code</a></p>
</html>
</div>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p>Copyright &copy;2004&#x2013;2021
<a href="https://www.apache.org/">The Apache Software Foundation</a>.
All rights reserved.</p>
</div>
</div>
</footer>
</body>
</html>