diff --git a/src/assembly/full.xml b/src/assembly/full.xml index ee15cf84..c2faa16a 100644 --- a/src/assembly/full.xml +++ b/src/assembly/full.xml @@ -33,11 +33,8 @@ docs/api - doc/target/docbkx + target/site/reference docs/reference - - **/*.fo - diff --git a/src/docbkx/common.xml b/src/docbkx/common.xml index c6615772..67d98f42 100644 --- a/src/docbkx/common.xml +++ b/src/docbkx/common.xml @@ -4,7 +4,7 @@ Shared components - In this chapter, we will explore the the components which are shared between client- and server side + 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. @@ -13,10 +13,10 @@
<interfacename>WebServiceMessage</interfacename> - One of the core interfaces within Spring Web Services is the + 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 + 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 @@ -74,39 +74,39 @@
<interfacename>SoapMessage</interfacename> - The SoapMessage is an extension of + 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 + 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 + 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 + 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 + 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 + 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 + 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. @@ -115,15 +115,15 @@
<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 + 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, + 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. + 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. @@ -133,7 +133,7 @@ ]]> - +
@@ -144,7 +144,7 @@ sent back to the client, where it is read. - In Spring Web Services, such a conversation is contained in a + 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 @@ -159,21 +159,30 @@ Handling XML With XPath One of the best ways to handle XML is to use XPath. Quoting , item 35: -
- - XPath is a fourth generation declarative language that allows you to specify which nodes you want to - process without specifying exactly how the processor is supposed to navigate to those nodes. XPath's - data model is very well designed to support exactly what almost all developers want from XML. For - instance, it merges all adjacent text including that in CDATA sections, allows values to be - calculated that skip over comments and processing instructions` and include text from child and - descendant elements, and requires all external entity references to be resolved. In practice, XPath - expressions tend to be much more robust against unexpected but perhaps insignificant changes in the - input document. - - Elliotte Rusty Harold -
- + + What is XPath? + + XPath is a language for addressing parts of an XML document. + For more information about XPath, refer to the + XPath specification, or read the + XPath tutorial + + +
+ + XPath is a fourth generation declarative language that allows you to specify which nodes you want to + process without specifying exactly how the processor is supposed to navigate to those nodes. XPath's + data model is very well designed to support exactly what almost all developers want from XML. For + instance, it merges all adjacent text including that in CDATA sections, allows values to be + calculated that skip over comments and processing instructions` and include text from child and + descendant elements, and requires all external entity references to be resolved. In practice, XPath + expressions tend to be much more robust against unexpected but perhaps insignificant changes in the + input document. + + Elliotte Rusty Harold +
+ Spring Web Services has two ways to use XPath within your application: the faster XPathExpression or the more flexible XPathTemplate. diff --git a/src/docbkx/server.xml b/src/docbkx/server.xml index 6ac527a5..c9de2f7d 100644 --- a/src/docbkx/server.xml +++ b/src/docbkx/server.xml @@ -16,8 +16,8 @@ of course AbstractMarshallingPayloadEndpoint. Application endpoints will typically be subclasses of those. Alternatively, there is a endpoint development that uses Java 5 annotations, such as - @Endpoint for marking a POJO as endpoint, and marking a method with - @PayloadRoot or @SoapAction. + @Endpoint for marking a POJO as endpoint, and marking a method with + @PayloadRoot or @SoapAction. Spring-WS's XML handling is extremely flexible. An endpoint can choose from @@ -253,8 +253,10 @@ public class SampleEndpoint extends AbstractDomPayloadEndpoint { base classes which use alternative DOM APIs. Spring Web Services supports most DOM APIs, so that you can use the one you are familiar with. For instance, the AbstractJDomPayloadEndpoint allows you to use JDOM, and the - AbstractXomPayloadEndpoint uses XOM to handle the XML. All endpoints have an - invokeInternal method similar to above. + AbstractXomPayloadEndpoint uses XOM to handle the XML. All of these endpoints + have an invokeInternal method similar to above. + Also, consider to use Spring-WS's XPath support to extract the information you need out of the payload, + see .
@@ -295,8 +297,7 @@ public class MarshallingOrderEndpoint extends AbstractMarshallingPayloadEndpoint return order; } }]]> - + @@ -312,6 +313,8 @@ public class MarshallingOrderEndpoint extends AbstractMarshallingPayloadEndpoint + + ]]> In this sample, we configure a Jaxb2Marshaller for the @@ -356,7 +359,74 @@ public class MarshallingOrderEndpoint extends AbstractMarshallingPayloadEndpoint
<literal>@Endpoint</literal> - + + The previous two programming models were based on inheritance, and handled individual XML mesages. + Spring Web Services offer another endpoint with which you aggregate multiple handling into one + controller, thus grouping functionality together. This model is based on annotations, so you can only + use it under Java 5 and higher. Here is an example that uses the same marshalled objects as above: + + + + By annotating the class with @Endpoint, you mark it as a Spring-WS + endpoint. Because the endpoint class can have multiple request handling methods, we need to instruct + Spring-WS which method to invoke for which request. This is done using the + @PayloadRoot annotation: the getOrder method + will be invoked for requests with a orderRequest local name, and a + http://samples namespace URI; the order method for requests with + a order local name. For more information about these annotations, refer to + . + Obviously, we also need to configure Spring-WS to support the JAXB objects + OrderRequest and Order by defining a + Jaxb2Marshaller. This is what the configuration + looks like: + + + + + + + + + + + + + + + + + + +]]> + + The MarshallingMethodEndpointAdapter converts the incoming + XML messages to marshalled objects used as parameters and return value; the + PayloadRootAnnotationMethodEndpointMapping is the mapping that detects and + handles the @PayloadRoot annotations. +
@@ -411,66 +481,70 @@ public class MarshallingOrderEndpoint extends AbstractMarshallingPayloadEndpoint PayloadRootQNameEndpointMapping
+
+ <classname>MethodEndpointMapping</classname> + +
Adding <interfacename>EndpointInterceptors</interfacename>
-
- Handling Exceptions - - Spring-WS provides - EndpointExceptionResolvers - to ease the pain of unexpected - exceptions occurring while your message is being processed by an endpoint which matched the request. - EndpointExceptionResolver - s somewhat resemble the exception mappings that can be - defined in the web application descriptor - web.xml - . - Rather than expose the innards of your application by giving a client a full stack trace, you can handle - the exception any way you want, e.g. return a SOAP fault with a specific fault code and string. - Furthermore, a programmatic way of handling exceptions gives you many more options for how to respond - appropriately. - - - Besides implementing the - HandlerExceptionResolver - interface, which is only a - matter of implementing the - resolveException(MessageContext, endpoint, Exception) - method and returning a - boolean, you may also use the - SoapFaultMappingExceptionResolver - . - This resolver enables you to take the class name of any exception that might be thrown and map it to a - SOAP Fault, like so: - +
+ Handling Exceptions + + Spring-WS provides + EndpointExceptionResolvers + to ease the pain of unexpected + exceptions occurring while your message is being processed by an endpoint which matched the request. + EndpointExceptionResolver + s somewhat resemble the exception mappings that can be + defined in the web application descriptor + web.xml + . + Rather than expose the innards of your application by giving a client a full stack trace, you can handle + the exception any way you want, e.g. return a SOAP fault with a specific fault code and string. + Furthermore, a programmatic way of handling exceptions gives you many more options for how to respond + appropriately. + + + Besides implementing the + HandlerExceptionResolver + interface, which is only a + matter of implementing the + resolveException(MessageContext, endpoint, Exception) + method and returning a + boolean, you may also use the + SoapFaultMappingExceptionResolver + . + This resolver enables you to take the class name of any exception that might be thrown and map it to a + SOAP Fault, like so: + - - - - - - SENDER,Invalid request - - - +class="org.springframework.ws.soap.endpoint.SoapFaultMappingExceptionResolver"> + + + + + + SENDER,Invalid request + + + ]]> - This configuration will map exceptions of type - ValidationFailureException - to a - sender side SOAP Fault with a fault string "Invalid request". - If any other exception occurs, it will return the default fault: a server side fault with fault string - "Server error". - Refer to the Javadoc of - SoapFaultDefinitionEditor - to read more about the exact - notation of the faults. - -
-
+ This configuration will map exceptions of type + ValidationFailureException + to a + sender side SOAP Fault with a fault string "Invalid request". + If any other exception occurs, it will return the default fault: a server side fault with fault string + "Server error". + Refer to the Javadoc of + SoapFaultDefinitionEditor + to read more about the exact + notation of the faults. + +
Similarities between Spring-MVC and Spring-WS @@ -535,4 +609,4 @@ public class MarshallingOrderEndpoint extends AbstractMarshallingPayloadEndpoint
- \ No newline at end of file + diff --git a/src/docbkx/tutorial.xml b/src/docbkx/tutorial.xml index 71e8102a..781edd51 100644 --- a/src/docbkx/tutorial.xml +++ b/src/docbkx/tutorial.xml @@ -379,7 +379,7 @@ - + ]]> @@ -431,7 +431,7 @@ - The http://mycompany.com/humanresources address is the URL where the Web + The http://localhost:8080/holidayService/ address is the URL where the Web service can be invoked.