Spring/spring-ws
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated reference documentation to Docbook 5

Browse Source
This commit is contained in:
Arjen Poutsma
2014-04-15 12:50:12 +02:00
parent f11317c560
commit a2d228b774
10 changed files with 324 additions and 289 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
src/reference/docbook/bibliography.xml
View File

@@ -1,21 +1,29 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bibliography PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<bibliography>
<bibliography
xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd">
<title>Bibliography</title>
<biblioentry id="waldo-94">
<biblioentry xml:id="waldo-94">
<authorgroup>
<author>
<firstname>Jim</firstname>
<surname>Waldo</surname>
<personname>
<firstname>Jim</firstname>
<surname>Waldo</surname>
</personname>
</author>
<author>
<firstname>Ann</firstname>
<surname>Wollrath</surname>
<personname>
<firstname>Ann</firstname>
<surname>Wollrath</surname>
</personname>
</author>
<author>
<firstname>Sam</firstname>
<surname>Kendall</surname>
<personname>
<firstname>Sam</firstname>
<surname>Kendall</surname>
</personname>
</author>
</authorgroup>
<title>A Note on Distributed Computing</title>
@@ -24,15 +32,19 @@
</publisher>
<date>1994</date>
</biblioentry>
<biblioentry id="alpine">
<biblioentry xml:id="alpine">
<authorgroup>
<author>
<firstname>Steve</firstname>
<surname>Loughran</surname>
<personname>
<firstname>Steve</firstname>
<surname>Loughran</surname>
</personname>
</author>
<author>
<firstname>Edmund</firstname>
<surname>Smith</surname>
<personname>
<firstname>Edmund</firstname>
<surname>Smith</surname>
</personname>
</author>
</authorgroup>
<title>Rethinking the Java SOAP Stack</title>
@@ -42,16 +54,20 @@
<holder>IEEE Telephone Laboratories, Inc.</holder>
</copyright>
</biblioentry>
<biblioentry id="effective-enterprise-java">
<biblioentry xml:id="effective-enterprise-java">
<authorgroup>
<author>
<firstname>Ted</firstname>
<surname>Neward</surname>
<personname>
<firstname>Ted</firstname>
<surname>Neward</surname>
</personname>
</author>
</authorgroup>
<editor>
<firstname>Scott</firstname>
<surname>Meyers</surname>
<personname>
<firstname>Scott</firstname>
<surname>Meyers</surname>
</personname>
</editor>
<title>Effective Enterprise Java</title>
<publisher>
@@ -59,16 +75,20 @@
</publisher>
<date>2004</date>
</biblioentry>
<biblioentry id="effective-xml">
<biblioentry xml:id="effective-xml">
<authorgroup>
<author>
<firstname>Elliotte Rusty</firstname>
<surname>Harold</surname>
<personname>
<firstname>Elliotte Rusty</firstname>
<surname>Harold</surname>
</personname>
</author>
</authorgroup>
<editor>
<firstname>Scott</firstname>
<surname>Meyers</surname>
<personname>
<firstname>Scott</firstname>
<surname>Meyers</surname>
</personname>
</editor>
<title>Effective XML</title>
<publisher>

56
src/reference/docbook/client.xml
View File

