This blog tries to help you go through the process of creating a web service via Axis2/Java in Windows operating system. Axis2 is a Web Service engine and using Axis2 we can create our web services easily.
Before we dive into the detailed steps, we need to get our tools prepared. Java, Axis2, of course, and Eclipse are needed. It is also recommended to install Ant. Axis2 can be gotten from http://axis.apache.org/axis2/java/core/download.cgi. We can use the standard binary distribution for study purpose. Eclipse can be retrieved from http://www.eclipse.org/downloads/. Note, when downloading Eclipse, Java EE package is the right one for us. The download page of Ant is http://ant.apache.org/bindownload.cgi. Following the installation guider on the web page, you can get all these tools installed smoothly. Pay attention to set the corresponding environment variables, especially their HOMEs, for Java, Axis2 and Ant.
After unzipping the binary package of Axis2 and setting the AXIS2_HOME, go to %AXIS2_HOME%\bin directory under command line. Simply use ‘axis2server.bat’ file to start Axis2 as below:
The port 8080 is listening to our request so we can have a quick look at the resources published on that port. Go to http://localhost:8080.
We can find one operation named ‘Version’ has already been deployed. Checking the %AXIS2_HOME%\repository\services, you can find the corresponding ‘Version.aar’ file.
Now it is time to create our own Web Service. We would like to create a simple Web Service to provide a service of calculating the addition value of two integers. When creating a Web Service, basically we have two ways, top-down and bottom-up. Following a top-down approach, we need to create WSDL file first and then create implementation codes according to the WSDL file. WSDL, standing for Web Service Description Language, is an XML-based language that is used for describing the functionality offered by a web service. We would like to use WSDL of version 1.1 here. A bottom-up way need us to write the implementation code first and then based on the codes we get the WSDL file. When we need to create web services based on a legacy system, we had better choose the bottom-up solution, however, now we create our web service from nothing, we could choose the top-down approach.
Now open the Eclipse and do some configurations for using Axis2 in the IDE. Go to ‘Window>Preferences’ and expand the ‘Web Services’ entry. You could find ‘Axis2 Preferences’ entry. Provide the correct ‘Axis2 runtime location’ according to your installation of the Axis2
Now, we can create a dynamic web project named ‘AddtionServie’ and pay attention that the ‘Axis2 Web Service’ facet is chosen.
Since we choose the top-down approach, we need to create a WSDL file first. We can go to ‘File>New>Other…’. Expanding the ‘Web Services’ category and choose ‘WSDL’ entry. Give a proper name to the WSDL file and choose a directory you want to place the WSDL file. For the settings on ‘Options’ page, we can use the default settings or you can change the target namespace to what you want, but we had better use the ‘SOAP’ protocol and ‘document literal’ binding.
Then we need to do some modifications on the generated WSDL file. First of all let us modify the schema which will be used for the input and output messages. By clicking the arrows besides the input and output messages we can navigate to the inline schema editor. We can first change the schema of the input message. Click the grey arrow besides the input message we will be navigated to the schema editor for input message schema as following:
Since we provide the addition service for two integers, we need to change this schema to what we desire and in addition, we can change the name of the element from ‘NewOperation’ to a more meaningful name. Note if we would like to change the name of the element via GUI design, we need to use the ‘rename’ operation under ‘Refactor’ menu. Pay attention to the type of the elements.
We then need to do the similar modification to the output schema.
Then we need to change the name of the operation and the string value of the port. The port is where Axis2 really provides the service and client will send the messages to this address. For now we can change it to ‘http://localhost:8080/axis2/services/Addition/Addtion’. Note other values can be set for the port here, but when Axis2 publishes the service, it will generate the real effective value for use. We can see that value later in this blog.
We have finished the WSDL file and now we need to implement our web service on the server side. In Eclipse, right click the WSDL file and choose ‘Web ServicesàGenerate Java Bean Skeleton’
Make sure the ‘Web service type’ is ‘Top down Java bean Web Service’ and pay attention that ‘Apache Axis2’ is used for ‘Web service runtime’.
Then click Next button and in the following page we can tick ‘Generate an interface for the skeleton’. This causes an Interface to be created for the skeleton Java class. Then click Next button again. When the server side codes generation process ends we have a choice to start server. For now we click cancel button because we have not implemented our service.
Now go to view the generated codes. Open the AdditionSkeleton.java and we could find the addition function only contains one statement which throws an exception. Modify the codes as following:
Apparently we ignore the border of integer, however, for the study purpose we are okay to not be too nitpicky on this sort of issue. Then we need to build the project via the generated Ant build file. We can simply use the default target of that build file.
Then you can find one aar file under the build\lib directory. Now simply put that file under %AXIS2_HOME%\repository\services. Axis2 has a hot deployment feature so when you drop that aar file to the publish directory directly, Axis2 will find that file and do the deployment.
Now check the published service in web browser again. Go to http://localhost:8080/axis2/services/ and this time we can find the ‘Addition’ service is exposed to the clients and there is one available operation named ‘Addition’.
Click the blue ‘Addition’ link to view the published WSDL file of that web service. Find the port info
This is the port that the client programs need to send message to. It is not equal to the value we entered in the WSDL editor before.
Now we need to validate if the web service really works. One simple way is you can write the code to send and receive messages from/to our Addition web service. Another way is we can leverage one tool named ‘soapUI’. Pay attention that soapUI has two different version one is free version and the other is the commercial version called ‘soapUI Pro’. Free version is okay for most cases of our daily use. We can get soapUI via http://sourceforge.net/projects/soapui/files/.
We would like to create a simple client Java program to test our web service. First we download the WSDL file from the web browser. Just visit http://localhost:8080/axis2/services/Addition?wsdl and save it as Addtion.wsdl. Then in Eclipse we create another dynamic web project named ‘SimpleClient’. We copy the WSDL file into that project and then right click on the WSDL file and choose ‘Web Services>Generate Client’.
Similarly pay attention to the ‘Web service runtime’ should be Axis2 instead of Axis. We can choose to create a synchronous client in the wizard.
After clicking ‘Finish’ one class named AdditionStub will be generated. We can treat this class as the agent of the web service. We communicate with it and it in turn communicates with the server. Now we can create a new class as the client of our web service. In the same package of AdditionStub, we create a class named ‘SimpleTestClient’. Create a main function and in that function we try our web service as below diagram:
Pay attention to creating the Stub object. From the published WSDL file, we get the port address as http://localhost:8080/axis2/services/Addition/. The tricky thing is we have to use the machine name or the actually IP address instead of ‘localhost’. This is something tricky with the Common Http Client used by Axis2. If ‘localhost’ or 127.0.0.1 is used we will get the 404 error. Running the program, we get the result as below:
