Goal

This article describes how to develop JAX-WS web service With Top-Down approach (contract first). We need a WSDL and only javax.xml.ws.Endpoint API and JAX-WS to test this way.

Used technologies

JDK 1.8
Eclipse (we will create a java project from wizard)

1. WSDL

At first we will structure our wsdl file in three sections:

1.1 XML schema (TutorialService.xsd)

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema id="PassengerManagerSchema.xsd" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:tns="http://www.wstutorial.com/ws/TutorialService"
	elementFormDefault="qualified" targetNamespace="http://www.wstutorial.com/ws/TutorialService">
	<xsd:complexType name="statusCode">
		<xsd:sequence>
			<xsd:element name="code" type="xsd:long" />
		</xsd:sequence>
	</xsd:complexType>
	<xsd:complexType name="TutorialType">
		<xsd:all>
			<xsd:element name="id" type="xsd:long" />
			<xsd:element name="name" type="xsd:string" />
			<xsd:element name="author" type="xsd:string" />
		</xsd:all>
	</xsd:complexType>
	<xsd:complexType name="TutorialTypes">
		<xsd:sequence>
			<xsd:element type="tns:TutorialType" minOccurs="0" maxOccurs="unbounded" name="tutorials" />
		</xsd:sequence>
	</xsd:complexType>
	<xsd:complexType name="idAsLong">
		<xsd:sequence>
			<xsd:element name="id" type="xsd:long" />
		</xsd:sequence>
	</xsd:complexType>

	<xsd:element name="tutorialType" type="tns:TutorialType" />
	<xsd:element name="tutorialTypes" type="tns:TutorialTypes" />
	<xsd:element name="tutorialFault" type="xsd:string" />
	<xsd:element name="tutorialID" type="tns:idAsLong" />
	<xsd:element name="tutID" type="tns:idAsLong" />
	<xsd:element name="statusCode" type="tns:statusCode" />
	<xsd:element name="deleteID" type="tns:idAsLong" />
	<xsd:element name="deleteStatusCode" type="tns:statusCode" />
	<xsd:element name="updateTutorialType" type="tns:TutorialType" />
	<xsd:element name="updateStatusCode" type="tns:statusCode" />
</xsd:schema>

1.2 Abstract wsdl (TutorialServiceAbstract.wsdl)

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="PassengerManagerPort.wsdl" xmlns="http://schemas.xmlsoap.org/wsdl/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
	xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://www.wstutorial.com/ws/TutorialService"
	targetNamespace="http://www.wstutorial.com/ws/TutorialService">

	<types>
		<xsd:schema>
			<xsd:import namespace="http://www.wstutorial.com/ws/TutorialService"
				schemaLocation="TutorialService.xsd" />
		</xsd:schema>
	</types>

	<message name="addTutorialRequest">
		<part name="params" element="tns:tutorialType" />
	</message>
	<message name="addTutorialResponse">
		<part name="params" element="tns:statusCode" />
	</message>
	<message name="tutorialFault">
		<part name="params" element="tns:tutorialFault" />
	</message>
	<message name="getTutorialsRequest">
		<part name="params" element="tns:tutorialID" />
	</message>
	<message name="getTutorialsResponse">
		<part name="params" element="tns:tutorialTypes" />
	</message>
	<message name="getTutorialRequest">
		<part name="params" element="tns:tutID" />
	</message>
	<message name="getTutorialResponse">
		<part name="params" element="tns:tutorialType" />
	</message>
	<message name="deleteTutorialRequest">
		<part name="params" element="tns:deleteID" />
	</message>
	<message name="deleteTutorialResponse">
		<part name="params" element="tns:deleteStatusCode" />
	</message>
	<message name="updateTutorialRequest">
		<part name="params" element="tns:updateTutorialType" />
	</message>
	<message name="updateTutorialResponse">
		<part name="params" element="tns:updateStatusCode" />
	</message>

	<portType name="TutorialServicePortType">
		<operation name="addTutorial">
			<input message="tns:addTutorialRequest" />
			<output message="tns:addTutorialResponse" />
			<fault name="fault" message="tns:tutorialFault" />
		</operation>
		<operation name="deleteTutorial">
			<input message="tns:deleteTutorialRequest" />
			<output message="tns:deleteTutorialResponse" />
			<fault name="fault" message="tns:tutorialFault" />
		</operation>
		<operation name="updateTutorial">
			<input message="tns:updateTutorialRequest" />
			<output message="tns:updateTutorialResponse" />
			<fault name="fault" message="tns:tutorialFault" />
		</operation>
		<operation name="getTutorials">
			<input message="tns:getTutorialsRequest" />
			<output message="tns:getTutorialsResponse" />
			<fault name="fault" message="tns:tutorialFault" />
		</operation>
		<operation name="getTutorialById">
			<input message="tns:getTutorialRequest" />
			<output message="tns:getTutorialResponse" />
			<fault name="fault" message="tns:tutorialFault" />
		</operation>
	</portType>

</definitions>

