From 6e8ebbdbfeb8aa571c89c2aacfa0ff03f3d3fc3d Mon Sep 17 00:00:00 2001 From: Arjen Poutsma Date: Thu, 7 Feb 2008 13:53:34 +0000 Subject: [PATCH] SWS-267 --- src/docbkx/common.xml | 332 +++++++++++++++++++++++++++++------------- 1 file changed, 232 insertions(+), 100 deletions(-) diff --git a/src/docbkx/common.xml b/src/docbkx/common.xml index 4cff0902..f379e188 100644 --- a/src/docbkx/common.xml +++ b/src/docbkx/common.xml @@ -11,14 +11,21 @@
Web service messages
- <interfacename>WebServiceMessage</interfacename> + + <interfacename>WebServiceMessage</interfacename> + - One of the core interfaces of Spring Web Services is the WebServiceMessage. + One of the core interfaces of 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 + 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 following table. @@ -31,27 +38,45 @@ - javax.xml.transform.dom.DOMSource - org.w3c.dom.Node + + javax.xml.transform.dom.DOMSource + + + org.w3c.dom.Node + - javax.xml.transform.dom.DOMResult - org.w3c.dom.Node + + javax.xml.transform.dom.DOMResult + + + org.w3c.dom.Node + - javax.xml.transform.sax.SAXSource - org.xml.sax.InputSource and + + 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.sax.SAXResult + + + org.xml.sax.ContentHandler + - javax.xml.transform.stream.StreamSource - java.io.File, java.io.InputStream, or + javax.xml.transform.stream.StreamSource + + + java.io.File,java.io.InputStream, or java.io.Reader @@ -60,7 +85,7 @@ javax.xml.transform.stream.StreamResult - java.io.File, java.io.OutputStream, or + java.io.File,java.io.OutputStream, or java.io.Writer @@ -72,40 +97,63 @@
- <interfacename>SoapMessage</interfacename> + + <interfacename>SoapMessage</interfacename> + - The SoapMessage is a subclass of + The + SoapMessage + is a subclass of WebServiceMessage. It contains SOAP-specific methods, such as getting SOAP Headers, SOAP Faults, etc. Generally, your code should not be dependent on SoapMessage, because the content of the SOAP Body can be obtained via - getPayloadSource() and getPayloadResult() in the + 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. + WebServiceMessage + toSoapMessage.
Message Factories - Concrete message implementations are created by a WebServiceMessageFactory. + Concrete message implementations 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 + concrete implementations ofWebServiceMessageFactory; 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> + + <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. - Here is an overview of the SAAJ versions supplied + 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. + Here is an overview of the + SAAJ + versions supplied by common application servers: Application Server - SAAJ Version + + SAAJ + Version + @@ -115,15 +163,22 @@ BEA WebLogic 9 - 1.1/1.2 - - Weblogic 9 has a known bug in the SAAJ 1.2 - implementation: it implement all the 1.2 interfaces, but throws a - UnsupportedOperationException when called. - Spring Web Services has a workaround: it uses SAAJ 1.1 - when operating on WebLogic 9. - - + 1.1/1.2 + + + Weblogic 9 has a known bug in the + SAAJ + 1.2 + implementation: it implement all the 1.2 interfaces, but throws a + UnsupportedOperationException + when called. + Spring Web Services has a workaround: it uses + SAAJ + 1.1 + when operating on WebLogic 9. + + + IBM WebSphere 6 @@ -136,36 +191,53 @@ - Additionally, Java SE 6 includes SAAJ 1.3. + Additionally, Java SE 6 includes + SAAJ + 1.3. You wire up a - SaajSoapMessageFactory like so: - ]]> + SaajSoapMessageFactory + like so: + ]]> - SAAJ is based on DOM, the Document Object Model. This means that all SOAP messages are - stored in memory. For larger SOAP messages, this may not be very performant. - In that case, the AxiomSoapMessageFactory might be more applicable. + SAAJ + is based on DOM, the Document Object Model. This means that all SOAP messages are + storedin memory. For larger SOAP messages, this may not be very performant. + In that case, the + AxiomSoapMessageFactory + might be more applicable.
- <classname>AxiomSoapMessageFactory</classname> + + <classname>AxiomSoapMessageFactory</classname> + - The AxiomSoapMessageFactory uses the AXis 2 Object Model to create - SoapMessage implementations. AXIOM is based on + 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). + To increase reading performance on theAxiomSoapMessageFactory, + you can set the + payloadCaching + property to false (default is true). 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: + You use the + AxiomSoapMessageFactory + as follows: @@ -173,11 +245,21 @@
- <acronym>SOAP</acronym> 1.1 or 1.2 + + <acronym>SOAP</acronym> + 1.1 or 1.2 + - Both the SaajSoapMessageFactory and the - AxiomSoapMessageFactory have a soapVersion property, - where you can inject a SoapVersion constant. By default, the version + Both the + SaajSoapMessageFactory + and the + AxiomSoapMessageFactory + have a + soapVersion + property, + where you can inject a + SoapVersion + constant. By default, the version is 1.1, but you can set it to 1.2 like so: ]]> - In the example above, we define a SaajSoapMessageFactory that only accepts - SOAP 1.2 messages. + In the example above, we define a + SaajSoapMessageFactory + that only accepts + SOAP + 1.2 messages. - Even though both versions of SOAP are quite similar in format, the 1.2 + Even though both versions of + SOAP + are quite similar in format, the 1.2 version is not backwards compatible with 1.1 because it uses a different XML namespace. - Other major differences between SOAP 1.1 and 1.2 include the different structure - of a Fault, and the fact that SOAPAction HTTP headers are deprecated, which - means that you cannot use the - SoapActionEndpointMapping or the + Other major differences between + SOAP + 1.1 and 1.2 include the different structure + of a Fault, and the fact that + SOAPAction + HTTP headers are deprecated, which + means that you cannot use the + + SoapActionEndpointMapping + + or the SoapActionAnnotationMethodEndpointMapping. - One important thing to note with SOAP version numbers, or WS-* specification + One important thing to note with + SOAP + version numbers, or WS-* specification version numbers in general, is that the latest version of a specification is generally not the most popular version. - For SOAP, this means that currently, the best version to use is 1.1. + ForSOAP, this means that currently, the best version to use is 1.1. Version 1.2 might become more popular in the future, but currently 1.1 is the safest bet.
- <interfacename>MessageContext</interfacename> - - Typically, messages come in pairs: a request and a response. A request is created on the client-side, + + <interfacename>MessageContext</interfacename> + + + Typically, messages come in pairs: a request and a response. A request is created on the client-side, which is sent over some transport to the server-side, where a response is generated. This response gets - sent back to the client, where it is read. - - - In Spring Web Services, such a conversation is contained in a - MessageContext, which has properties to get request and response - messages. - On the client-side, the message context is created by the - WebServiceTemplate. - On the server-side, the message context is read from the transport-specific input stream. - For example, in HTTP, it is read from the HttpServletRequest and the - response is written back to the HttpServletResponse. - + sent back to the client, where it is read. + + + In Spring Web Services, such a conversation is contained in a + MessageContext, which has properties to get request and response + messages. + On the client-side, the message context is created by the + + WebServiceTemplate + + . + On the server-side, the message context is read from the transport-specific input stream. + For example, in HTTP, it is read from the + HttpServletRequest + and the + response is written back to theHttpServletResponse. +
- <interfacename>TransportContext</interfacename> + + <interfacename>TransportContext</interfacename> + One of the key properties of the SOAP protocol is that it tries to be transport-agnostic. This is why, for instance, Spring-WS does not support mapping messages to endpoints by HTTP request URL, but @@ -248,10 +353,15 @@ However, sometimes it is necessary to get access to the underlying transport, either on the client or server - side. For this, Spring Web Services has the TransportContext. The transport - context allows access to the underlying WebServiceConnection, which typically - is a HttpServletConnection on the server side; or a - HttpUrlConnection or CommonsHttpConnection on the client side. + side. For this, Spring Web Services has theTransportContext. The transport + context allows access to the underlyingWebServiceConnection, which typically + is a + HttpServletConnection + on the server side; or a + HttpUrlConnection + or + CommonsHttpConnection + on the client side. For example, you can obtain the IP address of the current request in a server-side endpoint or interceptor like so: @@ -265,7 +375,7 @@ String ipAddress = request.getRemoteAddr();]]> Handling XML With XPath One of the best ways to handle XML is to use XPath. - Quoting , item 35: + Quoting, item 35:
@@ -282,14 +392,20 @@ String ipAddress = request.getRemoteAddr();]]>
Spring Web Services has two ways to use XPath within your application: the faster - XPathExpression or the more flexible XPathTemplate. + XPathExpression + or the more flexibleXPathTemplate.
- <interfacename>XPathExpression</interfacename> + + <interfacename>XPathExpression</interfacename> + - The XPathExpression is an abstraction over a compiled XPath expression, - such as the Java 5 javax.xml.xpath.XPathExpression, or the Jaxen - XPath class. + The + XPathExpression + is an abstraction over a compiled XPath expression, + such as the Java 5javax.xml.xpath.XPathExpression, or the Jaxen + XPath + class. To construct an expression in an application context, there is the XPathExpressionFactoryBean. Here is an example which uses this factory bean: @@ -309,7 +425,8 @@ String ipAddress = request.getRemoteAddr();]]> ]]> The expression above does not use namespaces, but we could set those using the - namespaces property of the factory bean. The expression + namespaces + property of the factory bean. The expression can be used in the code as follows: - For a more flexible approach, you can use a NodeMapper, which is similar - to the RowMapper in Spring's JDBC support. The following + For a more flexible approach, you can use aNodeMapper, which is similar + to the + RowMapper + in Spring's JDBC support. The following example shows how we can use it: // do something with list of Contact objects + // do something with list of + Contact + objects + + +}]]> + - Similar to mapping rows in Spring JDBC's RowMapper, each result node is - mapped using an anonymous inner class. In this case, we create a Contact object, + Similar to mapping rows in Spring JDBC'sRowMapper, each result node is + mapped using an anonymous inner class. In this case, we create a + Contact + object, which we use later on.
- <classname>XPathTemplate</classname> + + <classname>XPathTemplate</classname> + - The XPathExpression only allows you to evaluate a single, pre-compiled - expression. A more flexible, though slower, alternative is the XpathTemplate. + The + XPathExpression + only allows you to evaluate a single, pre-compiled + expression. A more flexible, though slower, alternative is theXpathTemplate. This class follows the common template pattern used throughout Spring (JdbcTemplate, JmsTemplate, etc.). Here is an example: @@ -381,7 +512,8 @@ public class MyXPathClass { ]]>// do something with name +}]]> +
\ No newline at end of file