Apache Axis2: JAX-WS based Web Service using Top-Down approach

In this article, we will implement/develop SOAP based Web Service using Apache Axis2 reference implementation

Basically, we got two options while developing/implementation of SOAP Web Service

  • Top-Down approach or Contract first
  • Bottom-UP approach or Code first

We will concentrate on the first approach i.e.; Top-Down approach. Although bottom-up approach is comparatively quite simpler to develop, but developer in collaboration with designer should prefer to implement Top-Down approach as it is advantageous and involves writing contact document first i.e.; WSDL

In this approach, XSD i.e.; XML Schema and WSDL i.e.; Web Service Description Language are designed/written before implementation and later we can generate java artifacts using Eclipse IDE wizards configure with axis2 and tomcat server

Note: For simple use case, we can use command line interface to generate java artifacts

Technology Used

  • Java 1.7
  • Eclipse Kepler IDE
  • Apache Axis2-1.6.2
  • Apache Tomcat-8.0.12

Pre-requisite

  • Configure Apache Axis2 plugin in Eclipse IDE
  • Configure Apache Tomcat server in Eclipse IDE

Steps to configure apache axis2 plugin

  • Download latest Apache Axis2- Binary Distribution from here
  • Make sure to download zip for windows OS from Binary Distribution
  • Extract to some suitable location like D:\Downloads\Software\axis2-1.6.2
    1_Apache-Axis2-JAX-WS-Top-Down_axis2_plugin
  • Open Eclipse IDE Windows –> Preferences
    2_Apache-Axis2-JAX-WS-Top-Down_eclipse_ide_preferences
  • Browse through “axis2-1.6.2” location
    Note: select Axis2 Preferences
    3_Apache-Axis2-JAX-WS-Top-Down_browse_axis2_plugin
  • That’s it !! we are done with installing Apache Axis2 plugin in Eclipse IDE

Now that we have installed Apache Axis2 plugin in Eclipse IDE and similarly configure Tomcat server
We will move on developing top-down approach using above configuration

Step 1: In Eclipse, create new “Dynamic Web Project”

4_Apache-Axis2-JAX-WS-Top-Down_new_dynamic_web_project

Step 2: Provide “Project Name” and make sure to change the “Dynamic web module version” to 2.5 –> click Next
Reason: Apache Axis2 doesn’t work above 2.5 even with the latest version-1.6.2

5_Apache-Axis2-JAX-WS-Top-Down_new_dynamic_web_project_wizrd

Step 3: By default, there will be “src” folder –> add “resources” folder to place XSD/WSDL using “Add Folder…” button

6_Apache-Axis2-JAX-WS-Top-Down_new_dynamic_web_project_default_folder

Step 4: after adding “resources” folder –> click Next

7_Apache-Axis2-JAX-WS-Top-Down_new_dynamic_web_project_add_folder

Step 5: check “Generate web.xml DD” and Click Finish

8_Apache-Axis2-JAX-WS-Top-Down_new_dynamic_web_xml

Step 6: Initial project structure (Eclipse Package Explorer view)

9_Apache-Axis2-JAX-WS-Top-Down_Initial_Project_Structure

Step 7: Add Book Service WSDL and its associated XSD files under “resources” folder
book.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	targetNamespace="http://benchresources.in/entities/Book" xmlns:tns="http://benchresources.in/entities/Book"
	elementFormDefault="qualified">

	<!-- Book Request Type -->
	<xsd:element name="BookRequestType">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="isbnNumber" type="xsd:string" />
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

	<!-- Book Response Type -->
	<xsd:element name="BookResponseType">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="bookISBN" type="xsd:string" />
				<xsd:element name="bookName" type="xsd:string" />
				<xsd:element name="author" type="xsd:string" />
				<xsd:element name="category" type="xsd:string" />
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

</xsd:schema>

BookService.wsdl

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
	targetNamespace="http://benchresources.in/services/BookService/"
	xmlns:tns="http://benchresources.in/services/BookService/" xmlns:book="http://benchresources.in/entities/Book"
	name="BookService">

	<wsdl:types>
		<xsd:schema targetNamespace="http://benchresources.in/services/BookService/">
			<xsd:import namespace="http://benchresources.in/entities/Book"
				schemaLocation="book.xsd" />
		</xsd:schema>
	</wsdl:types>

	<wsdl:message name="BookRequest">
		<wsdl:part element="book:BookRequestType" name="parameters" />
	</wsdl:message>
	<wsdl:message name="BookResponse">
		<wsdl:part element="book:BookResponseType" name="parameters" />
	</wsdl:message>

	<wsdl:portType name="IBookService">
		<wsdl:operation name="getBookByISDNRequestNumber">
			<wsdl:input message="tns:BookRequest" />
			<wsdl:output message="tns:BookResponse" />
		</wsdl:operation>
	</wsdl:portType>

	<wsdl:binding name="BookServiceSOAPBinding" type="tns:IBookService">
		<soap:binding style="document"
			transport="http://schemas.xmlsoap.org/soap/http" />
		<wsdl:operation name="getBookByISDNRequestNumber">
			<soap:operation soapAction="" />
			<wsdl:input>
				<soap:body use="literal" />
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal" />
			</wsdl:output>
		</wsdl:operation>
	</wsdl:binding>

	<wsdl:service name="BookService">
		<wsdl:port name="BookServicePort" binding="tns:BookServiceSOAPBinding">
			<soap:address
				location="http://localhost:8080/ApacheCXF-JAX-WS-Top-Down/services/book/BookService" />
		</wsdl:port>
	</wsdl:service>

