Technology weblog

Thursday Apr 14, 2011

Spring-WS and Exception Handling through wsdl:fault - Part 1

I have learned, eventhough the spring-ws documentation is pretty clear, still alot of features are not properly documented. In this post I will focus on creating a demo webservice using Spring-WS 2. I will provide code samples for all elements required to get all exception code where you want it. All this information is based on contract-first webservice development. Here we focus on the XSD's required and how to create your WSDL from those XSD's. This post is divided into 3 parts. This post is part 1. 


During this post we will follow below steps:

  1. Project structure (part 1)
  2. Creating domain related XSDs (part 1)
  3. Creating exception specific XSDs (part 1)
  4. Creating the wsdl specific XSD (part 1)
  5. Creating a Spring-WS webapp (part 2)
  6. Configuring the WSDL (part 2)
  7. Coding Endpoint class to handle a WebService operation (part 2)
  8. Exception resolving (setting fault detail) (part 2)
  9. Handling multiple exceptions via multiple wsdl:fault elements (part 3)
  10. Adding Security (part 3)
  11. Versioning/Backwards compatibility (part 3)
  12. Writing a client... (part 3)

1. Project structure

+-+ project-directory
  +-+ src
  | +-+ main
  |   +-- java (Sources for the endpoint service class)
  |   +-- resources (XSD files)
  |   +-+ webapp
  |     +-- WEB-INF (web.xml and spring config file)
  +-+ target
  | +-+ generated-sources
  |   +-- xjc (generated sources from XSD files)
  +-- pom.xml (maven config)

2. Creating domain related XSDs

When providing a WebService we need to focus on what information we want to share from business domain. Following XSD is an example of what it could look like (base.xsd):

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs=""
	targetNamespace="" xmlns=""
<xs:complexType name="AddressType"> <xs:sequence> <xs:element name="street" type="xs:string" /> <xs:element name="houseNumber" type="xs:int" /> <xs:element name="houseNumberExtension" type="xs:string" minOccurs="0" /> <xs:element name="zipCode" type="xs:string" /> <xs:element name="city" type="xs:string" /> </xs:sequence> </xs:complexType> </xs:schema>

Following schema is a domain related (user.xsd):

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="" 

	<xs:import namespace="" schemaLocation="base.xsd"/>
	<xs:complexType name="UserType">
<xs:sequence> <xs:element name="name" type="xs:string"/> <xs:element name="username" type="xs:string"/>
<xs:element name="address" type="base:AddressType"/>
<xs:element name="groups" type="GroupsType" minOccurs="0"/> </xs:sequence> </xs:complexType>
	<xs:complexType name="GroupsType">
			<xs:element name="groups" type="GroupType" maxOccurs="unbounded"/>
<xs:complexType name="GroupType"> <xs:sequence> <xs:element name="name" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:schema>

3. Creating exception specific XSD


To do exception handling for WebServices you need to provide XSD information that can be used as soap fault details content.

Following is an example of an exception XSD (exception.xsd):

 <?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs=""
	targetNamespace="" xmlns=""
	<xs:complexType name="ExceptionsType">
			<xs:element name="userNameInvalidException" type="UserNameInvalidExceptionType" />
<!-- add many more --> </xs:choice> </xs:complexType> <xs:complexType name="UserNameInvalidExceptionType"> <xs:sequence> <xs:element name="message" type="xs:string" /> </xs:sequence> </xs:complexType> </xs:schema>

4. Creating wsdl specific XSD

Spring-WS can provide the WSDL in 2 ways:

  1. static - A WSDL created by hand
  2. dynamic - A WSDL generated by Spring-WS using an XSD using naming conventions 

 We will use the dynamic WSDL part. The actual naming conventions possible are not documented anywhere I could find. But searching through the sources I found below elements that apply:

  • xxxRequest - request message info
  • xxxResponse - response message info
  • xxxFault - fault message info

Here xxx will be the service method created in the WSDL.

Following is an example of a WSDL XSD (userservice.xsd):

 <?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs=""
xmlns:exception="" elementFormDefault="qualified"> <xs:import namespace="" schemaLocation="base.xsd"/> <xs:import namespace="" schemaLocation="user.xsd"/>
<xs:import namespace="" schemaLocation="exception.xsd"/> <xs:element name="getUsersByNameRequest"> <xs:complexType> <xs:sequence> <xs:element name="name" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="getUsersByNameResponse"> <xs:complexType> <xs:sequence> <xs:element name="users" type="UsersType"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="getUsersByNameFault"> <xs:complexType> <xs:sequence> <xs:element name="exceptions" type="exception:ExceptionsType"/> </xs:sequence> </xs:complexType> </xs:element> <xs:complexType name="UsersType"> <xs:sequence> <xs:element name="user" type="user:UserType" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:schema>

5. Creating a Spring-WS webapp

This paragraph will be described in part 2 of this post, coming soon. I hope people can appreciate the information I share here and hope they will enjoy developing WebService using Spring-WS with included exception handling. 





Post a Comment:
Comments are closed for this entry.

Hire us