Axis2 is one of the most widely-used web services stacks for Java, providing support for both basic SOAP message exchange and a variety of add-on technologies (such as WS-Security and WS-ReliableMessaging) through extension modules. JiBX data binding can be used directly in Axis2, so you can work with your generated OTA data model on both client and server code. You do need to generate some linkage code first, though, and you also need to replace the JiBX jars included in the Axis2 distribution (which use an older version of JiBX) with those from the current JiBX release.

Axis2 setup

You need to install Axis2, and update the JiBX jars included in the Axis2 distribution, before you can actually build the sample web service code. To do this, first download the Axis2 binary distribution and expand it to a directory on your system. Next, delete the jibx-* jars from the lib directory of the Axis2 distribution, and copy the corresponding jar files (jibx-bind.jar and jibx-run.jar) from the lib directory of your JiBX distribution into the Axis2 lib directory.

Once you've updated the JiBX jars, you can create an Axis2 war file for deployment to a web server such as Tomcat. To do this, open a console to the webapp directory of the Axis2 distribution and type ant to run the build.xml script. This creates an axis2.war file in the dist directory of the Axis2 installation. You can deploy this war file directly to any web server supporting the Java Servlet API (such as Apache Tomcat) to create an Axis2 server installation.

Note that if you're starting out with an Axis2 server installation already in place, you'll need to replace the jibx-run-#.jar file (where '#' is a version number) with the jibx-run.jar from your JiBX installation, and restart the server, before you can deploy the example web service .aar file as discussed below.

Building and running the code

After you've set up your Axis2 installation, you next need to configure the supplied web service build. First edit the build.properties file in the webservice/axis2 directory of your JiBX OTA distribution, and set the path to your Axis2 installation (using doubled '\' directory separator characters on Windows, or Unix/Linux-style '/' directory separator characters, as with the other .properties files). Next edit the air-service.properties file in the webservice/axis2/config directory to set the path to the directory containing the documents you want to use as response messages (which can just be the directory containing the OTA sample documents). If you're running Axis2 on a different host system, or on a port other than 8080, you also need to edit the air-client.properties file in the same directory and change the service endpoint address.

You can then open a console to the webservice/axis2 directory and type ant prepare. This runs a sequence of build steps, generating and compiling client and server linkage code for Axis2 and merging it with the supplied implementation code, then creating an AirService.aar Axis2 archive file which can be deployed to the Axis2 server installation (by copying it into the WEB-INF/services directory of the expanded Axis2 server war, or by uploading it through the Axis2 administration web page interface).

Once you've deployed the service to your Axis2 server installation, you can try it out using the supplied client by typing ant run on the console. As supplied, this sends several of the OTA sample request documents to the server, printing the response received for each request.

Implementation code

The Axis2 client implementation code is in the webservice/axis2/client/src directory. The Axis2 linkage code generated from the WSDL service definition provides an interface with methods matching those defined in the original Java code used to generate the WSDL, and the client just creates an instance of the Axis2 stub class and calls those methods on the stub to invoke server operations.

The Axis2 server implementation code is in the webservice/axis2/server/src directory. Similarly to the client side, the generated Axis2 linkage code calls out to an interface with methods matching those defined in the original Java code used to generate the WSDL. The server implementation code just implements that generated interface class.

For a more-detailed look at how Axis2 links in to data binding code for processing service messages, and a (somewhat dated, but still largely accurate) comparison of the main data binding frameworks supported by Axis2, see Java Web Services: Axis2 Data Binding, along with the newer Java Web services: JAXB and JAX-WS in Axis2, both by JiBX and JiBX/OTA primary developer Dennis Sosnoski.

Axis2 advantages

Axis2 has some significant advantages as a platform for developing OTA web services. It's stable and fairly solid, and allows for plug-in extension modules to implement add-on technologies such as WS-Security (for details of WS-Security and it's use with Axis2 see Java Web services: Axis2 WS-Security basics and Java Web services: Axis2 WS-Security signing and encryption, along with other articles in the Java Web Services series by JiBX and JiBX/OTA primary developer Dennis Sosnoski).

WS-Security isn't necessary for many web service applications. When clients connect directly to servers (rather than going through intermediaries), SSL or TLS can instead be used to keep data secure, with much lower overhead than WS-Security. But in cases where WS-Security is needed (including when messages are routed through untrusted intermediary services, or when digital signatures are needed for audit trails), Axis2 allows you to easily use JiBX data binding to convert documents to and from Java object structures.