diff --git a/src/docbkx/client.xml b/src/docbkx/client.xml index 2950b89f..218686ac 100644 --- a/src/docbkx/client.xml +++ b/src/docbkx/client.xml @@ -53,7 +53,8 @@ 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. + AxiomSoapMessageFactory. If no message factory is specified, Spring-WS will + use the SaajSoapMessageFactory by default. @@ -102,9 +103,6 @@ public class WebServiceClient { - - - @@ -116,7 +114,7 @@ public class WebServiceClient { 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. + The WebServiceTemplate is injected with the message 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 diff --git a/src/docbkx/common.xml b/src/docbkx/common.xml new file mode 100644 index 00000000..8529b9d2 --- /dev/null +++ b/src/docbkx/common.xml @@ -0,0 +1,158 @@ + + + + Shared components + + In this chapter, we will explore the the components which are shared between client- and server side + Spring-WS development. These interfaces and classes represent the building blocks of Spring-WS, so + it's important to understand what they do, even if you do not use them directly. + +
+ Web service messages +
+ <interfacename>WebServiceMessage</interfacename> + + One of the core interfaces 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. + +
+
+ <interfacename>SoapMessage</interfacename> + + 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 is based on 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 diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml index 268fc76c..004830bd 100644 --- a/src/docbkx/index.xml +++ b/src/docbkx/index.xml @@ -32,15 +32,51 @@ - - - Document-driven Web services with Spring-WS - This chapter will contain the reference for server-side Spring-WS usage. - - - - - - + + Introduction + + + This first part of the reference documentation gives an overview of Spring Web Services, and the + underlying concepts. We will introduce Spring-WS, and explain the concepts behind contract-first + Web service development. + + + + + + + + Reference + + + This part of the reference documentation gives an in-depth look into the various pieces that make up + Spring Web Services. + It consists of a chapter which discusses the parts common to both client- and server-side, a chapter + about writing server-side Web services, about using Web services on the client-side, using WS-Security, + and the flexible Object/XML mapping. + + + + + + Document-driven Web services with Spring-WS + This chapter will contain the reference for server-side Spring-WS usage. + + + + + + + + Other Resources + + + In addition to this reference documentation, a number of other resources + exist to help you learn how to use Spring Web Services. These resources are + discussed in this section. + + + + diff --git a/src/docbkx/overview.xml b/src/docbkx/overview.xml deleted file mode 100644 index e551c502..00000000 --- a/src/docbkx/overview.xml +++ /dev/null @@ -1,142 +0,0 @@ - - - - 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/resources/images/spring-deps.png b/src/docbkx/resources/images/spring-deps.png new file mode 100644 index 00000000..0bf08e21 Binary files /dev/null and b/src/docbkx/resources/images/spring-deps.png differ diff --git a/src/docbkx/server.xml b/src/docbkx/server.xml index 953c2bcc..d27a7864 100644 --- a/src/docbkx/server.xml +++ b/src/docbkx/server.xml @@ -1,157 +1,8 @@ - - 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: - - -]]> - -
-
-
+ + Creating a Web service with Spring-WS