Axis2官网QuickStart Guide 理解

Axis2 Quick Start Guide

Axis2快速开始向导

The purpose of this guide is to get you started on creating services and clients using Axis2 as quickly as possible. We'll take a simple StockQuote Service and show you some of the different ways in which you can create and deploy it, as well as take a quick look at one or two utilities that come with Axis2. We'll then look at creating clients to access those services.

这个向导的目的是使你能够尽快的使用Axis2创建服务端和客户端.我们将会做一个简单的StockQuote Service并且向你展示一些你能创建和部署它的不同的方式，而且（未完成）

A Quick Setup Note:

The code for the document can be found in the extracted Standard Binary Distribution, more specifically at Axis2_HOME/samples/ inside the directories- quickstart, quickstartadb, quickstartaxiom, quickstartjibx and quickstartxmlbeans. (Consider getting it now as it will help you to follow along.) It includes Ant buildfiles (build.xml) that we'll refer to throughout the examples to make compilation easier.

（翻译未完成）

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.5). 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.

1.这里第一步是下载和安装jdk，如果不清楚怎么做，网上很多这种帖子。

2.下载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.

2.Generate the WSDL using the command:

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

这里需要使用dos命令cd到StockQuoteService这个类的根目录下否则找不到该类，运行这个命令之后会产生一个wsdl文件

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).

这里，服务的名字是StockQuoteService,它是在services.xml中被指定的，而且要和顶层的文件夹名称一致。编译之后的Java类文件被放置在最下面，它是基于包名的合适的地方。lib文件夹持有一些服务运行的特殊服务的JAR文件（这个例子中没有）除了已经放置在Axis2 WAR文件中的和servlet容器中的共有JAR文件夹。最后，META-INF文件夹包含一些额外的信息关于怎么合适的执行Axis2.services.xml文件定义了服务本身并且连接Java类。

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.

你可以以这种层次结构来部署一个服务并且复制它到 webapps/axis2/WEB-INF/services 的servlet引擎目录下（注意Axis2 WAR包必须被首先安装在Servlet引擎中）这被称作“exploded”格式。你也可以压缩你的文档到一个aar文件中，并且把这个aar文件放在webapps/axis2/WEB-INF/services 文件夹下。

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.

首先，下载并且解压Axis2 Standard Binary Distribution合适的版本。确保你设置的AXIS2_HOME环境变量跟这个目录是一直的。

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

让我们来看看一些创建客户端和服务端不同的方式。

Creating Services

In this section, we'll look at five ways to create a service based on the StockQuoteService class: deploying Plain Old Java Objects (POJO), building the service using AXIOM's OMElement, generating the service using Axis2 Databinding Framework (ADB), generating the service using XMLBeans, and generating the service using JiBX.



这里介绍了五种方式，不一一翻译了。

Creating Services

In this section, we'll look at five ways to create a service based on the StockQuoteService class: deploying Plain Old Java Objects (POJO), building the service using AXIOM's OMElement, generating the service using Axis2 Databinding Framework (ADB), generating the service using XMLBeans, and generating the service using JiBX.

Deploying POJOs

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

使用POJOs (Plain Old Java Objects)来部署服务，执行下面的步骤。

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

注意这里的目录结构，这里的services.xml是使用的一开始章节的。

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

请注意， 你可以从quickstart目录 通过键入 生成 WSDL文件 ：

ant generate.wsdl

However, creating StockQuoteService.wsdl is optional. It can be the version generated directly from the Java class, or a customized version of that file, and that services.xml is the same file referenced earlier in this document.

无论如何，创建StockQuoteService.wsdl是可选的。它可以从Java类直接生成，或者是一个文件的定制版本，并且services.xml文件时和之前的文档一样。

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:

如果你想以一种松散的目录格式部署这个服务,重命名这个类的目录为StockQuoteService，并且复制它到你的Servlet引擎中的webapps/axis2/WEB-INF/services目录下。否则，复制build/StockQuoteService.aar文件到 webapps/axis2/WEB-INF/services文件夹下。然后通过服务列表视图来检查确保服务已经被正确的部署了。

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

You can also checkout the WSDL at:

<a target=_blank href="http://localhost:8080/axis2/services/StockQuoteService?wsdl">http://localhost:8080/axis2/services/StockQuoteService?wsdl</a>

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

and then execute the first getPrice URL, you will see that the price has got updated.

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.