Apache CXF JAX-WS: SOAP based Web Service using Top-Down approach + Integrating with Spring framework

In the previous articles top-down-approach, security-policy and cxf-interceptor we have learnt/implemented a JAX-WS based SOAP Web Service using top-down approach. Now, in this article we will extend that concept/approach integrating with spring framework

This way after client hits web service with endpoint URL further processing happens in layers, delegating the request to business layer and then to DAO layer, etc

Note: Last articles describe about Book Service, but in this we will switch to Music Service
Let’s play some music baby J

Technology Used

  • Java 1.7
  • Eclipse Luna IDE
  • Apache CXF-3.0.2
  • Spring-4.1.0.RELEASE
  • Apache Maven 3.2.1
  • Apache Tomcat-8.0.15
  • Oracle Weblogic server 12c

Mavenize or download required jars

Add apache-cxf-3.0.2 & spring-4.1.0.RELEASE dependencies to pom.xml

<!-- properties -->

	<!-- apache cxf jax-ws 3.0.2 -->

	<!-- spring framework 4.1.0 -->


Folks who aren’t familiar with Maven concepts or don’t require maven for their project, can download the below jars individually from the central repository or maven repository or maven2 and include them in the classpath

Steps to generate Java artifacts from WSDL/XSD

  • write/design XML Schema (XSD)
  • similarly, write/design WSDL document including above XSD for Type attributes
  • configure maven plugins (wsimport/wsdl2java goal) in pom.xml with correct and complete path of the wsdl file under wsdlOptions/wsdlOption
  • Run maven command “mvn generate-sources” from project’s context-root
  • java artifacts will be generated under “generated” folder within specified targetNamespace


Let us understand above steps in more detail

Write/design well-formed XML Schema

music.xsd (src/main/resources/com/jaxws/series/td/spring/integration/entities)

Below XSD contains two elements with name “MusicRequestType” and “MusicResponseType” with a “BusinessFaultType” element in case of any exception

  • MusicRequestType contains single string called composerName
  • MusicResponseType contains four sub-elements namely movieName, year, director and comments
  • BusinessFaultType for exception wraps three sub-elements namely errorCode, errorMessage and errorDescription
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	targetNamespace="http://benchresources.in/entities/music" xmlns:tns="http://benchresources.in/entities/music"

	<!-- Music Request Type -->
	<xsd:element name="MusicRequestType">
				<xsd:element name="composerName" type="xsd:string" />

	<!-- Music Response Type -->
	<xsd:element name="MusicResponseType">
				<xsd:element name="movieName" type="xsd:string" />
				<xsd:element name="year" type="xsd:string" />
				<xsd:element name="director" type="xsd:string" />
				<xsd:element name="comments" type="xsd:string" />

	<!-- Business Exception Type -->
	<xsd:element name="BusinessFaultType">
				<xsd:element name="errorCode" type="xsd:int" />
				<xsd:element name="errorMessage" type="xsd:string" />
				<xsd:element name="errorDescription" type="xsd:string" />


Write/design well-formed WSDL

MusicService.wsdl (src/main/resources/com/jaxws/series/td/spring/integration/services)

This is the contract document for Music Service exposing one operation called “getMovieDetailByComposer” whose input argument is “MusicRequestType” and return type is “MusicResponseType” and fault is “BusinessFaultType

Note: In case of any exception while invoking this exposed service, business exception will be returned stating the reason instead of actual response type

<?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/"
	xmlns:muzix="http://benchresources.in/entities/music" name="MusicService">

		<xsd:schema targetNamespace="http://benchresources.in/services/MusicService/">
			<xsd:import namespace="http://benchresources.in/entities/music"
				schemaLocation="../entities/music.xsd" />

	<wsdl:message name="MusicRequest">
		<wsdl:part element="muzix:MusicRequestType" name="parameters" />
	<wsdl:message name="MusicResponse">
		<wsdl:part element="muzix:MusicResponseType" name="parameters" />
	<wsdl:message name="BusinessException">
		<wsdl:part element="muzix:BusinessFaultType" name="parameters" />

	<wsdl:portType name="IMusicService">
		<wsdl:operation name="getMovieDetailByComposer">
			<wsdl:input message="tns:MusicRequest" />
			<wsdl:output message="tns:MusicResponse" />
			<wsdl:fault name="businessException" message="tns:BusinessException" />

	<wsdl:binding name="MusicServiceSOAPBinding" type="tns:IMusicService">
		<soap:binding style="document"
			transport="http://schemas.xmlsoap.org/soap/http" />
		<wsdl:operation name="getMovieDetailByComposer">
				soapAction="http://benchresources.in/services/MusicService/getMovieDetailByComposer" />
				<soap:body use="literal" />
				<soap:body use="literal" />
			<wsdl:fault name="businessException">
				<soap:fault name="businessException" use="literal" />

	<wsdl:service name="MusicService">
		<wsdl:port name="MusicServicePort" binding="tns:MusicServiceSOAPBinding">
				location="http://localhost:8080/ApacheCXF-JAX-WS-Top-Down-Spring-Integration/services/music/MusicService" />


