diff --git a/oxm/pom.xml b/oxm/pom.xml index 1914b604..b5eb9a08 100644 --- a/oxm/pom.xml +++ b/oxm/pom.xml @@ -17,11 +17,6 @@ JiBX Maven Repository http://jibx.sourceforge.net/maven2/ - - maven2-repository.dev.java.net - Java.net Repository for Maven2 - https://maven2-repository.dev.java.net/nonav/repository - diff --git a/pom.xml b/pom.xml index 052a09fc..bad4e05b 100644 --- a/pom.xml +++ b/pom.xml @@ -124,12 +124,6 @@ samples - - doc - - doc - - 2.0.4 @@ -140,7 +134,19 @@ Spring External Dependencies Repository https://svn.sourceforge.net/svnroot/springframework/repos/repo-ext/ + + maven2-repository.dev.java.net + Java.net Repository for Maven2 + https://maven-repository.dev.java.net/nonav/repository + legacy + + + + agilejava + http://agilejava.com/maven/ + + @@ -181,6 +187,60 @@ true + + com.agilejava.docbkx + docbkx-maven-plugin + + + + generate-html + generate-pdf + + pre-site + + + + + org.docbook + docbook-xml + 4.4 + runtime + + + + index.xml + true + css/html.css + true + src/docbkx/resources/xsl/html_chunk.xsl + src/docbkx/resources/xsl/fopdf.xsl + + + version + ${version} + + + + + + + + + + + + + + + + + + + + + diff --git a/sandbox/pom.xml b/sandbox/pom.xml index a0c7f6d4..b8f4d8df 100644 --- a/sandbox/pom.xml +++ b/sandbox/pom.xml @@ -3,7 +3,7 @@ spring-ws org.springframework.ws - 1.0-m4-SNAPSHOT + 1.0-rc1-SNAPSHOT 4.0.0 spring-ws-sandbox diff --git a/src/docbkx/bibliography.xml b/src/docbkx/bibliography.xml new file mode 100644 index 00000000..f093da89 --- /dev/null +++ b/src/docbkx/bibliography.xml @@ -0,0 +1,58 @@ + + + + Bibliography + + + + Jim + Waldo + + + Ann + Wollrath + + + Sam + Kendall + + + A Note on Distributed Computing + + Springer Verlag + + 1994 + + + + + Steve + Loughran + + + Edmund + Smith + + + Rethinking the Java SOAP Stack + May 17, 2005 + + 2005 + IEEE Telephone Laboratories, Inc. + + + + + + Ted + Neward + + + Effective Enterprise Java + + Addison-Wesley + + 2004 + + \ No newline at end of file diff --git a/src/docbkx/client.xml b/src/docbkx/client.xml new file mode 100644 index 00000000..2950b89f --- /dev/null +++ b/src/docbkx/client.xml @@ -0,0 +1,160 @@ + + + + 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. + +
+
+ Message factories + + In addition to a message sender, the WebServiceTemplate requires a Web service + message factory. As explained in , there are two message factories + for SOAP: SaajSoapMessageFactory and + AxiomSoapMessageFactory. + +
+
+
+ Sending and receiving a <interfacename>WebServiceMessage</interfacename> + + The WebServiceTemplate contains many convenience methods to send and receive + web service messages. There are methods that take and return Source + and those that return a Result. Additionally, there are methods which + marshal and unmarshal objects to XML. Here is an example that sends a simple XML message to a Web + service. + + Hello World"; + private WebServiceTemplate webServiceTemplate = new WebServiceTemplate(); + + public void setMessageFactory(WebServiceMessageFactory messageFactory) { + webServiceTemplate.setMessageFactory(messageFactory); + } + + public void setMessageSender(WebServiceMessageSender messageSender) { + webServiceTemplate.setMessageSender(messageSender); + } + + public void simpleSendAndReceive() throws IOException { + StreamSource source = new StreamSource(new StringReader(MESSAGE)); + StreamResult result = new StreamResult(System.out); + webServiceTemplate.sendAndReceive(source, result); + } + +}]]> + + Here is the corresponding configuration: + + + + + + + + + + + + + + +]]> + + This example uses the template to send a hello world message to the web service located at + http://localhost:8080/WebService, and writes the result to the console. + The WebServiceTemplate is injected with the message factory and sender. + A zero argument constructor and messageFactory / + messageSender bean properties are provided and can be used for constructing + the instance (using a BeanFactory or plain Java code). Alternatively, consider deriving from + Spring-WS's WebServiceGatewaySupport convenience base class, which provides + pre-built bean properties for configuration. + +
+
+ Marshalling, sending, receiving, and unmarshalling + + In order to facilitate the sending of plain Java objects, the WebServiceTemplate + has a send methods that take an object as an argument for a message's data content. + The method marshalSendAndReceive in WebServiceTemplate + delegates the conversion of the request object to XML to a Marshaller, and + the conversion of the response XML to an object to an Unmarshaller. + For more information about marshalling and unmarshaller, refer to . + By using the marshallers, you and 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 use the marshalling functionality, you have to set a marshaller and unmarshaller with the + marshaller/unmarshaller properties of the + WebServiceTemplate. + +
+
+ <interface>WebServiceMessageCallback</interface> + + To accommodate the setting of a SOAP headers, and other settings on the message, the + WebServiceMessageCallback interface gives you access to the message + after it has been created, but before it is sent. The example below demonstrates how to set the SOAP + Action header on a message that is created by marshalling an object. + + +
+
+ \ No newline at end of file diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml new file mode 100644 index 00000000..268fc76c --- /dev/null +++ b/src/docbkx/index.xml @@ -0,0 +1,46 @@ + + + + + + Spring Web Services - Reference Documentation + + &version; + + + + + Arjen + Poutsma + + + Rick + Evans + + + + + + 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. + + + + + + + + + + Document-driven Web services with Spring-WS + This chapter will contain the reference for server-side Spring-WS usage. + + + + + + + + diff --git a/src/docbkx/overview.xml b/src/docbkx/overview.xml new file mode 100644 index 00000000..e551c502 --- /dev/null +++ b/src/docbkx/overview.xml @@ -0,0 +1,142 @@ + + + + Introduction + +
+ Overview + + Spring-WS consists of three separate modules. This chapter discusses each of the modules in turn. + + + The Core package is the central part of the Web services functionality. It + provides the central WebServiceMessage and SoapMessage + interfaces, the powerful message dispatching, and the various support classes for implementing Web service + endpoints. + + + The Security package provides a WS-Security implementation that integrates + with the core Web service package. It allows you to add principal tokens, sign, and decrypt and encrypt SOAP + messages. Addtionally, it allows you to leverage your existing Acegi security implementation for + authentication and authorization. + + + The OXM package provides integration for popular XML marshalling APIs, including + JAXB 1 and 2. Using the OXM package means that you benefit from a unified exception hierarchy, and can wire + up your favorite XML marshalling technology easily. + +
+ + +
+ Why Spring Web Services? + + There are various other SOAP stacks available, why and where should you use Spring-WS? This section answers + that question by showing what the focus of Spring-WS is. + +
+ Spring-WS is meant for Public Web Services + + One can distinguish between two different sorts of Web services. Private Web services are not used + outside your application domain. They might form a part of your Enterprise Service Bus, or used as a + means to communicate between a fat .NET client and a J2EE server. When the two sides of the spectrum + (client and server) are under your control, you can easily expose (existing) methods, since you can + (re)generate client code easily. + + + Public Web services provide a separate interface to your application. They are often used by clients + that are outside of your reach. When developing a public Web service, you should really think about the + interface you are providing: it is probably going to be around for a while, and you cannot change it + that often. As such, it is a good idea to place the Web service in a separate layer, thus hiding the + inner workings of the application. As a result, you can change the Web service and the rest of the + appliciation seperately. + +
+
+ Spring-WS makes Web Services First Class Citizens of the Architecture + + Web Services deserve a proper place in an application architecture. Often, they exist as an afterthought + in the application architecture, mostly because existing Java business interfaces are exposed as SOAP + services. One could say that they are "SOAPified". Spring-WS provides a MVC-like framework for + developing a Web service application layer, just like you would develop a layer especially for a Web + user interface using Spring-MVC. Spring-WS also provides useful integration points with you existing + Spring application architecture, such as the Acegi integration. + +
+
+ Spring-WS is Data-Driven + + When Web Services started making their way into the Enterprise Computing world, developers considered + Web Services just another, XML-based remoting protocol. Such remoting frameworks can be used with + relative ease: on the server-side, one simply implements a specific interface such as + java.rmi.Remote, and on the client side, a dynamic proxy is used. + Unfortunately, because of this simplicity, remoting architectures have some issues: + + + + They pretend there is no latency between the client and the server, + while in fact there is both network and application latency, + + + + + They pretend that client and server have shared memory access, while in + fact data must be both marshalled and unmarshalled, + + + + + They ignore the possibility of a request or response not reaching its + destination, + + + + + They enforce a non-concurrent programming model, while in fact a + concurrent approach seems more in place, + + + + + They enforce a tightly coupled architecture, where changes on the + server-side result in changes on the client-side. + + + + It is not without reason that Gregor Hohpe calls a distributed architecture a fairy tale + architecture: one is made to believe things that simply are not true. To quote : +
+ + Objects that interact in a distributed system need to be dealt with in ways that are + intrinsically different from objects that interact in a single address space. + +
+ + + Instead of being behavior-driven, Spring-WS is data-driven: it focusses on the data being sent, not on a + particular method being invoked. + +
+
+ Spring-WS Focusses on Contract-first Development + + SOAP services are defined in two contracts: the data contract (the XSD schema), and the service contract + (the WSDL). Generating these contracts from Java-code is called contract-last + development identifies some problems with this approach, most + importantly: +
+ + There is no way to ensure that a service’s published interface remains constant over time. + Every redeployment of the service may change the classes, and hence the contract. + +
+ The alternative of contract-last development is contract-first development. + Using this approach, the service and data contract are leading. Spring-WS focusses on contract-first Web + service development, because is considered to be a best practice. After all, the actual XML that is sent + across the wire is more important than the Java code that is used to implement it. + +
+
+ diff --git a/src/docbkx/oxm.xml b/src/docbkx/oxm.xml new file mode 100644 index 00000000..941e8bf9 --- /dev/null +++ b/src/docbkx/oxm.xml @@ -0,0 +1,709 @@ + + + + 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. + + The + Marshaller + interface has just one method, which marshals the given + object to a given + javax.xml.transform.Result + . Result is a tagging interface that + basically represents an XML output abstraction: concrete implementations wrap various XML + representations, as indicated in the table below. + + + + + + javax.xml.transform.Result + implementation + + Wraps XML representation + + + + + + javax.xml.transform.dom.DOMResult + + + org.w3c.dom.Node + + + + + javax.xml.transform.sax.SAXResult + + + org.xml.sax.ContentHandler + + + + + javax.xml.transform.stream.StreamResult + + + java.io.File + , + java.io.OutputStream + , + or + java.io.Writer + + + + + + + + Although the + marshal + method accepts a plain object as its first parameter, + most + Marshaller + implementations cannot handle arbitrary objects. Instead, an + object class must be mapped in a mapping file, registered with the marshaller, or have a common + base + class. Refer to the further sections in this chapter to determine how your O/X technology of + choice + manages this. + + + +
+
+ Unmarshaller + + Similar to the + Marshaller + , there is the + org.springframework.oxm.Unmarshaller + interface. + + This interface also has one method, which reads from the given + javax.xml.transform.Source + (an XML input abstraction), and returns the + object read. As with Result, Source is a tagging interface that has three concrete implementations. Each + wraps a different XML representation, as indicated in the table below. + + + + + + javax.xml.transform.Source + implementation + + Wraps XML representation + + + + + + javax.xml.transform.dom.DOMSource + + + org.w3c.dom.Node + + + + + javax.xml.transform.sax.SAXSource + + + org.xml.sax.InputSource + and + org.xml.sax.XMLReader + + + + + javax.xml.transform.stream.StreamSource + + + java.io.File + , + java.io.InputStream + , + or + java.io.Reader + + + + + + +
+ + Even though there are two separate marshalling interfaces ( + Marshaller + and + Unmarshaller + ), most implementations found in Spring-WS implement both in one class. + This means that you can wire up one marshaller class and refer to it as marshaller and unmarshaller in your + applicationContext.xml + . + +
+ XmlMappingException + + Spring converts 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 will be lost. + + + Additionally, the + MarshallingFailureException + and + UnmarshallingFailureException + provide a distinction between marshalling and + unmarshalling operations, even though the underlying O/X mapping tool does not do so. + + + The O/X Mapping exception hierarchy is shown in the following figure: + + + + + + + + + + O/X Mapping exception hierarchy + + + + +
+
+
+ Using Marshaller and Unmarshaller + + Spring's OXM can be used for a wide variety of situations. In the following example, we will use it to + marshal the settings of a Spring-managed application as an XML file. We will use a simple JavaBean to + represent the settings: + + + + The application class uses this bean to store its settings. Besides a main method, the class has two + methods: + saveSettings + saves the settings bean to a file named + settings.xml + , and + loadSettings + loads these settings again. A + main + method constructs a Spring application context, and calls these two methods. + + The + Application + requires both a + marshaller + and + unmarshaller + property to be set. We can do so using the following + applicationContext.xml + : + + + + + + + + +]]> + This application context uses Castor, but we could have used any of the other marshaller instances described + later in this chapter. Note that Castor does not require any further configuration by default, so the bean + definition is rather simple. Also note that the + CastorMarshaller + implements both + Marshaller + and + Unmarshaller + , so we can refer to the + castorMarshaller + bean in both the + marshaller + and + unmarshaller + property of the application. + + + This sample application produces the following + settings.xml + file: + + +]]> + +
+
+ JAXB + + The JAXB binding compiler translates a W3C XML Schema into one or more Java classes, a + jaxb.properties + file, and possibly other files, depending on the specific implementation of JAXB. Alternatively, JAXB2 + offers a way to generate a schema from annotated Java classes. + + + Spring supports both the JAXB 1.0 as the JAXB 2.0 API as XML marshalling strategy, following the + Marshaller + and + Unmarshaller + interfaces described in + + . The corresponding integration classes reside in the + org.springframework.oxm.jaxb + package. + +
+ Jaxb1Marshaller + + The + Jaxb1Marshaller + class implements both the Spring + Marshaller + and + Unmarshaller + interface. It requires a + context path to operate, which you can set using the + contextPath + property. The + context path is a list of colon (:) separated Java package names that contain schema derived classes. + The marshaller has an additional + validating + property which defines whether to + validate invoming XML. + + + The next sample bean configuration shows how to configure a + JaxbMarshaller + using the classes generated to + org.springframework.ws.samples.airline.schema + . + + + + + + + ... + +]]> +
+
+ Jaxb2Marshaller + + The + Jaxb2Marshaller + can be configured using the same + contextPath + property as the + Jaxb1Marshaller + . However, it also offers a + classesToBeBound + property, which allows you to set an array of classes to be supported by the marshaller. Schema + validation is performed by specifying one or more schema resource to the bean, like so: + + + + + + + org.springframework.oxm.jaxb.Flight + org.springframework.oxm.jaxb.Flights + + + + + ... + +]]> +
+
+
+ Castor + + Castor XML mapping is an open source XML binding framework. It allows you to transform the data contained in + a java object model into/from an XML document. By default, it does not require any further configuration, + though a mapping file can be used to have more control over the behavior of Castor. + + + For more information on Castor, refer to the + + Castor web site + + . The Spring integration classes reside in the + org.springframework.oxm.castor + package. + +
+ CastorMarshaller + + As with JAXB, the + CastorMarshaller + implements both the + Marshaller + and + Unmarshaller + interface. It can be wired up + as follows: + + + + + ... + +]]> +
+
+ Mapping + + Although it is possible to rely on Castor's default marshalling behavior, it might be necessary to have + more control over it. This can be accomplished using a Castor mapping file. For more information, refer + to + Castor XML Mapping + . + + + The mapping can be set using the + mappingLocation + resource property, indicated + below with a classpath resource. + + + + + + +]]> +
+
+ +
+ XMLBeans + + XMLBeans is an XML binding tool that has full XML Schema support, and offers full XML Infoset fidelity. It + takes a different approach that most other O/X mapping frameworks, in that all classes that are + generated from an XML Schema are all derived from + XmlObject + , and contain XML binding + information in them. + + + For more information on XMLBeans, refer to the + + XMLBeans + web site + + + . The Spring-WS integration classes reside in the + org.springframework.oxm.xmlbeans + package. + +
+ XmlBeansMarshaller + + The + XmlBeansMarshaller + implements both the + Marshaller + and + Unmarshaller + interface. It can be wired up as follows: + + + + + ... + +]]> + + + Note that the + XmlBeansMarshaller + can only marshal objects of type + XmlObject + , and not every + java.lang.Object + . + + +
+ + +
+ +
+ JiBX + + The JiBX framework offers a solution similar to JDO does for ORM: a binding definition defines the + rules for how your Java objects are converted to or from XML. After preparing the binding and compiling the + classes, a JiBX binding compiler enhances the class files, and adds code to handle converting instances of + the classes from or to XML. + + + For more information on JiBX, refer to the + + JiBX web + site + + + . The Spring integration classes reside in the + org.springframework.oxm.jibx + package. + +
+ JibxMarshaller + + The + JibxMarshaller + class implements both the + Marshaller + and + Unmarshaller + interface. To operate, it requires the name of the class to + marshall in, which you can set using the + targetClass + property. Optionally, you can + set the binding name using the + bindingName + property. In the next sample, we refer to + the + flightsBindingFactory + defined in the previous bean definition. + + + + + org.springframework.oxm.jibx.Flights + + + ... +]]> + + + A + JibxMarshaller + is configured for a single class. If you want to marshal + multiple classes, you have to configure multiple + JibxMarshaller + s with + different + targetClass + es. + + +
+
+
+ XStream + + XStream is a simple library to serialize objects to XML and back again. It does not require any mapping, and + generates clean XML. + + + For more information on XStream, refer to the + + XStream + web site + + + . The Spring integration classes reside in the + org.springframework.oxm.xstream + package. + +
+ XStreamMarshaller + + The + XStreamMarshaller + does not require any configuration, and can be configured + in an application context directly. To further customize the XML, you can set an + alias map + , which consists of string aliases mapped to classes: + + + + + + + org.springframework.oxm.xstream.Flight + + + + ... + +]]> + + + 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/src/docbkx/preface.xml b/src/docbkx/preface.xml new file mode 100644 index 00000000..bd0596ef --- /dev/null +++ b/src/docbkx/preface.xml @@ -0,0 +1,22 @@ + + + + Preface + + Web services development is a complicated affair. There is SOAP, there is REST. There is SOAP 1.1, and there is + SOAP 1.2. There is rpc/encoded, and there is document/literal. There is WS-Addressing, WS-Security, WS-Policy, + and various other Web service specifications. Implementing Web services using abstractions that magically turn + Java into XML, but turn out to be leaky abstractions makes it even harder. Spring Web Services provides a + solution for building interoperable Web services, while making it clear what XML is received and sent across the + wire. Spring-WS provides a powerful message dispatching framework, various XML marshalling techniques that can be used outside a Web service environment, and a WS-Security solution that integrates with your existing application security + solution. + + + This document provides a reference guide to Spring-WS's features. Since this document is still a + work-in-progress, if you have any requests or comments, please post them on the support forums at . + + \ No newline at end of file diff --git a/src/docbkx/resources/css/html.css b/src/docbkx/resources/css/html.css new file mode 100644 index 00000000..36297ac3 --- /dev/null +++ b/src/docbkx/resources/css/html.css @@ -0,0 +1,421 @@ +body { + text-align: justify; + margin-right: 2em; + margin-left: 2em; +} + +a, + a[accesskey^ + += +"h" +] +, +a[accesskey^ + += +"n" +] +, +a[accesskey^ + += +"u" +] +, +a[accesskey^ + += +"p" +] +{ +font-family: Verdana, Arial, helvetica, sans-serif + +; +font-size: + +12 +px + +; +color: #003399 + +; +} + +a:active { + color: #003399; +} + +a:visited { + color: #888888; +} + +p { + font-family: Verdana, Arial, sans-serif; +} + +dt { + font-family: Verdana, Arial, sans-serif; + font-size: 12px; +} + +p, dl, dt, dd, blockquote { + color: #000000; + margin-bottom: 3px; + margin-top: 3px; + padding-top: 0px; +} + +ol, ul, p { + margin-top: 6px; + margin-bottom: 6px; +} + +p, blockquote { + font-size: 90%; +} + +p.releaseinfo { + font-size: 100%; + font-weight: bold; + font-family: Verdana, Arial, helvetica, sans-serif; + padding-top: 10px; +} + +p.pubdate { + font-size: 120%; + font-weight: bold; + font-family: Verdana, Arial, helvetica, sans-serif; +} + +td { + font-size: 80%; +} + +td, th, span { + color: #000000; +} + +td[width^ + += +"40%" +] +{ +font-family: Verdana, Arial, helvetica, sans-serif + +; +font-size: + +12 +px + +; +color: #003399 + +; +} + +table[summary^ + += +"Navigation header" +] +tbody tr th[colspan^ + += +"3" +] +{ +font-family: Verdana, Arial, helvetica, sans-serif + +; +} + +blockquote { + margin-right: 0px; +} + +h1, h2, h3, h4, h6, H6 { + color: #000000; + font-weight: 500; + margin-top: 0px; + padding-top: 14px; + font-family: Verdana, Arial, helvetica, sans-serif; + margin-bottom: 0px; +} + +h2.title { + font-weight: 800; + margin-bottom: 8px; +} + +h2.subtitle { + font-weight: 800; + margin-bottom: 20px; +} + +.firstname, .surname { + font-size: 12px; + font-family: Verdana, Arial, helvetica, sans-serif; +} + +table { + border-collapse: collapse; + border-spacing: 0; + border: 1px black; + empty-cells: hide; + margin: 10px 0px 30px 50px; + width: 90%; +} + +div.table { + margin: 30px 0px 30px 0px; + border: 1px dashed gray; + padding: 10px; +} + +div .table-contents table { + border: 1px solid black; +} + +div.table > p.title { + padding-left: 10px; +} + +table[summary^ + += +"Navigation footer" +] +{ +border-collapse: collapse + +; +border-spacing: + +0 +; +border: + +1 +px black + +; +empty-cells: hide + +; +margin: + +0 +px + +; +width: + +100 +% +; +} + +table[summary^ + += +"Note" +] +, +table[summary^ + += +"Warning" +] +, +table[summary^ + += +"Tip" +] +{ +border-collapse: collapse + +; +border-spacing: + +0 +; +border: + +1 +px black + +; +empty-cells: hide + +; +margin: + +10 +px + +0 +px + +10 +px + +- +20 +px + +; +width: + +100 +% +; +} + +td { + padding: 4pt; + font-family: Verdana, Arial, helvetica, sans-serif; +} + +div.warning TD { + text-align: justify; +} + +h1 { + font-size: 150%; +} + +h2 { + font-size: 110%; +} + +h3 { + font-size: 100%; + font-weight: bold; +} + +h4 { + font-size: 90%; + font-weight: bold; +} + +h5 { + font-size: 90%; + font-style: italic; +} + +h6 { + font-size: 100%; + font-style: italic; +} + +tt { + font-size: 110%; + font-family: "Courier New", Courier, monospace; + color: #000000; +} + +.navheader, .navfooter { + border: none; +} + +div.navfooter table { + border: dashed gray; + border-width: 1px 1px 1px 1px; + background-color: #cde48d; +} + +pre { + font-size: 110%; + padding: 5px; + border-style: solid; + border-width: 1px; + border-color: #CCCCCC; + background-color: #f3f5e9; +} + +ul, ol, li { + list-style: disc; +} + +hr { + width: 100%; + height: 1px; + background-color: #CCCCCC; + border-width: 0px; + padding: 0px; +} + +.variablelist { + padding-top: 10px; + padding-bottom: 10px; + margin: 0; +} + +.term { + font-weight: bold; +} + +.mediaobject { + padding-top: 30px; + padding-bottom: 30px; +} + +.legalnotice { + font-family: Verdana, Arial, helvetica, sans-serif; + font-size: 12px; + font-style: italic; +} + +.sidebar { + float: right; + margin: 10px 0px 10px 30px; + padding: 10px 20px 20px 20px; + width: 33%; + border: 1px solid black; + background-color: #F4F4F4; + font-size: 14px; +} + +.property { + font-family: "Courier New", Courier, monospace; +} + +a code { + font-family: Verdana, Arial, monospace; + font-size: 12px; +} + +td code { + font-size: 110%; +} + +div.note * td, + div.tip * td, + div.warning * td, + div.calloutlist * td { + text-align: justify; + font-size: 100%; +} + +.programlisting .interfacename, + .programlisting .literal, + .programlisting .classname { + font-size: 95%; +} + +.title .interfacename, + .title .literal, + .title .classname { + font-size: 130%; +} + +/* everything in a is displayed in a coloured, comment-like font */ +.programlisting * .lineannotation, + .programlisting * .lineannotation * { + color: green; +} diff --git a/src/docbkx/resources/images/i21-banner-rhs.jpg b/src/docbkx/resources/images/i21-banner-rhs.jpg new file mode 100644 index 00000000..8b24a773 Binary files /dev/null and b/src/docbkx/resources/images/i21-banner-rhs.jpg differ diff --git a/src/docbkx/resources/images/oxm-exceptions.png b/src/docbkx/resources/images/oxm-exceptions.png new file mode 100644 index 00000000..9503d600 Binary files /dev/null and b/src/docbkx/resources/images/oxm-exceptions.png differ diff --git a/src/docbkx/resources/images/oxm-exceptions.svg b/src/docbkx/resources/images/oxm-exceptions.svg new file mode 100644 index 00000000..e33c67ae --- /dev/null +++ b/src/docbkx/resources/images/oxm-exceptions.svg @@ -0,0 +1,48 @@ + + + + + +G +c1 + +XmlMappingException + +c2 + +GenericMarshallingFailureException + +c1->c2 + + + +c5 + +ValidationFailureException + +c1->c5 + + + +c3 + +MarshallingFailureException + +c2->c3 + + + +c4 + +UnmarshallingFailureException + +c2->c4 + + + + + diff --git a/src/docbkx/resources/images/xdev-spring_logo.jpg b/src/docbkx/resources/images/xdev-spring_logo.jpg new file mode 100644 index 00000000..622962ee Binary files /dev/null and b/src/docbkx/resources/images/xdev-spring_logo.jpg differ diff --git a/src/docbkx/resources/xsl/fopdf.xsl b/src/docbkx/resources/xsl/fopdf.xsl new file mode 100644 index 00000000..5bc10b51 --- /dev/null +++ b/src/docbkx/resources/xsl/fopdf.xsl @@ -0,0 +1,470 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Copyright © 2004-2007 + + + , + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -5em + -5em + + + + + + + + + + + Spring Web Services ( + + ) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + bold + + + + + + + + + + + + + + + + + + + + + + + + + + + 1 + 0 + 1 + + 1 + + + + + + book toc + + + + 2 + + + + + + + + + + 0 + 0 + 0 + + + 5mm + 10mm + 10mm + + 15mm + 10mm + 0mm + + 18mm + 18mm + + + 0pc + + + + + justify + false + + + 11 + 8 + + + 1.4 + + + + + + + 0.8em + + + + + + 17.4cm + + + + 4pt + 4pt + 4pt + 4pt + + + + 0.1pt + 0.1pt + + + + + 1 + + + + + + + + left + bold + + + pt + + + + + + + + + + + + + + + 0.8em + 0.8em + 0.8em + + + pt + + 0.1em + 0.1em + 0.1em + + + 0.6em + 0.6em + 0.6em + + + pt + + 0.1em + 0.1em + 0.1em + + + 0.4em + 0.4em + 0.4em + + + pt + + 0.1em + 0.1em + 0.1em + + + + + bold + + + pt + + false + 0.4em + 0.6em + 0.8em + + + + + + + + + pt + + + + + 1em + 1em + 1em + #444444 + solid + 0.1pt + 0.5em + 0.5em + 0.5em + 0.5em + 0.5em + 0.5em + + + + 1 + + #F0F0F0 + + + + + + 0 + 1 + + + 90 + + + + + '1' + + + + + + + figure after + example before + equation before + table before + procedure before + + + + 1 + + + + 0.8em + 0.8em + 0.8em + 0.1em + 0.1em + 0.1em + + + + + + + + + + + + + + + + + diff --git a/src/docbkx/resources/xsl/html.xsl b/src/docbkx/resources/xsl/html.xsl new file mode 100644 index 00000000..aa7930ba --- /dev/null +++ b/src/docbkx/resources/xsl/html.xsl @@ -0,0 +1,91 @@ + + + + + + + + + html.css + + + 1 + 0 + 1 + 0 + + + + + + book toc + + + + 3 + + + + + 1 + + + + + + + 0 + + + 90 + + + + + 0 + + + + + figure after + example before + equation before + table before + procedure before + + + + , + + + + + + + + +
+

