Axis2 Quick Start Guide

Deploying POJOs

To deploy the service using POJOs (Plain Old Java Objects), execute the following steps.

Note the directory structure contained at AXIS2_HOME/samples/quickstart (the services.xml file is from the first section of this guide):

- quickstart
   - README.txt
   - build.xml
   - resources
     - META-INF
       - services.xml
   - src
     - samples
       - quickstart
         - service
           - pojo
             - StockQuoteService.java

Note that you can generate a WSDL from the quickstart directory by typing:

ant generate.wsdl

Now build the project by typing ant generate.service in the quickstart directory, which creates the following directory structure:

- quickstart/build/classes
   - META-INF
     - services.xml
   - samples
     - quickstart
       - service
         - pojo
           - StockQuoteService.class

If you want to deploy the service in an exploded directory format, rename the classes directory to StockQuoteService, and copy it to the webapps/axis2/WEB-INF/services directory in your servlet engine. Otherwise, copy the build/StockQuoteService.aar file to the webapps/axis2/WEB-INF/services directory in your servlet engine. Then check to make sure that the service has been properly deployed by viewing the list of services at:

http://localhost:8080/axis2/services/listServices

You can also checkout the WSDL at:

http://localhost:8080/axis2/services/StockQuoteService?wsdl

And the schema at:

http://localhost:8080/axis2/services/StockQuoteService?xsd

Once the URLs are working, quickly test the service. Try pointing your browser to the following URL:

http://localhost:8080/axis2/services/StockQuoteService/getPrice?symbol=IBM

You will get the following response:

<ns:getPriceResponse xmlns:ns="http://pojo.service.quickstart.samples/xsd"><ns:return>42</ns:return></ns:getPriceResponse>

If you invoke the update method as,

http://localhost:8080/axis2/services/StockQuoteService/update?symbol=IBM&price=100

Building the Service using AXIOM

To build a service "from scratch" using AXIOM, execute the following steps.

Note the directory structure contained at /samples/quickstartaxiom:

- quickstartaxiom
   - README.txt
   - build.xml
   - resources
     - META-INF
       - services.xml
       - StockQuoteService.wsdl
   - src
     - samples
       - quickstart
         - service
           - axiom
             - StockQuoteService.java
         - clients
           - AXIOMClient.java

Since AXIOM is a little different, you're going to need a different services.xml file from the one used for POJO. Define it, as shown in Code Listing 4.

Code Listing 4: The Service Definition File.

<service name="StockQuoteService" scope="application">
    <description>
        Stock Quote Service
    </description>
    <operation name="getPrice">
        <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
    </operation>
    <operation name="update">
        <messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/>
    </operation>
    <parameter name="ServiceClass">samples.quickstart.service.axiom.StockQuoteService</parameter>
</service>

Note that it's almost the same, except that the operations are explicitly defined in the service.xml file, and the MessageReceivers are now RawXML.

Now, the above referenced StockQuoteService.java class, a plain Java class that uses classes from the Axis2 libraries, is defined as shown in Code Listing 5.

Code Listing 5: The StockQuoteService Class using AXIOM

package samples.quickstart.service.axiom;

import javax.xml.stream.XMLStreamException;
import org.apache.axiom.om.OMAbstractFactory;
import org.apache.axiom.om.OMElement;
import org.apache.axiom.om.OMFactory;
import org.apache.axiom.om.OMNamespace;

import java.util.HashMap;
public class StockQuoteService {
    private HashMap map = new HashMap();

    public OMElement getPrice(OMElement element) throws XMLStreamException {
        element.build();
        element.detach();

        OMElement symbolElement = element.getFirstElement();
        String symbol = symbolElement.getText();

        String returnText = "42";
        Double price = (Double) map.get(symbol);
        if(price != null){
            returnText  = "" + price.doubleValue();
        }
        OMFactory fac = OMAbstractFactory.getOMFactory();
        OMNamespace omNs =
            fac.createOMNamespace("http://axiom.service.quickstart.samples/xsd", "tns");
        OMElement method = fac.createOMElement("getPriceResponse", omNs);
        OMElement value = fac.createOMElement("price", omNs);
        value.addChild(fac.createOMText(value, returnText));
        method.addChild(value);
        return method;
    }