Configure maven plugin in pom.xml (wsdl2java goal)

This plugin which defines wsdl2java goal from cxf-codegen-plugin generates java artifacts from the supplied WSDL file under resources folder

<!-- plugin 4- apache cxf codegen wsdl2java goal -->

Run “mvn generate-sources”

Look at the generated java source files in the generated folder

After running above maven command, you will get to see below generated java files


  • IMusicService.java
  • MusicRequestType.java
  • MusicResponseType.java
  • BusinessFaultType.java
  • BusinessException.java
  • MusicService.java
  • ObjectFactory.java
  • package-info.java

We will look at one file IMusicService.java, for other files you can download this eclipse project provided in the last section “Download Project”

This interface which is implemented by our endpoint business implementation class


package in.benchresources.services.musicservice;

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.xml.bind.annotation.XmlSeeAlso;

 * This class was generated by Apache CXF 3.0.2
 * 2014-11-20T01:31:52.423+05:30
 * Generated source version: 3.0.2
@WebService(targetNamespace = "http://benchresources.in/services/MusicService/", name = "IMusicService")
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
public interface IMusicService {

    @WebResult(name = "MusicResponseType", targetNamespace = "http://benchresources.in/entities/music", partName = "parameters")
    @WebMethod(action = "http://benchresources.in/services/MusicService/getMovieDetailByComposer")
    public in.benchresources.entities.music.MusicResponseType getMovieDetailByComposer(
        @WebParam(partName = "parameters", name = "MusicRequestType", targetNamespace = "http://benchresources.in/entities/music")
        in.benchresources.entities.music.MusicRequestType parameters
    ) throws BusinessException;


Directory Structure

Before moving on, let us understand the directory/package structure once you create project and/plus after generating java artifacts in Eclipse IDE

Maven has to follow certain directory structure

  • src/test/java –> test related files, mostly JUnit test cases
  • src/main/java –> create java source files under this folder
  • generated/java/source –> generated java source files are placed here
  • src/main/resources –> all configuration files placed here
  • src/test/resources –> all test related configuration files placed here
  • Maven Dependencies or Referenced Libraries –> includes jars in the classpath
  • WEB-INF under webapp –> stores web.xml & other configuration files related to web application

Project Structure (Package Explorer view in Eclipse)


Jar Libraries Used in the Project (Maven Dependencies)



Web application

For any web application, entry point is web.xml which describes how the incoming http requests are served / processed. Further, it describes about the global-context and local-context param (i.e.; <context-param> & <init-param>) for loading files particular to project requirements & contains respective listener

With this introduction, we will understand how we configured web.xml for Apache CXF JAX-WS SOAP based Web Service

web.xml (the entry point –> under WEB-INF)

This web.xml file describes,

