Steps to use web service via Eclipse and Axis 2 1.6 十一步轻松创建WebService

Part I Setup

第一部分 环境搭建

Step 1. Install Axis2 environment to c:\axis\ and run it.

第一步 安装Axis2环境并运行

This step is simple. Just download and unzip the "Standard Binary Distribution" into c:\axis and run c:\axis\bin\axis2server.bat

第一步很简单，只要下载Axis2的发布包并解压在某个位置，然后用命令行运行bin下的axis2server.bat就可以了。

The Axis server is based on Tomcat server. We can open http://localhost:8080 to the axis server.

Axis服务器就是一个配置好的Tomcat服务器，运行之后打开localhost:8080就可以看见WebService的页面。

There may be a port conflict. Please solve it by yourself.

关于端口号可能与既存的端口有冲突，请自行解决。

Step 2. Install Axis plugin to Eclipse

第二步 安装Axis插件

This step is a little bit troublesome. Because we need to download the plugin from Apache website manually.

第二步有点麻烦，因为需要手动从Apache的网站上下载插件包。

And if you don't use the "Install New Software" feature of Eclipse. It sometimes cannot startup the plugin correctly.

并且如果不使用Eclipse的安装新软件的功能，有时候插件还无法正确启动。

So, if you failed to install it by other ways, please open the text file c:\eclipse\configuration\org.eclipse.equinox.simpleconfigurator\bundles.info and add this "org.apache.axis2.eclipse.codegen.plugin,1.6.2,plugins/org.apache.axis2.eclipse.codegen.plugin_1.6.2.jar,4,false" in a convient place inside the file.

所以说，如果用其他途径安装插件失败，请尝试打开c:\eclipse\configuration\org.eclipse.equinox.simpleconfigurator\bundles.info这个文件，并将上述配置行添加到合适位置。

And then restart Eclipse, it should be okay. You will see a new wizard named Axis2 Code Generator.

然后重启Eclipse，插件就该安装好了，在新建项目中可以看到一个新的选项Axis2 Code Generator。

Part II Implementation

第二部分 实现

Step 3. Create and edit WSDL, then validate it.

第三步 创建、编辑和验证WSDL

Create a WSDL using WSDL wizard in base directory of project.

使用WSDL向导在工程根目录中创建一个WSDL。

The WSDL is the core of a web service. It consists of elements, types, target namespace, port type, ports and binding.

WSDL是Web Service的核心，由下列部分组成：

Elements and Types: This part can be defined in another xsd file and imported. 这部分可以由另一个XSD文件定义，并导入到该WSDL中。

Target Namespace: e.g. http://sample.com/ss => com.sample.ss

Port Type: A port type contains one or more operations. Every operation likes a method which client can call it remotely. We can define input, output and fault in an operation. 一个端口类型可包含多个操作，每个操作就像一个函数方法，可由客户端远程调用。可以在一个操作中定义输入、输出和错误。

Ports: A service may contain one or more ports. A port has a name and an endpoint. The endpoint is just a url. People can access it as a web service. 一个服务或包含多个端口，端口包括一个名称和一个终端点，终端点就是一个URL，用于提供Web Service。

Binding: There is no manual editing on this part. 该部分无需手动编辑。But the soap action needs to be modified to as the same as operation. 但是Soap Action需要改成和operation的名字一样。

Step 4. Use Axis2 Codegen Wizard (Axis plugin) to generate Java code.

第三步 使用向导生成Java代码

Step 4.1 Generate Server Side Code 生成服务器代码

打开Axis2 Codegen向导，按照如下描述进行。

Open the Axis2 Codegen Wizard and select "Generate Java source code from a WSDL file". Select the WSDL in base directory.

In Options screen, select Codegen option as "custom" and check "Generate server side code", "Generate a default services.xml" and "Generate an Interface for Skeleton".

In Output screen, select "Browse  and select a project on current eclipse workspace" and choose the base directory of project as "Output path". Check "Add Axis2 libraries to the codegen resulted project" and find out Axis home (c:\axis here). Then click "Check Libs...".

Step 4.2 Generate Client Side Code

打开Axis2 Codegen向导，按照如下描述进行。

Open the Axis2 Codegen Wizard and select "Generate Java source code from a WSDL file". Select the WSDL in base directory.

In Options screen, select Codegen option as "custom" and check "Generate client side code" and "Generate both sync and async".

In Output screen, as well as Step 4.1.

Finally, we can see some java code files are generated by this plugin.

最后，可以看到插件生成的代码。

These steps can be processed by Ant automatically. We will do it in Step 9.

这些步骤可以由Ant自动执行，参见第九步。

Step 5. Add all dependency jars of Axis2 from lib.

第五步 添加依赖项

After previous step, java code files are generated. But there may be some errors caused by dependecy.

上一步执行之后，代码文件生成成功，但是或许会有一些错误，因为缺少依赖项。

