Google Git
Sign in
apache / axis-axis2-java-core / refs/tags/v1.1 / . / xdocs / 1_1 / userguide.html
blob: c408d629324a290fa6de6f00a7d1b5122363d957 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Axis2 User's Guide</title>
<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
</head>
<body dir="ltr" lang="en-US">
<a name="_Toc96697849" id="_Toc96697849"></a>
<h1 align="center"> Apache Axis2 User's Guide</h1>
<p>This guide will help you get started with Axis2, the next generation of
Apache Axis! It describes in detail how to write Web services and Web
service clients using Axis2; how to write custom modules and how to use them
with a Web service. Advanced Topics and Samples which are shipped with the
binary distribution of Axis2, are also discussed.</p>
<a name="Introduction"></a>
<h2>Introduction</h2>
<p>This User's Guide is written based on <a
href="../download/1_1/download.html/#std-bin">Axis2 Standard Binary
Distribution</a>. The Standard Binary Distribution can be directly <a
href="../download/1_1/download.html/#std-bin">downloaded</a> or
built using the <a href="../download/1_1/download.html#src">Source
Distribution</a>. If you choose to go for the latter, then <a
href="installationguide.html">Installation Guide</a> will instruct you on how
to build Axis2 Standard Binary Distribution using the Source.</p>
<p>We hope you enjoy using Axis2. 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 us a hand! The Axis developer community welcomes your
participation.</p>
<p>Let us know what you think! Send your feedback on Axis2 to "<a
href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a>". Make sure
to prefix the subject of the mail with [Axis2].</p>
<h2>Getting Started</h2>
<p>First two sections of the user guide will walk you through writing and
deploying a new Web Service using Axis2, and writing a Web Service client
using Axis2. Next section - <a href="#config"> Configuring Axis2</a> -
provides a introduction to important configuration options in Axis2. Final
section - <a href="#advanced">Advanced Topics</a> - provides references for
other features</p>
<p>In this section, we will learn how to write and deploy Web services using
Axis2. All the samples mentioned in this guide are located in the
<b>"samples/userguide/src"</b> directory of <a
href="../download/1_1/download.html/#std-bin">Axis2 standard binary
distribution</a>.</p>
<p>Please deploy axis2.war in your servlet container and ensure that it works
fine. <a href="installationguide.html" target="_blank">Installation Guide</a>
gives you step by step instructions on just how to build axis2.war and deploy
it in your servlet container.</p>
<a name="ws_codegen"></a><a name="Web_Services_Using_Axis2"></a>
<h2>Creating a New Web Service</h2>
<p>If you are looking for "How to Write a Web Service Client using Axis2?"
please go to the <a href="#client">next section</a>. Axis2 provides two ways
to create new Web Services, using <strong>code generation</strong> and using XML based primary
APIs. The following section explains how to start from a WSDL, and create a new
Service with code generation. For the XML based primary API please refer to
the section <a href="xmlbased-server.html">Writing Web Services Using Axis2's
Primary APIs</a> for more information. However if you are a new user it is
better to follow the code generation approach first (given below)</p>
<h3>Starting with WSDL, Create and Deploy a Service</h3>
<p>We start with a WSDL, however if you do not have a WSDL and need to create
a WSDL from a java class please try <a
href="reference.html#wsdl2java">Java2WSDL tool</a> and create a WSDL. As you
might already know, a WSDL description of a Service provides precise
definition of a Web Service. Axis2 could process the WSDL and generate java
code that does most of work for you. At the server side we call them
Skeletons and at the client side Stubs.</p>
This method of writing a Web service with Axis2 involves four steps:
<ol>
<li>Generate the skeleton code</li>
<li>Add business logic</li>
<li>Create a *.aar archive (Axis Archive) for the Web service</li>
<li>Deploy the Web service</li>
</ol>
<a name="Step1_:Generate_skeleton"></a>
<h3>Step1: Generate Skeleton Code</h3>
<p>To generate the skeleton and required classes, you can use the WSDL2Java
tool provided in Axis2. This tool is located in the bin directory of the
distribution and can be executed using the provided scripts (.bat or .sh).
The tool's parameter list can be found from <a
href="reference.html#wsdl2code">Axis2 Reference Document</a>.</p>
<p>The parameters for wsdl2java tool in our example are as follows. Please
note that we use xmlbeans as the data binding framework and generated code
will be sent to samples directory. Other data binding tools you could use are
adb (Axis data binding) and jaxme (<a
href="http://ws.apache.org/jaxme/">JaxMe data binding</a>)</p>
<pre>
WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans
-o ../samples -p org.apache.axis2.userguide
</pre>
<p>This will generate the required classes in the <b>"sample/src"</b>
directory, and the schema classes in
<strong>"samples/resources/schemaorg_apache_xmlbeans"</strong>
directory<strong></strong>. Note that these are not source files and should
be available in the class path in order to compile the generated classes.</p>
<a name="Step2_Implement_Business_Logic"></a>
<h3>Step 2: Implement Business
Logic</h3>
<p>Now you should fill the business logic in the skeleton class. You can
find the skeleton class -Axis2SampleDocLitServiceSkeleton.java- among the
generated classes in the
<strong>"samples/src/org/apache/axis2/userguide</strong> directory. Let's
fill the <code>echoString(..)</code> method in the skeleton as shown below. Our sample
WSDL-Axis2SampleDocLit.wsdl in <strong>"samples/wsdl"</strong> directory has
three operations: echoString, echoStringArray, echoStruct. To see how others
will look when they are filled up see <a
href="src/Axis2SampleDocLitServiceCode.html">Code Listing For
Axis2SampleDocLitService Service</a></p>
<source>
<pre>
public org.apache.axis2.userguide.xsd.EchoStringReturnDocument
echoString(org.apache.axis2.userguide.xsd.EchoStringParamDocument param4) throws Exception {
//Use the factory to create the output document.
org.apache.axis2.userguide.xsd.EchoStringReturnDocument retDoc =
org.apache.axis2.userguide.xsd.EchoStringReturnDocument.Factory.newInstance();
//send the string back.
retDoc.setEchoStringReturn(param4.getEchoStringParam());
return retDoc;<br>
</pre></source>
<a name="Step4_Create_archive"></a>
<h3>Step 3: Create Archive File</h3>
<p>An Axis2 service must be bundled as a service archive. The next step is to
package the classes in an .aar (axis2 archive) and deploy it in Axis2. There
is an ant file generated with the code, this will generate the Axis2 service
archive for you. However if you do not want to use ant, you could create
archive with following steps :</p>
<ol>
<li>Compile the generated code</li>
<li>Copy <strong>"resources/schemaorg_apache_xmlbeans</strong>" xmlbeans
classes to your class folder</li>
<li>Among the generated files, there will be services.xml file, which is the
deployment descriptor for Axis2 service.[<a
href="reference.html#servicedd">learn more about it</a>]. Copy the
resources/service.xml to META-INF/services.xml</li>
<p>(To write your own service.xml file see sub section in <a href="xmlbased-server.html#Step2_:Write_the_services_xml_file">Writing Web Services Using Axis2's Primary APIs</a> section.)</p>
<li>Create the archive using content of the class folder. Change directory
to class folder and run <code>jar -cf &lt;service-name&gt;.aar</code> to
create the archive</li>
</ol>
<p>Once the archive is created, the content of the jar should look like
this</p>
<p><img src="images/userguide/DirectoryStructure.jpg" align="bottom"
border="0"></p>
<a name="Step5_Deploy_web_service"></a>
<h3>Step 4: Deploy Web Service</h3>
<p>The service can be deployed by simply dropping the ".aar" file into
"services" directory in "/webapps/axis2/WEB-INF" of your servlet container.
We recommend using <a href="http://tomcat.apache.org/">Apache Tomcat</a> as
servlet container. <strong>Please Note that the services directory is
available only after axis2.war is exploded by Tomcat. However, the easiest way
to do it is to start Tomcat after axis2.war is copied to the webapps
directory</strong> (if you have not already started). Check the link
"Services" on the <a href="http://localhost:8080/axis2/" target="_blank">Home
Page of Axis2 Web Application</a> (http://localhost:8080/axis2) and see
whether the Axis2SampleDocLitService is shown under the deployed services.</p>
<p>We recommend using the exploded configuration to deploy Axis2 WAR in
<strong>WebLogic and WebSphere</strong> application servers to support the
hotupdate/ hotdeployment features in Axis2. See <a href="app_server.html#weblogic_websphere">Application Server Specific
Configuration Guide</a> for details.</p>
<p>Note: Axis2 provides an easy way to deploy Web Services using the "Upload
Service" tool on Axis2 Web Application's Administration module. (See the <a
href="webadminguide.html" target="_blank">Web Administration Guide</a> for
more information on this)</p>
<a name="client"></a>
<h2>Writing a Web Service Client</h2>
<p>Axis2 also provides a more complex, yet powerful XML based client
API which is intended for advanced users. Read <a
href="dii.html">Writing Web Service Clients Using Axis2's Primary APIs</a> to
learn more about it. However, if you are a new user we recommend using the <strong>code
generation</strong> approach presented below.</p>
<h3>Generate Stubs</h3>
<p>Let's see how we could generate java code (Stub) to handle the client side
Web Service invocation for you. That can be done by running the WSDL2Java
tool using following arguments</p>
<source>
<pre>WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -d xmlbeans
-o ../samples/src -p org.apache.axis2.userguide
</pre></source>
<p>This will generate client side stubs and xmlbeans types for your types.
The Stub class that you need to use will be of the form
<strong>&lt;service-name&gt;Stub</strong>. For our example it will be called
"Axis2SampleDocLitServiceStub.java"</p>
<p>Axis2 clients can invoke Web Services both in blocking and non-blocking
manner. In a blocking invocation, the client waits till the service performs
its task without proceeding to the next step. Normally the client waits till
the response to the particular request arrives. In a non-blocking invocation,
the client proceeds to the next step immediately and any responses (if any)
are handled using a Callback mechanism. Please note that some explanations
use the terms Synchronous and Asynchronous to describe the similar invocation
strategies.</p>
<h3>Do a Blocking Invocation</h3>
<p>The following code fragment shows the necessary code calling
<code>echoString</code> operation of the
<code>Axis2SampleDocLitService</code> that we have already deployed. The code
is extremely simple to understand and the explanations are in the form of
comments.</p>
<source>
<pre> try {
org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub
= new org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,
"http://localhost:8080/axis2/services/Axis2SampleDocLitService");
//Create the request document to be sent.
org.apache.axis2.userguide.xsd.EchoStringParamDocument reqDoc =
org.apache.axis2.userguide.xsd.EchoStringParamDocument.Factory.newInstance();
reqDoc.setEchoStringParam("Axis2 Echo");
//invokes the Web service.
org.apache.axis2.userguide.xsd.EchoStringReturnDocument resDoc =
stub.echoString(reqDoc);
System.out.println(resDoc.getEchoStringReturn());
} catch (java.rmi.RemoteException e) {
e.printStackTrace();
}
</pre></source>
<p>First argument of <code>Axis2SampleDocLitPortTypeStub</code> should be the
Axis2 repository for the client. Here we use null to make the stub use
default configurations. However you could make Axis2 use your own repository
by providing it here. You could find more information about this from <a
href="#config">Axis2 Configuration section</a>. You can find code to invoke
other operations from <a href="src/Axis2SampleDocLitServiceCode.html">Code
Listing For Axis2SampleDocLitService Service</a></p>
<h3>Do a Non-Blocking Invocation</h3>
<p>The stubs also include a method that allows you to do a non-blocking
innovation, for each method in the Service there will be a method
<strong>start&lt;method-name&gt;</strong>. These methods accept a callback
object which would be called when the response is received. Sample code that
does an asynchronous interaction is given below.</p>
<source>
<pre>try {
org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub
= new org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,
"http://localhost:8080/axis2/services/Axis2SampleDocLitService");
//implementing the callback online
org.apache.axis2.userguide.Axis2SampleDocLitServiceCallbackHandler callback =
new org.apache.axis2.userguide.Axis2SampleDocLitServiceCallbackHandler() {
public void receiveResultechoString(
org.apache.axis2.userguide.xsd.EchoStringReturnDocument resDoc) {
System.out.println(resDoc.getEchoStringReturn());
}
};
org.apache.axis2.userguide.xsd.EchoStringParamDocument reqDoc =
org.apache.axis2.userguide.xsd.EchoStringParamDocument.Factory.newInstance();
reqDoc.setEchoStringParam("Axis2 Echo");
stub.startechoString(reqDoc, callback);
} catch (java.rmi.RemoteException e) {
e.printStackTrace();
}
</pre>
</source>
<p>Even though the above code does a non-blocking invocation at the client
API, the transport connection may still operate in blocking fashion. For
example, a single HTTP connection can be used to make the Web Service request
and to get the response where a blocking invocation happens at the transport
level. To perform a "true" Non-Blocking invocation in which two separate
transport connections are used for the request and the response please add
the following code segment after creating the stub. These will force Axis2 to
use two transport connections for the request and the response while the
client uses a Callback to process the response.</p>
<source>
<pre>
stub._getServiceClient().engageModule(new QName("addressing"));
stub._getServiceClient().getOptions().setUseSeparateListener(true);
</pre>
</source>
<p>Once those options are set, Axis2 client does the following:</p>
<ol>
<li>Start a new Transport Listener(Server) at the client side</li>
<li>Set the address of the Transport Listener, as the ReplyTo WS-Addressing
Header of the request Message</li>
<li>According to the WS-Addressing rules, Server will process the request
message and send the response back to the ReplyTo address</li>
<li>Client accepts the response, processes it and invokes the callback with
the response parameters</li>
</ol>
<h3>Using Your Own Repository</h3>
<p>You could use your own repository with Axis2 Client, code below shows
how to do this.</p>
<source>
<pre>
String axis2Repo = ...
String axis2xml = ...
ConfigurationContext configContext =
ConfigurationContextFactory.createConfigurationContextFromFileSystem(axis2Repo, axis2xml);
Service1Stub stub1 = new Service1Stub(configContext,...);
//invoke Service1
Service2Stub stub2 = new Service2Stub(configContext,...);
//invoke Service2
</pre>
</source>
<p>Note by creating the <code>ConfigurationContext</code> outside and
passing it to the stubs, you could make number of stubs to use same
repository, thus saving the configuration loading overhead from each
request.</p>
<a name="config"></a>
<h2>Configuring Axis2</h2>
<h3>Axis2 Repository</h3>
<p>Axis2 configuration is based on a repository and standard archives
formats. A repository is a directory in the file system and it should have
the following:</p>
<ol>
<li><strong>axis2.xml</strong>, the Axis2 global deployment descriptor in
conf/axis2.xml file</li>
<li><strong>services</strong> directory, which will have service
archives</li>
<li>optional <strong>modules</strong> directory, which will have module
archives</li>
</ol>
<p>Both services and modules will be identified and deployed once their
archives are copied to the corresponding directories. At the server side
users should specify the repository folder at the time of starting a Axis2
Server (e.g. HTTP or TCP). In Tomcat, <code>webapps/axis2/WEB-INF</code>
folder acts as the repository. At the client side binary distribution can
itself be a repository. You can copy the conf directory which includes the
axis2.xml file from the exploded axis2.war and edit it to change global
configurations repository.</p>
<h3>Global Configurations</h3>
<p>The Global configuration can be changed by editing the axis2.xml file,
look at the <a href="axis2config.html#Global_Configuration">Axis2
Configuration Guide</a> for more information</p>
<h3>Add new Services</h3>
<p>New Services can be written either using WSDL based code generation as we
did, or from the scratch as explained <a
href="xmlbased-server.html">here</a>. Read <a
href="xmlbased-server.html">Creating a Service from Scratch</a> for more
information. Also refer to <a
href="axis2config.html#Service_Configuration">Axis2 Configuration Guide</a>
for a reference on <strong>services.xml</strong> file.</p>
<h3 name="module_engage">Engaging Modules</h3>
<p>Each module(.mar file) provides extensions to Axis2. A module can be
deployed by copying it in to the modules directory in the repository. Then it
becomes available and can be engaged at global, service or operation scopes.
Once engaged it becomes active (add handlers to the execution flow) at the
respective scope. Please refer to <a href="Axis2ArchitectureGuide.html">Axis2
architecture guide</a> for detailed explanation. The following table explains the
semantics of scope and how to engage modules in those scopes.</p>
<table border="1">
<tbody>
<tr>
<th>Scope</th>
<th>Semantics</th>
<th>how to engage</th>
</tr>
<tr>
<td>Global</td>
<td>Add handlers in the module to all the services. Addressing Handler
can be only engaged as global</td>
<td>By adding a &lt;module ref="addressing"/&gt; to Axis2 xml file or
calling
<pre>stub._getServiceClient().engageModule(moduleName)</pre>
at client side</td>
</tr>
<tr>
<td>Service</td>
<td>Add handlers in the module to a specific service</td>
<td>By adding a &lt;module ref="addressing"/&gt; to service.xml file in
service archive</td>
</tr>
<tr>
<td>Operation</td>
<td>Add handlers in the module to a specific operation</td>
<td>By adding a &lt;module ref="addressing"/&gt; to inside a operation
tag of service.xml file in service archive</td>
</tr>
</tbody>
</table>
<p>* If a handler is added to a service or an operation, it will be invoked
for every request received by that service or operation</p>
<p>Axis2 provides a number of built in Modules such as (<a
href="">addressing</a>,<a href="">Security</a>, <a href="">WS-Reliable
Messaging</a> ...), and they can be engaged as shown above. Please refer to
each module for how to use and configure them. You can also <a
href="modules.html">create your own modules with Axis2</a>. Also refer to <a
href="axis2config.html#Global_Configuration">Axis2 Configuration Guide</a>
for a reference on module.xml file.</p>
<h3>WS-Addressing Support</h3>
<p>WS-Addressing support for Axis2 is implemented by the addressing module.
To enable addressing you need to engage the addressing module in both server
and client sides. In order to do this:</p>
<ol>
<li>To <strong>enable</strong> addressing at the server side you need to
copy addressing.mar file to modules directory of server's axis2
repository. To engage the module, add a &lt;module ref="addressing"/&gt; to
axis2.xml. <strong>Addressing module can be engaged only at global
level</strong></li>
<li>To <strong>enable</strong> addressing at the client side you should add
it to the repository and provide the repository as argument to the <a
href="dii.html">ServiceClient</a> or <a href="#client">generated stub</a>
or have it in your classpath</li>
<li>To <strong>engage</strong> addressing module you should either add
&lt;module ref="addressing"/&gt; to axis2.xml file at the client side or
call
<pre>stub._getServiceClient().engageModule(moduleName)</pre>
</li>
</ol>
<a name="advanced"></a>
<h2>Advanced Topics</h2>
<h3>Transports</h3>
<p>Axis2 is by default configured to use HTTP as the transport. However Axis2
supports HTTP, SMTP, TCP and JMS transports. You can also write your own
transports, and deploy them by adding new transportReceiver or
transportSender tags to axis2.xml. To learn how to configure and use
different transports please refer the following documents.</p>
<ol>
<li><a href="tcp-transport.html" target="_blank">TCP Transport</a></li>
<li><a href="mail-transport.html" target="_blank">Mail Transport</a></li>
<li><a href="http-transport.html" target="_blank">HTTP Transports</a></li>
<li><a href="jms-transport.html" target="_blank">JMS Transports</a></li>
</ol>
<h3>Attachments</h3>
<p>Axis2 provides attachment support using <a
href="http://www.w3.org/TR/soap12-mtom/">MTOM</a>. Please refer to <a
href="mtom-guide.html" target="_blank">MTOM with Axis2</a> for more
information.</p>
<h3>Security</h3>
<p>Axis2 provides Security support using the <a
href="http://ws.apache.org/axis2/modules/rampart/1_0/security-module.html">Apache
Rampart</a>. Please refer to <a
href="../modules/wss4j/1_0/security-module.html" target="_blank">Securing
SOAP Messages with Apache Rampart</a> for more information</p>
<h3>REST Web Service</h3>
<p>Please refer to <a href="rest-ws.html" target="_blank">RESTful Web
Services</a> for more information</p>
<h3>Pluggable Data Binding</h3>
<p>Axis2 ships with Axis Data Binding(ADB) as the default data binding
framework, however the data binding frameworks are pluggable to Axis2, and
you could use other data binding frameworks with Axis2. Please refer the
following documents for more information.</p>
<h4>Axis2 Data Binding(ADB)</h4>
<ol>
<li><a href="adb/adb-howto.html" target="_blank">Axis2 Databinding
Framework</a></li>
<li><a href="adb/adb-codegen-integration.html" target="_blank">ADB
Integration With Axis2</a></li>
<li><a href="adb/adb-advanced.html">Advanced Axis2 Databinding Framework
Features</a></li>
<li><a href="adb/adb-tweaking.html">ADB Tweaking Guide</a></li>
</ol>
<h4>JiBX</h4>
<a href="jibx/jibx-codegen-integration.html">JiBX Integration With Axis2</a>
<h3>Other Topics</h3>
<ol>
<li><a href="spring.html" target="_blank">Axis2 Integration With The Spring
Framework</a></li>
<li><a href="WS_policy.html" target="_blank">Web Services Policy Support In
Axis2</a></li>
<li><a href="axis2config.html#Global_Configuration">Axis2 Configuration
Guide</a></li>
<li><a href="Axis2-rpc-support.html">Axis2 RPC Support</a></li>
<li><a href="migration.html">Migrating from Apache Axis 1.x to Axis
2</a></li>
<li><a href="modules.html">Writing your Own Axis2 Module</a></li>
<li><a href="soapmonitor-module.html">Using the SOAP Monitor</a></li>
<li><a href="xmlbased-server.html">Writing Web Services Using Axis2's
Primary APIs</a></li>
<li><a href="dii.html">Writing Web Service Clients Using Axis2's Primary
APIs</a></li>
<li><a href="app_server.html">Application Server Specific Configuration
Guide</a></li>
</ol>
</body>
</html>