  • Like any JEE web framework register “org.apache.cxf.transport.servlet.CXFServlet” with servlet container
  • http requests with URL pattern “/services/*” will be sent to the registered servlet called “CXFServlet” i.e.; (org.apache.cxf.transport.servlet.CXFServlet)
  • configure spring context loader listener for loading spring context files “org.springframework.web.context.ContextLoaderListener
  • <context-param> with its attributes describes the location of the “apache-cxf-service.xml” & “spring-jax-ws” files from where it has to be loaded. We will discuss briefly about these files
  • configure session timeout in secs using <session-config> tag
  • <welcome-file-list> files under this tag is the start-up page


<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">


	<!-- listener to startup (spring) -->

	<!-- loading spring context file from classpath location -->

	<!-- Apache CXF servlet -->

	<!-- session timeout -->

	<!-- welcome file list -->



Apache CXF services

Apache CXF comes with spring based configuration, so it is easy to register beans in the spring container much like we do any bean in spring application in addition to configuring JAX-WS endpoints and interceptors, etc

In CXF endpoint, we can define implementor i.e.; Java endpoint implementation class and address. So, incoming requests from “CXFServlet” servlet invokes corresponding implementation class with configured address-pattern

For more JAX-WS element details see here

This apache-cxf-services.xml describes,

  • < jaxws:endpoint /> defines which service implementation class to be invoked for the incoming http/https SOAP requests with address-pattern configured

NOTE: For two different beans we can have two different url-pattern (address) like

<jaxws:endpoint id="bookservice"

<jaxws:endpoint id="otherservice" implementor="other.qualified.package.name"



<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxws="http://cxf.apache.org/jaxws"
	xmlns:jaxrs="http://cxf.apache.org/jaxrs" xmlns:context="http://www.springframework.org/schema/context"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
	http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
	http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
	http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">

	<jaxws:endpoint id="musicservice"



Spring Application Context file

This Spring Application Context file describes,

  • <context:annotation-config /> to activate annotation on the registered beans with application context
  • <context:component-scan base-package=”” /> tag scans all classes & sub-classes under the value of base-package attribute and register them with the Spring container


<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context"
	xmlns:tx="http://www.springframework.org/schema/tx" xmlns:ws="http://jax-ws.java.net/spring/core"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
	http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
	http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx.xsd
	http://jax-ws.java.net/spring/core http://jax-ws.java.net/spring/core.xsd
    http://jax-ws.java.net/spring/servlet http://jax-ws.java.net/spring/servlet.xsd">

	<!-- to activate annotations in beans already registered in the ApplicationContext -->
	<context:annotation-config />

	<!-- scans packages to find and register beans within the application context -->
	<context:component-scan base-package="com.jaxws.series.td.spring.integration" />



Let’s see coding in action


URL Pattern

Http url for any common web application is http://<server>:<port>/<root-context>/<from_here_application_specific_path>

In our example, we are going to deploy the war into Tomcat 8.0 server, so our server and port are localhost and 8080 respectively. Context root is the project name i.e.; ApacheCXF-JAX-WS-Top-Down-Spring-Integration. Initial path for this application is http://localhost:8080/ApacheCXF-JAX-WS-Top-Down-Spring-Integration

We have configured “/services/*” as url-pattern for the “CXFServlet” servlet in web.xml and our business implementation class implements the portType interface generated from WSDL file which is annotated with @WebService annotation at class-level


Model Class (POJO)

Model class Music with four primitive attributes and their getter/setter


package com.jaxws.series.td.spring.integration.model;

public class Music {

	// member variables
	private String movieName;
	private String director;
	private String yearOfRelease;
	private String comments;

	// getters & setters
	public String getMovieName() {
		return movieName;
	public void setMovieName(String movieName) {
		this.movieName = movieName;
	public String getDirector() {
		return director;
	public void setDirector(String director) {
		this.director = director;
	public String getYearOfRelease() {
		return yearOfRelease;
	public void setYearOfRelease(String yearOfRelease) {
		this.yearOfRelease = yearOfRelease;
	public String getComments() {
		return comments;
	public void setComments(String comments) {
		this.comments = comments;


Music Service Implementation (business logic)

This service provider class implements portType interface generated from WSDL file. Also, class got annotated with @WebService annotation at class-level and this is very important

Note: This class extends SpringBeanAutowiringSupport class to support annotation


package com.jaxws.series.td.spring.integration.service;

import in.benchresources.entities.music.BusinessFaultType;
import in.benchresources.entities.music.MusicRequestType;
import in.benchresources.entities.music.MusicResponseType;
import in.benchresources.services.musicservice.BusinessException;
import in.benchresources.services.musicservice.IMusicService;

import javax.jws.WebService;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.web.context.support.SpringBeanAutowiringSupport;

import com.jaxws.series.td.spring.integration.dao.MusicDAO;
import com.jaxws.series.td.spring.integration.model.Music;

@WebService(serviceName="MusicService", endpointInterface="in.benchresources.services.musicservice.IMusicService",
targetNamespace="http://benchresources.in/services/MusicService/", portName="MusicServicePort", name="MusicServiceImpl")
public class MusicServiceImpl extends SpringBeanAutowiringSupport implements IMusicService {

	private MusicDAO musicDAO;

	public MusicResponseType getMovieDetailByComposer(MusicRequestType parameters) throws BusinessException {

		// local variables
		Music music = null;
		MusicResponseType musicResponseType = null;
		BusinessFaultType businessFaultType = null;

			if(null != parameters && !parameters.getComposerName().equalsIgnoreCase("")){

				// invoke dao to get values
				music = musicDAO.getMovieByComposer(parameters.getComposerName());

				// set values in the return/response type
				musicResponseType = new MusicResponseType();
		catch(Exception ex){
			// dummy setting for business exception, we can set more meaningful error depending on the business requirements
			businessFaultType = new BusinessFaultType();
			businessFaultType.setErrorMessage("Error in invoking Music Service " + ex.getMessage());
			// close resources, if any
		return musicResponseType;


DAO layer

This DAO layer takes care of the database interaction. In this example, actually there is no database just returning dummy data for demo purpose. In the next article, we will enhance/improve this article by integrating with rich Hibernate ORM framework for database queries


import com.jaxws.series.td.spring.integration.model.Music;

public interface MusicDAO {

	public Music getMovieByComposer(String composerName);


package com.jaxws.series.td.spring.integration.dao;

import org.springframework.stereotype.Repository;

import com.jaxws.series.td.spring.integration.model.Music;

public class MusicDAOImpl implements MusicDAO {

	public Music getMovieByComposer(String composerName) {

		// local variables
		Music music = null;

		if(null != composerName && composerName.equalsIgnoreCase("AR Rahman")){

			// setting dummy values
			music = new Music();
			music.setMovieName("Thiruda Thiruda");
			music.setDirector("Mani Ratnam");
			music.setComments("Comedy Thriller");
			// setting test values
			music = new Music();
		return music;


That’s all with coding part, now let us move on to deployment and testing

Apache Tomcat-8.0.15 Deployment

  • Run maven command to build the war: mvn clean install (use command prompt or integrated maven in eclipse IDE
  • Copy(ctrl+c) the war file from the target folder
  • Paste(ctrl+v) it into apache tomcat (webapps folder)
  • Start the tomcat server (Tomcat_Home\bin\startup.bat)

Oracle Weblogic server Deployment

Apache CXF based JAX-WS web service can’t be deployed directly into Oracle WebLogic server as WAR file –> it’s a two step process. First build a WAR file and then package this WAR file into an EAR file –> Deploy EAR file into weblogic server

See this article for explanation: Packaging WAR as EAR

Steps to be followed

  • Run maven command to build the war: mvn clean install (use command prompt or integrated maven in eclipse IDE)
  • Once you see “BUILD SUCCESS” after running maven command, it means your war file is successfully built and installed in the local maven repository
  • Package this WAR file into an EAR file as explained in this article
  • Start weblogic 12c application server and hit the URL http://localhost:7001/console in any of the latest web browser and enter username/password you configured while setting up weblogic 12c server
  • Go to Deployments –> click install button –> browse through EAR file location –> say Next –> say Next –> Finish

For Oracle WebLogic 12c server Installation steps see here

Test the service !!


There are many ways to do testing

  • SOAP UI Client
  • Java Client using JDK’s in-built classes like HttpURLConnection
  • Java Client using SOAP API
  • Eclipse’s Web Services Explorer
  • Write your own client for example, Java client using httpcomponents from Apache

We will cover first 2 ways of testing above JAX-WS deployed service

1. SOAP UI Client

Load the endpoint URL in SOAP UI Client, which will pre-populate the request XML based on the operation deployed/exposed using WSDL

For example, http://localhost:8080/ApacheCXF-JAX-WS-Top-Down-Spring-Integration/services/music/MusicService?wsdl

Request XML

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	<soapenv:Header />
			<mus:composerName>AR Rahman</mus:composerName>

Response XML

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
		<MusicResponseType xmlns="http://benchresources.in/entities/music">
			<movieName>Thiruda Thiruda</movieName>
			<director>Mani Ratnam</director>
			<comments>Comedy Thriller</comments>



2. Java client

For this java client to work/execute, we don’t need to add any extra jars or any new dependency in pom.xml as these classes comes shipped along with JDK. Observe, import statements closely for this client

Note: Request XML pattern formed taking help from pre-populated request XML from SOAP UI client as explained above


package test.jaxws.series.td.spring.integration.service;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;

public class TestMusicService {

	 * wsimport - JAX-WS top-down web service approach
	 * main() method to test/start soap web service
	 * @param args
	 * @throws IOException
	public static void main(String[] args) throws IOException {

		String httpRequestURL = "http://localhost:8080/ApacheCXF-JAX-WS-Top-Down-Spring-Integration/services/music/MusicService?wsdl";
		String soapRequestParam = 	"<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:mus=\"http://benchresources.in/entities/music\">"
				+						"<soapenv:Header/>"
				+						"<soapenv:Body>"
				+							"<mus:MusicRequestType>"
				+								"<mus:composerName>AR Rahman</mus:composerName>"
				+							"</mus:MusicRequestType>"
				+						"</soapenv:Body>"
				+					"</soapenv:Envelope>";
		String responseString = testBookService(httpRequestURL, soapRequestParam);
		System.out.println("Response String : " + responseString);

	 * This method uses HttpURLConnection to invoke exposed SOAP web service and returns the response string to the calling client
	 * @param httpRequestURL
	 * @param requestXmlParam
	 * @return responseXML
	 * @throws IOException
	public static String testBookService(String httpRequestURL, String requestXmlParam) throws IOException {

		// local variables
		URL url = null;
		HttpURLConnection httpURLConnection = null;
		OutputStreamWriter outputStreamWriter = null;
		String responseMessageFromServer = null;
		String responseXML = null; 

		try {
			// set basic request parameters
			url = new URL(httpRequestURL);
			httpURLConnection = (HttpURLConnection) url.openConnection();
			//			httpURLConnection.setRequestProperty("SOAPAction", "");
			httpURLConnection.setRequestProperty("Content-Type", "text/xml");
			httpURLConnection.setRequestProperty("Accept", "text/xml");

			// write request XML to the HTTP request
			outputStreamWriter = new OutputStreamWriter(httpURLConnection.getOutputStream());

			System.out.println("Response code: " + httpURLConnection.getResponseCode());
			if (httpURLConnection.getResponseCode() == 200) {

				responseMessageFromServer = httpURLConnection.getResponseMessage();
				System.out.println("ResponseMessageFromServer: " + responseMessageFromServer);
				responseXML = getResponseXML(httpURLConnection);
		catch (IOException ioex) {
			throw ioex;
			// finally close all operations
		return responseXML;

	 * This method is used to get response XML from the HTTP POST request
	 * @param httpURLConnection
	 * @return stringBuffer.toString()
	 * @throws IOException
	private static String getResponseXML(HttpURLConnection httpURLConnection) throws IOException {

		// local variables
		StringBuffer stringBuffer = new StringBuffer();
		BufferedReader bufferedReader = null;
		InputStreamReader inputStreamReader = null;
		String readSingleLine = null;

			// read the response stream AND buffer the result into a StringBuffer
			inputStreamReader = new InputStreamReader(httpURLConnection.getInputStream());
			bufferedReader = new BufferedReader(inputStreamReader);

			// reading the XML response content line BY line
			while ((readSingleLine = bufferedReader.readLine()) != null) {
		catch (IOException ioex) {
			throw ioex;
			// finally close all operations
		return stringBuffer.toString();

Output in console

Response code: 200
ResponseMessageFromServer: OK
Response String : 
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
		<MusicResponseType xmlns="http://benchresources.in/entities/music">
			<movieName>Thiruda Thiruda</movieName>
			<director>Mani Ratnam</director>
			<comments>Comedy Thriller</comments>

Conclusion: Thus, we have implemented & understood SOAP based Web Service implementation using top-down approach integrating with Spring framework

In the next article, we will extend same example demonstrated here and enhance this code to perform database operations using rich Hibernate ORM framework

Download project

ApacheCXF-JAX-WS-Top-Down-Spring-Integration (17kB)

Happy Coding !!
Happy Learning !!

Apache CXF JAX-WS: SOAP based Web Service using Top-Down approach + Integrating with Spring & Hibernate ORM framework
Apache CXF JAX-WS: Web Service using Top-Down approach + Adding CXF interceptors using UsernameToken