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
  
• Open Eclipse IDE Windows –> Preferences
  
• Browse through “axis2-1.6.2” location
  Note: select Axis2 Preferences
  
  
• 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”

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

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

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

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

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

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

Step 9: Configure required parameters

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

Step 11: accept default and click Next

Step 12: Click “Start Server”

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

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

Project Structure after above steps

 

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

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

Step 19: BookService.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

 

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

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