1.3 The concret wsdl (TutorialService.wsdl)

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="UserDirectoryService.wsdl"
	targetNamespace="http://www.wstutorial.com/ws/TutorialService" xmlns="http://schemas.xmlsoap.org/wsdl/"
	xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://www.wstutorial.com/ws/TutorialService">

	<wsdl:import namespace="http://www.wstutorial.com/ws/TutorialService" location="TutorialServiceAbstract.wsdl" />

	<binding name="tutorialServiceSOAPBinding" type="tns:TutorialServicePortType">
		<soap:binding style="document"
			transport="http://schemas.xmlsoap.org/soap/http" />
		<operation name="addTutorial">
			<soap:operation />
			<input>
				<soap:body use="literal" />
			</input>
			<output>
				<soap:body use="literal" />
			</output>
			<fault name="fault">
				<soap:fault name="fault" use="literal" />
			</fault>
		</operation>
		<operation name="deleteTutorial">
			<soap:operation />
			<input>
				<soap:body use="literal" />
			</input>
			<output>
				<soap:body use="literal" />
			</output>
			<fault name="fault">
				<soap:fault name="fault" use="literal" />
			</fault>
		</operation>
		<operation name="updateTutorial">
			<soap:operation />
			<input>
				<soap:body use="literal" />
			</input>
			<output>
				<soap:body use="literal" />
			</output>
			<fault name="fault">
				<soap:fault name="fault" use="literal" />
			</fault>
		</operation>
		<operation name="getTutorials">
			<soap:operation />
			<input>
				<soap:body use="literal" />
			</input>
			<output>
				<soap:body use="literal" />
			</output>
			<fault name="fault">
				<soap:fault name="fault" use="literal" />
			</fault>
		</operation>
		<operation name="getTutorialById">
			<soap:operation />
			<input>
				<soap:body use="literal" />
			</input>
			<output>
				<soap:body use="literal" />
			</output>
			<fault name="fault">
				<soap:fault name="fault" use="literal" />
			</fault>
		</operation>
	</binding>
	<service name="TutorialService">
		<port name="TutorialServicePort" binding="tns:tutorialServiceSOAPBinding">
			<soap:address location="http://localhost:8090/ws/tutorialService" />
		</port>
	</service>
</definitions>

Project structure

2. Generate Code

wsimport -d ./generated -s ./src -p com.wstutorial.ws ./wsdl/TutorialService.wsdl
The generated files:

3. Implement Service

package com.wstutorial.ws.impl;

import javax.jws.WebService;

import com.wstutorial.ws.IdAsLong;
import com.wstutorial.ws.StatusCode;
import com.wstutorial.ws.TutorialFault;
import com.wstutorial.ws.TutorialServicePortType;
import com.wstutorial.ws.TutorialType;
import com.wstutorial.ws.TutorialTypes;

@WebService(endpointInterface = "com.wstutorial.ws.TutorialServicePortType")
public class TutorialServiceImpl implements TutorialServicePortType {

	public StatusCode addTutorial(TutorialType tutorialType) throws TutorialFault {
		if ((tutorialType.getName() == null|| tutorialType.getName().equals("")) ) {
			throw new TutorialFault("Tutorial should not be null or empty ", "Wrong input Data");
		}
		
		//Code to save this tutorial
		
		// If everything is fine, return 201 /Created
		StatusCode code = new StatusCode();
		code.setCode(201);
		return code;
	}

	public TutorialTypes getTutorials(IdAsLong tutorialID) throws TutorialFault {
		if (tutorialID.getId() == 0) {
			throw new TutorialFault("Id is not valid", "Wrong input Data");
		}
		TutorialTypes result = new TutorialTypes();
		
		TutorialType tutorial = new TutorialType();
		tutorial.setId(1);
		tutorial.setAuthor("Adam snake");
		tutorial.setName("Python Basics");
		
		TutorialType tutorial2 = new TutorialType();
		tutorial2.setId(4);
		tutorial2.setAuthor("will john");
		tutorial2.setName("Rest with jersey");
		
		result.getTutorials().add(tutorial);
		result.getTutorials().add(tutorial2);
		
		return result;
	}

	public TutorialType getTutorialById(IdAsLong tutorialID) throws TutorialFault {
		if (tutorialID.getId() == 0) {
			throw new TutorialFault("Id is not valid", "Wrong input Data");
		}
		
		TutorialType tutorial = new TutorialType();
		tutorial.setId(1);
		tutorial.setAuthor("Adam snake");
		tutorial.setName("Python Basics");
		
		return tutorial;
	}

	public StatusCode deleteTutorial(IdAsLong tutorialID) throws TutorialFault {
		if (tutorialID.getId() == 0) {
			throw new TutorialFault("Id is not valid", "Wrong input Data");
		}
		// code to delete this tutorial

		// If everything is fine, return 202 /Accepted
		StatusCode code = new StatusCode();
		code.setCode(202);
		return code;
	}

	public StatusCode updateTutorial(TutorialType tutorialType) throws TutorialFault {
		if ((tutorialType.getName() == null|| tutorialType.getName().equals("")) ) {
			throw new TutorialFault("Tutorial should not be null or empty ", "Wrong input Data");
		}
		
		// code to update this tutorial
		
		// If everything is fine, return 200 /OK
		StatusCode code = new StatusCode();
		code.setCode(200);
		return code;
	}

}

Warning! To avoid some trouble use endpointInterface = "com.wstutorial.ws.TutorialServicePortType"

4. Let's start

package com.wstutorial.ws.impl;

import javax.xml.ws.Endpoint;

public class TutorialPublisher {

	public static void main(String[] args) {
		Endpoint.publish("http://localhost:8090/ws/tutorialService", new TutorialServiceImpl());
		System.out.println("TutorialService is running");
	}
}

5. Check the url

http://localhost:8090/ws/tutorialService?wsdl

References

  • JAX-WS Endpoint