    public void update(OMElement element) throws XMLStreamException {
        element.build();
        element.detach();

        OMElement symbolElement = element.getFirstElement();
        String symbol = symbolElement.getText();

        OMElement priceElement = (OMElement)symbolElement.getNextOMSibling();
        String price = priceElement.getText();

        map.put(symbol, new Double(price));
    }
}

Axis2 uses AXIOM, or the AXIs Object Model, a DOM (Document Object Model)-like structure that is based on the StAX API (Streaming API for XML). Methods that act as services must take as their argument an OMElement, which represents an XML element that happens, in this case, to be the payload of the incoming SOAP message. Method getPrice(OMElement), for example, extracts the contents of the first child of the payload element, which corresponds to the stock symbol, and uses this to look up the current price of the stock. Unless this is an "in only" service, these methods must return an OMElement, because that becomes the payload of the return SOAP message.

Now build the project by typing ant generate.service in the Axis2_HOME/samples/quickstartaxiom directory.

Place the StockQuoteService.aar file in the webapps/axis2/WEB-INF/services directory of the servlet engine, and check to make sure that the service has been properly deployed by viewing the list of services at,

http://localhost:8080/axis2/services/listServices

You can also check the custom WSDL at,

http://localhost:8080/axis2/services/StockQuoteService?wsdl

and the schema at,

http://localhost:8080/axis2/services/StockQuoteService?xsd

Generating the Service using ADB

To generate and deploy the service using the Axis2 Databinding Framework (ADB), execute the following steps.

Generate the skeleton using the WSDL2Java utility by typing the following in the Axis2_HOME/samples/quickstartadb directory:

(Windows)
%AXIS2_HOME%\bin\wsdl2java.bat -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.service.adb -d adb -s -ss -sd -ssi -o build\service

(Linux)
$AXIS2_HOME/bin/wsdl2java.sh -uri resources/META-INF/StockQuoteService.wsdl -p samples.quickstart.service.adb -d adb -s -ss -sd -ssi -o build/service

Else, simply type ant generate.service in the Axis2_HOME/samples/quickstartadb directory.

The option -d adb specifies Axis Data Binding (ADB). The -s switch specifies synchronous or blocking calls only. The -ss switch creates the server side code (skeleton and related files). The -sd switch creates a service descriptor (services.xml file). The -ssi switch creates an interface for the service skeleton. The service files should now be located at build/service.

If you generated the code by using WSDL2Java directly, next you have to modify the generated skeleton to implement the service (if you used "ant generate.service", a completed skeleton will be copied over the generated one automatically).

Open the build/service/src/samples/quickstart/adb/service/StockQuoteServiceSkeleton.java file and modify it to add the functionality of your service to the generated methods; shown in Code Listing 6.

Code Listing 6: Defining the Service Skeleton File

package samples.quickstart.service.adb;

import samples.quickstart.service.adb.xsd.GetPriceResponse;
import samples.quickstart.service.adb.xsd.Update;
import samples.quickstart.service.adb.xsd.GetPrice;

import java.util.HashMap;

public class StockQuoteServiceSkeleton implements StockQuoteServiceSkeletonInterface {

    private static HashMap map;

    static{ map = new HashMap(); }

    public void update(Update param0) {
        map.put(param0.getSymbol(), new Double(param0.getPrice()));
    }

    public GetPriceResponse getPrice(GetPrice param1) {
        Double price = (Double) map.get(param1.getSymbol());
        double ret = 42;
        if(price != null){
            ret = price.doubleValue();
        }
        GetPriceResponse res =
                new GetPriceResponse();
        res.set_return(ret);
        return res;
    }
}

Now you can build the project by typing the following command in the build/service directory:

ant jar.server

If all goes well, you should see the BUILD SUCCESSFUL message in your window, and the StockQuoteService.aar file in the build/service/build/lib directory. Copy this file to the webapps/axis2/WEB-INF/services directory of the servlet engine.

You can check to make sure that the service has been properly deployed by viewing the list of services at,

http://localhost:8080/axis2/services/listServices

You can also check the custom WSDL at,

http://localhost:8080/axis2/services/StockQuoteService?wsdl

and the schema at,

http://localhost:8080/axis2/services/StockQuoteService?xsd

Generating the Service using XMLBeans

To generate a service using XMLBeans, execute the following steps.