We need to add all Axis 2 jars in lib folder. The lib folder is added in previous step automatically.

需要的依赖项都在lib文件夹中，这个文件夹会在上一步中自动生成。

For advanced developer, it is possible that not all libraries of Axis2 are required. But here, we need simple steps.

对于高端开发者，可能不会用到所有的依赖项，但此处一切从简。

Step 6. Create link folder "out" to output web service to Axis2 server in c:\axis\repository\services\xxx

第六步 创建外部链接以自动编译代码到服务器

We can output compiled class files to Axis server directly which means auto-deploy a web service.

可以直接将代码编译到Axis服务器上，这样依赖就相当于自动部署了。

We only need to link the output folder to the web service folder in Axis server and then set it as "Default output folder" in Source tab of Java Builder Path screen.

只需要将输出文件夹与服务器的某个文件夹链接起来，并将其设为默认的编译输出文件夹就可以了。

Linking folder: Create a new folder in base directory of project, click "Advanced", check "Link to folder in the file system" and then choose the web service folder in Axis server c:\axis\repository\services\XYZService.创建一个新的文件夹，在高级选项中，选择一个Axis服务器上的文件夹 就可以了。

Step 7.Change Axis2 server config element "hotupdate" to true in c:\axis\conf\axis2.xml

第七步 更改Axis服务器配置以自动重新部署

After this step, we don't need to restart Axis server after redeployment.

执行完该步骤，便无需再修改之后重启服务器。

Step 8. Create a debug batch to run Axis server in debug mode. Listen on port 8000.

第八步 为Axis服务器配置启动模式

Create debug.bat in c:\axis\bin\ as follow:

set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
axis2server.bat

The debug port is 8000 as default. There may be a conflict to it. Please solve this by yourself.
8000是默认端口，可能存在端口冲突，请自行解决。

Run debug.bat in command line and then we can debug it in eclipse thru http://localhost:8080

直接在命令行运行debug.bat，而不必在运行原来的axis2server.bat，便可以在Eclipse中调试。

Step 9. Create and edit build.xml to generate code (both service side and client side) automatically.

第九步 创建并编辑Ant文件以自动生成代码

The ant file build.xml will be generated by Axis Code Generator automatically. Thru changing it, we can generate code automatically.

Axis Code Generator向导会自动生成Ant文件，只需将其略微修改，就可以自动生成代码了。

Open Properties tab in Preferences->Ant->Runtime screen and Add Property as env.AXIS2_HOME (name) and c:\axis (value).

打开Preferences为Ant运行时添加env.AXIS2_HOME属性为c:\axis。

First, we need add some settings and element to build.xml.

按照下列描述修改build.xml文件。

Add following element before "target" elements in build.xml.

<taskdef name="wsdl2code" classname="org.apache.axis2.tool.ant.AntCodegenTask" classpathref="axis2.class.path" />

Step 9.1 Generate Server Side Code Automatically

Add following element to "target" elements in build.xml.

<target name="generate-service">
  <wsdl2code wsdlfilename="${name}.wsdl" serverside="true" generateservicexml="true" skipbuildxml="true"
             serversideinterface="true" namespacetopackages="http://sample.com/ss=com.sample.ss"
             targetsourcefolderlocation="src" targetresourcesfolderlocation="src/META-INF" overwrite="true" />
  <replaceregexp file="src/META-INF/services.xml" match="${name}Skeleton" replace="${name}Impl" />
</target>

Step 9.2 Generate Client Side Code Automatically

We can generate thru remote WSDL file as following.

We can also use an xsd file to define elements and types. The xsd file is better in the same folder as WSDL file.

Add following element to "target" elements in build.xml.

<target name="generate-client">
  <wsdl2code wsdlfilename="http://localhost:8080/axis/services/${name}?wsdl" skipbuildxml="true" 
             namespacetopackages="http://sample.com/ss=com.sample.ss.client" targetsourcefolderlocation="src" overwrite="true" />
</target>

Step 10. Chosse and run generate service/client process in Ant.

第十步 选择Ant的运行项

Right click -> Run as "2 Ant Build..." to open Edit configuration and launch screen. Select targets "generate-service" and "generate-client" we created in previous step.

右键点击运行为->2Ant Build... 打开Ant的运行配置界面，选择上一步中配置好的两项。

Then apply and run. Java code files appear.

应用并运行，Java代码文件就出现了。

Step 11. Create own implementation of skeleton interface. This implementation is the main entry for service side.

第十一步 创建自定义的骨架接口实现

In server side, we implement the interface XYZServiceSkeletonInterface by XYZServiceImpl. We need to implement all functional processes in this class.

在服务器端，要自定义一个实现类，来实现骨架接口，这个实现类实现了所有的服务器功能。

In client side, we can use XYZServiceStub which is generated by "generate-client" process to send web service request.

在客户端，使用Stub类来发送Web Service请求。