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

Starting on client docs.

Browse Source
This commit is contained in:
Arjen Poutsma
2007-02-12 22:21:54 +00:00
parent b3498234d3
commit 988473213a
7 changed files with 275 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
doc/src/docbkx/client.xml Normal file
View File

@@ -0,0 +1,51 @@
<?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">
<title>Using Spring Web Services on the Client</title>
<section>
<title>Introduction</title>
<para>
Spring-WS provides a client-side Web service API that allows for consistent, XML-driven access to Web
services. It also allows for use of <link linkend="oxm">marshallers and unmarshallers</link>.
</para>
<para>
The package <package>org.springframework.ws.client.core</package> provides the core functionality for using
the client-side access API. It contains template classes that simplifies the use of Web services, much like
the <classname>JdbcTemplate</classname> does for JDBC. The design principle common to Spring template
classes is to provide helper methods to perform common operations and for more sophisticated usage, delegate
the essence of the processing task to user implemented callback interfaces. The Web service template
follows the same design. The classes offer various
convenience methods for the sending and receiving of XML messages, marshalling objects to XML before sending,
and allows for multiple transports,
</para>
</section>
<section>
<title>Using the client-side API</title>
<section>
<title><classname>WebServiceTemplate</classname></title>
<para>
The <classname>WebServiceTemplate</classname> is the core class for client-side Web service access in
Spring-WS. It contains methods for sending <classname>Source</classname> objects, and receiving response
messages as either <classname>Source</classname> or <classname>Result</classname>. Additionally, it can
marshal objects to XML before sending them across a transport, and unmarshal the response XML into an
object again.
</para>
</section>
<section>
<title>Transports</title>
<para>
The <classname>WebServiceTemplate</classname> requires a reference to a
<classname>MessageSender</classname>. The message sender is responsible for sending the XML message
across a transport layer.
</para>
<para>
There are two implementations of the <classname>MessageSender</classname> interface for sending messages
via HTTP. The simplest implementation is the <classname>HttpUrlConnectionMessageSender</classname>,
which uses the facilities provided by Java SE itself. The alternative is the
<classname>CommonsHttpMessageSender</classname>, which uses the Jakarta Commons HttpClient. Use the
latter if you need more advanced and easy-to-use functionality. Both HTTP message senders require an
URL to be set using the <property>url</property> property.
</section>
</section>
</chapter>

73
doc/src/docbkx/index.xml
View File

@@ -1,50 +1,41 @@
<?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" [
<!ENTITY preface SYSTEM "preface.xml">
<!ENTITY overview SYSTEM "overview.xml">
<!ENTITY contract-first SYSTEM "contract-first.xml">
<!ENTITY ws SYSTEM "ws.xml">
<!ENTITY security SYSTEM "security.xml">
<!ENTITY oxm SYSTEM "oxm.xml">
<!ENTITY bibliography SYSTEM "bibliography.xml">
]>
<!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>
<releaseinfo>Version &version;</releaseinfo>
<pubdate>(Work in progress)</pubdate>
<bookinfo>
<title>Spring Web Services</title>
<subtitle>Reference Documentation</subtitle>
<releaseinfo>
Version
&version;
</releaseinfo>
<pubdate>(Work in progress)</pubdate>
<authorgroup>
<author>
<firstname>Arjen</firstname>
<surname>Poutsma</surname>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Arjen</firstname>
<surname>Poutsma</surname>
</author>
</authorgroup>
<legalnotice>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.
</legalnotice>
</bookinfo>
<legalnotice>
<para>
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.
</para>
</legalnotice>
</bookinfo>
<toc/>
<toc />
&preface;
&overview;
&contract-first;
&ws;
&security;
&oxm;
&bibliography;
<xi:include href="preface.xml" />
<xi:include href="overview.xml" />
<xi:include href="contract-first.xml" />
<xi:include href="server.xml" />
<xi:include href="client.xml" />
<xi:include href="security.xml" />
<xi:include href="oxm.xml" />
<xi:include href="bibliography.xml" />
</book>

2
doc/src/docbkx/overview.xml
View File

@@ -1,4 +1,6 @@
<?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="introduction">
<title>Introduction</title>

136
doc/src/docbkx/oxm.xml
View File

