09/03/2022 08:43 Spring Web Services Reference Documentation

Spring Web Services Reference Documentation

Authors
Arjen Poutsma
, Rick Evans
, Tareq Abed Rabbo

2.4.0.RELEASE

Copyright © 2005-2014
Copies of this document may be made for your own use and for distribution
to others, provided that you do not charge any fee for such copies and
further provided that each copy contains this Copyright Notice, whether
distributed in print or electronically.

Table of Contents

Preface

I. Introduction
1. What is Spring Web Services?
1.1. Introduction
1.2. Runtime environment
1.3. Supported standards

2. Why Contract First?

2.1. Introduction
2.2. Object/XML Impedance Mismatch
2.2.1. XSD extensions
2.2.2. Unportable types
2.2.3. Cyclic graphs

2.3. Contract-first versus Contract-last

2.3.1. Fragility
2.3.2. Performance
2.3.3. Reusability
2.3.4. Versioning

3. Writing Contract-First Web Services

3.1. Introduction
3.2. Messages
3.2.1. Holiday
3.2.2. Employee
3.2.3. HolidayRequest

3.3. Data Contract

3.4. Service contract
3.5. Creating the project
3.6. Implementing the Endpoint
3.6.1. Handling the XML Message
3.6.2. Routing the Message to the Endpoint
3.6.3. Providing the Service and Stub implementation

https://docs.spring.io/spring-ws/docs/2.4.0.RELEASE/reference/htmlsingle/ 1/71
09/03/2022 08:43 Spring Web Services Reference Documentation

3.7. Publishing the WSDL

II. Reference
4. Shared components
4.1. Web service messages
4.1.1. WebServiceMessage
4.1.2. SoapMessage
4.1.3. Message Factories
SaajSoapMessageFactory
AxiomSoapMessageFactory
SOAP 1.1 or 1.2
4.1.4. MessageContext

4.2. TransportContext

4.3. Handling XML With XPath

4.3.1. XPathExpression
4.3.2. XPathTemplate

4.4. Message Logging and Tracing

5. Creating a Web service with Spring-WS

5.1. Introduction
5.2. The MessageDispatcher

5.3. Transports
5.3.1. MessageDispatcherServlet
Automatic WSDL exposure
5.3.2. Wiring up Spring-WS in a DispatcherServlet
5.3.3. JMS transport
5.3.4. Email transport
5.3.5. Embedded HTTP Server transport
5.3.6. XMPP transport
5.3.7. MTOM

5.4. Endpoints
5.4.1. @Endpoint handling methods
Handling method parameters
Handling method return types

5.5. Endpoint mappings

5.5.1. WS-Addressing
AnnotationActionEndpointMapping
5.5.2. Intercepting requests - the EndpointInterceptor interface
PayloadLoggingInterceptor and
SoapEnvelopeLoggingInterceptor
PayloadValidatingInterceptor
PayloadTransformingInterceptor

5.6. Handling Exceptions

5.6.1. SoapFaultMappingExceptionResolver
5.6.2. SoapFaultAnnotationExceptionResolver

5.7. Server-side testing

5.7.1. Writing server-side integration tests
5.7.2. RequestCreator and RequestCreators
5.7.3. ResponseMatcher and ResponseMatchers

6. Using Spring Web Services on the Client

6.1. Introduction
6.2. Using the client-side API
6.2.1. WebServiceTemplate
URIs and Transports
Message factories
6.2.2. Sending and receiving a WebServiceMessage
6.2.3. Sending and receiving POJOs - marshalling and unmarshalling

https://docs.spring.io/spring-ws/docs/2.4.0.RELEASE/reference/htmlsingle/ 2/71
09/03/2022 08:43 Spring Web Services Reference Documentation
6.2.4.
WebServiceMessageCallback
WS-Addressing
6.2.5.
WebServiceMessageExtractor

6.3. Client-side testing

