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

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.

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.

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.

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

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.

You can confidently use Spring-WS in your project.

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:

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.

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:

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:

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.

Imagine we have the following simple class structure:

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:

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:

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.

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.

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.

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:

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

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.

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

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.

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

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.

Both the holiday and employee element can be put in a <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.

In this sample application, we are going to use JDom 2 to handle the XML message. We are also using XPath, because it allows us to select particular parts of the XML JDOM tree, without requiring strict schema conformance.

Using JDOM is just one of the options to handle the XML: other options include DOM, dom4j, XOM, SAX, and StAX, but also marshalling techniques like JAXB, Castor, XMLBeans, JiBX, and XStream, as is explained in the next chapter. We chose JDOM because it gives us access to the raw XML, and because it is based on classes (not interfaces and factory methods as with W3C DOM and dom4j), which makes the code less verbose. We use XPath because it is less fragile than marshalling technologies: we don’t care for strict schema conformance, as long as we can find the dates and the name.

Because we use JDOM, we must add some dependencies to the Maven pom.xml, which is in the root of our project directory. Here is the relevant section of the POM:

Here is how we would configure these classes in our spring-ws-servlet.xml Spring XML configuration file, by using component scanning. We also instruct Spring-WS to use annotation-driven endpoints, with the <sws:annotation-driven> element.

As part of writing the endpoint, we also used the @PayloadRoot annotation to indicate which sort of messages can be handled by the handleHolidayRequest method. In Spring-WS, this process is the responsibility of an EndpointMapping. Here we route messages based on their content, by using a PayloadRootAnnotationMethodEndpointMapping. The annotation used above:

basically means that whenever an XML message is received with the namespace http://mycompany.com/hr/schemas and the HolidayRequest local name, it will be routed to the handleHolidayRequest method. By using the <sws:annotation-driven> element in our configuration, we enable the detection of the @PayloadRoot annotations. It is possible (and quite common) to have multiple, related handling methods in an endpoint, each of them handling different XML messages.

There are also other ways to map endpoints to XML messages, which will be described in the next chapter.

Now that we have the Endpoint, we need HumanResourceService and its implementation for use by HolidayEndpoint.

For tutorial purposes, we will use a simple stub implementation of the HumanResourceService.

One of the core interfaces of Spring Web Services is the WebServiceMessage. This interface represents a protocol-agnostic XML message. The interface contains methods that provide access to the payload of the message, in the form of a javax.xml.transform.Source or a javax.xml.transform.Result. Source and Result are tagging interfaces that represent an abstraction over XML input and output. Concrete implementations wrap various XML representations, as indicated in the following table.

In addition to reading from and writing to the payload, a Web service message can write itself to an output stream.

The SoapMessage is a subclass of WebServiceMessage. It contains SOAP-specific methods, such as getting SOAP Headers, SOAP Faults, etc. Generally, your code should not be dependent on SoapMessage, because the content of the SOAP Body (the payload of the message) can be obtained via getPayloadSource() and getPayloadResult() in the WebServiceMessage. Only when it is necessary to perform SOAP-specific actions, such as adding a header, getting an attachment, etc., should you need to cast WebServiceMessage to SoapMessage.

Concrete message implementations are created by a WebServiceMessageFactory. This factory can create an empty message, or read a message based on an input stream. There are two concrete implementations of WebServiceMessageFactory; one is based on SAAJ, the SOAP with Attachments API for Java, the other based on Axis 2’s AXIOM, the AXis Object Model.

Typically, messages come in pairs: a request and a response. A request is created on the client-side, which is sent over some transport to the server-side, where a response is generated. This response gets sent back to the client, where it is read.

In Spring Web Services, such a conversation is contained in a MessageContext, which has properties to get request and response messages. On the client-side, the message context is created by the WebServiceTemplate. On the server-side, the message context is read from the transport-specific input stream. For example, in HTTP, it is read from the HttpServletRequest and the response is written back to the HttpServletResponse.

The XPathExpression is an abstraction over a compiled XPath expression, such as the Java 5 javax.xml.xpath.XPathExpression, or the Jaxen XPath class. To construct an expression in an application context, there is the XPathExpressionFactoryBean. Here is an example which uses this factory bean:

The expression above does not use namespaces, but we could set those using the namespaces property of the factory bean. The expression can be used in the code as follows:

For a more flexible approach, you can use a NodeMapper, which is similar to the RowMapper in Spring’s JDBC support. The following example shows how we can use it:

Similar to mapping rows in Spring JDBC’s RowMapper, each result node is mapped using an anonymous inner class. In this case, we create a Contact object, which we use later on.

The XPathExpression only allows you to evaluate a single, pre-compiled expression. A more flexible, though slower, alternative is the XpathTemplate. This class follows the common template pattern used throughout Spring (JdbcTemplate, JmsTemplate, etc.). Here is an example:

The MessageDispatcherServlet is a standard Servlet which conveniently extends from the standard Spring Web DispatcherServlet, and wraps a MessageDispatcher. As such, it combines the attributes of these into one: as a MessageDispatcher, it follows the same request handling flow as described in the previous section. As a servlet, the MessageDispatcherServlet is configured in the web.xml of your web application. Requests that you want the MessageDispatcherServlet to handle will have to be mapped using a URL mapping in the same web.xml file. This is standard Java EE servlet configuration; an example of such a MessageDispatcherServlet declaration and mapping can be found below.

In the example above, all requests will be handled by the 'spring-ws' MessageDispatcherServlet. This is only the first step in setting up Spring Web Services, because the various component beans used by the Spring-WS framework also need to be configured; this configuration consists of standard Spring XML <bean/> definitions. Because the MessageDispatcherServlet is a standard Spring DispatcherServlet, it will look for a file named [servlet-name]-servlet.xml in the WEB-INF directory of your web application and create the beans defined there in a Spring container. In the example above, that means that it looks for ‘/WEB-INF/spring-ws-servlet.xml’. This file will contain all of the Spring Web Services beans such as endpoints, marshallers and suchlike.

As an alternative for web.xml, if you are running on a Servlet 3+ environment, you can configure Spring-WS programmatically. For this purpose, Spring-WS provides a number of abstract base classes that extend the WebApplicationInitializer interface found in the Spring Framework. If you are also using @Configuration classes for your bean definitions, you are best of extending the AbstractAnnotationConfigMessageDispatcherServletInitializer, like so:

In the example above, we tell Spring that endpoint bean definitions can be found in the MyEndpointConfig class (which is a @Configuration class). Other bean definitions (typically services, repositories, etc.) can be found in the MyRootConfig class. By default, the AbstractAnnotationConfigMessageDispatcherServletInitializer maps the servlet to two patterns: /services and *.wsdl, though this can be changed by overriding the getServletMappings() method. For more details on the programmatic configuration of the MessageDispatcherServlet, refer to the Javadoc of AbstractMessageDispatcherServletInitializer and AbstractAnnotationConfigMessageDispatcherServletInitializer.

As an alternative to the MessageDispatcherServlet, you can wire up a MessageDispatcher in a standard, Spring-Web MVC DispatcherServlet. By default, the DispatcherServlet can only delegate to Controllers, but we can instruct it to delegate to a MessageDispatcher by adding a WebServiceMessageReceiverHandlerAdapter to the servlet’s web application context:

Note that by explicitly adding the WebServiceMessageReceiverHandlerAdapter, the dispatcher servlet does not load the default adapters, and is unable to handle standard Spring-MVC @Controllers. Therefore, we add the RequestMappingHandlerAdapter at the end.

In a similar fashion, you can wire up a WsdlDefinitionHandlerAdapter to make sure the DispatcherServlet can handle implementations of the WsdlDefinition interface:

Spring Web Services supports server-side JMS handling through the JMS functionality provided in the Spring framework. Spring Web Services provides the WebServiceMessageListener to plug in to a MessageListenerContainer. This message listener requires a WebServiceMessageFactory to and MessageDispatcher to operate. The following piece of configuration shows this:

In addition to HTTP and JMS, Spring Web Services also provides server-side email handling. This functionality is provided through the MailMessageReceiver class. This class monitors a POP3 or IMAP folder, converts the email to a WebServiceMessage, sends any response using SMTP. The host names can be configured through the storeUri, which indicates the mail folder to monitor for requests (typically a POP3 or IMAP folder), and a transportUri, which indicates the server to use for sending responses (typically a SMTP server).

How the MailMessageReceiver monitors incoming messages can be configured with a pluggable strategy: the MonitoringStrategy. By default, a polling strategy is used, where the incoming folder is polled for new messages every five minutes. This interval can be changed by setting the pollingInterval property on the strategy. By default, all MonitoringStrategy implementations delete the handled messages; this can be changed by setting the deleteMessages property.

As an alternative to the polling approaches, which are quite inefficient, there is a monitoring strategy that uses IMAP IDLE. The IDLE command is an optional expansion of the IMAP email protocol that allows the mail server to send new message updates to the MailMessageReceiver asynchronously. If you use a IMAP server that supports the IDLE command, you can plug in the ImapIdleMonitoringStrategy into the monitoringStrategy property. In addition to a supporting server, you will need to use JavaMail version 1.4.1 or higher.

The following piece of configuration shows how to use the server-side email support, overiding the default polling interval to a value which checks every 30 seconds (30.000 milliseconds):

Spring Web Services provides a transport based on Sun’s JRE 1.6 HTTP server. The embedded HTTP Server is a standalone server that is simple to configure. It lends itself to a lighter alternative to conventional servlet containers.

When using the embedded HTTP server, no external deployment descriptor is needed (web.xml). You only need to define an instance of the server and configure it to handle incoming requests. The remoting module in the Core Spring Framework contains a convenient factory bean for the HTTP server: the SimpleHttpServerFactoryBean. The most important property is contexts, which maps context paths to corresponding `HttpHandler`s.

Spring Web Services provides 2 implementations of the HttpHandler interface: WsdlDefinitionHttpHandler and WebServiceMessageReceiverHttpHandler. The former maps an incoming GET request to a WsdlDefinition. The latter is responsible for handling POST requests for web services messages and thus needs a WebServiceMessageFactory (typically a SaajSoapMessageFactory) and a WebServiceMessageReceiver (typically the SoapMessageDispatcher) to accomplish its task.

To draw parallels with the servlet world, the contexts property plays the role of servlet mappings in web.xml and the WebServiceMessageReceiverHttpHandler is the equivalent of a MessageDispatcherServlet.

The following snippet shows a simple configuration example of the HTTP server transport:

For more information on the SimpleHttpServerFactoryBean, refer to the Javadoc.

Finally, Spring Web Services 2.0 introduced support for XMPP, otherwise known as Jabber. The support is based on the Smack library.

Spring Web Services support for XMPP is very similar to the other transports: there is a a XmppMessageSender for the WebServiceTemplate and and a XmppMessageReceiver to use with the MessageDispatcher.

The following example shows how to set up the server-side XMPP components:

MTOM is the mechanism of sending binary data to and from Web Services. You can look at how to implement this with Spring WS through the MTOM sample.

In order for an endpoint to actually handle incoming XML messages, it needs to have one or more handling methods. Handling methods can take wide range of parameters and return types, but typically they have one parameter that will contain the message payload, and they return the payload of the response message (if any). You will learn which parameter and return types are supported in this section.

To indicate what sort of messages a method can handle, the method is typically annotated with either the @PayloadRoot or @SoapAction annotation. You will learn more about these annotations in Endpoint mappings.

Here is an example of a handling method:

The order method takes a Element as a parameter, annotated with @RequestPayload. This means that the payload of the message is passed on this method as a DOM element. The method has a void return type, indicating that no response message is sent.

WS-Addressing specifies a transport-neutral routing mechanism. It is based on a To and Action SOAP header, which indicate the destination and intent of the SOAP message, respectively. Additionally, WS-Addressing allows you to define a return address (for normal messages and for faults), and a unique message identifier which can be used for correlation ^[2]. Here is an example of a WS-Addressing message:

In this example, the destination is set to http://example/com/fabrikam, while the action is set to http://example.com/fabrikam/mail/Delete. Additionally, there is a message identifier, and an reply-to address. By default, this address is the "anonymous" address, indicating that a response should be sent using the same channel as the request (i.e. the HTTP response), but it can also be another address, as indicated in this example.

In Spring Web Services, WS-Addressing is implemented as an endpoint mapping. Using this mapping, you associate WS-Addressing actions with endpoints, similar to the SoapActionAnnotationMethodEndpointMapping described above.

The endpoint mapping mechanism has the notion of endpoint interceptors. These can be extremely useful when you want to apply specific functionality to certain requests, for example, dealing with security-related SOAP headers, or the logging of request and response message.

Endpoint interceptors are typically defined by using a <sws:interceptors> element in your application context. In this element, you can simply define endpoint interceptor beans that apply to all endpoints defined in that application context. Alternatively, you can use <sws:payloadRoot> or <sws:soapAction> elements to specify for which payload root name or SOAP action the interceptor should apply. For example:

Here, we define one 'global' interceptor (MyGlobalInterceptor) that intercepts all request and responses. We also define an interceptor that only applies to XML messages that have the http://www.example.com as a payload root namespace. Here, we could have defined a localPart attribute in addition to the namespaceUri to further limit the messages the interceptor applies to. Finally, we define two interceptors that apply when the message has a http://www.example.com/SoapAction SOAP action. Notice how the second interceptor is actually a reference to a bean definition outside of the <interceptors> element. You can use bean references anywhere inside the <interceptors> element.

When using @Configuration classes, you can extend from WsConfigurerAdapter to add interceptors. Like so:

Interceptors must implement the EndpointInterceptor interface from the org.springframework.ws.server package. This interface defines three methods, one that can be used for handling the request message before the actual endpoint will be executed, one that can be used for handling a normal response message, and one that can be used for handling fault messages, both of which will be called after the endpoint is executed. These three methods should provide enough flexibility to do all kinds of pre- and post-processing.

The handleRequest(..) method on the interceptor returns a boolean value. You can use this method to interrupt or continue the processing of the invocation chain. When this method returns true, the endpoint execution chain will continue, when it returns false, the MessageDispatcher interprets this to mean that the interceptor itself has taken care of things and does not continue executing the other interceptors and the actual endpoint in the invocation chain. The handleResponse(..) and handleFault(..) methods also have a boolean return value. When these methods return false, the response will not be sent back to the client.

There are a number of standard EndpointInterceptor implementations you can use in your Web service. Additionally, there is the XwsSecurityInterceptor, which is described in XwsSecurityInterceptor.

The SoapFaultMappingExceptionResolver is a more sophisticated implementation. This resolver enables you to take the class name of any exception that might be thrown and map it to a SOAP Fault, like so:

The key values and default endpoint use the format faultCode,faultString,locale, where only the fault code is required. If the fault string is not set, it will default to the exception message. If the language is not set, it will default to English. The above configuration will map exceptions of type ValidationFailureException to a client-side SOAP Fault with a fault string "Invalid request", as can be seen in the following response:

If any other exception occurs, it will return the default fault: a server-side fault with the exception message as fault string.

Finally, it is also possible to annotate exception classes with the @SoapFault annotation, to indicate the SOAP Fault that should be returned whenever that exception is thrown. In order for these annotations to be picked up, you need to add the SoapFaultAnnotationExceptionResolver to your application context. The elements of the annotation include a fault code enumeration, fault string or reason, and language. Here is an example exception:

Whenever the MyBusinessException is thrown with the constructor string "Oops!" during endpoint invocation, it will result in the following response:

Spring Web Services 2.0 introduced support for creating endpoint integration tests. In this context, an endpoint is class handles (SOAP) messages (see Endpoints).

The integration test support lives in the org.springframework.ws.test.server package. The core class in that package is the MockWebServiceClient. The underlying idea is that this client creates a request message, and then sends it over to the endpoint(s) that are configured in a standard MessageDispatcherServlet application context (see MessageDispatcherServlet). These endpoints will handle the message, and create a response. The client then receives this response, and verifies it against registered expectations.

The typical usage of the MockWebServiceClient is: .

Consider, for example, this simple Web service endpoint class:

A typical test for CustomerEndpoint would look like this:

Initially, the MockWebServiceClient will need to create a request message for the endpoint to consume. The client uses the RequestCreator strategy interface for this purpose:

You can write your own implementations of this interface, creating a request message by using the message factory, but you certainly do not have to. The RequestCreators class provides a way to create a RequestCreator based on a given payload in the withPayload() method. You will typically statically import RequestCreators.

When the request message has been processed by the endpoint, and a response has been received, the MockWebServiceClient can verify whether this response message meets certain expectations. The client uses the ResponseMatcher strategy interface for this purpose:

Once again you can write your own implementations of this interface, throwing AssertionError`s when the message does not meet your expectations, but you certainly do not have to, as the `ResponseMatchers class provides standard ResponseMatcher implementations for you to use in your tests. You will typically statically import this class.

The ResponseMatchers class provides the following response matchers:

You can set up multiple response expectations by chaining andExpect() calls, like so:

For more information on the response matchers provided by ResponseMatchers, refer to the class level Javadoc.

The WebServiceTemplate is the core class for client-side Web service access in Spring-WS. It contains methods for sending Source objects, and receiving response messages as either Source or Result. Additionally, it can marshal objects to XML before sending them across a transport, and unmarshal any response XML into an object again.

The WebServiceTemplate contains many convenience methods to send and receive web service messages. There are methods that accept and return a Source and those that return a Result. Additionally, there are methods which marshal and unmarshal objects to XML. Here is an example that sends a simple XML message to a Web service.

The above example uses the WebServiceTemplate to send a hello world message to the web service located at http://localhost:8080/WebService (in the case of the simpleSendAndReceive() method), and writes the result to the console. The WebServiceTemplate is injected with the default URI, which is used because no URI was supplied explicitly in the Java code.

Please note that the WebServiceTemplate class is thread-safe once configured (assuming that all of it’s dependencies are thread-safe too, which is the case for all of the dependencies that ship with Spring-WS), and so multiple objects can use the same shared WebServiceTemplate instance if so desired. The WebServiceTemplate exposes a zero argument constructor and messageFactory/messageSender bean properties which can be used for constructing the instance (using a Spring container or plain Java code). Alternatively, consider deriving from Spring-WS’s WebServiceGatewaySupport convenience base class, which exposes convenient bean properties to enable easy configuration. (You do not have to extend this base class…​ it is provided as a convenience class only.)

In order to facilitate the sending of plain Java objects, the WebServiceTemplate has a number of send(..) methods that take an Object as an argument for a message’s data content. The method marshalSendAndReceive(..) in the WebServiceTemplate class delegates the conversion of the request object to XML to a Marshaller, and the conversion of the response XML to an object to an Unmarshaller. (For more information about marshalling and unmarshaller, refer to the Spring documentation.) By using the marshallers, your application code can focus on the business object that is being sent or received and not be concerned with the details of how it is represented as XML. In order to use the marshalling functionality, you have to set a marshaller and unmarshaller with the marshaller/unmarshaller properties of the WebServiceTemplate class.

To accommodate the setting of SOAP headers and other settings on the message, the WebServiceMessageCallback interface gives you access to the message after it has been created, but before it is sent. The example below demonstrates how to set the SOAP Action header on a message that is created by marshalling an object.

The WebServiceMessageExtractor interface is a low-level callback interface that allows you to have full control over the process to extract an Object from a received WebServiceMessage. The WebServiceTemplate will invoke the extractData(..) method on a supplied WebServiceMessageExtractor while the underlying connection to the serving resource is still open. The following example illustrates the WebServiceMessageExtractor in action:

Spring Web Services 2.0 introduced support for creating Web service client integration tests. In this context, a client is a class that uses the WebServiceTemplate to access a Web service.

The integration test support lives in the org.springframework.ws.test.client package. The core class in that package is the MockWebServiceServer. The underlying idea is that the web service template connects to this mock server, sends it request message, which the mock server then verifies against the registered expectations. If the expectations are met, the mock server then prepares a response message, which is send back to the template.

The typical usage of the MockWebServiceServer is: .

Consider, for example, this Web service client class:

A typical test for CustomerClient would look like this:

To verify whether the request message meets certain expectations, the MockWebServiceServer uses the RequestMatcher strategy interface. The contract defined by this interface is quite simple:

