diff --git a/doc/pom.xml b/doc/pom.xml index 9c1bcf6a..406d33df 100644 --- a/doc/pom.xml +++ b/doc/pom.xml @@ -40,7 +40,7 @@ index.xml true - true + true version diff --git a/doc/src/docbkx/client.xml b/doc/src/docbkx/client.xml index 897a400e..27dd91ce 100644 --- a/doc/src/docbkx/client.xml +++ b/doc/src/docbkx/client.xml @@ -48,5 +48,15 @@ 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. + +
+ diff --git a/doc/src/docbkx/index.xml b/doc/src/docbkx/index.xml index 4fa3347d..6d1511aa 100644 --- a/doc/src/docbkx/index.xml +++ b/doc/src/docbkx/index.xml @@ -1,5 +1,6 @@ - + @@ -32,6 +33,10 @@ + + Document-driven Web services with Spring-WS + This chapter will contain the reference for server-side Spring-WS usage. + diff --git a/doc/src/docbkx/server.xml b/doc/src/docbkx/server.xml index 05743a54..953c2bcc 100644 --- a/doc/src/docbkx/server.xml +++ b/doc/src/docbkx/server.xml @@ -1,9 +1,157 @@ + - Document-driven Web services with Spring-WS - - This chapter will contain the reference for server-side Spring-WS usage. - + 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: + + +]]> + +
+
+