Spring Web Services - Reference Documentation 1.5.9 Copyright © 2005-2007 Arjen Poutsma, Rick Evans, Tareq Abed Rabbo 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. Preface .............................................................................................................................................v I. Introduction ..................................................................................................................................1 1. What is Spring Web Services? ............................................................................................... 2 1.1. Introduction ............................................................................................................... 2 1.2. Runtime environment ................................................................................................. 2 2. Why Contract First? .............................................................................................................. 4 2.1. Introduction ............................................................................................................... 4 2.2. Object/XML Impedance Mismatch .............................................................................. 4 2.2.1. XSD extensions ............................................................................................... 4 2.2.2. Unportable types ............................................................................................. 4 2.2.3. Cyclic graphs .................................................................................................. 5 2.3. Contract-first versus Contract-last ............................................................................... 6 2.3.1. Fragility .......................................................................................................... 6 2.3.2. Performance .................................................................................................... 6 2.3.3. Reusability ...................................................................................................... 7 2.3.4. Versioning ...................................................................................................... 7 3. Writing Contract-First Web Services ...................................................................................... 8 3.1. Introduction ............................................................................................................... 8 3.2. Messages ...................................................................................................................8 3.2.1. Holiday ...........................................................................................................8 3.2.2. Employee ........................................................................................................ 8 3.2.3. HolidayRequest ............................................................................................... 9 3.3. Data Contract ............................................................................................................. 9 3.4. Service contract ....................................................................................................... 11 3.5. Creating the project .................................................................................................. 13 3.6. Implementing the Endpoint ....................................................................................... 13 3.6.1. Handling the XML Message ........................................................................... 14 3.6.2. Routing the Message to the Endpoint .............................................................. 15 3.7. Publishing the WSDL ............................................................................................... 16 II. Reference .................................................................................................................................. 17 4. Shared components ............................................................................................................. 18 4.1. Web service messages .............................................................................................. 18 4.1.1. WebServiceMessage ...................................................................................... 18 4.1.2. SoapMessage ................................................................................................. 18 4.1.3. Message Factories ......................................................................................... 18 4.1.4. MessageContext ............................................................................................ 20 4.2. TransportContext ................................................................................................... 20 4.3. Handling XML With XPath ...................................................................................... 21 4.3.1. XPathExpression .......................................................................................... 21 4.3.2. XPathTemplate .............................................................................................. 22 4.4. Message Logging and Tracing .................................................................................. 22 5. Creating a Web service with Spring-WS ............................................................................... 24 5.1. Introduction ............................................................................................................. 24 5.2. The MessageDispatcher ........................................................................................... 24 5.3. Transports ............................................................................................................... 25 5.3.1. MessageDispatcherServlet .......................................................................... 25 5.3.2. Wiring up Spring-WS in a DispatcherServlet ............................................... 27 5.3.3. JMS transport ................................................................................................ 28 5.3.4. Email transport .............................................................................................. 29 5.3.5. Embedded HTTP Server transport .................................................................. 30 5.4. Endpoints ................................................................................................................ 31 5.4.1. AbstractDomPayloadEndpoint and other DOM endpoints ............................... 31 Spring-WS (1.5.9) ii Spring Web Services - Reference Documentation 5.4.2. AbstractMarshallingPayloadEndpoint ......................................................... 32 5.4.3. Using Spring Validator with Marshalling Endpoints ...................................... 34 5.4.4. @Endpoint ..................................................................................................... 35 5.5. Endpoint mappings ................................................................................................... 37 5.5.1. PayloadRootQNameEndpointMapping .............................................................. 38 5.5.2. SoapActionEndpointMapping ........................................................................ 38 5.5.3. MethodEndpointMapping ............................................................................... 39 5.5.4. WS-Addressing ............................................................................................. 39 5.5.5. Intercepting requests - the EndpointInterceptor interface .............................. 41 5.6. Handling Exceptions ................................................................................................ 43 5.6.1. SoapFaultMappingExceptionResolver .......................................................... 43 5.6.2. SoapFaultAnnotationExceptionResolver ..................................................... 44 6. Using Spring Web Services on the Client ............................................................................. 45 6.1. Introduction ............................................................................................................. 45 6.2. Using the client-side API .......................................................................................... 45 6.2.1. WebServiceTemplate ..................................................................................... 45 6.2.2. Sending and receiving a WebServiceMessage .................................................. 47 6.2.3. Sending and receiving POJOs - marshalling and unmarshalling ........................ 48 6.2.4. WebServiceMessageCallback ........................................................................ 48 6.2.5. WebServiceMessageExtractor ....................................................................... 49 7. Securing your Web services with Spring-WS ........................................................................ 50 7.1. Introduction ............................................................................................................. 50 7.2. XwsSecurityInterceptor ........................................................................................ 50 7.2.1. Keystores ...................................................................................................... 51