From d2b6899f34090221a8dd9efbe6b022dd166f9292 Mon Sep 17 00:00:00 2001 From: Arjen Poutsma Date: Mon, 20 Dec 2010 15:42:28 +0000 Subject: [PATCH] Documentation --- src/docbkx/server.xml | 342 ++++++++++++++++-------------------------- 1 file changed, 128 insertions(+), 214 deletions(-) diff --git a/src/docbkx/server.xml b/src/docbkx/server.xml index 8fd2a4d7..c3b49918 100644 --- a/src/docbkx/server.xml +++ b/src/docbkx/server.xml @@ -1085,230 +1085,109 @@ public class AnnotationOrderEndpoint { Endpoint mappings The endpoint mapping is responsible for mapping incoming messages to appropriate endpoints. - There are some endpoint mappings you can use out of the box, for example, the - PayloadRootQNameEndpointMapping or the - SoapActionEndpointMapping, but let's first examine the general concept of an - EndpointMapping. + There are some endpoint mappings that are enabled out of the box, for example, the + PayloadRootAnnotationMethodEndpointMapping or the + SoapActionAnnotationMethodEndpointMapping, but let's first examine the general + concept of an EndpointMapping. An EndpointMapping delivers a EndpointInvocationChain, which contains the endpoint that matches the incoming request, and may also contain a list of endpoint - interceptors that will be applied to the request and response. When a request comes in, the - MessageDispatcher will hand it over to the endpoint mapping to let it inspect the - request and come up with an appropriate EndpointInvocationChain. Then - the MessageDispatcher will invoke the endpoint and any interceptors in the chain. + interceptors that will be applied to the request and response. + When a request comes in, the MessageDispatcher will hand it over to the endpoint + mapping to let it inspect the request and come up with an appropriate + EndpointInvocationChain. + Then the MessageDispatcher will invoke the endpoint and any interceptors in the + chain. The concept of configurable endpoint mappings that can optionally contain interceptors (which can manipulate - the request or the response, or both) is extremely powerful. A lot of supporting functionality can be built - into custom EndpointMappings. For example, there could be a custom endpoint - mapping that chooses an endpoint not only based on the contents of a message, but also on a specific SOAP - header (or indeed multiple SOAP headers). + the request or the response, or both) is extremely powerful. + A lot of supporting functionality can be built into custom EndpointMappings. + For example, there could be a custom endpoint mapping that chooses an endpoint not only based on the + contents of a message, but also on a specific SOAP header (or indeed multiple SOAP headers). Most endpoint mappings inherit from the AbstractEndpointMapping, which offers an 'interceptors' property, which is the list of interceptors to use. EndpointInterceptors are discussed in - . Additionally, there is the - 'defaultEndpoint', which is the default endpoint to use, when this endpoint mapping does - not result in a matching endpoint. + . + Additionally, there is the 'defaultEndpoint', which is the default endpoint to use + when this endpoint mapping does not result in a matching endpoint. + + + As explained in , the @Endpoint style + allows you to handle multiple requests in one endpoint class. + This is the responsibility of the MethodEndpointMapping. + This mapping determines which method is to be invoked for an incoming request message. + + + There are two endpoint mappings that can direct requests to methods: the + PayloadRootAnnotationMethodEndpointMapping and the + SoapActionAnnotationMethodEndpointMapping, both of which are enabled by using + <sws:annotation-driven/> in your application context. + + + The PayloadRootAnnotationMethodEndpointMapping uses the + @PayloadRoot annotation, with the localPart and + namespace elements, to mark methods with a particular qualified + name. + Whenever a message comes in which has this qualified name for the payload root element, the + method will be invoked. + For an example, see above. + + + Alternatively, the SoapActionAnnotationMethodEndpointMapping uses the + @SoapAction annotation to mark methods with a particular SOAP Action. + Whenever a message comes in which has this SOAPAction header, the + method will be invoked. -
- <classname>PayloadRootQNameEndpointMapping</classname> - - The PayloadRootQNameEndpointMapping will use the qualified name of the root - element of the request payload to determine the endpoint that handles it. A qualified name consists of - a namespace URI and a local part, the combination of which - should be unique within the mapping. Here is an example: - - - - ]]><!-- no 'id' required, EndpointMapping beans are automatically detected by the MessageDispatcher --> - - - getOrderEndpoint - createOrderEndpoint - - - - - - - - - - - -]]> - - The qualified name is expressed as { + namespace URI + } + - local part. Thus, the endpoint mapping above routes requests for which have a payload root element with - namespace http://samples and local part orderRequest to the - 'getOrderEndpoint'. Requests with a local part order will - be routed to the 'createOrderEndpoint'. - -
-
- <classname>SoapActionEndpointMapping</classname> - - Rather than base the routing on the contents of the message with the - PayloadRootQNameEndpointMapping, you can use the SOAPAction - HTTP header to route messages. Every client sends this header when making a SOAP request, and the - header value used for a request is defined in the WSDL. By making the SOAPAction - unique per operation, you can use it as a discriminator. Here is an example: - - - - - - getOrderEndpoint - createOrderEndpoint - - - - - - - - - - - -]]> - - The mapping above routes requests which have a SOAPAction of - http://samples/RequestOrder to the 'getOrderEndpoint'. Requests with - http://samples/CreateOrder will be routed to the 'createOrderEndpoint'. - - - - Note that using SOAP Action headers is SOAP 1.1-specific, so it cannot be used when using Plain Old - XML, nor with SOAP 1.2. - - -
-
- <classname>MethodEndpointMapping</classname> - - As explained in , the @Endpoint style - allows you to handle multiple requests in one endpoint class. This is the responsibility of the - MethodEndpointMapping. Similar to the endpoint mapping described above, this - mapping determines which method is to be invoked for an incoming request message. - - - There are two endpoint mappings that can direct requests to methods: the - PayloadRootAnnotationMethodEndpointMapping and the - SoapActionAnnotationMethodEndpointMapping, both of which are very similar to - their non-method counterparts described above. - - - The PayloadRootAnnotationMethodEndpointMapping uses the - @PayloadRoot annotation, with the localPart and - namespace elements, to mark methods with a particular qualified - name. Whenever a message comes in which has this qualified name for the payload root element, the - method will be invoked. For an example, see above. - - - Alternatively, the SoapActionAnnotationMethodEndpointMapping uses the - @SoapAction annotation to mark methods with a particular SOAP Action. - Whenever a message comes in which has this SOAPAction header, the - method will be invoked. - -
WS-Addressing - WS-Addressing specifies a transport-neutral routing mechanism. It is based on a - To and Action SOAP header, which indicate the destination and - intent of the SOAP message, respectively. Additionally, WS-Addressing allows you to define a return - address (for normal messages and for faults), and a unique message identifier which can be used for - correlation + WS-Addressing specifies a transport-neutral routing mechanism. + It is based on a To and Action SOAP header, which indicate the + destination and intent of the SOAP message, respectively. + Additionally, WS-Addressing allows you to define a return address (for normal messages and for faults), + and a unique message identifier which can be used for correlation For more information on WS-Addressing, see . . Here is an example of a WS-Addressing message: - - urn:uuid:21363e0d-2645-4eb7-8afd-2f5ee1bb25cf - - http://example.com/business/client1 - - http://example/com/fabrikam - http://example.com/fabrikam/mail/Delete - - - - 42 - - + + urn:uuid:21363e0d-2645-4eb7-8afd-2f5ee1bb25cf + + http://example.com/business/client1 + + http://example/com/fabrikam + http://example.com/fabrikam/mail/Delete + + + + 42 + + ]]> In this example, the destination is set to http://example/com/fabrikam, while the action is - set to http://example.com/fabrikam/mail/Delete. Additionally, there is a message identifier, - and an reply-to address. By default, this address is the "anonymous" address, indicating that a response - should be sent using the same channel as the request (i.e. the HTTP response), but it can also be - another address, as indicated in this example. + set to http://example.com/fabrikam/mail/Delete. + Additionally, there is a message identifier, and an reply-to address. + By default, this address is the "anonymous" address, indicating that a response should be sent using + the same channel as the request (i.e. the HTTP response), but it can also be another address, + as indicated in this example. - In Spring Web Services, WS-Addressing is implemented as an endpoint mapping. Using this mapping, you - associate WS-Addressing actions with endpoints, similar to the SoapActionEndpointMapping - described above. + In Spring Web Services, WS-Addressing is implemented as an endpoint mapping. + Using this mapping, you associate WS-Addressing actions with endpoints, similar to the + SoapActionAnnotationMethodEndpointMapping described above. -
- <classname>SimpleActionEndpointMapping</classname> - - The SimpleActionEndpointMapping is meant to be used in a standard Spring - application context. It maps actions to endpoints via an exposed mappings - property. Here is an example: - - - - getOrderEndpoint - createOrderEndpoint - - - - - - - - - - - -]]> - - - The mapping above routes requests which have a WS-Addressing Action of - http://samples/RequestOrder to the 'getOrderEndpoint'. Requests with - http://samples/CreateOrder will be routed to the 'createOrderEndpoint'. - - - By default, the SimpleActionEndpointMapping supports both the 1.0 - (May 2006), and the August 2004 editions of WS-Addressing. These two versions are most popular, and - are interoperably with Axis 1 and 2, JAX-WS, XFire, Windows Communication Foundation (WCF), and - Windows Services Enhancemenets (WSE) 3.0. If necessary, specific versions of the spec can be - injected into the versions property. - - - Besides the mappings property, the endpoint mapping also has an - address property. If set, value of this property is compared to the - To header property of the incominging message. - - - Finally, there is the messageSenders property, which is required for sending - response messages to non-anonymous, out-of-bound addresses. You can set MessageSender - implementations in this property, the same as you would on the WebServiceTemplate. - See . - -
<classname>AnnotationActionEndpointMapping</classname> - The AnnotationActionEndpointMapping is quite similar to the SimpleActionEndpointMapping. - It has the same versions and messageSenders properties, - but uses Java 5 annotations. + The AnnotationActionEndpointMapping is similar to the + SoapActionAnnotationMethodEndpointMapping, but uses WS-Addressing headers + instead of the SOAP Action transport header. To use the AnnotationActionEndpointMapping, annotate the handling methods @@ -1341,10 +1220,30 @@ public class AnnotationOrderEndpoint { }]]> + + The mapping above routes requests which have a WS-Addressing Action of + http://samples/RequestOrder to the getOrder method. + Requests with http://samples/CreateOrder will be routed to the + order method.. + + + By default, the AnnotationActionEndpointMapping supports both the 1.0 + (May 2006), and the August 2004 editions of WS-Addressing. These two versions are most popular, and + are interoperable with Axis 1 and 2, JAX-WS, XFire, Windows Communication Foundation (WCF), and + Windows Services Enhancements (WSE) 3.0. + If necessary, specific versions of the spec can be injected into the + versions property. + In addition to the @Action annotation, you can annotate the class with the @Address annotation. If set, the value is compared to the - To header property of the incominging message. + To header property of the incoming message. + + + Finally, there is the messageSenders property, which is required for sending + response messages to non-anonymous, out-of-bound addresses. You can set MessageSender + implementations in this property, the same as you would on the WebServiceTemplate. + See .
@@ -1356,7 +1255,35 @@ public class AnnotationOrderEndpoint { security-related SOAP headers, or the logging of request and response message. - Interceptors located in the endpoint mapping must implement the + Endpoint interceptors are typically defined by using a <sws;interceptors > + element in your application context. + In this element, you can simply define endpoint interceptor beans that apply to all endpoints defined + in that application context. + Alternatively, you can use <sws:payloadRoot> or + <sws:soapAction> elements to specify for which payload root name or SOAP + action the interceptor should apply. + For example: + + + + + + + + + +]]> + Here, we define one 'global' interceptor (MyGlobalInterceptor) that intercepts + all request and responses. + We also define an interceptor that only applies to XML messages that have the + http://www.example.com as a payload root namespace. + Here, we could have defined a localPart attribute in addition to the + namespaceUri to further limit the messages the interceptor applies to. + Finally, we define two interceptors that apply when the message has a + http://www.example.com/SoapAction SOAP action. + + + Interceptors must implement the EndpointInterceptor interface from the org.springframework.ws.server package. This interface defines three methods, one that can be used for handling the request message before the actual @@ -1391,24 +1318,11 @@ public class AnnotationOrderEndpoint { the message to the Commons Logging Log; the latter logs the entire SOAP envelope, including SOAP headers. The following example shows you how to define them in an endpoint mapping: - - - - - - - - - - getOrderEndpoint - createOrderEndpoint - - - + + + - ]]> Both of these interceptors have two properties: 'logRequest' and @@ -1452,7 +1366,7 @@ public class AnnotationOrderEndpoint { To transform the payload to another XML format, Spring Web Services offers the PayloadTransformingInterceptor. This endpoint interceptor is based on XSLT - stylesheets, and is especially useful when supporting multiple versions of a Web service: + style sheets, and is especially useful when supporting multiple versions of a Web service: you can transform the older message format to the newer format. Here is an example to use the PayloadTransformingInterceptor: