From a2d228b77433be4a03d4ba96d2e5b291e737e856 Mon Sep 17 00:00:00 2001 From: Arjen Poutsma Date: Tue, 15 Apr 2014 12:50:12 +0200 Subject: [PATCH] Updated reference documentation to Docbook 5 --- src/reference/docbook/bibliography.xml | 70 +++++---- src/reference/docbook/client.xml | 56 +++---- src/reference/docbook/common.xml | 32 ++-- src/reference/docbook/index.xml | 43 ++++-- src/reference/docbook/preface.xml | 15 +- src/reference/docbook/security.xml | 96 ++++++------ src/reference/docbook/server.xml | 145 ++++++++++--------- src/reference/docbook/tutorial.xml | 110 +++++++------- src/reference/docbook/what-is-spring-ws.xml | 26 +--- src/reference/docbook/why-contract-first.xml | 20 ++- 10 files changed, 324 insertions(+), 289 deletions(-) diff --git a/src/reference/docbook/bibliography.xml b/src/reference/docbook/bibliography.xml index 435cf212..5003bc53 100644 --- a/src/reference/docbook/bibliography.xml +++ b/src/reference/docbook/bibliography.xml @@ -1,21 +1,29 @@ - - + Bibliography - + - Jim - Waldo + + Jim + Waldo + - Ann - Wollrath + + Ann + Wollrath + - Sam - Kendall + + Sam + Kendall + A Note on Distributed Computing @@ -24,15 +32,19 @@ 1994 - + - Steve - Loughran + + Steve + Loughran + - Edmund - Smith + + Edmund + Smith + Rethinking the Java SOAP Stack @@ -42,16 +54,20 @@ IEEE Telephone Laboratories, Inc. - + - Ted - Neward + + Ted + Neward + - Scott - Meyers + + Scott + Meyers + Effective Enterprise Java @@ -59,16 +75,20 @@ 2004 - + - Elliotte Rusty - Harold + + Elliotte Rusty + Harold + - Scott - Meyers + + Scott + Meyers + Effective XML diff --git a/src/reference/docbook/client.xml b/src/reference/docbook/client.xml index 9bd849d8..30823b25 100644 --- a/src/reference/docbook/client.xml +++ b/src/reference/docbook/client.xml @@ -1,7 +1,11 @@ - - + Using Spring Web Services on the Client
Introduction @@ -23,7 +27,7 @@
Using the client-side API -
+
<classname>WebServiceTemplate</classname> The WebServiceTemplate is the core class for client-side Web service @@ -32,7 +36,7 @@ Result. Additionally, it can marshal objects to XML before sending them across a transport, and unmarshal any response XML into an object again. -
+
URIs and Transports The WebServiceTemplate class uses an URI as the message destination. @@ -52,7 +56,7 @@ HttpUrlConnectionMessageSender, which uses the facilities provided by Java itself. The alternative is the HttpComponentsMessageSender, which uses the - Apache HttpComponents HttpClient. + Apache HttpComponents HttpClient. Use the latter if you need more advanced and easy-to-use functionality (such as authentication, HTTP connection pooling, and so forth). @@ -325,7 +329,7 @@ public class WebServiceClient { 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.) + 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 @@ -523,9 +527,9 @@ public void marshalWithSoapActionHeader(final Source s) { - - - + + + - - - - + + + + - - - + + + - - - - - - + + + + + + - +
-
+
<interfacename>RequestMatcher</interfacename> and <classname>RequestMatchers</classname> To verify whether the request message meets certain expectations, the @@ -789,7 +793,7 @@ public class CustomerClientIntegrationTest { refer to the class level Javadoc.
-
+
<interfacename>ResponseCreator</interfacename> and <classname>ResponseCreators</classname> When the request message has been verified and meets the defined expectations, the diff --git a/src/reference/docbook/common.xml b/src/reference/docbook/common.xml index 3abee3ba..20aef474 100644 --- a/src/reference/docbook/common.xml +++ b/src/reference/docbook/common.xml @@ -1,16 +1,18 @@ - - + Shared components In this chapter, we will explore the components which are shared between client- and server-side Spring-WS development. These interfaces and classes represent the building blocks of Spring-WS, so it is important to understand what they do, even if you do not use them directly. -
+
Web service messages -
+
<interfacename>WebServiceMessage</interfacename> One of the core interfaces of Spring Web Services is the WebServiceMessage. @@ -71,7 +73,7 @@ output stream.
-
+
<interfacename>SoapMessage</interfacename> The SoapMessage is a subclass of @@ -86,7 +88,7 @@ SoapMessage.
-
+
Message Factories Concrete message implementations are created by a WebServiceMessageFactory. @@ -192,7 +194,7 @@ StreamingPayload.
-
+
<acronym>SOAP</acronym> 1.1 or 1.2 Both the SaajSoapMessageFactory and the @@ -238,7 +240,7 @@
-
+
<interfacename>MessageContext</interfacename> Typically, messages come in pairs: a request and a response. A request is created on the client-side, @@ -257,7 +259,7 @@
-
+
<interfacename>TransportContext</interfacename> One of the key properties of the SOAP protocol is that it tries to be transport-agnostic. This is why, for @@ -279,7 +281,7 @@ HttpServletConnection connection = (HttpServletConnection )context.getConnection HttpServletRequest request = connection.getHttpServletRequest(); String ipAddress = request.getRemoteAddr();]]>
-
+
Handling XML With XPath One of the best ways to handle XML is to use XPath. @@ -302,7 +304,7 @@ String ipAddress = request.getRemoteAddr();]]> Spring Web Services has two ways to use XPath within your application: the faster XPathExpression or the more flexible XPathTemplate. -
+
<interfacename>XPathExpression</interfacename> The XPathExpression is an abstraction over a compiled XPath expression, @@ -371,7 +373,7 @@ public class MyXPathClass { return new Contact(nameElement.getTextContent(), phoneElement.getTextContent()); } }); - ]]>// do something with list of Contact objects// do something with list of Contact objects @@ -380,7 +382,7 @@ public class MyXPathClass { which we use later on.
-
+
<classname>XPathTemplate</classname> The XPathExpression only allows you to evaluate a single, pre-compiled @@ -402,7 +404,7 @@ public class MyXPathClass { }]]>
-
+
Message Logging and Tracing When developing or debugging a Web service, it can be quite useful to look at the content of a (SOAP) diff --git a/src/reference/docbook/index.xml b/src/reference/docbook/index.xml index e452203d..d18f2ad8 100644 --- a/src/reference/docbook/index.xml +++ b/src/reference/docbook/index.xml @@ -1,27 +1,40 @@ - - - - - Spring Web Services - Reference Documentation + + + + Spring Web Services Reference Documentation + Spring Web Services ${version} - Arjen - Poutsma + + Arjen + Poutsma + - Rick - Evans + + Rick + Evans + - Tareq - Abed Rabbo + + Tareq + Abed Rabbo + + + 2005-2014 + + Copies of this document may be made for your own use and for distribution @@ -30,7 +43,7 @@ distributed in print or electronically. - + @@ -69,7 +82,7 @@ - + Other Resources diff --git a/src/reference/docbook/preface.xml b/src/reference/docbook/preface.xml index 5c029957..cb7f4271 100644 --- a/src/reference/docbook/preface.xml +++ b/src/reference/docbook/preface.xml @@ -1,7 +1,11 @@ - - + Preface In the current age of Service Oriented Architectures, more and more people are using Web Services to @@ -23,9 +27,4 @@ linkend="security">WS-Security solution that integrates with your existing application security solution, and a Client-side API that follows the familiar Spring template pattern. - - This document provides a reference guide to Spring-WS's features. Since this document is still a - work-in-progress, if you have any requests or comments, please post them on the support forums at . - \ No newline at end of file diff --git a/src/reference/docbook/security.xml b/src/reference/docbook/security.xml index 69d668cf..56726f81 100644 --- a/src/reference/docbook/security.xml +++ b/src/reference/docbook/security.xml @@ -1,10 +1,14 @@ - - + Securing your Web services with Spring-WS -
+
Introduction This chapter explains how to add WS-Security aspects to your Web services. We will focus on the @@ -50,7 +54,7 @@
-
+
<classname>XwsSecurityInterceptor</classname> @@ -58,7 +62,7 @@ The XwsSecurityInterceptor is an EndpointInterceptor (see ) that is based on SUN's XML and Web Services Security package (XWSS). This WS-Security implementation is part of the Java Web Services Developer Pack - (Java WSDP). + (Java WSDP). Like any other endpoint interceptor, it is defined in the endpoint mapping (see @@ -77,9 +81,9 @@ to operate. This XML file tells the interceptor what security aspects to require from incoming SOAP messages, and what aspects to add to outgoing messages. The basic format of the policy file will be explained in the following sections, but you can find a more in-depth tutorial - + here - . + . You can set the policy with the policyConfiguration property, which requires a Spring resource. The policy file can contain multiple elements, e.g. require a username token on incoming messages, and sign all outgoing messages. It contains a @@ -117,7 +121,7 @@ uses two callback handlers which are defined further on in the file. -
+
Keystores For most cryptographic operations, you will use the standard @@ -169,9 +173,9 @@ the keytool command, but you can find a reference - + here - + , or by giving the command keytool -help @@ -198,7 +202,7 @@
-
+
KeyStoreCallbackHandler To use the keystores within a @@ -363,10 +367,9 @@ passwordDigestRequired attribute set tofalse. You can find a reference of possible child elements - + here - + . -
+
SimplePasswordValidationCallbackHandler The simplest password validation handler is the @@ -414,12 +417,12 @@ SpringPlainTextPasswordValidationCallbackHandler The SpringPlainTextPasswordValidationCallbackHandler uses - Spring Security + Spring Security to authenticate users. It is beyond the scope of this document to describe Spring Security, but suffice it to say that it is a full-fledged security framework. - You can read more about it in the + You can read more about it in the Spring Security reference documentation - . + . The SpringPlainTextPasswordValidationCallbackHandler requires @@ -454,17 +457,16 @@ The JaasPlainTextPasswordValidationCallbackHandler is based on the standard - + Java Authentication and Authorization Service - + . It is beyond the scope of this document to provide a full introduction into JAAS, but there is a - + good tutorial - + available. @@ -538,10 +540,9 @@ nonceRequired should be set totrue: You can find a reference of possible child elements - + here - + .
-
+
Certificate Authentication A more secure way of authentication uses X509 certificates. In this scenerario, the SOAP message @@ -612,9 +613,9 @@ further carry other elements, which will be covered in. You can find a reference of possible child elements - + here - + . In this case, we are using a custom user details service to obtain authentication details based on the certificate. Refer to the - + Spring Security reference documentation - + for more information about authentication against X509 certificates.
@@ -816,7 +817,7 @@ and the signer's private key. There are two main tasks related to signatures in WS-Security: verifying signatures and signing messages. -
+
Verifying Signatures Just like + here - + . + here - + . SymmetricKey to indicate that a shared secret instead of the regular private key should be used to decrypt the message. You can read a description of the other elements - + here - + . + here - + .
-
+
Security Exception Handling When an securement or validation action fails, the XwsSecurityInterceptor @@ -1119,14 +1117,14 @@
-
+
<classname>Wss4jSecurityInterceptor</classname> The Wss4jSecurityInterceptor is an EndpointInterceptor - (see) that is based on - Apache's WSS4J. + (see ) that is based on + Apache's WSS4J. WSS4J implements the following standards: @@ -1554,7 +1552,7 @@ ]]>
-
+
Digital Signatures This section describes the various signature options available in the diff --git a/src/reference/docbook/server.xml b/src/reference/docbook/server.xml index 6e9944f1..2ce173d3 100644 --- a/src/reference/docbook/server.xml +++ b/src/reference/docbook/server.xml @@ -1,9 +1,13 @@ - - + Creating a Web service with Spring-WS -
+
Introduction Spring-WS's server-side support is designed around a @@ -38,10 +42,7 @@ The processing and dispatching flow of the MessageDispatcher is illustrated in the following sequence diagram. - - - - + @@ -106,7 +107,7 @@ Spring Web Services supports multiple transport protocols. The most common is the HTTP transport, for which a custom servlet is supplied, but it is also possible to send messages over JMS, and even email. -
+
<classname>MessageDispatcherServlet</classname> The MessageDispatcherServlet is a standard Servlet @@ -182,7 +183,7 @@ Javadoc of AbstractMessageDispatcherServletInitializer and AbstractAnnotationConfigMessageDispatcherServletInitializer. -
+
Automatic WSDL exposure The MessageDispatcherServlet will automatically detect any @@ -506,7 +507,7 @@ public DefaultWsdl11Definition orders() { Embedded HTTP Server transport Spring Web Services provides a transport based on Sun's JRE 1.6 - HTTP server. + 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. @@ -571,14 +572,14 @@ public DefaultWsdl11Definition orders() { For more information on the SimpleHttpServerFactoryBean, refer to the - Javadoc. + Javadoc.
XMPP transport Finally, Spring Web Services 2.0 introduced support for XMPP, otherwise known as Jabber. The support - is based on the Smack + is based on the Smack library. @@ -619,7 +620,7 @@ public DefaultWsdl11Definition orders() {
-
+
Endpoints Endpoints are the central concept in Spring-WS's server-side support. Endpoints provide access to the @@ -639,13 +640,13 @@ public DefaultWsdl11Definition orders() { Consider the following sample endpoint: - - - - - - - + + + + + + + Spring Reference documentation. + Spring Reference documentation. Note that all abstract base classes provided in Spring-WS are thread safe, unless otherwise indicated in the class-level Javadoc. -
+
<interfacename>@Endpoint</interfacename> handling methods In order for an endpoint to actually handle incoming XML messages, it needs to have one or more handling @@ -876,31 +877,31 @@ public void order(@RequestPayload Element orderElement) { (DOMSource, SAXSource, StreamSource, and StAXSource) - ✓ + Yes Enabled by default. W3C DOM org.w3c.dom.Element - ✓ + Yes Enabled by default dom4j org.dom4j.Element - ✓ + Yes Enabled when dom4j is on the classpath. JDOM org.jdom.Element - ✓ + Yes Enabled when JDOM is on the classpath. XOM nu.xom.Element - ✓ + Yes Enabled when XOM is on the classpath. @@ -909,7 +910,7 @@ public void order(@RequestPayload Element orderElement) { javax.xml.stream.XMLStreamReader and javax.xml.stream.XMLEventReader - ✓ + Yes Enabled when StAX is on the classpath. @@ -919,16 +920,16 @@ public void order(@RequestPayload Element orderElement) { org.w3c.Node, org.w3c.dom.NodeList, or type that can be converted from a String by a Spring 3 - conversion service, + conversion service, and that is annotated with @XPathParam. - ✗ + No Enabled by default, see . Message context org.springframework.ws.context.MessageContext - ✗ + No Enabled by default. @@ -942,7 +943,7 @@ public void order(@RequestPayload Element orderElement) { when used in combination with the @SoapHeader annotation. - ✗ + No Enabled by default. @@ -952,16 +953,16 @@ public void order(@RequestPayload Element orderElement) { javax.xml.bind.annotation.XmlRootElement, and javax.xml.bind.JAXBElement. - ✓ + Yes Enabled when JAXB2 is on the classpath. OXM Any type supported by a Spring OXM - Unmarshaller. + Unmarshaller. - ✓ + Yes Enabled when the unmarshaller attribute of <sws:annotation-driven/> is specified. @@ -1002,7 +1003,7 @@ public void order(@RequestPayload Element orderElement) { Refer to the class-level Javadoc of DefaultMethodEndpointAdapter and MethodArgumentResolver to see how. -
+
<interfacename>@XPathParam</interfacename> One parameter type needs some extra explanation: @XPathParam. @@ -1011,7 +1012,7 @@ public void order(@RequestPayload Element orderElement) { evaluation of the expression. Here is an example: - package samples; + package samples; import javax.xml.transform.Source; @@ -1057,7 +1058,7 @@ public class AnnotationOrderEndpoint { In addition to this list, you can use any type that can be converted from a String by a Spring 3 - conversion service. + conversion service.
@@ -1097,7 +1098,7 @@ public class AnnotationOrderEndpoint { void - ✗ + No Enabled by default. @@ -1107,31 +1108,31 @@ public class AnnotationOrderEndpoint { (DOMSource, SAXSource, StreamSource, and StAXSource) - ✓ + Yes Enabled by default. W3C DOM org.w3c.dom.Element - ✓ + Yes Enabled by default dom4j org.dom4j.Element - ✓ + Yes Enabled when dom4j is on the classpath. JDOM org.jdom.Element - ✓ + Yes Enabled when JDOM is on the classpath. XOM nu.xom.Element - ✓ + Yes Enabled when XOM is on the classpath. @@ -1141,16 +1142,16 @@ public class AnnotationOrderEndpoint { javax.xml.bind.annotation.XmlRootElement, and javax.xml.bind.JAXBElement. - ✓ + Yes Enabled when JAXB2 is on the classpath. OXM Any type supported by a Spring OXM - Marshaller. + Marshaller. - ✓ + Yes Enabled when the marshaller attribute of <sws:annotation-driven/> is specified. @@ -1170,7 +1171,7 @@ public class AnnotationOrderEndpoint {
-
+
Endpoint mappings The endpoint mapping is responsible for mapping incoming messages to appropriate endpoints. @@ -1231,7 +1232,7 @@ public class AnnotationOrderEndpoint { Whenever a message comes in which has this SOAPAction header, the method will be invoked. -
+
WS-Addressing WS-Addressing specifies a transport-neutral routing mechanism. @@ -1240,7 +1241,7 @@ public class AnnotationOrderEndpoint { 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 - For more information on WS-Addressing, see . + For more information on WS-Addressing, see . . Here is an example of a WS-Addressing message:
-
+
Intercepting requests - the <interfacename>EndpointInterceptor</interfacename> interface The endpoint mapping mechanism has the notion of endpoint interceptors. These can be extremely useful @@ -1502,7 +1503,7 @@ public class MyWsConfiguration extends WsConfigurerAdapter {
-
+
Handling Exceptions Spring-WS provides EndpointExceptionResolvers to ease the pain of unexpected @@ -1696,11 +1697,11 @@ public class MyBusinessException extends Exception { - - - - - + + + + + - - - - + + + + - - - + + + - - - - - + + + + +
-
+
<interfacename>RequestCreator</interfacename> and <classname>RequestCreators</classname> Initially, the MockWebServiceClient will need to create a request message for the @@ -1884,7 +1885,7 @@ public class CustomerEndpointIntegrationTest { You will typically statically import RequestCreators.
-
+
<interfacename>ResponseMatcher</interfacename> and <classname>ResponseMatchers</classname> When the request message has been processed by the endpoint, and a response has been received, diff --git a/src/reference/docbook/tutorial.xml b/src/reference/docbook/tutorial.xml index fb2aed04..17bb6ee7 100644 --- a/src/reference/docbook/tutorial.xml +++ b/src/reference/docbook/tutorial.xml @@ -1,7 +1,11 @@ - - + Writing Contract-First Web Services
Introduction @@ -48,7 +52,7 @@ A holiday consists of a start date and an end date. We have also decided to use the standard - ISO 8601 + 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. @@ -100,7 +104,7 @@
-
+
Data Contract Now that we have seen some examples of the XML data that we will use, @@ -110,9 +114,9 @@ DTDs - XML Schema (XSD) - RELAX NG - Schematron + XML Schema (XSD) + RELAX NG + Schematron DTDs have limited namespace support, so they are not suitable for Web @@ -226,14 +230,14 @@ - - - - + + + + - - - + + + hr.xsd.
-
+
Service contract - A service contract is generally expressed as a WSDL file. + A service contract is generally expressed as a WSDL file. Note that in Spring-WS, writing the WSDL by hand is not required. Based on the XSD and some conventions, Spring-WS can create the WSDL for you, as explained in the section entitled . @@ -345,27 +349,27 @@ - - - - + + + + - - - - + + + + - - - + + + - - - + + + - - - + + +
-
+
Creating the project - In this section, we will be using Maven3 to create the + In this section, we will be using Maven3 to create the initial project structure for us. Doing so is not required, but greatly reduces the amount of code we have to write to setup our HolidayService. @@ -526,7 +530,7 @@ 'WEB-INF/' folder.
-
+
Implementing the Endpoint In Spring-WS, you will implement Endpoints to handle incoming XML messages. @@ -539,17 +543,17 @@
Handling the XML Message - In this sample application, we are going to use JDom 2 to handle + 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 + We are also using XPath, because it allows us to select particular parts of the XML JDOM tree, without requiring strict schema conformance. - - - - + + + + <sws:annotation-driven> element. - - +
-
+
Publishing the WSDL Finally, we need to publish the WSDL. As stated in , we don't @@ -816,11 +820,11 @@ public class StubHumanResourceService implements HumanResourceService { - - - - - + + + + + You can create a WAR file using mvn install. If you deploy the application (to Tomcat, Jetty, etc.), and point your browser at - this location, you will + this location, you will see the generated WSDL. This WSDL is ready to be used by clients, such as - soapUI, or other SOAP frameworks. + soapUI, or other SOAP frameworks.
diff --git a/src/reference/docbook/what-is-spring-ws.xml b/src/reference/docbook/what-is-spring-ws.xml index 1dc1589b..df508f44 100644 --- a/src/reference/docbook/what-is-spring-ws.xml +++ b/src/reference/docbook/what-is-spring-ws.xml @@ -1,7 +1,8 @@ - - + What is Spring Web Services?
Introduction @@ -37,9 +38,8 @@ Flexible XML Marshalling - The Object/XML Mapping module in the Spring Web Services distribution supports JAXB 1 and 2, Castor, - XMLBeans, JiBX, and XStream. And because it is a separate module, you can use it in non-Web services code - as well. + 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. @@ -62,12 +62,6 @@ This means you can use your existing Spring Security configuration for your SOAP service as well. - - Built by Maven - - This assists you in effectively reusing the Spring Web Services artifacts in your own Maven-based projects. - - Apache license @@ -122,13 +116,9 @@ 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. + dependencies, i.e. Spring-WS Core depends on Spring-XML and the OXM module found in Spring 3 and higher. - - - - + diff --git a/src/reference/docbook/why-contract-first.xml b/src/reference/docbook/why-contract-first.xml index 1790d280..e004ae06 100644 --- a/src/reference/docbook/why-contract-first.xml +++ b/src/reference/docbook/why-contract-first.xml @@ -1,7 +1,11 @@ - - + Why Contract First?
Introduction @@ -17,8 +21,8 @@ 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, or read the - WSDL tutorial + WSDL specification, or read the + WSDL tutorial @@ -29,7 +33,7 @@ Object/XML Impedance Mismatch Similar to the field of ORM, where we have an - Object/Relational impedance mismatch, + 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 @@ -153,8 +157,8 @@ public class Passenger { 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). + Basic + Profile).