6.3.1. Writing client-side integration tests
6.3.2. RequestMatcher and RequestMatchers
6.3.3. ResponseCreator and ResponseCreators

7. Securing your Web services with Spring-WS

7.1. Introduction
7.2.
XwsSecurityInterceptor
7.2.1. Keystores
KeyTool
KeyStoreFactoryBean
KeyStoreCallbackHandler
7.2.2. Authentication
Plain Text Username Authentication
Digest Username Authentication
Certificate Authentication
7.2.3. Digital Signatures
Verifying Signatures
Signing Messages
7.2.4. Encryption and Decryption
Decryption
Encryption
7.2.5. Security Exception Handling

7.3.
Wss4jSecurityInterceptor
7.3.1. Configuring
Wss4jSecurityInterceptor
7.3.2. Handling Digital Certificates
CryptoFactoryBean
7.3.3. Authentication
Validating Username Token
Adding Username Token
Certificate Authentication
7.3.4. Security Timestamps
Validating Timestamps
Adding Timestamps
7.3.5. Digital Signatures
Verifying Signatures
Signing Messages
Signature Confirmation
7.3.6. Encryption and Decryption
Decryption
Encryption
7.3.7. Security Exception Handling

III. Other Resources

Bibliography

Preface
In the current age of Service Oriented Architectures, more and more people are using Web Services to
connect previously
unconnected systems. Initially, Web services were considered to be just another way to do
a Remote Procedure Call (RPC).
Over time however, people found out that there is a big difference
between RPCs and Web services. Especially when
interoperability with other platforms is important, it is often
better to send encapsulated XML documents, containing all the data
necessary to process the request.
Conceptually, XML-based Web services are better off being compared to message queues

https://docs.spring.io/spring-ws/docs/2.4.0.RELEASE/reference/htmlsingle/ 3/71
09/03/2022 08:43 Spring Web Services Reference Documentation

rather than remoting

solutions.
Overall, XML should be considered the platform-neutral representation of data, the
interlingua of
SOA. When developing or using Web services, the focus should be
on this XML, and not on Java.

Spring Web Services focuses on creating these document-driven Web services.

Spring Web Services facilitates contract-first
SOAP service development, allowing for the creation of
flexible web services using one of the many ways to manipulate XML
payloads.
Spring-WS provides a powerful message dispatching framework, a WS-Security solution that integrates with your
existing application security
solution, and a Client-side API that follows the familiar Spring template pattern.

Part I. Introduction
This first part of the reference documentation
is an overview of
Spring Web Services and the underlying concepts. Spring-WS is
then introduced, and the concepts
behind contract-first Web service development are explained.

1. What is Spring Web Services?

1.1 Introduction
Spring Web Services (Spring-WS) is a product of the Spring community focused on creating document-driven
Web services.
Spring Web Services aims to facilitate contract-first SOAP service development, allowing for the creation of
flexible web services
using one of the many ways to manipulate XML payloads.
The product is based on Spring itself, which means you can use the
Spring concepts such as dependency
injection as an integral part of your Web service.

People use Spring-WS for many reasons, but most are drawn to it after finding alternative SOAP stacks
lacking when it comes to
following Web service best practices.
Spring-WS makes the best practice an easy practice. This includes practices such as the
WS-I basic profile,
Contract-First development, and having a loose coupling between contract and implementation.
The other key
features of Spring Web services are:

Powerful mappings. 
You can distribute incoming XML requests to any object, depending on message payload, SOAP Action
header,
or an XPath expression.

XML API support. 

Incoming XML messages can be handled not only with standard JAXP APIs such as DOM, SAX, and StAX,
but also JDOM,
dom4j, XOM, or even marshalling technologies.

Flexible XML Marshalling. 

Spring Web Services builds on the Object/XML Mapping module in the Spring Framework, which
supports JAXB 1 and 2, Castor,
XMLBeans, JiBX, and XStream.

Reuses your Spring expertise. 

