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.
This User's Guide is written based on Axis2 Standard Binary Distribution. The Standard Binary Distribution can be directly downloaded or built using the Source Distribution. If you choose to go for the latter, then Installation Guide will instruct you on how to build Axis2 Standard Binary Distribution using the Source.
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.
Let us know what you think! Send your feedback on Axis2 to "axis-user@ws.apache.org". Make sure to prefix the subject of the mail with [Axis2].
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 - Configuring Axis2 - provides a introduction to important configuration options in Axis2. Final section - Advanced Topics - provides references for other features
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 "samples/userguide/src" directory of Axis2 standard binary distribution.
Please deploy axis2.war in your servlet container and ensure that it works fine. Installation Guide gives you step by step instructions on just how to build axis2.war and deploy it in your servlet container.
If you are looking for "How to Write a Web Service Client using Axis2?" please go to the next section. Axis2 provides two ways to create new Web Services, using code generation 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 Writing Web Services Using Axis2's Primary APIs for more information. However if you are a new user it is better to follow the code generation approach first (given below)
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 Java2WSDL tool 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.
This method of writing a Web service with Axis2 involves four steps:
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 Axis2 Reference Document.
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), JibX and jaxme (experimental) (JaxMe data binding). You can get the Axis2SampleDocLit.wsdl from here.
WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans -o ../samples -p org.apache.axis2.userguide
This will generate the required classes in the "sample/src" directory, and the schema classes in "samples/resources/schemaorg_apache_xmlbeans" directory. Note that these are not source files and should be available in the class path in order to compile the generated classes.
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
"samples/src/org/apache/axis2/userguide directory. Let's
fill the echoString(..) method in the skeleton as shown below. Our sample
WSDL- Axis2SampleDocLit.wsdl in has
three operations: echoString, echoStringArray, echoStruct. To see how others
will look when they are filled up see Code Listing For
Axis2SampleDocLitService Service
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;
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 :
(To write your own service.xml file see sub section in Writing Web Services Using Axis2's Primary APIs section.)
jar -cf <service-name>.aar to
create the archiveOnce the archive is created, the content of the jar should look like this
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 Apache Tomcat as servlet container. 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 (if you have not already started). Check the link "Services" on the Home Page of Axis2 Web Application (http://localhost:8080/axis2) and see whether the Axis2SampleDocLitService is shown under the deployed services.
We recommend using the exploded configuration to deploy Axis2 WAR in WebLogic and WebSphere application servers to support the hotupdate/ hotdeployment features in Axis2. See Application Server Specific Configuration Guide for details.
Note: Axis2 provides an easy way to deploy Web Services using the "Upload Service" tool on Axis2 Web Application's Administration module. (See the Web Administration Guide for more information on this)
Axis2 also provides a more complex, yet powerful XML based client API which is intended for advanced users. Read Writing Web Service Clients Using Axis2's Primary APIs to learn more about it. However, if you are a new user we recommend using the code generation approach presented below.
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
WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -d xmlbeans
-o ../samples/src -p org.apache.axis2.userguide
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 <service-name>Stub. For our example it will be called "Axis2SampleDocLitServiceStub.java"
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.
The following code fragment shows the necessary code calling
echoString operation of the
Axis2SampleDocLitService that we have already deployed. The code
is extremely simple to understand and the explanations are in the form of
comments.
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();
}
First argument of Axis2SampleDocLitPortTypeStub 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 Axis2 Configuration section. You can find code to invoke
other operations from Code
Listing For Axis2SampleDocLitService Service
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 start<method-name>. 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.
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();
}
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.
stub._getServiceClient().engageModule(new QName("addressing"));
stub._getServiceClient().getOptions().setUseSeparateListener(true);
Once those options are set, Axis2 client does the following:
You could use your own repository with Axis2 Client, code below shows how to do this.
String axis2Repo = ... String axis2xml = ... ConfigurationContext configContext = ConfigurationContextFactory.createConfigurationContextFromFileSystem(axis2Repo, axis2xml); Service1Stub stub1 = new Service1Stub(configContext,...); //invoke Service1 Service2Stub stub2 = new Service2Stub(configContext,...); //invoke Service2
Note by creating the ConfigurationContext 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.
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:
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, webapps/axis2/WEB-INF
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.
The Global configuration can be changed by editing the axis2.xml file, look at the Axis2 Configuration Guide for more information
New Services can be written either using WSDL based code generation as we did, or from the scratch as explained here. Read Creating a Service from Scratch for more information. Also refer to Axis2 Configuration Guide for a reference on services.xml file.
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 Axis2 architecture guide for detailed explanation. The following table explains the semantics of scope and how to engage modules in those scopes.
| Scope | Semantics | how to engage |
|---|---|---|
| Global | Add handlers in the module to all the services. Addressing Handler can be only engaged as global | By adding a <module ref="addressing"/> to Axis2 xml file or
calling
stub._getServiceClient().engageModule(moduleName)at client side |
| Service | Add handlers in the module to a specific service | By adding a <module ref="addressing"/> to service.xml file in service archive |
| Operation | Add handlers in the module to a specific operation | By adding a <module ref="addressing"/> to inside a operation tag of service.xml file in service archive |
* If a handler is added to a service or an operation, it will be invoked for every request received by that service or operation
Axis2 provides a number of built in Modules such as (addressing,Security, WS-Reliable Messaging ...), and they can be engaged as shown above. Please refer to each module for how to use and configure them. You can also create your own modules with Axis2. Also refer to Axis2 Configuration Guide for a reference on module.xml file.
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:
stub._getServiceClient().engageModule(moduleName)
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.
Axis2 provides attachment support using MTOM. Please refer to MTOM with Axis2 for more information.
Axis2 provides Security support using the Apache Rampart. Please refer to Securing SOAP Messages with Apache Rampart for more information
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.