You can write your own implementations of this interface, throwing AssertionError`s when the message does not meet your expectations, but you certainly do not have to. The `RequestMatchers class provides standard RequestMatcher implementations for you to use in your tests. You will typically statically import this class.

The RequestMatchers class provides the following request matchers:

You can set up multiple request expectations by chaining andExpect() calls, like so:

For more information on the request matchers provided by RequestMatchers, refer to the class level Javadoc.

When the request message has been verified and meets the defined expectations, the MockWebServiceServer will create a response message for the WebServiceTemplate to consume. The server uses the ResponseCreator strategy interface for this purpose:

Once again you can write your own implementations of this interface, creating a response message by using the message factory, but you certainly do not have to, as the ResponseCreators class provides standard ResponseCreator implementations for you to use in your tests. You will typically statically import this class.

The ResponseCreators class provides the following responses:

For more information on the request matchers provided by RequestMatchers, refer to the class level Javadoc.

For most cryptographic operations, you will use the standard java.security.KeyStore objects. These operations include certificate verification, message signing, signature verification, and encryption, but excludes username and time-stamp verification. This section aims to give you some background knowledge on keystores, and the Java tools that you can use to store keys and certificates in a keystore file. This information is mostly not related to Spring-WS, but to the general cryptographic features of Java.

The java.security.KeyStore class represents a storage facility for cryptographic keys and certificates. It can contain three different sort of elements:

Private Keys. These keys are used for self-authentication. The private key is accompanied by certificate chain for the corresponding public key. Within the field of WS-Security, this accounts to message signing and message decryption.

Symmetric Keys. Symmetric (or secret) keys are used for message encryption and decryption as well. The difference being that both sides (sender and recipient) share the same, secret key.

Trusted certificates. These X509 certificates are called a trusted certificate because the keystore owner trusts that the public key in the certificates indeed belong to the owner of the certificate. Within WS-Security, these certificates are used for certificate validation, signature verification, and encryption.

As stated in the introduction, authentication is the task of determining whether a principal is who they claim to be. Within WS-Security, authentication can take two forms: using a username and password token (using either a plain text password or a password digest), or using a X509 certificate.

The digital signature of a message is a piece of information based on both the document and the signer’s private key. There are two main tasks related to signatures in WS-Security: verifying signatures and signing messages.

When encrypting, the message is transformed into a form that can only be read with the appropriate key. The message can be decrypted to reveal the original, readable message.

When a securement or validation action fails, the XwsSecurityInterceptor will throw a WsSecuritySecurementException or WsSecurityValidationException respectively. These exceptions bypass the standard exception handling mechanism, but are handled in the interceptor itself.

WsSecuritySecurementException exceptions are handled in the handleSecurementException method of the XwsSecurityInterceptor. By default, this method will simply log an error, and stop further processing of the message.

Similarly, WsSecurityValidationException exceptions are handled in the handleValidationException method of the XwsSecurityInterceptor. By default, this method will create a SOAP 1.1 Client or SOAP 1.2 Sender Fault, and send that back as a response.

WSS4J uses no external configuration file; the interceptor is entirely configured by properties. The validation and securement actions executed by this interceptor are specified via validationActions and securementActions properties, respectively. Actions are passed as a space-separated strings. Here is an example configuration:

Validation actions are:

Securement actions are:

The order of the actions is significant and is enforced by the interceptor. The interceptor will reject an incoming SOAP message if its security actions were performed in a different order than the one specified by`validationActions`.

For cryptographic operations requiring interaction with a keystore or certificate handling (signature, encryption and decryption operations), WSS4J requires an instance of`org.apache.ws.security.components.crypto.Crypto`.

Crypto instances can be obtained from WSS4J’s CryptoFactory or more conveniently with the Spring-WS`CryptoFactoryBean`.

This section describes the various timestamp options available in the Wss4jSecurityInterceptor.

This section describes the various signature options available in the Wss4jSecurityInterceptor.

This section describes the various encryption and descryption options available in the Wss4jSecurityInterceptor.

The exception handling of the Wss4jSecurityInterceptor is identical to that of the XwsSecurityInterceptor. See Security Exception Handling for more information.