Generate the skeleton using the WSDL2Java utility by typing the following in the Axis2_HOME/samples/quickstartxmlbeans directory.

%AXIS2_HOME%\bin\wsdl2java.bat -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.service.xmlbeans -d xmlbeans -s -ss -sd -ssi -o build\service

Else simply type ant generate.service in the Axis2_HOME/samples/quickstartxmlbeans directory.

The option -d xmlbeans specifies XML Beans data binding. The -s switch specifies synchronous or blocking calls only. The -ss switch creates the server side code (skeleton and related files). The -sd switch creates a service descriptor (services.xml file). The -ssi switch creates an interface for the service skeleton. The service files should now be located at build/service.

If you generated the code by using WSDL2Java directly, next you have to modify the generated skeleton to implement the service (if you used "ant generate.service", a completed skeleton will be copied over the generated one automatically).

Next open the build/service/src/samples/quickstart/service/xmlbeans/StockQuoteServiceSkeleton.java file and modify it to add the functionality of your service to the generated methods (see Code Listing 7).

Code Listing 7: Defining the Service Skeleton

package samples.quickstart.service.xmlbeans;

import samples.quickstart.service.xmlbeans.xsd.GetPriceDocument;
import samples.quickstart.service.xmlbeans.xsd.GetPriceResponseDocument;
import samples.quickstart.service.xmlbeans.xsd.UpdateDocument;

import java.util.HashMap;

public class StockQuoteServiceSkeleton implements StockQuoteServiceSkeletonInterface {

    private static HashMap map;

    static{ map = new HashMap(); }

    public void update(UpdateDocument param0) {
        map.put(param0.getUpdate().getSymbol(), new Double(param0.getUpdate().getPrice()));
    }

    public GetPriceResponseDocument getPrice(GetPriceDocument param1) {
        Double price = (Double) map.get(param1.getGetPrice().getSymbol());
        double ret = 42;
        if(price != null){
            ret = price.doubleValue();
        }
        System.err.println();
        GetPriceResponseDocument resDoc =
                GetPriceResponseDocument.Factory.newInstance();
        GetPriceResponseDocument.GetPriceResponse res =
                resDoc.addNewGetPriceResponse();
        res.setReturn(ret);
        return resDoc;
    }
}

Build the project by typing the following command in the build/service directory, which contains the build.xml file:

ant jar.server

If all goes well, you should see the BUILD SUCCESSFUL message in your window, and the StockQuoteService.aar file in the newly created build/service/build/lib directory. Copy this file to the webapps/axis2/WEB-INF/services directory of the servlet engine.

You can check to make sure that the service has been properly deployed by viewing the list of services at,

http://localhost:8080/axis2/services/listServices

You can also check the custom WSDL at,

http://localhost:8080/axis2/services/StockQuoteService?wsdl

and the schema at,

http://localhost:8080/axis2/services/StockQuoteService?xsd

Generating the Service using JiBX

To generate and deploy the service using JiBX data binding, execute the following steps.

Generate the skeleton using the WSDL2Java utility by typing the following at a console in the Axis2_HOME/samples/quickstartjibx directory:

%AXIS2_HOME%\bin\wsdl2java.bat -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.service.jibx -d jibx -s -ss -sd -ssi -uw -o build\service

Else, simply type "ant generate.service" in the Axis2_HOME/samples/quickstartjibx directory.

The option -d jibx specifies JiBX data binding. The -s switch specifies synchronous or blocking calls only. The -ss switch creates the server side code (skeleton and related files). The -sd switch creates a service descriptor (services.xml file). The -ssi switch creates an interface for the service skeleton. The -uw switch unwraps the parameters passed to and from the service operations in order to create a more natural programming interface.

After running WSDL2Java, the service files should be located at build/service. If you generated the code by using WSDL2Java directly, you need to modify the generated skeleton to implement the service (if you used "ant generate.service" a completed skeleton will be copied over the generated one automatically). Open the build/service/src/samples/quickstart/service/jibx/StockQuoteServiceSkeleton.java file and modify it to add the functionality of your service to the generated methods, as shown in Code Listing 8.

Code Listing 8: Defining the Service Skeleton File

package samples.quickstart.service.jibx;

import java.util.HashMap;

