Steps to Set up and Implement Web Service via Eclipse and Axis2 1.6

Part I Setup

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

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

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

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

Step 2. Install Axis plugin to Eclipse

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

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

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.

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

Part II Implementation

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

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

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

Elements and Types: This part can be defined in another xsd file and imported.

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.

Binding: There is no manual editing on this part.

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

Step 4.1 Generate Server Side Code

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

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.

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.

For advanced user, 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.

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.

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

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.

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.

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

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

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

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

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

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.

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.

Then apply and run. Java code files appear.

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.