Axis2 基础

Introduction

Let's start with the service itself. We'll make it simple so you can see what is going on when we build and deploy the services. A StockQuoteService example seems to be mandatory in instances like this one, so let's use the following (see Code Listing 1).

Code Listing 1: The StockQuoteService class

package samples.quickstart.service.pojo;

import java.util.HashMap;

public class StockQuoteService {
    private HashMap map = new HashMap();

    public double getPrice(String symbol) {
        Double price = (Double) map.get(symbol);
        if(price != null){
            return price.doubleValue();
        }
        return 42.00;
    }

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

It will be a simple service with two possible calls. One of which is an in/out message, and the other is an in-only service. Ultimately, we'll package the service and deploy it in four different ways.

First, let's look at how this simple Java class corresponds to a service.

Getting Ready

Before we build anything using Axis2, we have to take care of a little housekeeping. First off, you'll need to get your environment ready for working with Axis2. Fortunately, it involves just a few simple steps:

1. Download and install Java (Minimum version is JDK1.4). Set the JAVA_HOME environment variable to the pathname of the directory into which you installed the JDK release.
2. Download Axis2 and extract it to a target directory.
3. Copy the axis2.war file to the webapps directory of your servlet engine.
4. Set the AXIS2_HOME environment variable to point to the target directory in step. Note that all of the scripts and build files Axis2 generates depend on this value, so don't skip this step! Linux users can alternatively run the setenv.sh file in the AXIS2_HOME/bin directory to set the AXIS2_HOME environment variable to the pathname of the extracted directory of Axis2.

In most cases, we're also going to need a WSDL file for our service. Axis2's Java2WSDL can be used to bootstrap a WSDL. To generate a WSDL file from a Java class, perform the following steps:

1. Create and compile the Java class.

   (Windows)
   %AXIS2_HOME%\bin\java2wsdl -cp . -cn samples.quickstart.service.pojo.StockQuoteService -of StockQuoteService.wsdl
   
   (Linux)
   $AXIS2_HOME/bin/java2wsdl -cp . -cn samples.quickstart.service.pojo.StockQuoteService -of StockQuoteService.wsdl
   

2. Generate the WSDL using the command:

Once you've generated the WSDL file, you can make the changes you need. For example, you might add custom faults or change the name of the generated elements. For example, this StockQuoteService.wsdl is in AXIS2_HOME/samples/quickstartadb/resources/META-INF folder, which we'll be using throughout the rest of this guide, replaces the generic parameters created by the generation process.

Axis2 Services

Before we build anything, it's helpful to understand what the finished product looks like.

The server side of Axis2 can be deployed on any Servlet engine, and has the following structure. Shown in Code Listing 2.

Code Listing 2: The Directory Structure of axis2.war

axis2-web 
META-INF
WEB-INF
    classes 
    conf
        axis2.xml 
    lib
        activation.jar
        ...
        xmlSchema.jar
    modules
        modules.list 
        addressing.mar
        ...
        soapmonitor.mar
    services
        services.list
        aservice.aar
        ...
        version.aar
    web.xml

Starting at the top, axis2-web is a collection of JSPs that make up the Axis2 administration application, through which you can perform any action such as adding services and engaging and dis-engaging modules. The WEB-INF directory contains the actual java classes and other support files to run any services deployed to the services directory.

The main file in all this is axis2.xml, which controls how the application deals with the received messages, determining whether Axis2 needs to apply any of the modules defined in the modules directory.

Services can be deployed as *.aar files, as you can see here, but their contents must be arranged in a specific way. For example, the structure of this service will be as follows:

- StockQuoteService
   - META-INF
     - services.xml
   - lib
   - samples
     - quickstart
       - service
         - pojo
           - StockQuoteService.class

Here, the name of the service is StockQuoteService, which is specified in the services.xml file and corresponds to the top-level folder of this service. Compiled Java classes are placed underneath this in their proper place based on the package name. The lib directory holds any service-specific JAR files needed for the service to run (none in this case) besides those already stored with the Axis2 WAR file and the servlet container's common JAR directories. Finally, the META-INF directory contains any additional information about the service that Axis2 needs to execute it properly. The services.xml file defines the service itself and links the Java class to it (See Code Listing 3).

Code Listing 3: The Service Definition File

<service name="StockQuoteService" scope="application">
    <description>
        Stock Quote Sample Service
    </description>
    <messageReceivers>
        <messageReceiver 
            mep="http://www.w3.org/2004/08/wsdl/in-only"
    class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/>
        <messageReceiver
            mep="http://www.w3.org/2004/08/wsdl/in-out"
    class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
    </messageReceivers>
    <parameter name="ServiceClass">
        samples.quickstart.service.pojo.StockQuoteService
    </parameter>
</service>

Here the service is defined, along with the relevant messageReceiver types for the different message exchange patterns.

The META-INF directory is also the location for any custom WSDL files you intend to include for this application.

You can deploy a service by simply taking this hierarchy of files and copying it to the webapps/axis2/WEB-INF/services directory of your servlet engine. (Note the Axis2 WAR file must be installed first in the servlet engine.) This is known as the "exploded" format. You can also compress your documents into an *.aar file, similar to a *.jar file, and place the *.aar file directly in the servlet engine's webapps/axis2/WEB-INF/services directory.

Now that you understand what we're trying to accomplish, we're almost ready to start building.

First, download and unzip the appropriate version of Axis2 Standard Binary Distribution. Make sure that you set the value of the AXIS2_HOME variable to match the location into which you extracted the contents of this release.

Let's look at some different ways to create clients and services.

 

Creating Services

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 -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 -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 {

    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

Creating Clients
To build a client using Axis Data Binding (ADB), execute the following 
steps.
Generate the client databings by typing the following in the 
Axis2_HOME/samples/quickstartadb directory:
%AXIS2_HOME%\bin\WSDL2Java -uri resources\META-INF\StockQuoteService.wsdl -p samples.quickstart.clients -d adb -s -o build\client

Else, simply type ant generate.client in the Axis2_HOME/samples/quickstartadb 
directory.
Next take a look at 
quickstartadb/src/samples/quickstart/clients/ADBClient.java, and see how it's 
defined in Code Listing 10.
Code Listing 10: The ADBClient Class
 
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");
        }
    }

}

This class creates a client stub using the Axis Data Bindings you created. 
Then it calls the getPrice and update operations on the Web service. The 
getPrice method operation creates the GetPrice payload and sets the symbol to 
ABC. It then sends the request and displays the current price. The update method 
creates an Update payload, setting the symbol to ABC and the price to 42.35.
Now build and run the client by typing ant run.client in the 
Axis2_HOME/samples/quickstartadb directory.
You should get the following as output:
42
price updated
42.35