public class StockQuoteServiceSkeleton implements StockQuoteServiceSkeletonInterface {
    private HashMap map = new HashMap();

    public void update(String symbol, Double price) {
        map.put(symbol, price);
    }

    public Double getPrice(String symbol) {
        Double ret = (Double) map.get(symbol);
        if (ret == null) {
            ret = new Double(42.0);
        }
        return ret;
    }
}

Now you can build the project by typing the following command in the build/service directory:

ant jar.server

If all goes well, you should see the BUILD SUCCESSFUL message in your window, and the StockQuoteService.aar file in the build/service/build/lib directory. Copy this file to the webapps/axis2/WEB-INF/services directory of the servlet engine.

You can check to make sure that the service has been properly deployed by viewing the list of services at,

http://localhost:8080/axis2/services/listServices

You can also check the custom WSDL at,

http://localhost:8080/axis2/services/StockQuoteService?wsdl

and the schema at,

http://localhost:8080/axis2/services/StockQuoteService?xsd

For more information on using JiBX with Axis2, see the JiBX code generation integration details.

Creating Clients

In this section, we'll look at four ways to create clients based on the StockQuoteService class: building an AXIOM based client, generating a client using Axis2 Databinding Framework (ADB), generating a client using XMLBeans, and generating a client using JiBX.

- quickstartaxiom
   - README.txt
   - build.xml
   - resources
     - META-INF
       - services.xml
       - StockQuoteService.wsdl
   - src
     - samples
       - quickstart
         - service
           - axiom
             - StockQuoteService.java
         - clients
           - AXIOMClient.java

package samples.quickstart.clients;

import org.apache.axiom.om.OMAbstractFactory;
import org.apache.axiom.om.OMElement;
import org.apache.axiom.om.OMFactory;
import org.apache.axiom.om.OMNamespace;
import org.apache.axis2.Constants;
import org.apache.axis2.addressing.EndpointReference;
import org.apache.axis2.client.Options;
import org.apache.axis2.client.ServiceClient;

public class AXIOMClient {

    private static EndpointReference targetEPR = 
        new EndpointReference("http://localhost:8080/axis2/services/StockQuoteService");

    public static OMElement getPricePayload(String symbol) {
        OMFactory fac = OMAbstractFactory.getOMFactory();
        OMNamespace omNs = fac.createOMNamespace("http://axiom.service.quickstart.samples/xsd", "tns");

        OMElement method = fac.createOMElement("getPrice", omNs);
        OMElement value = fac.createOMElement("symbol", omNs);
        value.addChild(fac.createOMText(value, symbol));
        method.addChild(value);
        return method;
    }

    public static OMElement updatePayload(String symbol, double price) {
        OMFactory fac = OMAbstractFactory.getOMFactory();
        OMNamespace omNs = fac.createOMNamespace("http://axiom.service.quickstart.samples/xsd", "tns");

        OMElement method = fac.createOMElement("update", omNs);

        OMElement value1 = fac.createOMElement("symbol", omNs);
        value1.addChild(fac.createOMText(value1, symbol));
        method.addChild(value1);

        OMElement value2 = fac.createOMElement("price", omNs);
        value2.addChild(fac.createOMText(value2,
                                         Double.toString(price)));
        method.addChild(value2);
        return method;
    }