</wsdl:definitions>

 

Step 8: Right Click on Project –> New –> Web Service

10_Apache-Axis2-JAX-WS-Top-Down_web_service_wizard

Step 9: Configure required parameters

11_Apache-Axis2-JAX-WS-Top-Down_web_service_initial_wizard

Step 10: Configuring parameters as below for this approach

Web service type: Top down Java bean Web Service
Service definition: browse through WSDL file here
Configuration:

  • Server runtime: Tomcat 8.x server
  • Web service runtime: Apache Axis2
  • Service project: Project-name

12_Apache-Axis2-JAX-WS-Top-Down_web_service_change_settings

Step 11: accept default and click Next

13_Apache-Axis2-JAX-WS-Top-Down_web_service_change_settings_next

Step 12: Click “Start Server

14_Apache-Axis2-JAX-WS-Top-Down_web_service_start_server

Step 13: This is optional –> accept default and click Finish

15_Apache-Axis2-JAX-WS-Top-Down_web_service_optional_uddi

Step 14: After clicking Finish in the above step -> default endpoint implementation class will be opened in Eclipse IDE

16_Apache-Axis2-JAX-WS-Top-Down_web_service_implementation_class

Project Structure after above steps

17_Apache-Axis2-JAX-WS-Top-Down_generated_project_artifacts

 

Step 15: Provide business logic to the endpoint class

BookServiceSkeleton.java

/**
 * BookServiceSkeleton.java
 *
 * This file was auto-generated from WSDL
 * by the Apache Axis2 version: 1.6.2  Built on : Apr 17, 2012 (05:33:49 IST)
 */
package in.benchresources.services.bookservice;

import in.benchresources.entities.book.BookResponseType;

/**
 *  BookServiceSkeleton java skeleton for the axisService
 */
public class BookServiceSkeleton{

	/**
	 * Auto generated method signature
	 *
	 * @param bookRequestType
	 * @return bookResponseType
	 */

	public in.benchresources.entities.book.BookResponseType getBookByISDNRequestNumber(in.benchresources.entities.book.BookRequestType bookRequestType) {
		// create object of responseType and set values & return
		BookResponseType bookResponseType = new BookResponseType();
		bookResponseType.setBookISBN(bookRequestType.getIsbnNumber());
		bookResponseType.setBookName("Objective Microbiology");
		bookResponseType.setAuthor("S. Nandi");
		bookResponseType.setCategory("Microbiology");
		return bookResponseType;
	}
}

 

Step 16: Web service implemented –> deploy the service to tomcat server

Deployment
Right click on project –> Run As –> Run on Server

Check whether web service is correctly deployed or not?

Step 17: This is home page, after deploying apache axis2 based web service in tomcat server. Click services

18_Apache-Axis2-JAX-WS-Top-Down_axis2_home_page

Step 18: Click BookService to view wsdl of the deployed book service

19_Apache-Axis2-JAX-WS-Top-Down_axis2_click_services

Step 19: BookService.wsdl

20_Apache-Axis2-JAX-WS-Top-Down_axis2_services_wsdl

Step 20: With the above steps, a simple SOAP Web Service implemented and deployed onto the tomcat server successfully

Step 21: Testing using SOAP UI –> Get the endpoint URL and load into SOAP UI

21_Apache-Axis2-JAX-WS-Top-Down_axis2_services_wsdl_soap_1

 

22_Apache-Axis2-JAX-WS-Top-Down_axis2_services_wsdl_soap_2

Step 22: Input the request ISBN as “ISBN-2134”

23_Apache-Axis2-JAX-WS-Top-Down_axis2_services_wsdl_soap_3

Request XML:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:book="http://benchresources.in/entities/Book">
	<soapenv:Header />
	<soapenv:Body>
		<book:BookRequestType>
			<book:isbnNumber>ISBN-2134</book:isbnNumber>
		</book:BookRequestType>
	</soapenv:Body>
</soapenv:Envelope>

Response XML:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Body>
		<ns1:BookResponseType xmlns:ns1="http://benchresources.in/entities/Book">
			<ns1:bookISBN>ISBN-2134</ns1:bookISBN>
			<ns1:bookName>Objective Microbiology</ns1:bookName>
			<ns1:author>S. Nandi</ns1:author>
			<ns1:category>Microbiology</ns1:category>
		</ns1:BookResponseType>
	</soapenv:Body>
</soapenv:Envelope>

Conclusion: Simple JAX-WS based web service implemented, deployed and tested for top-down approach using Apache Axis2 Reference Implementation
In the next article, we will explore another approach i.e.; “Bottom-up” approach

Download project

Apache-Axis2-JAX-WS-Top-Down (168kB)

Happy Coding !!
Happy Learning !!

Apache Axis2: JAX-WS based Web Service using Bottom-Up approach