You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by Chathura Herath <ch...@opensource.lk> on 2005/06/07 05:08:57 UTC
RE: [Axis2] M2 Userguide Review
Thanks Harsha.. Jaliya is working on incorporating your comments.
_____
From: Harsha Perera [mailto:harshap@bigpond.net.au]
Sent: Monday, June 06, 2005 8:42 PM
To: Chathura Herath
Subject: [Axis2]M2 Userguide
Hi Chathura,
A new version of the userguide was looked at and a modified copy of it
is attached.
The parts that are unclear are:
- What is written in blue is incomplete.
- In Sample1- Case1 : Echo Synchronous call, under the deployment sample
section the following lines are not clear:
- Once the service.xml and the web service (in this case EchoXML) are
ready, it is necessary to package it into a jar. Actually with the above
>ant compile
Option 2 below actually requires the container to be online.
>ant deploy
Thanks
Harsha
Axis 2.0 User's Guide
Introduction
Welcome to Axis 2.0, the next generation of Apache Axis !!! This User Guide
will help you understand what you can get from Axis 2.0 and how to get
started. We hope that you will benefit from the power of Axis 2.0.
What is Axis 2.0 ?
Before we start, it is highly recommended that you read the Axis 1.x User's
guide <http://ws.apache.org/axis/java/user-guide.html> , if you are new to
Axis.
Axis 2.0 is the next generation of Apache Axis. In late August 2004, during
the Axis Summit held in Colombo, Sri Lanka, a new architecture was
introduced to have a much more flexible, efficient and configurable Axis.
Even though the architecture is new, some of the well established concepts
from Axis 1.x, like handlers are preserved in Axis 2.0 also. Axis 2.0 comes
with lots of new features, enhancements and implementations of new industry
specifications.
After months of continued discussion and coding effort in this direction,
Axis 2.0 now delivers the following key features:
* Speed. Axis uses its own object model and StAX (streaming) parsing
to achieve significantly greater speed than earlier versions of Apache AXIS.
* Low memory foot print. Axis 2.0 was designed ground-up keeping a low
memory foot print in mind.
* AXIOM. Axis 2.0 comes with its own light-weight object model, AXIOM,
for message processing which is extensible, high performance and developer
convenient
* Hot Deployment. One can now hot deploy web services and handlers.
* Asynchronous Web Services. Axis 2.0 now supports asynchronous web
services invocation and asynchronous web services.
* MEP Support. Axis 2.0 now comes handy with support for Message
Exchange Patterns.
* Flexibility. The Axis architecture gives the developer complete
freedom to insert extensions into the engine for custom header processing,
system management, or anything else you can imagine.
* Stability. Axis defines a set of published interfaces which change
relatively slowly compared to the rest of Axis.
* Component-oriented deployment. You can easily define reusable
networks of Handlers to implement common patterns of processing for your
applications, or to distribute to partners.
* Transport framework. We have a clean and simple abstraction for
designing transports (i.e., senders and listeners for SOAP over various
protocols such as SMTP, FTP, message-oriented middleware, etc), and the core
of the engine is completely transport-independent.
* WSDL support. Axis 2.0 supports the Web Service Description
<http://www.w3.org/TR/wsdl> Language , version 1.1 and 2.0, which allows
you to easily build stubs to access remote services, and also to
automatically export machine-readable descriptions of your deployed services
from Axis.
We hope you enjoy using Axis. 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 a hand! The Axis developer community welcomes your
participation .
Let us know what you think!
Please send feedback about the package to " axis-user@ws.apache.org
<ma...@ws.apache.org> " and make sure to prefix the subject of
the mail with [Axis2].
What's in this release?
This release includes the following features:
* AXIOM, a SOAP specific streaming XML infoset model for SOAP 1.1/1.2
Messages
* Modules, mechanism to extend the SOAP Processing Model
* Support for WS-Addressing
* Client API
* Support for One-Way Messaging
* Support for Request Response Messaging
1. Synchronous, Using a two way transport
2. Asynchronous, Using a two way transport
3. Synchronous, Using a one way transport
4. Asynchronous, Using a two way transport
* Hot deployment of Web Services and Module deployment based on the
archived modules
* WSDL Code Generation Tool.
* REST Web Service Support
* HTTP transport Support
* SMTP transport Support
* TCP transport Support
What's still to do?
Please see a list of what we think needs doing - and please consider helping
out if you're interested & able!
* Encoding/data binding
* JAX-RPC 1.1/2.0 compliance
* Data binding support for WSDL Based code (server/client) code
generator
* MTOM attachments support
* Complete XML infoset support for AXIOM
* Implementation of other transports. e.g. JMS..
Installation Guide
Introduction
Axis 2.0 can be downloaded as a zipped binary or the source . This section
describes how Axis2 can be installed either as a standalone server or as
part of a J2EE compliant servlet container.
Prerequisites
Axis2 requires the Java Runtime Environment to be properly installed. Axis
is developed to be run on JRE 1.4 and upwards, but it has not been fully
tested with the latest JRE 1.5. Hence it is safe to run Axis with Java 1.4.
If the JRE is not already in place it must be installed to proceed further.
For instructions on setting up the JRE in different operating systems,
please visit http://java.sun.com <http://java.sun.com/> .
All the required jars are shipped with the binary distribution and if the
source distribution is used, running the maven build will automatically
download the required jars for you.
The following sections describe how each type of distribution needs to be
installed. Since the process with the source distribution is similar to the
binary distribution after building, the first section explains the process
of building Axis from source. If you have the binary distribution you can
skip the build sections and directly go to the binary installation section.
Building Axis2 from source
Setting up the Environment and the tools
The Axis2 build is based on Maven <http://maven.apache.org/> . Hence the
prerequisite to build Axis2 from source is to have Maven installed. Even
though extensive instruction guides are available at the Maven site, this
guide also contains the easiest path for quick environment setting. Advanced
users who wish to know more about Maven can visit here
<http://maven.apache.org/start/index.html> .
For Windows users the easiest way is to download the windows installer
package. Once the installer package is run, all the necessary environment
variables will be properly set. Once Maven is installed, the success of the
installation can be tested by typing maven version in the command prompt.
For Linux users the tar ball or the zip archive is the best options.
(Unfortunately there is no rpm as such that can be easily installed) Once
the archive is downloaded expand it to a directory of choice and set the
environment variable MAVEN_HOME and add MAVEN_HOME/bin to the path as well.
More instructions for installing Maven on UNIX based operating systems can
be found here <http://maven.apache.org/start/install.html> .
Once maven is properly installed it's all that is needed to start building
Axis2.
The Axis source distribution
The source distribution is available as a zipped archive or a tar ball. All
the necessary build scripts are included with the source distribution. Once
the source archive is expanded into a directory of choice, moving to the
particular directory and typing maven will build the axis jar file.
Once the command completes, the binaries (jar files in this case) can be
found in a newly created target\lib directory.
Note For the first Maven build (if the maven repository is not built first)
it will take a while since the required jars need to be downloaded. However
this is a once only process and will not affect any successive builds.
The default maven build will however build only the Axis2 jar file. To
obtain a WAR (Web Archive), the maven war command should be issued. This
will create a complete WAR with the name axis2.war inside the target
directory.
Once this build step is complete, the binaries are ready to be deployed.
Installing Axis2 in a Servlet container
Installation of the WAR is quite simple. It's a matter of dropping the war
in the webapps folders and most servlet containers will automatically
install the war. However some servlet containers may require a restart in
order to capture the new web application. Please refer to your servlet
container documentation for more information about this.
Once the WAR is successfully installed it can be tested by pointing the web
browser to http:// <host :port>/ axis2. It should produce the following
page.
To ensure that everything is running smoothly, a probe of the system can
be done through the validate link. If the validation fails then the war has
failed to install properly or some essential jars are missing. In such a
situation the documentation of the particular servlet container should be
consulted to find the problem. The following page is a successful
validation. Note the statement core axis libraries are present.
The axis web application also provides an interface to upload services. Once
a service is created according to the service specification (see the service
jar file format structure) that jar file can be uploaded using the upload
page.
The uploaded jar files will be stored in the default service directory. For
Axis2 this will be the <webapps>/axis2/WEB-INF/services directory. Once a
service is uploaded it will be instantly installed.
Since Axis2 supports hot deployment one can drop the service jar directly
through the file system to the above mentioned services directory and it
will also cause the service to be automatically installed without the
container being restarted.
To check the successful installation of a service available services link is
provided. The services and the operations of successfully installed services
will be displayed in the available services page.
To test run an uploaded service, instructions are provided in the samples
guide about running the sample clients. The presence of a service can be
checked by pointing the browser to
http://<host>:<port>/axis2/services/<service name>.
Samples
In this section of the user guide we will look at how to write and deploy
Web Services and how to write Web Service Clients using Axis2. All the user
guide samples are located at the "modules/samples" directory. So let's
explore the samples.
Note: Please note that the rest of this user guide assumes that the user has
downloaded the binary distribution of Axis2. If you have already downloaded
the source tree of Axis2 then please create the binary distribution by
simply using the maven command maven dist-bin This will create the
"axis2-M2-bin.zip" and "axis2-M2-bin.tar" in the "target/dist" directory.
Extract the zip or the tar ball to any directory in your machine and for the
explanations purposes we will name this as "Axis2Home".
Web Services Using Axis2
Before starting, please check that you have deployed the "axis2.war" in your
servlet container and that it is working properly.
MyService
First let's see how we can write a simple Web Service (MyService) and deploy
it. For this purpose we will create a Web Service with two operations as
follows.
public void ping(OMElement element){} //sample IN-ONLY operation, just
accept the OMElement and do some processing.
public OMElement echo(OMElement element){}//sample IN-OUT operation, accept
an OMElement and respond with another OMElement after processing
You can find our first example Web Service(MyService) in the
"Axis2Home/samples/userguide/src" directory under the userguide/example1
package. As you can see, the two operations are very simple and need no
explanations on what they are doing. So let's see how we can write the
deployment descriptors for the service and deploy it.
Axis2 uses "service.xml" to keep configurations for a Web Service. Each Web
Service deployed under Axis2 needs a "service.xml" containing the
configurations. "service.xml" for MyService will be as follows; we will see
what each parameter means later.
<service name="MyService">
<description>
This is a sample Web Service with two operations,echo and ping.
</description>
<parameter name="ServiceClass"
locked="xsd:false">userguide.example1.MyService</parameter>
<operation name="echo">
<messageReceiver
class="org.apache.axis.receivers.RawXMLINOutMessageRecevier"/>
</operation>
<operation name="ping">
<messageReceiver
class="org.apache.axis.receivers.RawXMLINOnlyMessageRecevier"/>
</operation>
</service>
As it can be seen, the first line of the "service.xml" gives the name of the
Web Service. This is used in the URL to the service as the service name.
Next comes the description and the service class. The next two xml tags
describe the operations that are available in this service with respective
message receivers. For the "echo" operation we have used a
RawXMLINOutMessageRecevier since it is an InOut operation. For the one way
operation, "ping" we have used RawXMLINOnlyMessageRecevier as the message
receiver.
Axis2 uses a ".aar" file as the deployment package for Web Services. So for
the MyService we will use "MyService.aar" with the "service.xml" packaged
under META-INF as shown in the following picture.
To create "MyService.aar" an user can first create a jar file containing all
the files necessary for the service and then rename the "jar" to "aar" so
that Axis2 understands it as a service archive. For this explanation we can
use the "MyService.aar" that is in the Axis2Home/samples/userguide
directory.
Since this is our first service we need to go through a few more steps
before we deploy the service. That is to create a directory named "services"
under "webapps/axis2/WEB-INF" of you servlet container. Deploying is just a
matter of dropping the ".aar" in to this directory and hence please copy the
"MyService.aar" into the service directory. Once these steps are completed,
please start the servlet container (if you have not already started it) and
check the link "List Available services" in the page
http://localhost:8080/axis2/index.jsp and see if MyService is deployed
properly. If everything is ok, you will see the following out put..
If you can see the above output then you have successfully deployed
MyService on Axis2. Now let's see how we can write a Web Service client to
use this service.
Web Service Clients Using Axis2
EchoBlockingClient
Axis2 provides the user with various invocation patterns for Web Services,
ranging from pure blocking single channel invocations to a non blocking dual
channel invocations. First let's see how we can write a client to invoke
"echo" operation of "MyService" using the simplest good old blocking
invocation. The client code that you need to write will be as follows.
try {
OMElement payload = ClientUtil.getEchoOMElement();
Call call = new Call();
call.setTo(targetEPR);
call.setTransportInfo(Constants.TRANSPORT_HTTP,
Constants.TRANSPORT_HTTP, false);
OMElement result = (OMElement) call.invokeBlocking("echo",
payload);
StringWriter writer = new StringWriter();
result.serializeWithCache(XMLOutputFactory.newInstance().createXMLStreamWrit
er(writer));
writer.flush();
System.out.println(writer.toString());
} catch (AxisFault axisFault) {
axisFault.printStackTrace();
} catch (XMLStreamException e) {
e.printStackTrace();
}
}
The green lines shows the set of operations that you need to perform
in-order to invoke a web service while the rest is used to create the
OMElement that needs to be sent and to display the response OMElement. To
test this clent you can use the "TestEchoBlockingClient.bat" that can be
found in the "Axis2Home/samples/userguide/src/userguide/clients/bin"
directory. The bat or .sh files show the required jars for one to write Web
Service clients using Axis2. So if you can see the response OMElement
printed in your command line (as shown below) then you have successfully
tested the client as well.
PingClient
In the Web Service "MyService" we had a IN-ONLY operation with the name
"ping" (see Web Services Using Axis2). So let's write a client to invoke
this operation as well. As earlier the client code will be as follows.
try {
OMElement payload = ClientUtil.getPingOMElement();
MessageSender msgSender = new MessageSender();
msgSender.setTo(targetEPR);
msgSender.setSenderTransport(Constants.TRANSPORT_HTTP);
msgSender.send("ping", payload);
} catch (AxisFault axisFault) {
axisFault.printStackTrace();
}
Since we are accessing a one way operation we can directly use the
"MessageSender" to invoke this operation. As it can be seen in the above
code , it is very straight forward to invoke this type of operation.
MessageSender will not block the invocation, hence it will return control
immediately back to the client. You can find the "TestPingClient.bat" in the
"Axis2Home/samples/userguide/src/userguide/clients/bin" directory and give
it a try.
Ok, we have invoked the two operations in our service, Are we done? No!,
there is a lot more to explore. Let's see some other ways to invoke the same
operations.
EchoNonBlockingClient
In the EchoBlockingClient once the "call.invokeBlocking("echo", payload);"
is called, the client is blocked till the operation is completed. This
behaviour is not desireable when there are many Web Service invocations to
be done in a single client application. A solution, would be to use a
Non-Blocking API to invoke web services. Axis2 provides a callback based
non-blocking API for users.
A sample client for this can be found under
"Axis2Home/samples/userguide/src/userguide/clients" with the name
EchoNonBlockingClient. If we consider the changes that the user may have to
do with respect to the "EchoBlockingClient" that we have already seen, it
will be as follows.
call.invokeNonBlocking("echo", payload, callback);
The invocaton accepts a callback object as a parameter. The Axis2 client API
provides an abstract Callback with the following methods.
public abstract void onComplete(AsyncResult result);
public abstract void reportError(Exception e);
public boolean isComplete() {}
The user is expected to implement the "onComplete " and "reportError "
methods of their extended call back class. Axis2 engine calls the onComplete
method once the Web Service response is received by the Axis2 Client API
(Call). This will eliminate the blocking nature of the Web Service
invocations and provides the user with the flexibility to use the Non
Blocking API for Web Service Clients.
To run the sample client ( EchoNonBlockingClient) you can simply use the
"TestEchoNonBlockingClient.bat" or "TestEchoNonBlockingClient.sh" files that
can be found in the "Axis2Home/samples/userguide/src/userguide/clients/bin"
directory.
EchoNonBlockingDualClient
The solution provided by the Non-Blocking API, for the Web Service
invocations which take a long time to complete, has one limitation. That is
due to the use of a single transport connection to invoke the Web Service
and to retrieve the response. In other words, the client API provides a non
blocking invocation mechanism for the users, but the request and the
response comes in a single transport connection (needs two way transport
like HTTP). Long running Web Service invocations or Web Service invocations
using One-Way transports (like SMTP) cannot be utilized by simply using a
non blocking invocation.
The trivial solution is to use separate transport connections (either
One-Way or Two-Way) for the request and response. The next problem that
needs to be solved iscorrelation (correlating the request and the response).
WS-Addressing provides a neat solution to the above by using <wsa:MessageID>
and <wsa:RelatesTo> headers. Axis2 provides support for an addressing based
correlation mechanism and a complying Client API to invoke Web Services with
two transport connections.
Users can select between Blocking or Non-Blocking APIs for the Web Service
client. By simply using a boolean flag, this same API can be used to invoke
web services(IN-OUT operations) using two separate transport connections.
Let's see how we can do it using an example. The following code fragement
shows how to invoke the same "echo" operation, using a Non-Blocking API with
two transport connections. The ultimate asynchrony!!
try {
OMElement payload = ClientUtil.getEchoOMElement();
Call call = new Call();
call.setTo(targetEPR);
//The boolean flag informs the axis2 engine to use two separate
transport connections
//to retrieve the response.
call.engageModule(new QName("addressing"));
call.setTransportInfo(Constants.TRANSPORT_HTTP,
Constants.TRANSPORT_HTTP, true);
//Callback to handle the response
Callback callback = new Callback() {
public void onComplete(AsyncResult result) {
try {
StringWriter writer = new StringWriter();
result.getResponseEnvelope().serializeWithCache(
XMLOutputFactory.newInstance().createXMLStreamWriter(writer));
writer.flush();
System.out.println(writer.toString());
} catch (XMLStreamException e) {
reportError(e);
}
}
public void reportError(Exception e) {
e.printStackTrace();
}
};
//Non-Blocking Invocation
call.invokeNonBlocking("echo", payload, callback);
//Wait till the callback receives the response.
while (!callback.isComplete()) {
Thread.sleep(1000);
}
} catch (AxisFault axisFault) {
axisFault.printStackTrace();
} catch (Exception ex) {
ex.printStackTrace();
}
The two changes that we need at the client side are shown in green. Since
our correlation mechanism is based on addressing, we need to first "engage"
the addressing module.
Before we run the sample client we need to perform one more step. As
mentioned earlier Axis2 uses an addressing based correlation mechanism and
hence we need to "engage" an addressing module in the server side as well.
According to the Axis2 architecture, the addressing module is deployed in
the "pre-dispatch" phase and hence "engaging" means simply adding the module
reference in the "server.xml" (NOT the "service.xml"). Please add the
following line to the "server.xml" that you can find in the
"/webapps/axis2WEB-INF" directory under the servlet container.
<module ref="addressing"/>
This will enable the addressing in the server side and now you can test the
"TestEchoNonBlockingDualClient" using the
"TestEchoNonBlockingDualClient.bat" or "TestEchoNonBlockingDualClient.sh"
provided under "Axis2Home/samples/userguide/src/userguide/clients/bin"
directory.
Note: Please note that once you change the "server.xml" you need to restart
the servlet container and make sure that marr
MyService with a Logging Module
Other Samples //Links to Google Samples
Modules
Tools
There are three sample programs, which are listed below, that will be
explained in this user guide and the relevant code can be found in the
source directory under ../modules/samples/src/java/userguide/sample1.
1. Case1: Echo Synchronous call.
2. Case2: Echo Synchronous call with a phased handler.
3. Case3: Echo Asynchronous call at the client side.
For the above three cases the sample will make use of two web
services(namely sample1, sample1WithHandler) and two client applications.
The diagram shows how the two services and the two client applications are
used to come up with the three cases mentioned above.
Axis2 M1 currently does not support data binding, thus in the samples the
operation that will be supported will be the echoing of xml without data
binding. The message that will be sent and echoed will be the following.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sample1="http://sample1.org/sample1">
<soapenv:Header/>
<soapenv:Body>
<sample1:echo>
<sample1:Text>Axis2 Echo String</sample1:Text>
</sample1:echo>
</soapenv:Body>
</soapenv:Envelope>
Sample1 can be located at the src/samples/userguide/sample1 directory and it
will have (or eventually have after the build) the following files.
Directory
File
Description
modules/samples
build.xml
Ant build file to compile, deploy and run the sample
modules/samples/src
EchoXML.java
Actual web service
SynchronousClient.java
Echo Synchronous client. The same client will be used for Echo Synchronous
call with a phased handler.
LoggingHandler.java
A handler that will log when it gets called.
AsynchronousClient.java
Echo client with client side Asynchronous call
ClientEchoCallbackHandler.java
The callback that will be called after the completion of the Asynchronous
call.
ClientUtil.java
A client Utility class that will generate a SOAPEnvelope.
modules/samples/conf
service.xml
The deployment descriptor for the service sample1.
service4withhandler.xml
The deployment descriptor for the service sample1WithHandler.
modules/samples/
build/services
sample1.jar
The deployable jar that is created after building the sample.
sample1WithHandler.jar
The deployable jar of the web service sample1WithHandler that is created
after building this sample.
modules/samples/
build/lib
sample1-all.jar
The jar that bundles the server side and client side code.
Pre-Conditions
Axis2 should be installed (see the Installation guide above). For simplicity
samples will assume the servlet container is Tomcat.
The AXIS_HOME environment variable be set. (Rationale: The compile time and
runtime libraries required in the classpath for the samples will be picked
up from the deployed Asix2.)
Apache Ant should be installed and should be available in the path. The
installation of Ant can be tested by simply typing ant at the command
prompt. Please refer to http://ant.apache.org/ <http://ant.apache.org/> .
Building the sample
The source files that are required to run the samples can be compiled and
packaged using the following ant task provided in the build.xml. Thus to
build the samples the user can open a command prompt and change directory to
modules\samples where the build.xml is located and type
>ant compile
or simply
>ant
The compilation will build three jar files; two of which are deployable
services and the other contains the compiled classes required for running
the samples.
* sample1.jar Deployable web service that will be used for Case1 and
Case3 (Packaged to modules/samples/build/services)
* sample1Withhandler.jar Deployable web service that will be used for
Case2 (Packaged to modules/samples/build/services)
* sample1-all.jar Compiled sources required for running the client
applications (Packaged to modules/samples/build/lib)
Once the sample is compiled once, all the required jar files for deploying
and running all three Cases of the sample will be compiled and packaged.
Sample1- Case1 : Echo Synchronous call
The sample1 - Case1: Echo synchronous call is intended to demonstrate the
synchronous web service call in Axis2 with both the client side and server
side running Axis2. In the next few steps the user will be walked through:
* Compiling and building a web service
* Deploying
* Running the client
It is assumed that the sample is already compiled. Please refer to "Building
Sample1" above.
Deploying the sample
Before deploying the sample, it is necessary to package the web service. The
actual web service implementation is the EchoXML.java and it is necessary to
write a service.xml so that the necessary statistics about the service will
be available to the Axis2 engine at runtime.
<service provider="org.apache.axis.providers.RawXMLProvider" style="rpc">
<java:implementation class="userguide.sample1.EchoXML"
xmlns:java="http://ws.apache.org/axis2/deployment/java"/>
<operation name="echo" qname="echo"/>
</service>
Above service.xml provides five required types of information.
* Provider Provider that will invoke the service.
* Style - Style of the operations of the service.
* Implementation Actual web service implementation class, in this case
EchoXML.
* Operation The operations that the web service implementation
supports or needs to expose.
Once the service.xml and the web service (in this case EchoXML) are ready,
it is necessary to package it into a jar. Actually with the above
>ant compile
The web service will get packaged into the build\services directory. Now the
user can deploy the service by one of the following methods. Since Axis2
supports the hot deployment of services, they can be deployed while the
container is up and running. Option 2 below actually requires the container
to be online.
>ant deploy
. Uploading the jar using the web interface provided in the http:// <host
:port>/ axis2 location. Please refer to the Installation guide for further
information.
. Manually copying the sample1.jar in build\services to the
AXIS_HOME\WEB-INF\services directory.
The service will be deployed with the packaged jar file name. If the jar
file is sample1.jar, the service will be deployed with the name sample1.
Point to note here is that the above ant task is going to deploy two
services
1. sample1 Required for this(Case1) and the EchoAsync Call
examples(Case1 and Case3).
2. sample1WithHandler required for Echo Synchronous call with a phased
handler(Case2).
If the servlet container is now running the user ca check to see if the
above services are deployed. Please refer to the installation guide for
further information on checking the deployed services.
Running the sample
The sample provides a simple synchronous client in the
SynchronousClient.java class. First the user must start the servlet
container and run the client by simply typing
>ant echo
in the command prompt. If all goes well the user will get the following
output where the program will print the request SOAP message and the
response SOAP message, which will be the same as the request message.
Sample1 - Case2: Echo Synchronous call with a phased handler.
This example will go one step forward from the example above and will deploy
a web service with a Logging handler. The client application will not
change, of course with an exception; the Endpoint Reference will be changed
to refer the new service Sample1WithHandler .
There is a Handler (LoggingHandler.java) that is introduced in this case and
it will basically log the fact that it got called. The code can be found in
LoggingHandler.java.
public void invoke(MessageContext msgContext) throws AxisFault {
log.info("Incoming message From "+msgContext.getTo().getAddress());
public void revoke(MessageContext msgContext){
log.info("Incoming message Revoked at the server
"+msgContext.getTo().getAddress() );
}
It is assumed that the sample is compiled. Please refer to "Building Sample"
above.
Deploying the sample
The implementation of the web service will be EchoXML, operation will be
echo and the provider will be org.apache.axis.providers.RawXMLProvider,
which are similar to that of the Echo Synchronous call . The difference is
that there will be a handler that will be added on the server side. For
further discussion refer to the following service.xml which will be used in
deploying the service.
<service provider="org.apache.axis.providers.RawXMLProvider" style="rpc">
<java:implementation class="userguide.sample1.EchoXML"
xmlns:java="http://ws.apache.org/axis2/deployment/java"/>
<inflow>
<handler name="LoggingHandler"
class="userguide.sample1.LoggingHandler">
<order phase="Logging"/>
</handler>
</inflow>
<outflow>
</outflow>
<faultflow>
<handler name="LoggingHandler"
class="userguide.sample1.LoggingHandler">
<order phase="Logging"/>
</handler>
</faultflow>
<operation name="echo" qname="echo"/>
</service>
In extra this service.xml has defined three elements
1. inflow
2. outflow
3. faultflow
These refer to the flows of the Axis2 server and further information of each
could be found in the Architecture Guide. Using these elements the deployer
can specify the handlers that should go into each flow. It can be further
explained by referring to the entries in the above service.xml. In the above
descriptor for the inflow and the faultflow there is a handler element that
is added. At deployment time, Axis2 will incorporate that handler to both
the inflow and the fault flow. Since there is no such entry for the outflow
no handler will be associated with the outflow.
The handler should specify the implementation class and the phase to which
it belongs. In this case the handler belongs to the Logging phase and this
phase name should be one of that is defined in the server.xml (not
service.xml). So this Logging phase should be defined there in the
server.xml which is located in AXIS_HOME/ axis2/WEB-INF. The following is
the default server.xml that is shipped with axis2.war.
<server name="AxisJava2.0">
<parameter name="hotdeployment" locked="xsd:false">true</parameter>
<parameter name="hotupdate" locked="xsd:false">true</parameter>
<transports>
<transport name="http"/>
<transport name="smtp"/>
</transports>
<phaseOrder>
<phase name="global"/>
<phase name="transport"/>
<phase name="Logging"/>
<phase name="module"/>
<phase name="service"/>
</phaseOrder>
</server>
Since the Logging phase is there in the default server.xml, the user who
runs these samples need not edit the server.xml at all.
Nevertheless deploying the sample is very easy and it can be done in any of
the three methods described in the Echo Synchronous call case. Infact had
the user typed
>ant deploy
and deployed the service, in the Echo Synchronous call case then this
service too will be deployed. The relevant jar file is
sample1WithHandler.jar and will be packed to the \build\services directory
if the user wants to deploy it manually or upload using the web application.
Running the sample
In this case the client side is similar to Echo Synchronous call and the
changes are happening in the server side. The same SynchronousClient.java
can be used to invoke the service by changing the command line arguments.
Refer to the ant target for details
<target name= "echo" depends= "compile" >
<java classname= "userguide.sample1.SynchronousClient">
<classpath refid= "classpath.runtimelibraries" />
<arg value= "8080" />
<arg value= "/axis2/services/sample1" />
</java>
</target>
<target name= "echoWithHandler" >
<java classname= "userguide.sample1.SynchronousClient" >
<classpath refid= "classpath.runtimelibraries" />
<arg value= "8080" />
<arg value= "/axis2/services/sample1WithHandler" />
</java>
</target>
To run the sample first the user must start the servlet container and run
the client by simply typing
>ant echoWithHandler
in the command prompt. If all goes well the user will get the following
output where the program will print the request SOAP message and the
response SOAP message, which will be same as the request message.
The service sample1withhandler will run its logging handler as it gets
called and it will log the call as the handler gets called in the inflow.
This logged information can be found in the server logs.
Sample1 - Case3: Echo Asynchronous call.
In this case the example focuses on calling a synchronous web service in an
asynchronous manner in the client side. If this example is compared with the
first example, which is Echo Synchronous call , the server side is identical
for both the cases. The difference will be in the web service client that
will be used.
In this case the client will make a web service call and it will register a
call back handler and sends the message out. The difference will be that the
client application that is doing the web service call will not hang until
the response. Rather it will get returned and once the response returns the
client will get notified by way of the registered callback (This is one of
the two methods by which this can be done in Axis 2.0. Refer to the Client
Api Tutorial for more information).
The callback handler that will be used is ClientEchoCallbackHandler.java and
the client program is AsynchronousClient.java.
It is assumed that the sample is already compiled. Please refer to the
"Building Sample1" above.
On the other hand Case3 uses the sample1 web service. Thus if the user has
already deployed the sample1 web service in Case1 above, then there is no
requirement of deploying again. Please refer to the deployment of Case 1 to
deploy the required service above.
Running the sample
The class to run is AsynchronousClient.java and it will intialise the web
service call. It will register a call back, in this case an instance of the
ClientEchoCallbackHandler and then the client will sleep to keep the thread
alive. Eventually when the response is received the callback handler will be
called(if all goes well the onComplete() method will be called), in this
case the ClientEchoCallbackHandler instance that was registered.
Inside the ClientEchoCallbackHandler it will print the received SOAP
message. Please refer to the code.
To run the client one can simply type
>ant echoAsync
and it will give the following output.
Writing your own Service and a client
Writing a New Service
Writing a new Web Service in Axis2-M1 requires you to do following steps
. Writing a new Web Service implementation class
Axis2 M1 does not support data binding and supports only the XML level
messaging. The default provider (do not worry about this if you do not know
what it is) only supports the java methods having the return type as
OMElement and only parameter as an OMElement.
The OMElement is a Streaming representation of XML Message Element
Information Item (Even though the user sees the OMElement as a tree based
DOM/JDOM like node, it reads the information from the stream only when its
absolutely required.). For more information refer the OM Tutorial .
public class <class-name>{
public OMElelemnt <method-name>(OMEllemnt){
<business logic>
}
.....
}
. Write the service.xml file
the following XML snippet is a very simple service.xml file.
<service provider="org.apache.axis.providers.RawXMLProvider" style="rpc">
<java:implementation class="<implementation-classname>"
xmlns:java="http://ws.apache.org/axis2/deployment/java"/>
<operation name="<method-name>" qname="<method-name>"/> ...
</service>
Here the org.apache.axis.providers.RawXMLProvider is the default provider
for the Apache Axis2 M1, the provider can be changed by specifying the
relevant parameter. Note that <method-name> should be replaced by the
relevant method name.
. Create an archive with the service.xml file and with class files
Compile the the Web Service implementation class and any other supporting
class. Archive them in to a jar file. Place the service.xml file in the
META-INF directory.
Name of the archive would be the name of the service. For example if the
service name is echo the archive should be echo.jar or echo.aar ( axis
archive)
. Deploy the archive in the Axis2
While the Axis2 is running copy the archive to the services folder in the
repository directory or use web upload method. (in the case of a Servlet
container this directory is axis/WEB-INF/services/). Axis will automatically
pick the archive and deploy the service.
To make this whole process user-friendly, Axis2 is shipped with a service
creation GUI tool. It is a "wizard interface" and also provides the facility
for users to automatically create a very simple service.xml as well. The
tool start script can be found in the bin directory.
Writing a Client for the Axis2-M1
Axis2 M1 supports HTTP transport only. Axis2-M1 supports the following
interaction patterns.
. Blocking invocation of type in-out (request/response)
. Non blocking invocation of type in-out (Without a separate Listener)
for more information about the interaction patterns, visit the Client API
Tutorial .
To invoke the web service, the user needs to build the the SOAPEnvelope. The
SOAPEnvelope can be built by the following code.
OMFactory fac = OMFactory.newInstance();
SOAPEnvelope envelope = fac.getDefaultEnvelope();
OMElement omElement = .....
envelope.getBody().addChild(omElement);
OMElement can be build using one of the following methods;
1. Create a OM by building the OM tree
fac.createOMElement(method, ns);
1. Create an OM Element from a XML file
2. XMLStreamReader parser =
XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));
3. OMXMLParserWrapper builder =
OMXMLBuilderFactory.createStAXOMBuilder(OMFactory.newInstance(), parser);
4. builder.getDocumentElement();
for more information on handling OM objects please read the OM Tutorial .
Synchronous Client
Invoking the synchronous web service call can be done with the following
code.
EndpointReference targetEPR = new
EndpointReference(AddressingConstants.WSA_TO, "http://127.0.0.1:" +
(EngineUtils.TESTING_PORT) + "/axis/services/echo" );
Call call = new Call();
call.setTo(targetEPR);
SOAPEnvelope responseEnv = call.sendReceive(envelope);
. The Endpoint Reference (EPR) is the To location of the web service.
. call.setTo() method registers the created EPR with the call object.
. call.sendRecieve() method invokes the web service at the location
specified by the EPR, using the given SOAP Message.
Asynchronous Client
Invoking the asynchronous web service call can be done with the following
code.
EndpointReference targetEPR = new
EndpointReference(AddressingConstants.WSA_TO, "http://127.0.0.1:" +
(EngineUtils.TESTING_PORT)+ "/axis/services/echo" );
Call call = new Call();
call.setTo(targetEPR);
call.setListenerTransport(Constants.TRANSPORT_HTTP, true );
SOAPEnvelope responseEnv = call.sendReceiveAsync(envelope,callback);
. The Endpoint Reference (EPR) is the To location of the web service.
. call.setTo() method registers the created EPR with the call object.
. call.sendRecieveAsync() method invokes the web service at the location
specified by the EPR using the given SOAP Message.
. The ListenerTransport is the type of the transport to be used. Axis2-M1
only supports http and the second parameter expresses if a separate listener
is to be started or not. Axis-M1 only supports the value true for this
parameter.
. callback is the Callback object that is used to handle the response. e.g.
Callback callback = new Callback() {
public void onComplete(AsyncResult result) {
//process the result
}
public void reportError(Exception e) {
//handler error
}
}