diff --git a/doc/src/docbkx/client.xml b/doc/src/docbkx/client.xml new file mode 100644 index 00000000..46d07573 --- /dev/null +++ b/doc/src/docbkx/client.xml @@ -0,0 +1,51 @@ + + + + Using Spring Web Services on the Client +
+ Introduction + + 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 marshallers and unmarshallers. + + + The package org.springframework.ws.client.core 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 JdbcTemplate 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, + +
+
+ Using the client-side API +
+ <classname>WebServiceTemplate</classname> + + The WebServiceTemplate is the core class for client-side Web service access in + Spring-WS. It contains methods for sending Source objects, and receiving response + messages as either Source or Result. Additionally, it can + marshal objects to XML before sending them across a transport, and unmarshal the response XML into an + object again. + +
+
+ Transports + + The WebServiceTemplate requires a reference to a + MessageSender. The message sender is responsible for sending the XML message + across a transport layer. + + + There are two implementations of the MessageSender interface for sending messages + via HTTP. The simplest implementation is the HttpUrlConnectionMessageSender, + which uses the facilities provided by Java SE itself. The alternative is the + CommonsHttpMessageSender, 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 url property. +
+
+ diff --git a/doc/src/docbkx/index.xml b/doc/src/docbkx/index.xml index 5697ec65..4fa3347d 100644 --- a/doc/src/docbkx/index.xml +++ b/doc/src/docbkx/index.xml @@ -1,50 +1,41 @@ - - - - - - - - ]> + - - Spring Web Services - - Reference Documentation - - Version &version; - (Work in progress) + + Spring Web Services + Reference Documentation + + Version + &version; + + (Work in progress) - - - Arjen - Poutsma - - + + + Arjen + Poutsma + + - 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. - - + + + Copies of this document may be made for your own use and for distribution to others, provided that you + do not charge any fee for such copies and further provided that each copy contains this Copyright + Notice, whether distributed in print or electronically. + + + - + - &preface; - - &overview; - - &contract-first; - - &ws; - - &security; - - &oxm; - - &bibliography; + + + + + + + + diff --git a/doc/src/docbkx/overview.xml b/doc/src/docbkx/overview.xml index 504ef4cb..e551c502 100644 --- a/doc/src/docbkx/overview.xml +++ b/doc/src/docbkx/overview.xml @@ -1,4 +1,6 @@ + Introduction diff --git a/doc/src/docbkx/oxm.xml b/doc/src/docbkx/oxm.xml index 78ae2f81..1502ac0a 100644 --- a/doc/src/docbkx/oxm.xml +++ b/doc/src/docbkx/oxm.xml @@ -1,72 +1,72 @@ + - Marshalling XML using O/X Mappers + Marshalling XML using O/X Mappers -
- Introduction - - 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. - - - Within the field of O/X mapping, a marshaller is responsible for serializing an object - (graph) to XML. In similar fashion, an unmarshaller 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. - - - Some of the benefits of using Spring for your O/X mapping needs are: - - - Ease of configuration - - 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. - - - - Consistent Interfaces - - Spring's O/X mapping operates through two global interfaces: the - Marshaller - and - Unmarshaller - 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. - - - - Consistent Exception Hierarchy - - Spring provides a conversion from exceptions from the underlying O/X mapping tool to its own - exception hierarchy with the - XmlMappingException - as the root exception. As can be - expected, these runtime exceptions wrap the original exception so no information is lost. - - -
-
- Marshaller and Unmarshaller - - As stated in the introduction, a - marshaller - serializes an object to XML, and an - unmarshaller - deserializes XML stream to an object. In this section, we will describe - the two Spring interfaces used for this purpose. - -
- Marshaller - - Spring abstracts all marshalling operations behind the - org.springframework.oxm.Marshaller - interface, which is listed below. - + Introduction + + 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. + + + Within the field of O/X mapping, a + marshaller + is responsible for serializing an object (graph) to XML. In similar fashion, an + unmarshaller + 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. + + Some of the benefits of using Spring for your O/X mapping needs are: + + Ease of configuration + + 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. + + + + Consistent Interfaces + + Spring's O/X mapping operates through two global interfaces: the + Marshaller + and + Unmarshaller + 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. + + + + Consistent Exception Hierarchy + + Spring provides a conversion from exceptions from the underlying O/X mapping tool to its own exception + hierarchy with the + XmlMappingException + as the root exception. As can be expected, these runtime exceptions wrap the original exception so no + information is lost. + + +
+
+ Marshaller and Unmarshaller + + As stated in the introduction, a marshaller serializes an object to XML, and an + unmarshaller deserializes XML stream to an object. In this section, we will describe + the two Spring interfaces used for this purpose. + +
+ Marshaller + + Spring abstracts all marshalling operations behind the + org.springframework.oxm.Marshaller + interface, which is listed below. + - Although the @@ -141,6 +140,7 @@ public interface Marshaller { manages this. +
Unmarshaller @@ -606,12 +606,12 @@ public class Application { ... ]]> -
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. +
\ No newline at end of file diff --git a/doc/src/docbkx/preface.xml b/doc/src/docbkx/preface.xml index c4248d0b..bd0596ef 100644 --- a/doc/src/docbkx/preface.xml +++ b/doc/src/docbkx/preface.xml @@ -1,4 +1,6 @@ + Preface diff --git a/doc/src/docbkx/security.xml b/doc/src/docbkx/security.xml index 3920b434..79828333 100644 --- a/doc/src/docbkx/security.xml +++ b/doc/src/docbkx/security.xml @@ -1,87 +1,117 @@ + - Securing your Web services with Spring-WS + Securing your Web services with Spring-WS -
- Introduction - - 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: - - - Authentication - - This is the process of determining whether a principal 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. - - - - Digital signatures - - 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). - - - - Encryption and Decryption - - Encryption 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. Decryption is the reverse of encryption; it is the process of - transforming of encrypted data back into an readable form. - - - - All of these three areas are implemented using the XwsSecurityInterceptor, which we - will describe in - - - - 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. - - -
-
- XwsSecurityInterceptor - - 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). - - - Like any other endpoint interceptor, it is defined in the endpoint mapping (see ). This means that you can be selective about adding WS-Security support: - some endpoint mappings require it, while others do not. - - - The XwsSecurityInterceptor requires a security policy file 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 - SecurityConfiguration element as root (not a JAXRPCSecurity - element). - - - Additionally, the security interceptor requires one or more CallbackHandlers 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 callbackHandler or callbackHandlers property. - - - Here is an example that shows how to wire the XwsSecurityInterceptor up: - + Introduction + + 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: + + + Authentication + + This is the process of determining whether a + principal + 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. + + + + Digital signatures + + 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). + + + + Encryption and Decryption + + Encryption + 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. + Decryption + is the reverse of encryption; it is the process of transforming of encrypted data back into an readable + form. + + + + All of these three areas are implemented using the + XwsSecurityInterceptor + , which we will describe in + + + + + 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. + + +
+
+ XwsSecurityInterceptor + + 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 + + ). + + + Like any other endpoint interceptor, it is defined in the endpoint mapping (see + + ). This means that you can be selective about adding WS-Security support: some endpoint mappings require it, + while others do not. + + + The + XwsSecurityInterceptor + requires a + security policy file + 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 + SecurityConfiguration + element as root (not a + JAXRPCSecurity + element). + + + Additionally, the security interceptor requires one or more + CallbackHandler + 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 + callbackHandler + or + callbackHandlers + property. + + + Here is an example that shows how to wire the + XwsSecurityInterceptor + up: + @@ -140,13 +170,15 @@
KeyTool - Supplied with your Java Virtual Machine is the keytool, 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 keytool - command, but you can find a reference - here, or by giving the command keytool -help on the command - line. + + Supplied with your Java Virtual Machine is the keytool, 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 keytool command, but you can find a reference + here, or by giving the command keytool -help on + the command line. +
KeyStoreFactoryBean diff --git a/doc/src/docbkx/ws.xml b/doc/src/docbkx/server.xml similarity index 100% rename from doc/src/docbkx/ws.xml rename to doc/src/docbkx/server.xml