@@ -1,7 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="client">
<chapter xml:id="client"
xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xl="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">
<title>Using Spring Web Services on the Client</title>
<section>
<title>Introduction</title>
@@ -23,7 +27,7 @@
</section>
<section>
<title>Using the client-side API</title>
<section id="client-web-service-template">
<section xml:id="client-web-service-template">
<title><classname>WebServiceTemplate</classname></title>
<para>
The <classname>WebServiceTemplate</classname> is the core class for client-side Web service
@@ -32,7 +36,7 @@
<classname>Result</classname>. Additionally, it can marshal objects to XML before sending
them across a transport, and unmarshal any response XML into an object again.
</para>
<section id="client-transports">
<section xml:id="client-transports">
<title>URIs and Transports</title>
<para>
The <classname>WebServiceTemplate</classname> class uses an URI as the message destination.
@@ -52,7 +56,7 @@
<classname>HttpUrlConnectionMessageSender</classname>, which uses the facilities provided
by Java itself. The alternative is the <classname>HttpComponentsMessageSender</classname>,
which uses the
<ulink url="http://hc.apache.org/httpcomponents-client-ga">Apache HttpComponents HttpClient</ulink>.
<link xl:href="http://hc.apache.org/httpcomponents-client-ga">Apache HttpComponents HttpClient</link>.
Use the latter if you need more advanced and easy-to-use functionality (such as authentication,
HTTP connection pooling, and so forth).
</para>
@@ -325,7 +329,7 @@ public class WebServiceClient {
to XML to a <interfacename>Marshaller</interfacename>, and the conversion of the response
XML to an object to an <interfacename>Unmarshaller</interfacename>. (For more information
about marshalling and unmarshaller, refer to
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/oxm.html">the Spring documentation</ulink>.)
<link xl:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/oxm.html">the Spring documentation</link>.)
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) {
</para>
<programlistingco>
<areaspec>
<area id="client.test.client.gateway" coords="3"/>
<area id="client.test.client.request" coords="6"/>
<area id="client.test.client.response" coords="10"/>
<area xml:id="client.test.client.gateway" coords="3"/>
<area xml:id="client.test.client.request" coords="6"/>
<area xml:id="client.test.client.response" coords="10"/>
</areaspec>
<programlisting><![CDATA[import org.springframework.ws.client.core.support.WebServiceGatewaySupport;
@@ -572,23 +576,23 @@ public class CustomerClient extends WebServiceGatewaySupport {
</para>
<programlistingco>
<areaspec>
<areaset id="client.test.test.imports" coords="">
<area id="client.test.test.imports.server" coords="13"/>
<area id="client.test.test.imports.requestMatchers" coords="14"/>
<area id="client.test.test.imports.responseCreators" coords="15"/>
<areaset xml:id="client.test.test.imports">
<area xml:id="client.test.test.imports.server" coords="13"/>
<area xml:id="client.test.test.imports.requestMatchers" coords="14"/>
<area xml:id="client.test.test.imports.responseCreators" coords="15"/>
</areaset>
<areaset id="client.test.test.spring" coords="">
<area id="client.test.test.spring.runwith" coords="17"/>
<area id="client.test.test.spring.configuration" coords="18"/>
<areaset xml:id="client.test.test.spring">
<area xml:id="client.test.test.spring.runwith" coords="17"/>
<area xml:id="client.test.test.spring.configuration" coords="18"/>
</areaset>
<area id="client.test.test.client" coords="22"/>
<area id="client.test.test.mockserver" coords="24"/>
<area id="client.test.test.expectAndRespond" coords="42"/>
<areaset id="client.test.test.client.invoke" coords="">
<area id="client.test.test.client.invoke.actual" coords="44"/>
<area id="client.test.test.client.invoke.assert" coords="45"/>
<area xml:id="client.test.test.client" coords="22"/>
<area xml:id="client.test.test.mockserver" coords="24"/>
<area xml:id="client.test.test.expectAndRespond" coords="42"/>
<areaset xml:id="client.test.test.client.invoke">
<area xml:id="client.test.test.client.invoke.actual" coords="44"/>
<area xml:id="client.test.test.client.invoke.assert" coords="45"/>
</areaset>
<area id="client.test.test.client.verify" coords="47"/>
<area xml:id="client.test.test.client.verify" coords="47"/>
</areaspec>
<programlisting><![CDATA[import javax.xml.transform.Source;
import org.springframework.beans.factory.annotation.Autowired;
@@ -711,7 +715,7 @@ public class CustomerClientIntegrationTest {
</calloutlist>
</programlistingco>
</section>
<section id="client-test-request-matcher">
<section xml:id="client-test-request-matcher">
<title><interfacename>RequestMatcher</interfacename> and <classname>RequestMatchers</classname></title>
<para>
To verify whether the request message meets certain expectations, the
@@ -789,7 +793,7 @@ public class CustomerClientIntegrationTest {
refer to the class level Javadoc.
</para>
</section>
<section id="client-test-response-creator">
<section xml:id="client-test-response-creator">
<title><interfacename>ResponseCreator</interfacename> and <classname>ResponseCreators</classname></title>
<para>
When the request message has been verified and meets the defined expectations, the

32
src/reference/docbook/common.xml
View File

@@ -1,16 +1,18 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="common">
<chapter xml:id="common"
xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd">
<title>Shared components</title>
<para>
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.
</para>
<section id="web-service-messages">
<section xml:id="web-service-messages">
<title>Web service messages</title>
<section id="web-service-message">
<section xml:id="web-service-message">
<title><interfacename>WebServiceMessage</interfacename></title>
<para>
One of the core interfaces of Spring Web Services is the <interfacename>WebServiceMessage</interfacename>.
@@ -71,7 +73,7 @@
output stream.
</para>
</section>
<section id="soap-message">
<section xml:id="soap-message">
<title><interfacename>SoapMessage</interfacename></title>
<para>
The <interfacename>SoapMessage</interfacename> is a subclass of
@@ -86,7 +88,7 @@
<interfacename>SoapMessage</interfacename>.
</para>
</section>
<section id="message-factories">
<section xml:id="message-factories">
<title>Message Factories</title>
<para>
Concrete message implementations are created by a <interfacename>WebServiceMessageFactory</interfacename>.
@@ -192,7 +194,7 @@
<interfacename>StreamingPayload</interfacename>.
</para>
</section>
<section id="soap_11_or_12">
<section xml:id="soap_11_or_12">
<title><acronym>SOAP</acronym> 1.1 or 1.2</title>
<para>
Both the <classname>SaajSoapMessageFactory</classname> and the
@@ -238,7 +240,7 @@
</caution>
</section>
</section>
<section id="message-context">
<section xml:id="message-context">
<title><interfacename>MessageContext</interfacename></title>
<para>
Typically, messages come in pairs: a request and a response. A request is created on the client-side,
@@ -257,7 +259,7 @@
</para>
</section>
</section>
<section id="transport-context">
<section xml:id="transport-context">
<title><interfacename>TransportContext</interfacename></title>
<para>
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();]]></programlisting>
</section>
<section id="xpath">
<section xml:id="xpath">
<title>Handling XML With XPath</title>
<para>
One of the best ways to handle XML is to use XPath.
@@ -302,7 +304,7 @@ String ipAddress = request.getRemoteAddr();]]></programlisting>
Spring Web Services has two ways to use XPath within your application: the faster
<interfacename>XPathExpression</interfacename> or the more flexible <classname>XPathTemplate</classname>.
</para>
<section id="xpath-expression">
<section xml:id="xpath-expression">
<title><interfacename>XPathExpression</interfacename></title>
<para>
The <interfacename>XPathExpression</interfacename> is an abstraction over a compiled XPath expression,
@@ -371,7 +373,7 @@ public class MyXPathClass {
return new Contact(nameElement.getTextContent(), phoneElement.getTextContent());
}
});
]]><lineannotation>// do something with list of <classname>Contact</classname> objects</lineannotation><![CDATA[
]]><lineannotation>// do something with list of Contact objects</lineannotation><![CDATA[
}
}]]></programlisting>
<para>
@@ -380,7 +382,7 @@ public class MyXPathClass {
which we use later on.
</para>
</section>
<section id="xpath-template">
<section xml:id="xpath-template">
<title><classname>XPathTemplate</classname></title>
<para>
The <interfacename>XPathExpression</interfacename> only allows you to evaluate a single, pre-compiled
@@ -402,7 +404,7 @@ public class MyXPathClass {
}]]></programlisting>
</section>
</section>
<section id="logging">
<section xml:id="logging">
<title>Message Logging and Tracing</title>
<para>
When developing or debugging a Web service, it can be quite useful to look at the content of a (SOAP)

43
src/reference/docbook/index.xml
View File

@@ -1,27 +1,40 @@
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<bookinfo>
<title>Spring Web Services</title>
<subtitle>Reference Documentation</subtitle>
<?xml version="1.0" encoding="UTF-8"?>
<book xml:id="spring-framework-reference"
xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd">
<info>
<title>Spring Web Services Reference Documentation</title>
<productname>Spring Web Services</productname>
<releaseinfo>${version}</releaseinfo>
<authorgroup>
<author>
<firstname>Arjen</firstname>
<surname>Poutsma</surname>
<personname>
<firstname>Arjen</firstname>
<surname>Poutsma</surname>
</personname>
</author>
<author>
<firstname>Rick</firstname>
<surname>Evans</surname>
<personname>
<firstname>Rick</firstname>
<surname>Evans</surname>
</personname>
</author>
<author>
<firstname>Tareq</firstname>
<surname>Abed Rabbo</surname>
<personname>
<firstname>Tareq</firstname>
<surname>Abed Rabbo</surname>
</personname>
</author>
</authorgroup>
<copyright>
<year>2005-2014</year>
</copyright>
<legalnotice>
<para>
Copies of this document may be made for your own use and for distribution
@@ -30,7 +43,7 @@
distributed in print or electronically.
</para>
</legalnotice>
</bookinfo>
</info>
<toc/>
@@ -69,7 +82,7 @@
<xi:include href="client.xml"/>
<xi:include href="security.xml"/>
</part>
<part id="resources">
<part xml:id="resources">
<title>Other Resources</title>
<partintro>
<para>