    public static void main(String[] args) {
        try {
            OMElement getPricePayload = getPricePayload("WSO");
            OMElement updatePayload = updatePayload("WSO", 123.42);
            Options options = new Options();
            options.setTo(targetEPR);
            options.setTransportInProtocol(Constants.TRANSPORT_HTTP);

            ServiceClient sender = new ServiceClient();
            sender.setOptions(options);

            sender.fireAndForget(updatePayload);
            System.err.println("price updated");
            OMElement result = sender.sendReceive(getPricePayload);

            String response = result.getFirstElement().getText();
            System.err.println("Current price of WSO: " + response);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    
}

done
Current price of WSO: 123.42

%AXIS2_HOME%\bin\wsdl2java.bat -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.clients -d adb -s -o build\client

package samples.quickstart.clients;

import samples.quickstart.service.adb.StockQuoteServiceStub;

public class ADBClient{
    public static void main(java.lang.String args[]){
        try{
            StockQuoteServiceStub stub =
                new StockQuoteServiceStub
                ("http://localhost:8080/axis2/services/StockQuoteService");

            getPrice(stub);
            update(stub);
            getPrice(stub);

        } catch(Exception e){
            e.printStackTrace();
            System.err.println("\n\n\n");
        }
    }

    /* fire and forget */
    public static void update(StockQuoteServiceStub stub){
        try{
            StockQuoteServiceStub.Update req = new StockQuoteServiceStub.Update();
            req.setSymbol ("ABC");
            req.setPrice (42.35);

            stub.update(req);
            System.err.println("price updated");
        } catch(Exception e){
            e.printStackTrace();
            System.err.println("\n\n\n");
        }
    }

    /* two way call/receive */
    public static void getPrice(StockQuoteServiceStub stub){
        try{
            StockQuoteServiceStub.GetPrice req = new StockQuoteServiceStub.GetPrice();

            req.setSymbol("ABC");

            StockQuoteServiceStub.GetPriceResponse res =
                stub.getPrice(req);

            System.err.println(res.get_return());
        } catch(Exception e){
            e.printStackTrace();
            System.err.println("\n\n\n");
        }
    }

}

42
price updated
42.35

%AXIS2_HOME%\bin\wsdl2java.bat -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.service.xmlbeans -d xmlbeans -s -o build\client

package samples.quickstart.clients;

import samples.quickstart.service.xmlbeans.StockQuoteServiceStub;
import samples.quickstart.service.xmlbeans.xsd.GetPriceDocument;
import samples.quickstart.service.xmlbeans.xsd.GetPriceResponseDocument;
import samples.quickstart.service.xmlbeans.xsd.UpdateDocument;

public class XMLBEANSClient{

    public static void main(java.lang.String args[]){
        try{
            StockQuoteServiceStub stub =
                new StockQuoteServiceStub
                ("http://localhost:8080/axis2/services/StockQuoteService");

            getPrice(stub);
            update(stub);
            getPrice(stub);

        } catch(Exception e){
            e.printStackTrace();
            System.err.println("\n\n\n");
        }
    }

    /* fire and forget */
    public static void update(StockQuoteServiceStub stub){
        try{
            UpdateDocument reqDoc = UpdateDocument.Factory.newInstance();
            UpdateDocument.Update req = reqDoc.addNewUpdate();
            req.setSymbol ("BCD");
            req.setPrice (42.32);

            stub.update(reqDoc);
            System.err.println("price updated");
        } catch(Exception e){
            e.printStackTrace();
            System.err.println("\n\n\n");
        }
    }

    /* two way call/receive */
    public static void getPrice(StockQuoteServiceStub stub){
        try{
            GetPriceDocument reqDoc = GetPriceDocument.Factory.newInstance();
            GetPriceDocument.GetPrice req = reqDoc.addNewGetPrice();
            req.setSymbol("BCD");

            GetPriceResponseDocument res =
                stub.getPrice(reqDoc);

            System.err.println(res.getGetPriceResponse().getReturn());
        } catch(Exception e){
            e.printStackTrace();
            System.err.println("\n\n\n");
        }
    }
}

42
price updated
42.32

%AXIS2_HOME%\bin\wsdl2java.bat -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.clients -d jibx -s -uw -o build\client

package samples.quickstart.clients;

import samples.quickstart.service.jibx.StockQuoteServiceStub;

public class JiBXClient{
    public static void main(java.lang.String args[]){
        try{
            StockQuoteServiceStub stub =
                new StockQuoteServiceStub
                ("http://localhost:8080/axis2/services/StockQuoteService");

            getPrice(stub);
            update(stub);
            getPrice(stub);

        } catch(Exception e){
            e.printStackTrace();
            System.err.println("\n\n\n");
        }
    }

    /* fire and forget */
    public static void update(StockQuoteServiceStub stub){
        try{
            stub.update("CDE", new Double(42.35));
            System.err.println("price updated");
        } catch(Exception e){
            e.printStackTrace();
            System.err.println("\n\n\n");
        }
    }

    /* two way call/receive */
    public static void getPrice(StockQuoteServiceStub stub){
        try{
            System.err.println(stub.getPrice("CDE"));
        } catch(Exception e){
            e.printStackTrace();
            System.err.println("\n\n\n");
        }
    }

}

42
price updated
42.35