Spring-WS uses Spring application contexts for all configuration, which should help Spring
developers
get up-to-speed nice and quickly. Also, the architecture of Spring-WS resembles that of Spring-MVC.

Supports WS-Security. 
WS-Security allows you to sign SOAP messages, encrypt and decrypt them, or authenticate against
them.

Integrates with Spring Security. 

The WS-Security implementation of Spring Web Services provides integration with Spring
Security.
This means you can use your existing Spring Security configuration for your SOAP service as well.

Apache license. 
You can confidently use Spring-WS in your project.

1.2 Runtime environment
Spring Web Services requires a standard Java 7 Runtime Environment. Java 8 is also supported.
Spring-WS is built on Spring
Framework 4.0.9, but higher versions are supported.

Spring-WS consists of a number of modules, which are described in the remainder of this section.

https://docs.spring.io/spring-ws/docs/2.4.0.RELEASE/reference/htmlsingle/ 4/71
09/03/2022 08:43 Spring Web Services Reference Documentation

The XML module ( spring-xml.jar ) contains various XML support classes for Spring Web
Services. This module is mainly
intended for the Spring-WS framework itself, and not a Web service
developers.
The Core module ( spring-ws-core.jar ) is the central part of the Spring's
Web services functionality.
It provides the
central WebServiceMessage and SoapMessage interfaces, the server-side
framework, with powerful message dispatching,
and the various support classes for implementing Web
service endpoints; and the client-side
WebServiceTemplate .
The Support module ( spring-ws-support.jar ) contains additional transports
(JMS, Email, and others).
The Security package ( spring-ws-security.jar )
provides a WS-Security implementation that integrates
with the core
Web service package. It allows you to add principal tokens, sign, and decrypt and encrypt SOAP
messages. Additionally, it
allows you to leverage your existing Spring Security security implementation for
authentication and authorization.

The following figure illustrates the Spring-WS modules and the dependencies between them. Arrows indicate
dependencies, i.e.
Spring-WS Core depends on Spring-XML and the OXM module found in Spring 3 and higher.

Dependencies between Spring-WS modules

1.3 Supported standards
Spring Web Services supports the following standards:

SOAP 1.1 and 1.2

WSDL 1.1 and 2.0 (XSD-based generation only supported for WSDL 1.1)
WS-I Basic Profile 1.0, 1.1, 1.2 and 2.0
WS-Addressing 1.0 and the August 2004 draft
SOAP Message Security 1.1, Username Token Profile 1.1, X.509 Certificate Token Profile 1.1, SAML Token Profile 1.1,
Kerberos Token Profile 1.1, Basic Security Profile 1.1

2. Why Contract First?

2.1 Introduction
When creating Web services, there are two development styles: Contract Last and
Contract First. When using a contract-last
approach, you start with the Java code, and
let the Web service contract (WSDL, see sidebar) be generated from that.
When
using contract-first, you start with the WSDL contract, and use Java to implement said contract.

What is WSDL?

WSDL stands for Web Services Description Language. A WSDL file is an XML document that describes a Web
service. It
specifies the location of the service and the operations (or methods) the service exposes.
For more information about
WSDL, refer to the
WSDL specification.

Spring-WS only supports the contract-first development style, and this section explains why.

2.2 Object/XML Impedance Mismatch

Similar to the field of ORM, where we have an
Object/Relational impedance mismatch,
there is a similar problem when
converting Java objects to XML.
At first glance, the O/X mapping problem appears simple: create an XML element for each Java
object,
converting all Java properties and fields to sub-elements or attributes. However, things are not as
simple as they appear:

https://docs.spring.io/spring-ws/docs/2.4.0.RELEASE/reference/htmlsingle/ 5/71
09/03/2022 08:43 Spring Web Services Reference Documentation

there is a fundamental difference between hierarchical languages such as XML

(and especially XSD) and the graph model of
Java[1].