15
src/reference/docbook/preface.xml
View File

@@ -1,7 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<preface id="preface">
<preface xml:id="overview"
xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xl="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">
<title>Preface</title>
<para>
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</link> solution that integrates with your existing application security
solution, and a <link linkend="client">Client-side API</link> that follows the familiar Spring template pattern.
</para>
<para>
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 <ulink
url="http://forum.springframework.org/forumdisplay.php?f=39"/>.
</para>
</preface>

96
src/reference/docbook/security.xml
View File

@@ -1,10 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="security">
<chapter xml:id="security"
xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xl="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">
<title>Securing your Web services with Spring-WS</title>
<section id="security-introduction">
<section xml:id="security-introduction">
<title>Introduction</title>
<para>
This chapter explains how to add WS-Security aspects to your Web services. We will focus on the
@@ -50,7 +54,7 @@
</para>
</note>
</section>
<section id="security-xws-security-interceptor">
<section xml:id="security-xws-security-interceptor">
<title>
<classname>XwsSecurityInterceptor</classname>
</title>
@@ -58,7 +62,7 @@
The <classname>XwsSecurityInterceptor</classname> is an <classname>EndpointInterceptor</classname>
(see <xref linkend="server-endpoint-interceptor"/>) 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
(<ulink url="http://java.sun.com/webservices/"><citetitle>Java WSDP</citetitle></ulink>).
(<link xl:href="http://java.sun.com/webservices/"><citetitle>Java WSDP</citetitle></link>).
</para>
<para>
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
<ulink url="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp564887">
<link xl:href="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp564887">
<citetitle>here</citetitle>
</ulink>.
</link>.
You can set the policy with the <property>policyConfiguration</property> 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.
</para>
<section id="keystore">
<section xml:id="keystore">
<title>Keystores</title>
<para>
For most cryptographic operations, you will use the standard
@@ -169,9 +173,9 @@
the
<command>keytool</command>
command, but you can find a reference
<ulink url="http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html">
<link xl:href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html">
<citetitle>here</citetitle>
</ulink>
</link>
,
or by giving the command
<prompt>keytool -help</prompt>
@@ -198,7 +202,7 @@
</para>
</caution>
</section>
<section id="security-key-store-callback-handler">
<section xml:id="security-key-store-callback-handler">
<title>KeyStoreCallbackHandler</title>
<para>
To use the keystores within a
@@ -363,10 +367,9 @@
<literal>passwordDigestRequired</literal>
attribute set to<literal>false</literal>.
You can find a reference of possible child elements
<ulink
url="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp567459">
<link xl:href="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp567459">
<citetitle>here</citetitle>
</ulink>
</link>
.
</para>
<programlisting><![CDATA[
@@ -386,7 +389,7 @@
to the registered handlers. Within Spring-WS, there are three classes which handle this particular
callback.
</para>
<section id="security-simple-password-validation-callback-handler">
<section xml:id="security-simple-password-validation-callback-handler">
<title>SimplePasswordValidationCallbackHandler</title>
<para>
The simplest password validation handler is the
@@ -414,12 +417,12 @@
<title>SpringPlainTextPasswordValidationCallbackHandler</title>
<para>
The <classname>SpringPlainTextPasswordValidationCallbackHandler</classname> uses
<ulink url="http://www.springframework.org/security"><citetitle>Spring Security</citetitle></ulink>
<link xl:href="http://www.springframework.org/security"><citetitle>Spring Security</citetitle></link>
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 <ulink url="http://www.springframework.org/security">
You can read more about it in the <link xl:href="http://www.springframework.org/security">
<citetitle>Spring Security reference documentation</citetitle>
</ulink>.
</link>.
</para>
<para>
The <classname>SpringPlainTextPasswordValidationCallbackHandler</classname> requires
@@ -454,17 +457,16 @@
The
<classname>JaasPlainTextPasswordValidationCallbackHandler</classname>
is based on the standard
<ulink url="http://java.sun.com/products/jaas/">
<link xl:href="http://java.sun.com/products/jaas/">
<citetitle>Java Authentication and Authorization
Service
</citetitle>
</ulink>
</link>
. It is beyond the scope of this document to provide a full
introduction into JAAS, but there is a
<ulink
url="http://www.javaworld.com/javaworld/jw-09-2002/jw-0913-jaas.html">
<link xl:href="http://www.javaworld.com/javaworld/jw-09-2002/jw-0913-jaas.html">
<citetitle>good tutorial</citetitle>
</ulink>
</link>
available.
</para>
<para>
@@ -538,10 +540,9 @@
<literal>nonceRequired</literal>
should be set to<literal>true</literal>:
You can find a reference of possible child elements
<ulink
url="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp567459">
<link xl:href="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp567459">
<citetitle>here</citetitle>
</ulink>
</link>
.
</para>
<programlisting><![CDATA[
@@ -596,7 +597,7 @@
</section>
</section>
<section id="security-certificate-authentication">
<section xml:id="security-certificate-authentication">
<title>Certificate Authentication</title>
<para>
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<xref
linkend="security-verifying-signatures"/>.
You can find a reference of possible child elements
<ulink url="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp565769">
<link xl:href="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp565769">
<citetitle>here</citetitle>
</ulink>
</link>
.
</para>
<programlisting><![CDATA[
@@ -761,9 +762,9 @@
<para>
In this case, we are using a custom user details service to obtain authentication details based on
the certificate. Refer to the
<ulink url="http://www.springframework.org/security">
<link xl:href="http://www.springframework.org/security">
<citetitle>Spring Security reference documentation</citetitle>
</ulink>
</link>
for more information about authentication against X509 certificates.
</para>
</section>
@@ -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.
</para>
<section id="security-verifying-signatures">
<section xml:id="security-verifying-signatures">
<title>Verifying Signatures</title>
<para>
Just like<link
@@ -839,10 +840,9 @@
part which was expected to be signed, and various other subelements. You can also define the private key
alias to use, whether to use a symmetric instead of a private key, and many other properties. You can
find a reference of possible child elements
<ulink
url="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp565769">
<link xl:href="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp565769">
<citetitle>here</citetitle>
</ulink>
</link>
.
</para>
<programlisting><![CDATA[
@@ -909,10 +909,9 @@
part which was expected to be signed, and various other subelements. You can also define the private key
alias to use, whether to use a symmetric instead of a private key, and many other properties. You can
find a reference of possible child elements
<ulink
url="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp565497">
<link xl:href="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp565497">
<citetitle>here</citetitle>
</ulink>
</link>
.
</para>
<programlisting><![CDATA[
@@ -980,9 +979,9 @@
<literal>SymmetricKey</literal>
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
<ulink url="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp565951">
<link xl:href="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp565951">
<citetitle>here</citetitle>
</ulink>
</link>
.
</para>
<programlisting><![CDATA[
@@ -1043,10 +1042,9 @@
to indicate that a
shared secret instead of the regular public key should be used to encrypt the message. You can read a
description of the other elements
<ulink
url="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp565951">
<link xl:href="http://java.sun.com/webservices/docs/1.6/tutorial/doc/XWS-SecurityIntro4.html#wp565951">
<citetitle>here</citetitle>
</ulink>
</link>
.
</para>
<programlisting><![CDATA[
@@ -1088,7 +1086,7 @@
</section>
</section>
</section>
<section id="security-xws-exception-handling">
<section xml:id="security-xws-exception-handling">
<title>Security Exception Handling</title>
<para>
When an securement or validation action fails, the <classname>XwsSecurityInterceptor</classname>
@@ -1119,14 +1117,14 @@
</note>
</section>
</section>
<section id="security-wss4j-security-interceptor">
<section xml:id="security-wss4j-security-interceptor">
<title>
<classname>Wss4jSecurityInterceptor</classname>
</title>
<para>
The <classname>Wss4jSecurityInterceptor</classname> is an <classname>EndpointInterceptor</classname>
(see<xref linkend="server-endpoint-interceptor"/>) that is based on
<ulink url="http://ws.apache.org/wss4j/">Apache's WSS4J</ulink>.
(see <xref linkend="server-endpoint-interceptor"/>) that is based on
<link xl:href="http://ws.apache.org/wss4j/">Apache's WSS4J</link>.
</para>
<para>
WSS4J implements the following standards:
@@ -1554,7 +1552,7 @@
]]></programlisting>
</section>
</section>
<section id="security-wss4j-digital-signatures">
<section xml:id="security-wss4j-digital-signatures">
<title>Digital Signatures</title>
<para>
This section describes the various signature options available in the

145
src/reference/docbook/server.xml
View File

@@ -1,9 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="server">
<chapter xml:id="server"
xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xl="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">
<title>Creating a Web service with Spring-WS</title>
<section id="ws-introduction">
<section xml:id="ws-introduction">
<title>Introduction</title>
<para>
Spring-WS's server-side support is designed around a
@@ -38,10 +42,7 @@
The processing and dispatching flow of the <classname>MessageDispatcher</classname> is illustrated in the
following sequence diagram.
<mediaobject>
<imageobject role="fo">
<imagedata fileref="src/docbkx/resources/images/sequence.png" format="PNG" align="center"/>
</imageobject>
<imageobject role="html">
<imageobject>
<imagedata fileref="images/sequence.png" format="PNG" align="center"/>
</imageobject>
<caption>
@@ -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.
</para>
<section id="message-dispatcher-servlet">
<section xml:id="message-dispatcher-servlet">
<title><classname>MessageDispatcherServlet</classname></title>
<para>
The <classname>MessageDispatcherServlet</classname> is a standard <interfacename>Servlet</interfacename>
@@ -182,7 +183,7 @@
Javadoc of <classname>AbstractMessageDispatcherServletInitializer</classname> and
<classname>AbstractAnnotationConfigMessageDispatcherServletInitializer</classname>.
</para>
<section id="server-automatic-wsdl-exposure">
<section xml:id="server-automatic-wsdl-exposure">
<title>Automatic WSDL exposure</title>
<para>
The <classname>MessageDispatcherServlet</classname> will automatically detect any
@@ -506,7 +507,7 @@ public DefaultWsdl11Definition orders() {
<title>Embedded HTTP Server transport</title>
<para>
Spring Web Services provides a transport based on Sun's JRE 1.6
<ulink url="http://java.sun.com/javase/6/docs/jre/api/net/httpserver/spec/index.html">HTTP server</ulink>.
<link xl:href="http://java.sun.com/javase/6/docs/jre/api/net/httpserver/spec/index.html">HTTP server</link>.
The embedded HTTP Server is a standalone server that is simple to configure. It lends itself to a lighter
alternative to conventional servlet containers.
</para>
@@ -571,14 +572,14 @@ public DefaultWsdl11Definition orders() {
</para>
<para>
For more information on the <classname>SimpleHttpServerFactoryBean</classname>, refer to the
<ulink url="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/remoting/support/SimpleHttpServerFactoryBean.html">Javadoc</ulink>.
<link xl:href="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/remoting/support/SimpleHttpServerFactoryBean.html">Javadoc</link>.
</para>
</section>
<section>
<title>XMPP transport</title>
<para>
Finally, Spring Web Services 2.0 introduced support for XMPP, otherwise known as Jabber. The support
is based on the <ulink url="http://www.igniterealtime.org/projects/smack/index.jsp">Smack</ulink>
is based on the <link xl:href="http://www.igniterealtime.org/projects/smack/index.jsp">Smack</link>
library.
</para>
<para>
@@ -619,7 +620,7 @@ public DefaultWsdl11Definition orders() {
</para>
</section>
</section>
<section id="server-endpoints">
<section xml:id="server-endpoints">
<title>Endpoints</title>
<para>
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:
<programlistingco>
<areaspec>
<area coords="10" id="server-endpoint-atEndpoint"/>
<area coords="15" id="server-endpoint-constructor"/>
<area coords="21" id="server-endpoint-order"/>
<area coords="28" id="server-endpoint-getOrder"/>
<areaset coords="" id="server-endpoint-payloadRoot">
<area coords="20" id="server-endpoint-payloadRoot-1"/>
<area coords="26" id="server-endpoint-payloadRoot-2"/>
<area coords="10" xml:id="server-endpoint-atEndpoint"/>
<area coords="15" xml:id="server-endpoint-constructor"/>
<area coords="21" xml:id="server-endpoint-order"/>
<area coords="28" xml:id="server-endpoint-getOrder"/>
<areaset xml:id="server-endpoint-payloadRoot">
<area coords="20" xml:id="server-endpoint-payloadRoot-1"/>
<area coords="26" xml:id="server-endpoint-payloadRoot-2"/>
</areaset>
</areaspec>
<programlisting><![CDATA[package samples;
@@ -804,14 +805,14 @@ public class MyConfiguration extends WsConfigurerAdapter {
bean definition is created per container. Being a singleton implies that more than one thread
can use it at the same time, so the endpoint has to be thread safe. If you want to use a different
scope, such as prototype, refer to the
<ulink url="http://static.springframework.org/spring/docs/2.5.x/reference/beans.html#beans-factory-scopes">Spring Reference documentation</ulink>.
<link xl:href="http://static.springframework.org/spring/docs/2.5.x/reference/beans.html#beans-factory-scopes">Spring Reference documentation</link>.
</para>
<para>
Note that all abstract base classes provided in Spring-WS are thread safe, unless otherwise indicated
in the class-level Javadoc.
</para>
</note>
<section id="server-atEndpoint-methods">
<section xml:id="server-atEndpoint-methods">
<title><interfacename>@Endpoint</interfacename> handling methods</title>
<para>
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) {
(<interfacename>DOMSource</interfacename>, <interfacename>SAXSource</interfacename>,
<interfacename>StreamSource</interfacename>, and <interfacename>StAXSource</interfacename>)
</entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled by default.</entry>
</row>
<row>
<entry align="center">W3C DOM</entry>
<entry><interfacename>org.w3c.dom.Element</interfacename></entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled by default</entry>
</row>
<row>
<entry align="center">dom4j</entry>
<entry><interfacename>org.dom4j.Element</interfacename></entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled when dom4j is on the classpath.</entry>
</row>
<row>
<entry align="center">JDOM</entry>
<entry><classname>org.jdom.Element</classname></entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled when JDOM is on the classpath.</entry>
</row>
<row>
<entry align="center">XOM</entry>
<entry><classname>nu.xom.Element</classname></entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled when XOM is on the classpath.</entry>
</row>
<row>
@@ -909,7 +910,7 @@ public void order(@RequestPayload Element orderElement) {
<interfacename>javax.xml.stream.XMLStreamReader</interfacename> and
<interfacename>javax.xml.stream.XMLEventReader</interfacename>
</entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled when StAX is on the classpath.</entry>
</row>
<row>
@@ -919,16 +920,16 @@ public void order(@RequestPayload Element orderElement) {
<interfacename>org.w3c.Node</interfacename>,
<interfacename>org.w3c.dom.NodeList</interfacename>, or
type that can be converted from a <classname>String</classname> by a Spring 3
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/validation.html#core-convert">conversion service</ulink>,
<link xl:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/validation.html#core-convert">conversion service</link>,
and that is annotated with <interfacename>@XPathParam</interfacename>.
</entry>
<entry align="center">&cross;</entry>
<entry align="center">No</entry>
<entry>Enabled by default, see <xref linkend="server-xpath-param" />.</entry>
</row>
<row>
<entry align="center">Message context</entry>
<entry><interfacename>org.springframework.ws.context.MessageContext</interfacename></entry>
<entry align="center">&cross;</entry>
<entry align="center">No</entry>
<entry>Enabled by default.</entry>
</row>
<row>
@@ -942,7 +943,7 @@ public void order(@RequestPayload Element orderElement) {
when used in combination with the <interfacename>@SoapHeader</interfacename>
annotation.
</entry>
<entry align="center">&cross;</entry>
<entry align="center">No</entry>
<entry>Enabled by default.</entry>
</row>
<row>
@@ -952,16 +953,16 @@ public void order(@RequestPayload Element orderElement) {
<interfacename>javax.xml.bind.annotation.XmlRootElement</interfacename>,
and <classname>javax.xml.bind.JAXBElement</classname>.
</entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled when JAXB2 is on the classpath.</entry>
</row>
<row>
<entry align="center">OXM</entry>
<entry>
Any type supported by a Spring OXM
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/oxm.html#d0e26164"><interfacename>Unmarshaller</interfacename></ulink>.
<link xl:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/oxm.html#d0e26164"><interfacename>Unmarshaller</interfacename></link>.
</entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>
Enabled when the <literal>unmarshaller</literal> attribute of
<literal>&lt;sws:annotation-driven/&gt;</literal> is specified.
@@ -1002,7 +1003,7 @@ public void order(@RequestPayload Element orderElement) {
Refer to the class-level Javadoc of <classname>DefaultMethodEndpointAdapter</classname> and
<interfacename>MethodArgumentResolver</interfacename> to see how.
</para>
<section id="server-xpath-param">
<section xml:id="server-xpath-param">
<title><interfacename>@XPathParam</interfacename></title>
<para>
One parameter type needs some extra explanation: <interfacename>@XPathParam</interfacename>.
@@ -1011,7 +1012,7 @@ public void order(@RequestPayload Element orderElement) {
evaluation of the expression.
Here is an example:
</para>
<programlisting id="server-payload-root-annotation">package samples;
<programlisting xml:id="server-payload-root-annotation">package samples;
import javax.xml.transform.Source;
@@ -1057,7 +1058,7 @@ public class AnnotationOrderEndpoint {
</itemizedlist>
In addition to this list, you can use any type that can be converted from a
<classname>String</classname> by a Spring 3
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/validation.html#core-convert">conversion service</ulink>.
<link xl:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/validation.html#core-convert">conversion service</link>.
</para>
</section>
@@ -1097,7 +1098,7 @@ public class AnnotationOrderEndpoint {
<entry>
<literal>void</literal>
</entry>
<entry align="center">&cross;</entry>
<entry align="center">No</entry>
<entry>Enabled by default.</entry>
</row>
<row>
@@ -1107,31 +1108,31 @@ public class AnnotationOrderEndpoint {
(<interfacename>DOMSource</interfacename>, <interfacename>SAXSource</interfacename>,
<interfacename>StreamSource</interfacename>, and <interfacename>StAXSource</interfacename>)
</entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled by default.</entry>
</row>
<row>
<entry align="center">W3C DOM</entry>
<entry><interfacename>org.w3c.dom.Element</interfacename></entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled by default</entry>
</row>
<row>
<entry align="center">dom4j</entry>
<entry><interfacename>org.dom4j.Element</interfacename></entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled when dom4j is on the classpath.</entry>
</row>
<row>
<entry align="center">JDOM</entry>
<entry><classname>org.jdom.Element</classname></entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled when JDOM is on the classpath.</entry>
</row>
<row>
<entry align="center">XOM</entry>
<entry><classname>nu.xom.Element</classname></entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled when XOM is on the classpath.</entry>
</row>
<row>
@@ -1141,16 +1142,16 @@ public class AnnotationOrderEndpoint {
<interfacename>javax.xml.bind.annotation.XmlRootElement</interfacename>,
and <classname>javax.xml.bind.JAXBElement</classname>.
</entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>Enabled when JAXB2 is on the classpath.</entry>
</row>
<row>
<entry align="center">OXM</entry>
<entry>
Any type supported by a Spring OXM
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/oxm.html#d0e26096"><interfacename>Marshaller</interfacename></ulink>.
<link xl:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/oxm.html#d0e26096"><interfacename>Marshaller</interfacename></link>.
</entry>
<entry align="center">&check;</entry>
<entry align="center">Yes</entry>
<entry>
Enabled when the <literal>marshaller</literal> attribute of
<literal>&lt;sws:annotation-driven/&gt;</literal> is specified.
@@ -1170,7 +1171,7 @@ public class AnnotationOrderEndpoint {
</section>
</section>
</section>
<section id="server-endpoint-mapping">
<section xml:id="server-endpoint-mapping">
<title>Endpoint mappings</title>
<para>
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 <literal>SOAPAction</literal> header, the
method will be invoked.
</para>
<section id="server-ws-addressing">
<section xml:id="server-ws-addressing">
<title>WS-Addressing</title>
<para>
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
<footnote>
<para>For more information on WS-Addressing, see <ulink url="http://en.wikipedia.org/wiki/WS-Addressing"/>.</para>
<para>For more information on WS-Addressing, see <link xl:href="http://en.wikipedia.org/wiki/WS-Addressing"/>.</para>
</footnote>.
Here is an example of a WS-Addressing message:
<programlisting><![CDATA[<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope"
@@ -1336,7 +1337,7 @@ public class AnnotationOrderEndpoint {
</para>
</section>
</section>
<section id="server-endpoint-interceptor">
<section xml:id="server-endpoint-interceptor">
<title>Intercepting requests - the <interfacename>EndpointInterceptor</interfacename> interface</title>
<para>
The endpoint mapping mechanism has the notion of endpoint interceptors. These can be extremely useful
@@ -1502,7 +1503,7 @@ public class MyWsConfiguration extends WsConfigurerAdapter {
</section>
</section>
</section>
<section id="server-endpoint-exception-resolver">
<section xml:id="server-endpoint-exception-resolver">
<title>Handling Exceptions</title>
<para>
Spring-WS provides <classname>EndpointExceptionResolvers</classname> to ease the pain of unexpected
@@ -1696,11 +1697,11 @@ public class MyBusinessException extends Exception {
</para>
<programlistingco>
<areaspec>
<area id="server.test.endpoint.annotation" coords="5"/>
<areaset id="server.test.endpoint.method" coords="">
<area id="server.test.endpoint.method.responsePayload" coords="8"/>
<area id="server.test.endpoint.method.method" coords="9"/>
<area id="server.test.endpoint.method.requestPayload" coords="10"/>
<area xml:id="server.test.endpoint.annotation" coords="5"/>
<areaset xml:id="server.test.endpoint.method">
<area xml:id="server.test.endpoint.method.responsePayload" coords="8"/>
<area xml:id="server.test.endpoint.method.method" coords="9"/>
<area xml:id="server.test.endpoint.method.requestPayload" coords="10"/>
</areaset>
</areaspec>
<programlisting><![CDATA[import org.springframework.ws.server.endpoint.annotation.Endpoint;
@@ -1744,20 +1745,20 @@ public class CustomerEndpoint {
</para>
<programlistingco>
<areaspec>
<areaset id="server.test.test.imports" coords="">
<area id="server.test.test.imports.client" coords="12"/>
<area id="server.test.test.imports.requestCreators" coords="13"/>
<area id="client.test.test.imports.responseMatchers" coords="14"/>
<areaset xml:id="server.test.test.imports">
<area xml:id="server.test.test.imports.client" coords="12"/>
<area xml:id="server.test.test.imports.requestCreators" coords="13"/>
<area xml:id="client.test.test.imports.responseMatchers" coords="14"/>
</areaset>
<areaset id="server.test.test.spring" coords="">
<area id="server.test.test.spring.runWith" coords="16"/>
<area id="server.test.test.spring.configuration" coords="17"/>
<areaset xml:id="server.test.test.spring">
<area xml:id="server.test.test.spring.runWith" coords="16"/>
<area xml:id="server.test.test.spring.configuration" coords="17"/>
</areaset>
<area id="server.test.test.applicationContext" coords="21"/>
<area id="server.test.test.mockClient" coords="27"/>
<areaset id="server.test.test.sendAndExpect" coords="">
<area id="server.test.test.send" coords="41"/>
<area id="server.test.test.expect" coords="42"/>
<area xml:id="server.test.test.applicationContext" coords="21"/>
<area xml:id="server.test.test.mockClient" coords="27"/>
<areaset xml:id="server.test.test.sendAndExpect">
<area xml:id="server.test.test.send" coords="41"/>
<area xml:id="server.test.test.expect" coords="42"/>
</areaset>
</areaspec>
<programlisting><![CDATA[import javax.xml.transform.Source;
@@ -1861,7 +1862,7 @@ public class CustomerEndpointIntegrationTest {
</calloutlist>
</programlistingco>
</section>
<section id="server-test-request-creator">
<section xml:id="server-test-request-creator">
<title><interfacename>RequestCreator</interfacename> and <classname>RequestCreators</classname></title>
<para>
Initially, the <classname>MockWebServiceClient</classname> will need to create a request message for the
@@ -1884,7 +1885,7 @@ public class CustomerEndpointIntegrationTest {
You will typically statically import <classname>RequestCreators</classname>.
</para>
</section>
<section id="server-test-response-matcher">
<section xml:id="server-test-response-matcher">
<title><interfacename>ResponseMatcher</interfacename> and <classname>ResponseMatchers</classname></title>
<para>
When the request message has been processed by the endpoint, and a response has been received,

110
src/reference/docbook/tutorial.xml
View File

@@ -1,7 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="tutorial">
<chapter xml:id="tutorial"
xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xl="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">
<title>Writing Contract-First Web Services</title>
<section>
<title>Introduction</title>
@@ -48,7 +52,7 @@
<para>
A holiday consists of a start date and an end date. We have also decided to
use the standard
<ulink url="http://www.cl.cam.ac.uk/~mgk25/iso-time.html">ISO 8601</ulink>
<link xl:href="http://www.cl.cam.ac.uk/~mgk25/iso-time.html">ISO 8601</link>
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 @@
</para>
</section>
</section>
<section id="tutorial.xsd">
<section xml:id="tutorial.xsd">
<title>Data Contract</title>
<para>
Now that we have seen some examples of the XML data that we will use,
@@ -110,9 +114,9 @@
</para>
<itemizedlist>
<listitem><para>DTDs</para></listitem>
<listitem><para><ulink url="http://www.w3.org/XML/Schema">XML Schema (XSD)</ulink></para></listitem>
<listitem><para><ulink url="http://www.relaxng.org/">RELAX NG</ulink></para></listitem>
<listitem><para><ulink url="http://www.schematron.com/">Schematron</ulink></para></listitem>
<listitem><para><link xl:href="http://www.w3.org/XML/Schema">XML Schema (XSD)</link></para></listitem>
<listitem><para><link xl:href="http://www.relaxng.org/">RELAX NG</link></para></listitem>
<listitem><para><link xl:href="http://www.schematron.com/">Schematron</link></para></listitem>
</itemizedlist>
<para>
DTDs have limited namespace support, so they are not suitable for Web
@@ -226,14 +230,14 @@
</para>
<programlistingco>
<areaspec>
<area id="tutorial.xsd.all" coords="8"/>
<areaset id="tutorial.xsd.dates" coords="">
<area id="tutorial.xsd.dates.1" coords="16"/>
<area id="tutorial.xsd.dates.2" coords="17"/>
<area xml:id="tutorial.xsd.all" coords="8"/>
<areaset xml:id="tutorial.xsd.dates">
<area xml:id="tutorial.xsd.dates.1" coords="16"/>
<area xml:id="tutorial.xsd.dates.2" coords="17"/>
</areaset>
<areaset id="tutorial.xsd.strings" coords="">
<area id="tutorial.xsd.strings.1" coords="23"/>
<area id="tutorial.xsd.strings.2" coords="24"/>
<areaset xml:id="tutorial.xsd.strings">
<area xml:id="tutorial.xsd.strings.1" coords="23"/>
<area xml:id="tutorial.xsd.strings.2" coords="24"/>
</areaset>
</areaspec>
<programlisting><![CDATA[<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
@@ -287,10 +291,10 @@
We store this file as <filename>hr.xsd</filename>.
</para>
</section>
<section id="tutorial-service-contract">
<section xml:id="tutorial-service-contract">
<title>Service contract</title>
<para>
A service contract is generally expressed as a <ulink url="http://www.w3.org/TR/wsdl">WSDL</ulink> file.
A service contract is generally expressed as a <link xl:href="http://www.w3.org/TR/wsdl">WSDL</link> file.
Note that in Spring-WS, <emphasis>writing the WSDL by hand is not required</emphasis>. Based on the XSD and
some conventions, Spring-WS can create the WSDL for you, as explained in the section entitled
<xref linkend="tutorial.implementing.endpoint"/>.
@@ -345,27 +349,27 @@
</para>
<programlistingco>
<areaspec>
<area id="tutorial.wsdl.import" coords="9"/>
<areaset id="tutorial.wsdl.message" coords="">
<area id="tutorial.wsdl.message.def" coords="13"/>
<area id="tutorial.wsdl.message.ref" coords="18"/>
<area xml:id="tutorial.wsdl.import" coords="9"/>
<areaset xml:id="tutorial.wsdl.message">
<area xml:id="tutorial.wsdl.message.def" coords="13"/>
<area xml:id="tutorial.wsdl.message.ref" coords="18"/>
</areaset>
<area id="tutorial.wsdl.message.part" coords="14"/>
<areaset id="tutorial.wsdl.portType" coords="">
<area id="tutorial.wsdl.portType.def" coords="16"/>
<area id="tutorial.wsdl.portType.ref" coords="21"/>
<area xml:id="tutorial.wsdl.message.part" coords="14"/>
<areaset xml:id="tutorial.wsdl.portType">
<area xml:id="tutorial.wsdl.portType.def" coords="16"/>
<area xml:id="tutorial.wsdl.portType.ref" coords="21"/>
</areaset>
<areaset id="tutorial.wsdl.binding" coords="">
<area id="tutorial.wsdl.binding.def" coords="21"/>
<area id="tutorial.wsdl.binding.ref" coords="32"/>
<areaset xml:id="tutorial.wsdl.binding">
<area xml:id="tutorial.wsdl.binding.def" coords="21"/>
<area xml:id="tutorial.wsdl.binding.ref" coords="32"/>
</areaset>
<areaset id="tutorial.wsdl.doclit" coords="">
<area id="tutorial.wsdl.doclit.doc" coords="22"/>
<area id="tutorial.wsdl.doclit.lit" coords="27"/>
<areaset xml:id="tutorial.wsdl.doclit">
<area xml:id="tutorial.wsdl.doclit.doc" coords="22"/>
<area xml:id="tutorial.wsdl.doclit.lit" coords="27"/>
</areaset>
<area id="tutorial.wsdl.transport" coords="23"/>
<area id="tutorial.wsdl.soapAction" coords="25"/>
<area id="tutorial.wsdl.address" coords="33"/>
<area xml:id="tutorial.wsdl.transport" coords="23"/>
<area xml:id="tutorial.wsdl.soapAction" coords="25"/>
<area xml:id="tutorial.wsdl.address" coords="33"/>
</areaspec>
<programlisting><![CDATA[
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
@@ -461,10 +465,10 @@
This is the final WSDL. We will describe how to implement the resulting schema and WSDL in the next section.
</para>
</section>
<section id="tutorial-creating-project">
<section xml:id="tutorial-creating-project">
<title>Creating the project</title>
<para>
In this section, we will be using <ulink url="http://maven.apache.org/">Maven3</ulink> to create the
In this section, we will be using <link xl:href="http://maven.apache.org/">Maven3</link> 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.
</para>
@@ -526,7 +530,7 @@
<filename>'WEB-INF/'</filename> folder.
</para>
</section>
<section id="tutorial.implementing.endpoint">
<section xml:id="tutorial.implementing.endpoint">
<title>Implementing the Endpoint</title>
<para>
In Spring-WS, you will implement <emphasis>Endpoints</emphasis> to handle incoming XML messages.
@@ -539,17 +543,17 @@
<section>
<title>Handling the XML Message</title>
<para>
In this sample application, we are going to use <ulink url="http://www.jdom.org">JDom 2</ulink> to handle
In this sample application, we are going to use <link xl:href="http://www.jdom.org">JDom 2</link> to handle
the XML message.
We are also using <ulink url="http://www.w3schools.com/xpath/">XPath</ulink>, because it allows us to
We are also using <link xl:href="http://www.w3schools.com/xpath/">XPath</link>, because it allows us to
select particular parts of the XML JDOM tree, without requiring strict schema conformance.
</para>
<programlistingco>
<areaspec>
<area id="tutorial.endpoint.atEndpoint" coords="21"/>
<area id="tutorial.endpoint.constr" coords="35"/>
<area id="tutorial.endpoint.payloadRoot" coords="48"/>
<area id="tutorial.endpoint.method" coords="49"/>
<area xml:id="tutorial.endpoint.atEndpoint" coords="21"/>
<area xml:id="tutorial.endpoint.constr" coords="35"/>
<area xml:id="tutorial.endpoint.payloadRoot" coords="48"/>
<area xml:id="tutorial.endpoint.method" coords="49"/>
</areaspec>
<programlisting><![CDATA[package com.mycompany.hr.ws;
@@ -720,7 +724,7 @@ public class HolidayEndpoint {
We also instruct Spring-WS to use annotation-driven endpoints, with the
<literal>&lt;sws:annotation-driven&gt;</literal> element.
</para>
<programlisting id="tutorial.example.sws-conf-file"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans"
<programlisting xml:id="tutorial.example.sws-conf-file"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:sws="http://www.springframework.org/schema/web-services"
@@ -780,7 +784,7 @@ public interface HumanResourceService {
</para>
<programlistingco>
<areaspec>
<area id="tutorial.stubimpl.atService" coords="7"/>
<area xml:id="tutorial.stubimpl.atService" coords="7"/>
</areaspec>
<programlisting><![CDATA[package com.mycompany.hr.service;
@@ -807,7 +811,7 @@ public class StubHumanResourceService implements HumanResourceService {
</programlistingco>
</section>
</section>
<section id="tutorial-publishing-wsdl">
<section xml:id="tutorial-publishing-wsdl">
<title>Publishing the WSDL</title>
<para>
Finally, we need to publish the WSDL. As stated in <xref linkend="tutorial-service-contract"/>, we don't
@@ -816,11 +820,11 @@ public class StubHumanResourceService implements HumanResourceService {
</para>
<programlistingco>
<areaspec>
<area id="tutorial.wsdl.gen.bean" coords="1"/>
<area id="tutorial.wsdl.gen.schema" coords="5"/>
<area id="tutorial.wsdl.gen.portType" coords="2"/>
<area id="tutorial.wsdl.gen.locationUri" coords="3"/>
<area id="tutorial.wsdl.gen.tns" coords="4"/>
<area xml:id="tutorial.wsdl.gen.bean" coords="1"/>
<area xml:id="tutorial.wsdl.gen.schema" coords="5"/>
<area xml:id="tutorial.wsdl.gen.portType" coords="2"/>
<area xml:id="tutorial.wsdl.gen.locationUri" coords="3"/>
<area xml:id="tutorial.wsdl.gen.tns" coords="4"/>
</areaspec>
<programlisting><![CDATA[<sws:dynamic-wsdl id="holiday"
portTypeName="HumanResource"
@@ -879,9 +883,9 @@ public class StubHumanResourceService implements HumanResourceService {
<para>
You can create a WAR file using <command>mvn install</command>.
If you deploy the application (to Tomcat, Jetty, etc.), and point your browser at
<ulink url="http://localhost:8080/holidayService/holiday.wsdl">this location</ulink>, you will
<link xl:href="http://localhost:8080/holidayService/holiday.wsdl">this location</link>, you will
see the generated WSDL. This WSDL is ready to be used by clients, such as
<ulink url="http://www.soapui.org/">soapUI</ulink>, or other SOAP frameworks.
<link xl:href="http://www.soapui.org/">soapUI</link>, or other SOAP frameworks.
</para>
</section>
<para>

26
src/reference/docbook/what-is-spring-ws.xml
View File

@@ -1,7 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="what-is-spring-ws">
<chapter xml:id="what-is-spring-ws"
xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd">
<title>What is Spring Web Services?</title>
<section>
<title>Introduction</title>
@@ -37,9 +38,8 @@
<formalpara>
<title>Flexible XML Marshalling</title>
<para>
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.
</para>
</formalpara>
<formalpara>
@@ -62,12 +62,6 @@
This means you can use your existing Spring Security configuration for your SOAP service as well.
</para>
</formalpara>
<formalpara>
<title>Built by Maven</title>
<para>
This assists you in effectively reusing the Spring Web Services artifacts in your own Maven-based projects.
</para>
</formalpara>
<formalpara>
<title>Apache license</title>
<para>
@@ -122,13 +116,9 @@
</itemizedlist>
<para>
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.
<mediaobject>
<imageobject role="fo">
<imagedata fileref="src/docbkx/resources/images/spring-deps.png"
format="PNG" align="center"/>
</imageobject>
<imageobject role="html">
<imageobject>
<imagedata fileref="images/spring-deps.png"
format="PNG" align="center"/>
</imageobject>

20
src/reference/docbook/why-contract-first.xml
View File

@@ -1,7 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="why-contract-first">
<chapter xml:id="why-contract-first"
xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xl="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">
<title>Why Contract First?</title>
<section>
<title>Introduction</title>
@@ -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
<ulink url="http://www.w3.org/TR/wsdl">WSDL specification</ulink>, or read the
<ulink url="http://www.w3schools.com/wsdl/">WSDL tutorial</ulink>
<link xl:href="http://www.w3.org/TR/wsdl">WSDL specification</link>, or read the
<link xl:href="http://www.w3schools.com/wsdl/">WSDL tutorial</link>
</para>
</sidebar>
<para>
@@ -29,7 +33,7 @@
<title>Object/XML Impedance Mismatch</title>
<para>
Similar to the field of ORM, where we have an
<ulink url="http://en.wikipedia.org/wiki/Object-Relational_impedance_mismatch">Object/Relational impedance mismatch</ulink>,
<link xl:href="http://en.wikipedia.org/wiki/Object-Relational_impedance_mismatch">Object/Relational impedance mismatch</link>,
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
<ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.1.html#SOAP_encodingStyle_Attribute">Basic
Profile</ulink>).
<link xl:href="http://www.ws-i.org/Profiles/BasicProfile-1.1.html#SOAP_encodingStyle_Attribute">Basic
Profile</link>).
</para>
</section>
<para>