diff --git a/src/docbkx/oxm.xml b/src/docbkx/oxm.xml index 9b7e1503..d3394128 100644 --- a/src/docbkx/oxm.xml +++ b/src/docbkx/oxm.xml @@ -346,7 +346,7 @@ public class Application { ]]> -
+
Jaxb2Marshaller The Jaxb2Marshaller can be configured using the same diff --git a/src/docbkx/server.xml b/src/docbkx/server.xml index 7a123a02..6ac527a5 100644 --- a/src/docbkx/server.xml +++ b/src/docbkx/server.xml @@ -6,117 +6,117 @@
Introduction - Spring Web Services's server-side support in designed around a MessageDispatcher - that dispatches incoming messages to endpoints, with configurable endpoint mappings, response generation, - and endpoint interception. - The simplest endpoint is a PayloadEndpoint, just offering a - Source invoke(Source request) method. This interface can be implemented for creating an - endpoint, but you will prefer the included implementation hierarchy, consisting of, for example - AbstractDomPayloadEndpoint, AbstractSaxPayloadEndpoint, and - 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. - - - 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 techniques (JAXB, Castor, XMLBeans, JiBX, or XStream) to convert - the XML to objects and vice-versa. + Spring Web Services's server-side support in designed around a MessageDispatcher + that dispatches incoming messages to endpoints, with configurable endpoint mappings, response generation, + and endpoint interception. + The simplest endpoint is a PayloadEndpoint, just offering a + Source invoke(Source request) method. This interface can be implemented for creating an + endpoint, but you will prefer the included implementation hierarchy, consisting of, for example + AbstractDomPayloadEndpoint, AbstractSaxPayloadEndpoint, and + 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. + + + 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 techniques (JAXB, Castor, XMLBeans, JiBX, or XStream) to convert + the XML to objects and vice-versa.
- The <classname>MessageDispatcher</classname> - - The server-side of Spring-WS is designed around a central class that dispatches incoming XML messages to - endpoints. Spring-WS's MessageDispatcher is extremely flexible, allowing you to - use any sort of class as an endpoint, as long as it can be configured in the Spring IoC container. - In a way, the message dispatcher resembles Spring'sDispatcherServlet, the - Front Controller used in Spring Web MVC. - - - The processing and dispatching flow of the MessageDispatcher is illustrated in the - following sequence diagram. - - - - - - - - - The request processing workflow in Spring Web Services - - - - - 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. - - - + The <classname>MessageDispatcher</classname> - 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, - exception resolvers. - However, setting these properties is not required, since the dispatcher will automatically detect all of - these types that are registered in the application context. Only when detection needs to be overriden, - should these properties be set. - - - The message dispatcher operates on a message context, and not - transport-specific input stream and output stream. As a result, transport specific requests need to read - into a MessageContext. For HTTP, this is done with a - WebServiceMessageReceiverHandlerAdapter, which is a Spring Web - HandlerInterceptor, so that the MessageDispatcher - can be wired in a standard DispatcherServlet. There is a more convenient way to do - this, however, which is shown in the next section. - -
- <classname>MessageDispatcherServlet</classname> - - The MessageDispatcherServlet is a standard Servlet which - conveniently extends from the standard Spring Web DispatcherServlet, and wraps - 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 - standard Java EE servlet configuration; an example of such a - MessageDispatcherServlet declaration and mapping can be found below. - - + The server-side of Spring-WS is designed around a central class that dispatches incoming XML messages to + endpoints. Spring-WS's MessageDispatcher is extremely flexible, allowing you to + use any sort of class as an endpoint, as long as it can be configured in the Spring IoC container. + In a way, the message dispatcher resembles Spring'sDispatcherServlet, the + Front Controller used in Spring Web MVC. + + + The processing and dispatching flow of the MessageDispatcher is illustrated in the + following sequence diagram. + + + + + + + + + The request processing workflow in Spring Web Services + + + + + 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, + exception resolvers. + However, setting these properties is not required, since the dispatcher will automatically detect all of + these types that are registered in the application context. Only when detection needs to be overriden, + should these properties be set. + + + The message dispatcher operates on a message context, and not + transport-specific input stream and output stream. As a result, transport specific requests need to read + into a MessageContext. For HTTP, this is done with a + WebServiceMessageReceiverHandlerAdapter, which is a Spring Web + HandlerInterceptor, so that the MessageDispatcher + can be wired in a standard DispatcherServlet. There is a more convenient way to do + this, however, which is shown in the next section. + +
+ <classname>MessageDispatcherServlet</classname> + + The MessageDispatcherServlet is a standard Servlet which + conveniently extends from the standard Spring Web DispatcherServlet, and wraps + 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 + standard Java EE servlet configuration; an example of such a + MessageDispatcherServlet declaration and mapping can be found below. + + spring-ws @@ -130,34 +130,34 @@ ]]> - - In the example above, all requests will be handled by the 'spring-ws' - MessageDispatcherServlet. This is only the first step in setting up Spring Web - 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. - -
-
+ + In the example above, all requests will be handled by the 'spring-ws' + MessageDispatcherServlet. This is only the first step in setting up Spring Web + 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. - + 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. + 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. - - + 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 if we want a + response. 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> - + + 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. The SOAP message handled by this endpoint will look something like: + + + ]]> + Hello + ]]> +]]> + + Though it could also handle the following Plain Old XML (POX) message, since we are only working on + the payload of the message, and do not care whether it is SOAP or POX. + + + Hello +]]> + + The SOAP reponse looks like: + + + ]]> + Hello World! + ]]> +]]> + + 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> + Rather than handling XML directly using DOM, you can use marshalling to convert the payload of the XML message into a Java Object. Spring Web Services offers the AbstractMarshallingPayloadEndpoint for this purpose, which is built on the marshalling abstraction described in . The AbstractMarshallingPayloadEndpoint has two properties: - marshaller and unmarshaller, in which you can inject - + marshaller and unmarshaller, in which you can inject in the + constructor or by setters. -
-
- <literal>@Endpoint</literal> - -
+ + When extending from AbstractMarshallingPayloadEndpoint, you have to override + the invokeInternal(Object) method, where the passed + Object represents the unmarshalled request payload, and return an + Object that will be marshalled into the response payload. Here is an + example: + + + + + + + + + + + + samples.OrderRequest + samples.Order + + + + + +]]> + + In this sample, we configure a Jaxb2Marshaller for the + OrderRequest and Order classes, and inject that + marshaller together with the + DefaultOrderService into our endpoint. This business service is not shown, but + it is a normal transactional service, probably using DAOs to obtain data from a database. + In the invokeInternal method, we cast the request object to an + OrderRequest object, which is the JAXB object representing the payload of the + request. Using the identifier of that request, we obtain an order from our business service, which we + returned. The returned object is marshalled into XML, and used as the payload of the response message. + The SOAP request handled by this endpoint will look like: + + + + + + +]]> + + The resulting response will be something like: + + + + + + 1 + 20.0 + + + 1 + 10.0 + + + +]]> + + Instead of JAXB 2, we could have used any of the other marshallers described in . + The only thing that would change in the above example is the configuration of the + marshaller bean. + +
+
+ <literal>@Endpoint</literal> + +
Endpoint mappings