2.2.1 XSD extensions
In Java, the only way to change the behavior of a class is to subclass it, adding the new behavior to
that subclass. In XSD, you
can extend a data type by restricting it: that is, constraining the valid values
for the elements and attributes.
For instance,
consider the following example:

<simpleType name="AirportCode">

<restriction base="string">

<pattern value="[A-Z][A-Z][A-Z]"/>

</restriction>

</simpleType>

This type restricts a XSD string by ways of a regular expression, allowing only three upper case
letters. If this type is converted to
Java, we will end up with an ordinary
java.lang.String ; the regular expression is lost in the conversion process,
because
Java does not allow for these sorts of extensions.

2.2.2 Unportable types
One of the most important goals of a Web service is to be interoperable: to support multiple platforms
such as Java, .NET,
Python, etc. Because all of these languages have different class libraries, you
must use some common, interlingual format to
communicate between them. That format is XML, which is
supported by all of these languages.

Because of this conversion, you must make sure that you use portable types in your service
implementation. Consider, for
example, a service that returns a
java.util.TreeMap , like so:

public Map getFlights() {

// use a tree map, to make sure it's sorted

TreeMap map = new TreeMap();

map.put("KL1117", "Stockholm");

...

return map;

Undoubtedly, the contents of this map can be converted into some sort of
XML, but since there is no standard way to describe a
map in XML, it will be
proprietary. Also, even if it can be converted to XML, many platforms do not have a data structure
similar to
the TreeMap . So when a .NET client accesses your Web service, it
will probably end up with a
System.Collections.Hashtable , which has different
semantics.

This problem is also present when working on the client side. Consider the following XSD snippet, which
describes a service
contract:

<element name="GetFlightsRequest">

<complexType>

<all>

<element name="departureDate" type="date"/>

<element name="from" type="string"/>

<element name="to" type="string"/>

</all>

</complexType>

</element>

This contract defines a request that takes an date, which is a XSD datatype representing
a year, month, and day. If we call this
service from Java, we will probably use
either a java.util.Date or java.util.Calendar . However,
both of these classes
actually describe times, rather than dates. So, we will actually end up sending data that
represents the fourth of April 2007 at
midnight ( 2007-04-04T00:00:00 ), which is not
the same as 2007-04-04 .

https://docs.spring.io/spring-ws/docs/2.4.0.RELEASE/reference/htmlsingle/ 6/71
09/03/2022 08:43 Spring Web Services Reference Documentation

2.2.3 Cyclic graphs
Imagine we have the following simple class structure:

public class Flight {

private String number;

private List<Passenger> passengers;

// getters and setters omitted

public class Passenger {

private String name;

private Flight flight;

// getters and setters omitted

This is a cyclic graph: the Flight refers to the Passenger ,

which refers to the Flight again. Cyclic graphs like these are
quite common in
Java. If we took a naive approach to converting this to XML, we will end up with something
like:

<flight number="KL1117">

<passengers>

<passenger>

<name>Arjen Poutsma</name>

<flight number="KL1117">

<passengers>

<passenger>

<name>Arjen Poutsma</name>

<flight number="KL1117">

<passengers>

<passenger>

<name>Arjen Poutsma</name>

...

which will take a pretty long time to finish, because there is no stop condition for this loop.

One way to solve this problem is to use references to objects that were already marshalled, like
so:

<flight number="KL1117">

<passengers>

<passenger>

<name>Arjen Poutsma</name>

<flight href="KL1117" />

</passenger>

...

</passengers>

</flight>

This solves the recursiveness problem, but introduces new ones. For one, you cannot use an XML validator
to validate this
structure. Another issue is that the standard way to use these references in SOAP
(RPC/encoded) has been deprecated in favor
of document/literal (see WS-I
Basic
Profile).

These are just a few of the problems when dealing with O/X mapping. It is important to respect these issues
when writing Web
services. The best way to respect them is to focus on the XML completely, while using Java
as an implementation language. This
is what contract-first is all about.

2.3 Contract-first versus Contract-last

Besides the Object/XML Mapping issues mentioned in the previous section, there are other reasons for
preferring a contract-first
development style.

https://docs.spring.io/spring-ws/docs/2.4.0.RELEASE/reference/htmlsingle/ 7/71
09/03/2022 08:43 Spring Web Services Reference Documentation

2.3.1 Fragility
As mentioned earlier, the contract-last development style results in your web service contract
(WSDL and your XSD) being
generated from your Java contract (usually an interface). If you are using
this approach, you will have no guarantee that the
contract stays constant over time. Each time you
change your Java contract and redeploy it, there might be subsequent changes
to the web service
contract.

Aditionally, not all SOAP stacks generate the same web service contract from a Java contract. This
means changing your current
SOAP stack for a different one (for whatever reason), might also change
your web service contract.

When a web service contract changes, users of the contract will have to be instructed to obtain
the new contract and potentially
change their code to accommodate for any changes in the contract.

In order for a contract to be useful, it must remain constant for as long as possible. If a contract
changes, you will have to contact
all of the users of your service, and instruct them to get the new
version of the contract.

2.3.2 Performance
When Java is automatically transformed into XML, there is no way to be sure as to what is sent across
the wire. An object might
reference another object, which refers to another, etc. In the end, half of
the objects on the heap in your virtual machine might be
converted into XML,
which will result in slow response times.

When using contract-first, you explicitly describe what XML is sent where, thus making sure that it is
exactly what you want.

2.3.3 Reusability
Defining your schema in a separate file allows you to reuse that file in different scenarios. If you
define an AirportCode in a file
called airline.xsd , like so:

<simpleType name="AirportCode">

<restriction base="string">

<pattern value="[A-Z][A-Z][A-Z]"/>

</restriction>

</simpleType>

You can reuse this definition in other schemas, or even WSDL files, using an
import statement.

2.3.4 Versioning
Even though a contract must remain constant for as long as possible, they do need
to be changed sometimes. In Java, this
typically results in a new Java interface, such as
AirlineService2 , and a (new) implementation of that interface. Of
course,
the old service must be kept around, because there might be clients who have not migrated
yet.

If using contract-first, we can have a looser coupling between contract and implementation. Such a
looser coupling allows us to
implement both versions of the contract in one class. We could, for
instance, use an XSLT stylesheet to convert any "old-style"
messages to the "new-style" messages.

[1] Most of the contents in this section was inspired by [alpine] and
[effective-enterprise-java].

3. Writing Contract-First Web Services

3.1 Introduction
This tutorial shows you how to write
contract-first Web services, that is,
developing web services that start with the XML
Schema/WSDL contract first
followed by the Java code second. Spring-WS focuses on this development style,
and this tutorial

https://docs.spring.io/spring-ws/docs/2.4.0.RELEASE/reference/htmlsingle/ 8/71
09/03/2022 08:43 Spring Web Services Reference Documentation

will help you get started. Note that the first part of this
tutorial contains almost no Spring-WS specific information: it is mostly
about
XML, XSD, and WSDL. The second part
focuses on implementing this contract using Spring-WS .

The most important thing when doing contract-first Web service development is
to try and think in terms of XML. This means that
Java-language concepts are
of lesser importance. It is the XML that is sent across the wire, and you
should focus on that. The
fact that Java is used to implement the Web service
is an implementation detail. An important detail, but a detail nonetheless.

In this tutorial, we will define a Web service that is created by a Human Resources
department. Clients can send holiday request
forms to this service to book a holiday.

3.2 Messages
In this section, we will focus on the actual XML messages that are sent to
and from the Web service. We will start out by
determining what these messages
look like.

3.2.1 Holiday
In the scenario, we have to deal with holiday requests, so it makes sense
to determine what a holiday looks like in XML:

<Holiday xmlns="http://mycompany.com/hr/schemas">

<StartDate>2006-07-03</StartDate>

<EndDate>2006-07-07</EndDate>

</Holiday>

A holiday consists of a start date and an end date. We have also decided to
use the standard
ISO 8601
date format for the
dates, because that will save a lot of parsing hassle.
We have also added a namespace to the element, to make sure our
elements
can used within other XML documents.

3.2.2 Employee
There is also the notion of an employee in the scenario. Here is what it
looks like in XML:

<Employee xmlns="http://mycompany.com/hr/schemas">

<Number>42</Number>

<FirstName>Arjen</FirstName>

<LastName>Poutsma</LastName>

</Employee>

We have used the same namespace as before. If this

<Employee/> element could be used in other
scenarios, it might make
sense to use a different namespace, such as
http://mycompany.com/employees/schemas .

3.2.3 HolidayRequest
Both the holiday and employee element can be put in a
<HolidayRequest/> :

<HolidayRequest xmlns="http://mycompany.com/hr/schemas">

<Holiday>

<StartDate>2006-07-03</StartDate>

<EndDate>2006-07-07</EndDate>

</Holiday>

<Employee>

<Number>42</Number>

<FirstName>Arjen</FirstName>

<LastName>Poutsma</LastName>

</Employee>

</HolidayRequest>

The order of the two elements does not matter: <Employee/>

could have been the first element just as well. What is important
is
that all of the data is there. In fact, the data is the only thing
that is important: we are taking a data-driven
approach.

https://docs.spring.io/spring-ws/docs/2.4.0.RELEASE/reference/htmlsingle/ 9/71
09/03/2022 08:43 Spring Web Services Reference Documentation

3.3 Data Contract
Now that we have seen some examples of the XML data that we will use,
it makes sense to formalize this into a schema. This
data contract
defines the message format we accept. There are four different ways
of defining such a contract for XML:

DTDs
XML Schema (XSD)
RELAX NG
Schematron

DTDs have limited namespace support, so they are not suitable for Web
services. Relax NG and Schematron certainly are easier
than XML Schema.
Unfortunately, they are not so widely supported across platforms. We
will use XML Schema.

By far the easiest way to create an XSD is to infer it from sample

documents. Any good XML editor or Java IDE offers this
functionality.
Basically, these tools use some sample XML documents, and generate a
schema from it that validates them all. The
end result certainly needs
to be polished up, but it's a great starting point.

Using the sample described above, we end up with the following

generated schema:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"

elementFormDefault="qualified"

targetNamespace="http://mycompany.com/hr/schemas"

xmlns:hr="http://mycompany.com/hr/schemas">

<xs:element name="HolidayRequest">

<xs:complexType>

<xs:sequence>

<xs:element ref="hr:Holiday"/>

<xs:element ref="hr:Employee"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="Holiday">

<xs:complexType>

<xs:sequence>

<xs:element ref="hr:StartDate"/>

<xs:element ref="hr:EndDate"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="StartDate" type="xs:NMTOKEN"/>

<xs:element name="EndDate" type="xs:NMTOKEN"/>

<xs:element name="Employee">

<xs:complexType>

<xs:sequence>

<xs:element ref="hr:Number"/>

<xs:element ref="hr:FirstName"/>

<xs:element ref="hr:LastName"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="Number" type="xs:integer"/>

<xs:element name="FirstName" type="xs:NCName"/>

<xs:element name="LastName" type="xs:NCName"/>

</xs:schema>

This generated schema obviously can be improved. The first thing

to notice is that every type has a root-level element
declaration.
This means that the Web service should be able to accept all of
these elements as data. This is not desirable: we
only want to
accept a <HolidayRequest/> . By removing
the wrapping element tags (thus keeping the types), and inlining
the
results, we can accomplish this.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:hr="http://mycompany.com/hr/schemas"

elementFormDefault="qualified"

targetNamespace="http://mycompany.com/hr/schemas">

https://docs.spring.io/spring-ws/docs/2.4.0.RELEASE/reference/htmlsingle/ 10/71