From c2228d5d939f14e5f77b8e51cfab31727de8f72d Mon Sep 17 00:00:00 2001 From: Arjen Poutsma Date: Tue, 15 May 2007 01:53:21 +0000 Subject: [PATCH] More Docs. --- src/docbkx/client.xml | 2 +- src/docbkx/common.xml | 2 +- src/docbkx/server.xml | 149 +++++++++++++++++++++++++++++++++++++++--- 3 files changed, 142 insertions(+), 11 deletions(-) diff --git a/src/docbkx/client.xml b/src/docbkx/client.xml index 872fa277..a42c1a99 100644 --- a/src/docbkx/client.xml +++ b/src/docbkx/client.xml @@ -21,7 +21,7 @@
Using the client-side API -
+
<classname>WebServiceTemplate</classname> The WebServiceTemplate is the core class for client-side Web service access in diff --git a/src/docbkx/common.xml b/src/docbkx/common.xml index 7e40a4c0..b7d56e54 100644 --- a/src/docbkx/common.xml +++ b/src/docbkx/common.xml @@ -147,7 +147,7 @@ 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 + 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. In HTTP, it is read from the HttpServletRequest and the response is written back diff --git a/src/docbkx/server.xml b/src/docbkx/server.xml index 2b20ed58..7203e4d6 100644 --- a/src/docbkx/server.xml +++ b/src/docbkx/server.xml @@ -23,7 +23,8 @@ Spring-WS's XML handling is extremely flexible. An endpoint can choose from a large amount of XML handling libraries supported by Spring-WS, including the DOM family (W3C DOM, JDOM, dom4j, and XOM), SAX or StAX for faster performance, XPath to extract information from the message, or even - marshalling to convert the XML to objects and vice-versa. + marshalling techniques (JAXB, Castor, XMLBeans, JiBX, or XStream) to convert + the XML to objects and vice-versa.
@@ -37,12 +38,7 @@ The processing and dispatching flow of the MessageDispatcher is illustrated in the - following sequence diagram. Whenever a message comes in, a suitable endpoint is retrieved via the - EndpointMapping. After the endpoint has been determined, the - MessageDispatcher delegates to an EndpointAdapter - to adapt to the specific method signature of the endpoint class. After the endpoint has been invoked, the - result value of the endpoint, if any, is converted back by the adapter after the invocation, and the - response is sent on its way. + following sequence diagram. @@ -55,6 +51,39 @@ + + When a MessageDispatcher is set up for use and a request comes in for that + specific dispatcher, said MessageDispatcher starts processing the request. The + list below describes the complete process a request goes through when handled by a + MessageDispatcher: + + + + + An appropriate endpoint is searched for. If an endpoint is found, the invocation chain associated + with the handler (preprocessors, postprocessors, and endpoints) will be executed in order to create + a response. + + + + + An appropriate adapter is searched for the endpoint. The MessageDispatcher + delegates to this adapter to invoke the endpoint. + + + + + If a response is returned, it is sent on its way. If no response is returned (which could be due to + a pre- or postprocessor intercepting the request, for example, for security reasons), no response is + sent. + + + + + Exceptions that are thrown during handling of the request get picked up by any of the endpoint exception + resolvers that are declared in the application context. Using these exception resolvers allows you to define + custom behaviors in case such exceptions get thrown, such as return a SOAP Fault. + The MessageDispatcher has several properties, for setting endpoint adapters, mappings, @@ -77,7 +106,10 @@ The MessageDispatcherServlet is a standard Servlet which conveniently extends from the standard Spring Web DispatcherServlet, and wraps - a MessageDispatcher. As a servlet, the + a MessageDispatcher. As such, it combines the attributes of these into one: + as a MessageDispatcher, if follows the same request handling flow as described + in the previous section. + As a servlet, the MessageDispatcherServlet is configured in the web.xml of your web application. Requests that you want the MessageDispatcherServlet to handle will have to be mapped using a URL mapping in the same web.xml file. This is @@ -104,11 +136,110 @@ Services; the various endpoint and other beans used by the Spring Web Services framework also need to be configured. + + Because the MessageDispatcherServlet is a standard Spring + DispatcherServlet, it will look for a file named + [servlet-name]-servlet.xml in the WEB-INF directory + of your web application and create the beans defined there. + In the example above, that means that it looks for spring-ws-servlet.xml. +
Endpoints - + + Endpoints are the central concept in Spring-WS's server-side support. Endpoints provide access to the + application behavior which is typically defined by a business service interface. Endpoint interpret the XML + request message and uses that input to invoke a method on the business service. The result of that service + invocation is represented as a response message. Spring-WS has a wide variety of endpoints, using various + ways to handle the XML message, and to create a response. + + + The basis for most endpoint in Spring Web Services is the + org.springframework.ws.server.endpoint.PayloadEndpoint interface, the source + code of which is listed below. + + + + As you can see, the PayloadEndpoint interface defines a single method that + is invoked with the XML payload of a request (typically the contents of the SOAP Body, see + ). The returned Source, if any, is stored in the + response XML message. While the PayloadEndpoint interface is quite abstract, + Spring-WS offers a lot of endpoint implementations out of the box that already contain a lot of the + functionality you might need. The PayloadEndpoint interface just defines the + most basic responsibility required of every endpoint; namely handling a request and returning a response. + + + Alternatively, there is the MessageEndpoint, which operated on a + whole MessageContext rather than just + the payload. Typically, your code should only not be dependent on messages, because the payload should + contain the interesting information. Only when it is necessary to perform actions on the mesage a whole, + such as adding a SOAP header, get an attachment, etc., should you need to cast to implement + MessageEndpoint, though these actions are usually performed in a + endpoint interceptor. + +
+ <classname>AbstractDomPayloadEndpoint</classname> and other DOM endpoints + + One of the most basic ways to handle the incoming XML payload is by using a DOM (Document Object Model) + API. By extending from AbstractDomPayloadEndpoint, you can use the + org.w3c.dom.Element and related classes to handle the request, and create the + response. When using the AbstractDomPayloadEndpoint as the baseclass for your + endpoints you only have to override the invokeInternal(Element, Document) + method, implement your logic, and return an Element. Here is a short + example consisting of a class and a declaration in the application context. + + + + +]]> + + The above class and the declaration in the application context is all you need besides setting up a + endpoint mapping (see the section entitled ) to get this very + simple endpoint working. + + + Besides the AbstractDomPayloadEndpoint, which uses W3C DOM, there are other + 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. + +
+
+ <classname>AbstractMarshallingPayloadEndpoint</classname> + +
+
+ <literal>@Endpoint</literal> + +
Endpoint mappings