Authors

+

+ +

+ + + diff --git a/src/docbkx/resources/xsl/html_chunk.xsl b/src/docbkx/resources/xsl/html_chunk.xsl new file mode 100644 index 00000000..cfd07354 --- /dev/null +++ b/src/docbkx/resources/xsl/html_chunk.xsl @@ -0,0 +1,208 @@ + + + + + + + '5' + '1' + html.css + + 1 + 0 + 1 + 0 + + + + book toc + + + 3 + + + 1 + + + + + 90 + + + + figure after + example before + equation before + table before + procedure before + + + + , + + + + + + + + +
+

Authors

+

+ +

+ + + + + + + + + 1 + + + + + + + + + + +
+ +
+ + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +   + + + + + + + + + + + + + + +  |  + + +   + + + + + + + + -toc + + + + + + + + +   + + + + + + + + + + + + +
+ + + +   + + + Sponsored by Interface21 + + + +   + + + +
+ +
+ + + diff --git a/src/docbkx/security.xml b/src/docbkx/security.xml new file mode 100644 index 00000000..79828333 --- /dev/null +++ b/src/docbkx/security.xml @@ -0,0 +1,890 @@ + + + + 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 + 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: + + + + + + + + + + + ... + +]]> + This interceptor is configured using the securityPolicy.xml file on the classpath. It + uses two callback handlers which are defined further on in the file. + +
+ +
+ Key stores + + For most cryptographic operations, you will use standard java.security.KeyStore + objects. This includes certificate verification, message signing, signature verification, encryption, but + excludes username and time-stamp verification. This section aims to give you some background knowledge on + key stores, and the Java tools that you can use to store keys and certificates in a key store file. This + information is mostly not related to Spring-WS, but to the general cryptographic features of Java. + + + The java.security.KeyStore class represents a storage facility for cryptographic keys + and certificates. It can contain three different sort of elements: + + + Private Keys + + These keys are used for self-authentication. The private key is accompanied by certificate chain for + the corresponding public key. Within the field of WS-Security, this accounts to message signing and + message decryption. + + + + Symmetric Keys + + Symmetric (or secret) keys are used for message encryption and decryption as well. The difference + being that both sides (sender and recipient) share the same, secret key. + + + + Trusted certificates + + These X509 certificates are called a trusted certificate because the keystore owner + trusts that the public key in the certificates indeed belong to the owner of the certificate. Within + WS-Security, these certificates are used for certificate validation, signature verification, and + encryption. + + +
+ 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. + +
+
+ KeyStoreFactoryBean + + To easily load a key store using Spring configuration, you can use the + KeyStoreFactoryBean. It has a resource location property, which you can set to + point to the path of the key store to load. A password may be given to check the integrity of the + key store data. If a password is not given, integrity checking is not performed. + + + + +]]> + + + If you don't specify the location property, a new, empty key store will be created, which is most + likely not what you want. + + +
+
+ KeyStoreCallbackHandler + + To use the key stores within a XwsSecurityInterceptor, you will need to define a + KeyStoreCallbackHandler. This callback has three properties with type key store: + (keyStore, trustStore, and + symmetricStore). The exact stores used by the handler depend on the + cryptographic operations that are to be performed by this handler. For private key operation, the + keyStore is used, for symmetric key operations the + symmetricStore, and for determining trust relationships, the + trustStore. The following table indicates this: + + + + + Cryptographic operation + Key store used + + + + + Certificate validation + + first the keyStore, then the + trustStore + + + + Decryption based on private key + keyStore + + + Decryption based on symmetric key + symmetricStore + + + Encryption based on public key certificate + trustStore + + + Encryption based on symmetric key + symmetricStore + + + Signing + keyStore + + + Signature verification + trustStore + + + + + Additionally, the KeyStoreCallbackHandler has a + privateKeyPassword property, which should be set to unlock the private key(s) + contained in the keyStore. + + + If the symmetricStore is not set, it will default to the + keyStore. If the key or trust store is not set, the callback handler will use + the standard Java mechanism to load or create it. Refer to the JavaDoc of the + KeyStoreCallbackHandler to know how this mechanism works. + + + For instance, if you want to use the KeyStoreCallbackHandler to validate incoming + certificates or signatures, you would use a trust store, like so: + + + + + + + + + +]]> + If you want to use it to decrypt incoming certificates or sign outgoing messages, you would use a key + store, like so: + + + + + + + + + + +]]> + + + The following sections will indicate where the KeyStoreCallbackHandler can be + used, and which properties to set for particular cryptographic operations. + +
+
+ +
+ Authentication + + As stated in the introduction, authentication is the task of determining whether a + principal is who they claim to be. Within WS-Security, authentication can take two forms: using a username + and password token (using either a plain text password or a password digest), or using a X509 certificate. + +
+ Plain Text Username Authentication + + The simplest form of username authentication uses plain text passwords. In this + scenario, the SOAP message will contain a UsernameToken element, which itself + contains a Username element and a Password element which contains + the plain text password. Plain text authentication can be compared to the Basic Authentication provided + by HTTP servers. + + + + Note that plain text passwords are not very secure. Therefore, you should always add additional + security measures to your transport layer if you are using them (using HTTPS instead of plain HTTP, + for instance). + + + + To require that every incoming message contains a UsernameToken with a plain + text password, the security policy file should contain a RequireUsernameToken + element, with the passwordDigestRequired attribute set to false. + You can find a reference of possible child elements + here. + + + ... + + ... +]]> + + If the username token is not present, the XwsSecurityInterceptor will return a + SOAP Fault to the sender. If it is present, it will fire a + PasswordValidationCallback with a PlainTextPasswordRequest + to the registered handlers. Within Spring-WS, there are three classes which handle this particular + callback. + +
+ SimplePasswordValidationCallbackHandler + + The simplest password validation handler is the + SimplePasswordValidationCallbackHandler. This handler validates passwords + against a in-memory Properties object, which you can specify using the + users property, like so: + + + + + Ernie + + +]]> + + In this case, we are only allowing the user "Bert" to log in using the password "Ernie". + +
+
+ AcegiPlainTextPasswordValidationCallbackHandler + + The AcegiPlainTextPasswordValidationCallbackHandler uses the excellent Acegi Security Framework to + authenticate users. It is beyond the scope of this document to describe Acegi, but suffice it to say + that Acegi is a full-fledged security framework. You can read more about Acegi in the Acegi reference + documentation. + + + The AcegiPlainTextPasswordValidationCallbackHandler requires an Acegi + AuthenticationManager to operate. It uses this manager to authenticate against a + UsernamePasswordAuthenticationToken that it creates. If authentication is + successful, the token is stored in the SecurityContextHolder. You can set the + authentication manager using the authenticationManager property: + + + + + + + + + + + + + + + + ... +]]> +
+
+ JaasPlainTextPasswordValidationCallbackHandler + + The JaasPlainTextPasswordValidationCallbackHandler is based on the standard + Java Authentication and Authorization + Service. It is beyond the scope of this document to provide a full + introduction into JAAS, but there is a + good tutorial available. + + + The JaasPlainTextPasswordValidationCallbackHandler only requires a + loginContextName to operate. It creates a new JAAS + LoginContext using this name, and handles the standard JAAS + NameCallback and PasswordCallback using the username + and password provided in the SOAP message. This means that this callback handler + integrates with any JAAS + LoginModule that fires these callbacks during the + login() phase, which is standard behavior. + + + You can wire up a JaasPlainTextPasswordValidationCallbackHandler as follows: + + + +]]> + + In this case, the callback handler uses the LoginContext named + "MyLoginModule". This module should be defined in your jaas.config file, as + explained in the abovementioned tutorial. + +
+
+ +
+ Digest Username Authentication + + When using password digests, the SOAP message also contain a UsernameToken element, + which itself contains a Username element and a Password element. + The difference is that the password is not sent as plain text, but as a digest.The + recipient compares this digest to the digest he calculated from the known password of the user, and if + they are the same, the user is authenticated. It can be compared to the Digest + Authentication provided by HTTP servers. + + + To require that every incoming message contains a UsernameToken element with a + password digest, the security policy file should contain a RequireUsernameToken + element, with the passwordDigestRequired attribute set to true. + Additionally, the nonceRequired should be set to true: + You can find a reference of possible child elements + here. + + + ... + + ... +]]> + + If the username token is not present, the XwsSecurityInterceptor will return a + SOAP Fault to the sender. If it is present, it will fire a + PasswordValidationCallback with a DigestPasswordRequest + to the registered handlers. Within Spring-WS, there are two classes which handle this particular + callback. + +
+ SimplePasswordValidationCallbackHandler + + The SimplePasswordValidationCallbackHandler can handle both plain text + passwords as well as password digests. It is described in . + +
+
+ AcegiDigestPasswordValidationCallbackHandler + + The AcegiPlainTextPasswordValidationCallbackHandler requires an Acegi + UserDetailService to operate. It uses this service to retrieve the password + of the user specified in the token. The digest of the password contained in this details object is + then compared with the digest in the message. If they are equal, the user has succesfully + authenticated, and a UsernamePasswordAuthenticationToken is stored in the + SecurityContextHolder. You can set the service using the + userDetailsService. Additionally, you can set a + userCache property, to cache loaded user details. + + + + + + + + ... +]]> +
+
+ +
+ Certificate Authentication + + A more secure way of authentication uses X509 certificates. In this scenerario, the SOAP message + contains a BinarySecurityToken, which contains a Base 64-encoded version of a X509 + certificate. The recipient is used by the recipient to authenticate. The certificate stored in the + message is also used to sign the message (see ). + + + To make sure that all incoming SOAP messages carry a BinarySecurityToken, the + security policy file should contain a RequireSignature element. This element can + carry further other elements, which will be covered in . + You can find a reference of possible child elements + here. + + + ... + + ... +]]> + + When a message arrives that carries no certificate, the XwsSecurityInterceptor + will return a SOAP Fault to the sender. If it is present, it will fire a + CertificateValidationCallback. There are three handlers within Spring-WS + which handle this callback for authentication purposes. + + + + In most cases, certificate authentication should be preceded by certificate + validation, since you only want authenticate against valid certificates. + Invalid certificates such as certificates for which the expiration date has passed, or which are not + in your store of trusted certificates, should be ignored. + + + In Spring-WS terms, this means that the + AcegiCertificateValidationCallbackHandler or + JaasCertificateValidationCallbackHandler should be preceded by + KeyStoreCallbackHandler. This can be accomplished by setting the order of the + callbackHandlers property in the configuration of the + XwsSecurityInterceptor: + + + + + + + + + +]]> + Using this setup, the interceptor will first determine if the certificate in the message is valid + using the keystore, and then authenticate against it. + + +
+ KeyStoreCallbackHandler + + The KeyStoreCallbackHandler uses a standard Java key store to validate + certificates. This certificate validation process consists of the following steps: + + + + First, the handler will check whether the certificate is in the private + keyStore. If it is, it is valid. + + + + + If the certificate is not in the private key store, the handler will check whether the + the current date and time are within the validity period given in the certificate. + If they are not, the certificate is invalid; if it is, it will continue with the final + step. + + + + + Finally, a certification path for the certificate is created. This + basically means that the handler will determine whether the certificate has been issued + by any of the certificate authorities in the trustStore. If it + a certification path can be built succesfully, the certificate is valid. Otherwise, it + is not. + + + + + + To use the KeyStoreCallbackHandler for certificate validation purposes, you + will most likely only set the trustStore property: + + + + + + + + + +]]> + Using this setup, the certificate that is to be validated must either be in the trust store itself, + or the trust store must contain a certificate authority that issued the certificate. + +
+
+ AcegiCertificateValidationCallbackHandler + + The AcegiCertificateValidationCallbackHandler requires an Acegi + AuthenticationManager to operate. It uses this manager authenticate against a + X509AuthenticationToken that it creates. The configured authentication + manager is expected to supply a provider which can handle this token (usually an instance of + X509AuthenticationProvider). If authentication is succesfull, the token is + stored in the SecurityContextHolder. You can set the authentication manager + using the authenticationManager property: + + + + + + + + + + + + + + + + + + + + ... +]]> + + In this case, we are using a custom user details service to obtain authentication details based on + the certificate. Refer to the Acegi reference + documentation for more information about authentication against X509 + certificates. + +
+
+ JaasCertificateValidationCallbackHandler + + The JaasCertificateValidationCallbackHandler requires a + loginContextName to operate. It creates a new JAAS + LoginContext using this name and with the + X500Principal of the certificate. This means that this callback handler + integrates with any JAAS LoginModule that handles X500 principals. + + + You can wire up a JaasCertificateValidationCallbackHandler as follows: + + + MyLoginModule +]]> + + In this case, the callback handler uses the LoginContext named + "MyLoginModule". This module should be defined in your jaas.config file, and + should be able to authenticate against X500 principals. + +
+
+ +
+ +
+ Digital Signatures + + The digital signature of a message is a piece of information based on both the document + and the signer's private key. There are two main tasks related to signatures in WS-Security: verifying + signatures and signing messages. + +
+ Verifying Signatures + + Just like certificate-based authentication, + a signed message contains a BinarySecurityToken, which contains the certificate used + to sign the message. Additionally, it contains a SignedInfo block, which indicates + what part of the message was signed. + + + To make sure that all incoming SOAP messages carry a BinarySecurityToken, the + security policy file should contain a RequireSignature element. + It can also contain a SignatureTarget element, which specifies the target message + 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 + here. + + + +]]> + + If the signature is not present, the XwsSecurityInterceptor will return a + SOAP Fault to the sender. If it is present, it will fire a + SignatureVerificationKeyCallback to the registered handlers. Within Spring-WS, + there are is one class which handles this particular callback: the + KeyStoreCallbackHandler. + + +
+ KeyStoreCallbackHandler + + As described in , the + KeyStoreCallbackHandler uses a java.security.KeyStore + for handling various cryptographic callbacks, including signature verification. For signature + verification, the handler uses the trustStore property: + + + + + + + + + + +]]> +
+
+ +
+ Signing Messages + + When signing a message, the XwsSecurityInterceptor adds the + BinarySecurityToken to the message, and a SignedInfo block, which + indicates what part of the message was signed. + + + To sign all outgoing SOAP messages, the + security policy file should contain a Sign element. + It can also contain a SignatureTarget element, which specifies the target message + 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 + here. + + + +]]> + + The XwsSecurityInterceptor will fire a + SignatureKeyCallback to the registered handlers. Within Spring-WS, + there are is one class which handles this particular callback: the + KeyStoreCallbackHandler. + +
+ KeyStoreCallbackHandler + + As described in , the + KeyStoreCallbackHandler uses a java.security.KeyStore + for handling various cryptographic callbacks, including signing messages. For adding signatures, + the handler uses the keyStore property. Additionally, you must set + the privateKeyPassword property to unlock the private key used for signing. + + + + + + + + + + + +]]> +
+
+
+ +
+ Encryption and Decryption + + When encrypting, the message is transformed into a form that can only be read with the + appropriate key. The message can be decrypted to reveal the original, readable message. + +
+ Decryption + + To decrypt incoming SOAP messages, the security policy file should contain a + RequireEncryption element. This element can further carry a + EncryptionTarget element which indicates which part of the message should be + encrypted, a SymmetricKey to indicate that a shared secret instead of the regular + private key should be used to decrypt the message. You can read a description of the other elements + + here. + + + +]]> + + If an incoming message is not encrypted, the XwsSecurityInterceptor will return a + SOAP Fault to the sender. If it is present, it will fire a DecryptionKeyCallback + to the registered handlers. Within Spring-WS, there is one class which handled this particular callback: + the KeyStoreCallbackHandler. + +
+ KeyStoreCallbackHandler + + As described in , the + KeyStoreCallbackHandler uses a java.security.KeyStore + for handling various cryptographic callbacks, including decryption. For decryption, + the handler uses the keyStore property. Additionally, you must set + the privateKeyPassword property to unlock the private key used for + decryption. For decryption based on symmetric keys, it will use the + symmetricStore. + + + + + + + + + + + +]]> +
+
+ +
+ Encryption + + To encrypt outgoing SOAP messages, the security policy file should contain a Encrypt + element. This element can further carry a EncryptionTarget element which indicates + which part of the message should be encrypted, a SymmetricKey to indicate that a + shared secret instead of the regular private key should be used to decrypt the message. You can read a + description of the other elements + here. + + + +]]> + + The XwsSecurityInterceptor will fire a + EncryptionKeyCallback to the registered handlers in order to retrieve the + encryption information. Within Spring-WS, there is one class which handled this particular callback: the + KeyStoreCallbackHandler. + +
+ KeyStoreCallbackHandler + + As described in , the + KeyStoreCallbackHandler uses a java.security.KeyStore + for handling various cryptographic callbacks, including encryption. For encryption based on public + keys, the handler uses the trustStore property. For encryption based on + symmetric keys, it will use the symmetricStore. + + + + + + + + + + +]]> +
+
+ +
+ + diff --git a/src/docbkx/server.xml b/src/docbkx/server.xml new file mode 100644 index 00000000..953c2bcc --- /dev/null +++ b/src/docbkx/server.xml @@ -0,0 +1,345 @@ + + + + Creating a Web service with Spring-WS +
+ Web service messages +
+ + <interfacename>WebServiceMessage</interfacename> and <interfacename>SoapMessage</interfacename> + + + One of the core interfaces within Spring Web Services is the + WebServiceMessage. This interface represents a protocol agnostic XML + message. The interface contains methods that provide access to the payload of the message, in the form + of a javax.xml.transform.Source or a + javax.xml.transform.Result. Source and + Result are tagging interfaces that represent an abstraction over XML + input and output. Concrete implementations wrap various XML representations, as indicated in the table + below. + + + + + Source/Result implementation + Wraps XML representation + + + + + + javax.xml.transform.dom.DOMSource + + + org.w3c.dom.Node + + + + + javax.xml.transform.dom.DOMResult + + + org.w3c.dom.Node + + + + + javax.xml.transform.sax.SAXSource + + + org.xml.sax.InputSource + and + org.xml.sax.XMLReader + + + + + javax.xml.transform.sax.SAXResult + + + org.xml.sax.ContentHandler + + + + + javax.xml.transform.stream.StreamSource + + + java.io.File, java.io.InputStream, or + java.io.Reader + + + + + javax.xml.transform.stream.StreamResult + + + java.io.File, java.io.OutputStream, or + java.io.Writer + + + + + + In addition to reading from and writing to the payload, a Web service message can write itself to an + output stream. + + + The SoapMessage is an extension of + WebServiceMessage. It contains SOAP-specific methods, such as getting + SOAP Headers, SOAP Faults, etc. Generally, your code should only not be dependent on + SoapMessage, because the content of the SOAP Body can be obtained via + getPayloadSource() and getPayloadResult() in the + WebServiceMessage. Only when it is necessary to perform SOAP-specific + actions, such as adding a header, get an attachment, etc., should you need to cast + WebServiceMessage to SoapMessage. + +
+
+ Message Factories + + Concrete message implementation are created by a + WebServiceMessageFactory. This factory can create an empty message, or + read a message based on an input stream. + There are two concrete implementations of WebServiceMessageFactory. + One is based on SAAJ, the SOAP with Attachments API for Java, the other based on Axis 2's AXIOM, the + AXis Object Model. + +
+ <classname>SaajSoapMessageFactory</classname> + + The SaajSoapMessageFactory uses the SOAP with Attachments API for Java to + create SoapMessage implementations. SAAJ is part of J2EE 1.4, so it should be + supported under most modern application servers. You wire up a + SaajSoapMessageFactory like so: + + ]]> + + + + SAAJ is based on DOM, the Document Object Model. This means that all SOAP messages are + stored in memory as a whole. For larger SOAP messages, this may not be very performant. + In that case, the AxiomSoapMessageFactory might be more applicable. + + +
+
+ <classname>AxiomSoapMessageFactory</classname> + + The AxiomSoapMessageFactory uses the AXis 2 Object Model to create + SoapMessage implementations. AXIOM uses StAX, the Streaming API for + XML. StAX provides a pull-based mechanism for reading XML messages, which can be more efficient + for larger messages. + + + To increase reading performance on the AxiomSoapMessageFactory, + you can set the payloadCaching property to false (default is true). + This this will read the contents of the SOAP body directly from the stream. + When this setting is enabled, the payload can only be read once. + This means that you have to make sure that any preprocessing of the message does not consume it. + + + You use the AxiomSoapMessageFactory as follows: + + +]]> + +
+
+
+ + \ No newline at end of file