@@ -1,72 +1,72 @@
<?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="oxm">
<title>Marshalling XML using O/X Mappers</title>
<title>Marshalling XML using O/X Mappers</title>
<section id="oxm-introduction">
<title>Introduction</title>
<para>
In this chapter, we will describe Spring's Object/XML Mapping support. Object/XML Mapping, or O/X mapping
for short, is the act of converting an XML document to and from an object. This conversion process is also
known as XML Marshalling, or XML Serialization. This chapter uses these terms interchangeably.
</para>
<para>
Within the field of O/X mapping, a <emphasis>marshaller</emphasis> is responsible for serializing an object
(graph) to XML. In similar fashion, an <emphasis>unmarshaller</emphasis> deserializes the XML to an object
graph. This XML can take the form of a DOM document, an input or output stream, or a SAX handler.
</para>
<para>
Some of the benefits of using Spring for your O/X mapping needs are:
</para>
<formalpara>
<title>Ease of configuration</title>
<para>
Spring's bean factory makes it easy to configure marshallers, without needing to construct JAXB context,
JiBX binding factories, etc. The marshallers can be configured as any other bean in your application
context.
</para>
</formalpara>
<formalpara>
<title>Consistent Interfaces</title>
<para>
Spring's O/X mapping operates through two global interfaces: the
<classname>Marshaller</classname>
and
<classname>Unmarshaller</classname>
interface. These abstractions allow you to switch O/X mapping
frameworks with relative ease, with little or no changes required on the classes that do the
marshalling. This approach has the additional benefit of making it possible to do XML marshalling with a
mix-and-match approach (e.g. some marshalling performed using JAXB, other using XMLBeans) in a
non-intrusive fashion, leveraging the strength of each technology.
</para>
</formalpara>
<formalpara>
<title>Consistent Exception Hierarchy</title>
<para>
Spring provides a conversion from exceptions from the underlying O/X mapping tool to its own
exception hierarchy with the
<classname>XmlMappingException</classname>
as the root exception. As can be
expected, these runtime exceptions wrap the original exception so no information is lost.
</para>
</formalpara>
</section>
<section id="oxm-marshaller-unmarshaller">
<title>Marshaller and Unmarshaller</title>
<para>
As stated in the introduction, a
<emphasis>marshaller</emphasis>
serializes an object to XML, and an
<emphasis>unmarshaller</emphasis>
deserializes XML stream to an object. In this section, we will describe
the two Spring interfaces used for this purpose.
</para>
<section>
<title>Marshaller</title>
<para>
Spring abstracts all marshalling operations behind the
<classname>org.springframework.oxm.Marshaller</classname>
interface, which is listed below.
<programlisting><![CDATA[
<section id="oxm-introduction">
<title>Introduction</title>
<para>
In this chapter, we will describe Spring's Object/XML Mapping support. Object/XML Mapping, or O/X mapping
for short, is the act of converting an XML document to and from an object. This conversion process is also
known as XML Marshalling, or XML Serialization. This chapter uses these terms interchangeably.
</para>
<para>
Within the field of O/X mapping, a
<emphasis>marshaller</emphasis>
is responsible for serializing an object (graph) to XML. In similar fashion, an
<emphasis>unmarshaller</emphasis>
deserializes the XML to an object graph. This XML can take the form of a DOM document, an input or output
stream, or a SAX handler.
</para>
<para>Some of the benefits of using Spring for your O/X mapping needs are:</para>
<formalpara>
<title>Ease of configuration</title>
<para>
Spring's bean factory makes it easy to configure marshallers, without needing to construct JAXB context,
JiBX binding factories, etc. The marshallers can be configured as any other bean in your application
context.
</para>
</formalpara>
<formalpara>
<title>Consistent Interfaces</title>
<para>
Spring's O/X mapping operates through two global interfaces: the
<classname>Marshaller</classname>
and
<classname>Unmarshaller</classname>
interface. These abstractions allow you to switch O/X mapping frameworks with relative ease, with little
or no changes required on the classes that do the marshalling. This approach has the additional benefit
of making it possible to do XML marshalling with a mix-and-match approach (e.g. some marshalling
performed using JAXB, other using XMLBeans) in a non-intrusive fashion, leveraging the strength of each
technology.
</para>
</formalpara>
<formalpara>
<title>Consistent Exception Hierarchy</title>
<para>
Spring provides a conversion from exceptions from the underlying O/X mapping tool to its own exception
hierarchy with the
<classname>XmlMappingException</classname>
as the root exception. As can be expected, these runtime exceptions wrap the original exception so no
information is lost.
</para>
</formalpara>
</section>
<section id="oxm-marshaller-unmarshaller">
<title>Marshaller and Unmarshaller</title>
<para>
As stated in the introduction, a <emphasis>marshaller</emphasis> serializes an object to XML, and an
<emphasis>unmarshaller</emphasis> deserializes XML stream to an object. In this section, we will describe
the two Spring interfaces used for this purpose.
</para>
<section>
<title>Marshaller</title>
<para>
Spring abstracts all marshalling operations behind the
<classname>org.springframework.oxm.Marshaller</classname>
interface, which is listed below.
<programlisting><![CDATA[
public interface Marshaller {
/**
@@ -127,7 +127,6 @@ public interface Marshaller {
</tbody>
</tgroup>
</informaltable>
</para>
<note>
<para>
Although the
@@ -141,6 +140,7 @@ public interface Marshaller {
manages this.
</para>
</note>
</para>
</section>
<section>
<title>Unmarshaller</title>
@@ -606,12 +606,12 @@ public class Application {
...
</beans>]]></programlisting>
</section>
<note>
<para>
Note that XStream is an XML serialization library, not a data binding library. Therefore, it has
limited namespace support. As such, it is rather unsuitable for usage within Web services.
</para>
</note>
</section>
</section>
</chapter>

2
doc/src/docbkx/preface.xml
View File

@@ -1,4 +1,6 @@
<?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">
<title>Preface</title>
<para>

208
doc/src/docbkx/security.xml
View File

@@ -1,87 +1,117 @@
<?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">
<title>Securing your Web services with Spring-WS</title>
<title>Securing your Web services with Spring-WS</title>
<section id="security-introduction">
<title>Introduction</title>
<para>
In this chapter, we will show you how to add WS-Security aspects to your Web services. We
will focus on the three different areas of WS-Security, namely:
</para>
<formalpara>
<title>Authentication</title>
<para>
This is the process of determining whether a <emphasis>principal</emphasis> is who they claim to be.
In this context, a "principal" generally means a user, device or some other system which can perform an
action in your application.
</para>
</formalpara>
<formalpara>
<title>Digital signatures</title>
<para>
The digital signature of a message is a piece of information based on both the document and the signer's
private key. It is created through the use of a hash function and a private signing function
(encrypting with the signer's private key).
</para>
</formalpara>
<formalpara>
<title>Encryption and Decryption</title>
<para>
<emphasis>Encryption</emphasis> is the process of transforming data into a form that is impossible to
read without the appropriate key. It is mainly used to keep information hidden from anyone for whom it
is not intended. <emphasis>Decryption</emphasis> is the reverse of encryption; it is the process of
transforming of encrypted data back into an readable form.
</para>
</formalpara>
<para>
All of these three areas are implemented using the <classname>XwsSecurityInterceptor</classname>, which we
will describe in <xref linkend="security-xws-security-interceptor"/>
</para>
<note>
<para>
Note that WS-Security (especially encryption and signing) requires substantial amounts of memory,
and will also decrease performance. If performance is important to you, you might want to consider using
not using WS-Security.
</para>
</note>
</section>
<section id="security-xws-security-interceptor">
<title>XwsSecurityInterceptor</title>
<para>
The <classname>XwsSecurityInterceptor</classname> is an <classname>EndpointInterceptor</classname> (see
<xref linkend="ws-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>).
</para>
<para>
Like any other endpoint interceptor, it is defined in the endpoint mapping (see <xref
linkend="ws-endpoint-mapping"/>). This means that you can be selective about adding WS-Security support:
some endpoint mappings require it, while others do not.
</para>
<para>
The <classname>XwsSecurityInterceptor</classname> requires a <emphasis>security policy file</emphasis> 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">
<citetitle>here</citetitle></ulink>. You can set the policy with the
<methodname>policyConfiguration</methodname> 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
<literal>SecurityConfiguration</literal> element as root (not a <literal>JAXRPCSecurity</literal>
element).
</para>
<para>
Additionally, the security interceptor requires one or more <classname>CallbackHandler</classname>s to
operate. These handlers are used to retrieve certificates, private keys, validate user credentials, etc.
Spring-WS offers handlers for most common security concerns, e.g. authenticating against a Acegi
authentication manager, signing outgoing messages based on a X509 certificate. The following sections
will indicate what callback handler to use for which security concern. You can set the callback handlers
using the <methodname>callbackHandler</methodname> or <methodname>callbackHandlers</methodname> property.
</para>
<para>
Here is an example that shows how to wire the <classname>XwsSecurityInterceptor</classname> up:
<programlisting><![CDATA[
<section id="security-introduction">
<title>Introduction</title>
<para>
In this chapter, we will show you how to add WS-Security aspects to your Web services. We will focus on the
three different areas of WS-Security, namely:
</para>
<formalpara>
<title>Authentication</title>
<para>
This is the process of determining whether a
<emphasis>principal</emphasis>
is who they claim to be. In this context, a "principal" generally means a user, device or some other
system which can perform an action in your application.
</para>
</formalpara>
<formalpara>
<title>Digital signatures</title>
<para>
The digital signature of a message is a piece of information based on both the document and the signer's
private key. It is created through the use of a hash function and a private signing function (encrypting
with the signer's private key).
</para>
</formalpara>
<formalpara>
<title>Encryption and Decryption</title>
<para>
<emphasis>Encryption</emphasis>
is the process of transforming data into a form that is impossible to read without the appropriate key.
It is mainly used to keep information hidden from anyone for whom it is not intended.
<emphasis>Decryption</emphasis>
is the reverse of encryption; it is the process of transforming of encrypted data back into an readable
form.
</para>
</formalpara>
<para>
All of these three areas are implemented using the
<classname>XwsSecurityInterceptor</classname>
, which we will describe in
<xref linkend="security-xws-security-interceptor" />
</para>
<note>
<para>
Note that WS-Security (especially encryption and signing) requires substantial amounts of memory, and
will also decrease performance. If performance is important to you, you might want to consider using not
using WS-Security.
</para>
</note>
</section>
<section id="security-xws-security-interceptor">
<title>XwsSecurityInterceptor</title>
<para>
The
<classname>XwsSecurityInterceptor</classname>
is an
<classname>EndpointInterceptor</classname>
(see
<xref linkend="ws-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>
).
</para>
<para>
Like any other endpoint interceptor, it is defined in the endpoint mapping (see
<xref linkend="ws-endpoint-mapping" />
). This means that you can be selective about adding WS-Security support: some endpoint mappings require it,
while others do not.
</para>
<para>
The
<classname>XwsSecurityInterceptor</classname>
requires a
<emphasis>security policy file</emphasis>
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">
<citetitle>here</citetitle>
</ulink>
. You can set the policy with the
<methodname>policyConfiguration</methodname>
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
<literal>SecurityConfiguration</literal>
element as root (not a
<literal>JAXRPCSecurity</literal>
element).
</para>
<para>
Additionally, the security interceptor requires one or more
<classname>CallbackHandler</classname>
s to operate. These handlers are used to retrieve certificates, private keys, validate user credentials,
etc. Spring-WS offers handlers for most common security concerns, e.g. authenticating against a Acegi
authentication manager, signing outgoing messages based on a X509 certificate. The following sections will
indicate what callback handler to use for which security concern. You can set the callback handlers using
the
<methodname>callbackHandler</methodname>
or
<methodname>callbackHandlers</methodname>
property.
</para>
<para>
Here is an example that shows how to wire the
<classname>XwsSecurityInterceptor</classname>
up:
<programlisting><![CDATA[
<beans>
<bean id="wsSecurityInterceptor"
class="org.springframework.ws.soap.security.xwss.XwsSecurityInterceptor">
@@ -140,13 +170,15 @@
</formalpara>
<section>
<title>KeyTool</title>
Supplied with your Java Virtual Machine is the <command>keytool</command>, a key and certificate management
utility. You can use this tool to create new key stores, add new private keys and certificates to them, etc.
It is beyond the scope of this document to provide a full reference of the <command>keytool</command>
command, but you can find a reference <ulink
url="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/keytool.html">
<citetitle>here</citetitle></ulink>, or by giving the command <prompt>keytool -help</prompt> on the command
line.
<para>
Supplied with your Java Virtual Machine is the <command>keytool</command>, a key and certificate
management utility. You can use this tool to create new key stores, add new private keys and
certificates to them, etc. It is beyond the scope of this document to provide a full reference of
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">
<citetitle>here</citetitle></ulink>, or by giving the command <prompt>keytool -help</prompt> on
the command line.
</para>
</section>
<section>
<title>KeyStoreFactoryBean</title>

0
doc/src/docbkx/ws.xml → doc/src/docbkx/server.xml
View File