diff --git a/core/src/main/java/org/springframework/ws/transport/http/MessageDispatcherServlet.java b/core/src/main/java/org/springframework/ws/transport/http/MessageDispatcherServlet.java index 48648e21..54b157a7 100644 --- a/core/src/main/java/org/springframework/ws/transport/http/MessageDispatcherServlet.java +++ b/core/src/main/java/org/springframework/ws/transport/http/MessageDispatcherServlet.java @@ -47,13 +47,13 @@ import org.springframework.ws.wsdl.WsdlDefinition; * instances. *

* This servlet automatically detects {@link EndpointAdapter EndpointAdapters}, {@link EndpointMapping - * EndpointMappings}, and {@link EndpointExceptionResolver EndpointExceptionResolvers} by type. + * EndpointMappings}, and {@link EndpointExceptionResolver EndpointExceptionResolvers} by type. *

- * This servlet also automatically detects any {@link WsdlDefinition} in its application context. This WSDL is - * exposed under the bean name: for example, a {@link WsdlDefinition} bean named 'echo' will be exposed as - * echo.wsdl in this servlet's context: http://localhost:8080/spring-ws/echo.wsdl. When the - * transformWsdlLocations init-param is set to true in this servlet's configuration in - * web.xml, all location attributes in the WSDL definitions will reflect the URL of the + * This servlet also automatically detects any {@link WsdlDefinition} defined in its application context. This WSDL is + * exposed under the bean name: for example, a WsdlDefinition bean named 'echo' will be + * exposed as echo.wsdl in this servlet's context: http://localhost:8080/spring-ws/echo.wsdl. + * When the transformWsdlLocations init-param is set to true in this servlet's configuration + * in web.xml, all location attributes in the WSDL definitions will reflect the URL of the * incoming request. * * @author Arjen Poutsma diff --git a/core/src/main/java/org/springframework/ws/transport/http/WsdlDefinitionHandlerAdapter.java b/core/src/main/java/org/springframework/ws/transport/http/WsdlDefinitionHandlerAdapter.java index c8f26591..5d766523 100644 --- a/core/src/main/java/org/springframework/ws/transport/http/WsdlDefinitionHandlerAdapter.java +++ b/core/src/main/java/org/springframework/ws/transport/http/WsdlDefinitionHandlerAdapter.java @@ -44,8 +44,9 @@ import org.w3c.dom.Attr; import org.w3c.dom.Document; /** - * Adapter to use the WsdlDefinition interface with the generic DispatcherServlet. Reads the - * source from the mapped WsdlDefinition implementation, and writes that as result to the + * Adapter to use the WsdlDefinition interface with the generic DispatcherServlet. + *

+ * Reads the source from the mapped WsdlDefinition implementation, and writes that as the result to the * HttpServletResponse. *

* If the property transformLocations is set to true, this adapter will change @@ -91,8 +92,8 @@ public class WsdlDefinitionHandlerAdapter extends TransformerObjectSupport imple /** * Sets the XPath expression used for extracting the location attributes from the WSDL 1.1 definition. + *

* Defaults to DEFAULT_LOCATION_EXPRESSION. - * * @see #DEFAULT_LOCATION_EXPRESSION */ public void setLocationExpression(String locationExpression) { diff --git a/src/docbkx/server.xml b/src/docbkx/server.xml index 46286970..6cef09de 100644 --- a/src/docbkx/server.xml +++ b/src/docbkx/server.xml @@ -133,22 +133,64 @@ /* - ]]><!-- ... -->]]> 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-WS framework also need to be - configured. - - - Because the MessageDispatcherServlet is a standard Spring + Services, because the various component beans used by the Spring-WS framework also need to be + configured; this configuration consists of standard Spring XML <bean/> + definitions. 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. + of your web application and create the beans defined there in a Spring container. In the example above, + that means that it looks for '/WEB-INF/spring-ws-servlet.xml'. This file will + contain all of the SWS-specific beans such as endpoints, marshallers and suchlike. +

+ Automatic WSDL exposure + The MessageDispatcherServlet will automatically detect any + WsdlDefinition beans defined in it's Spring container. All such + WsdlDefinition beans that are detected will also be exposed via + a WsdlDefinitionHandlerAdapter; this is a very convenient way to expose your WSDL + to clients simply by just defining some beans. + By way of an example, consider the following bean definition, defined in the Spring-WS framework's + configuration file ('/WEB-INF/[servlet-name]-servlet.xml'). Take notice of the + value of the bean's 'id' attribute, because this will be used when exposing + the WSDL. + + +]]> + The WSDL defined in the 'Orders.wsdl' file can then be accessed via + GET requests to a URL of the following form (substitute the host, port and servlet + context path as appropriate). + + Another cool feature of the MessageDispatcherServlet (or more + correctly the WsdlDefinitionHandlerAdapter) is that it is able to + transform the value of the 'location' of all the WSDL that it exposes to reflect the + URL of the incoming request. + Please note that this 'location' transformation feature is + off by default.To switch this feature on, you just need to specify an + initialization parameter to the MessageDispatcherServlet, like so: + + + + spring-ws + org.springframework.ws.transport.http.MessageDispatcherServlet + + transformWsdlLocations + true + + + + + spring-ws + /* + + +]]> + Consult the class-level Javadoc on the WsdlDefinitionHandlerAdapter class + which explains the whole transformation process in more detail. +
@@ -404,12 +446,11 @@ public class AnnotationOrderEndpoint { 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: + We also need to configure Spring-WS to support the JAXB objects OrderRequest and + Order by defining a Jaxb2Marshaller: + @@ -443,9 +484,9 @@ public class AnnotationOrderEndpoint { As an alternative to using marshalling, we could have used XPath to extract the information out of the incoming XML request. Spring-WS offers another annotation for - this purpose: @XPathParam. You simply annotate method parameters - with this annotation, and it will be bound with the evaluation of that annotation. - Here is an example: + this purpose: @XPathParam. You simply annotate one or more method + parameter with this annotation (each), and each such annotated parameter will be bound to the + evaluation of that annotation. Here is an example: // create Source from order and return it// create Source from order and return it - Since we use the prefix s in our XPath expression, we must bind it to the + Since we use the prefix 's' in our XPath expression, we must bind it to the http://samples namespace: @@ -514,7 +555,7 @@ public class AnnotationOrderEndpoint { 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 a + SoapActionEndpointMapping, but let's first examine the general concept of an EndpointMapping. @@ -528,16 +569,16 @@ public class AnnotationOrderEndpoint { 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). + 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 + '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 + 'defaultEndpoint', which is the default endpoint to use, when this endpoint mapping does not result in a matching endpoint.
@@ -680,12 +721,11 @@ public class AnnotationOrderEndpoint { <classname>PayloadLoggingInterceptor</classname> and <classname>SoapEnvelopeLoggingInterceptor</classname> - When developing a Web service, it can be useful to log the incoming and outgoing XML messages to - the log. Spring Web Services facilitates this with the - PayloadLoggingInterceptor and the - SoapEnvelopeLoggingInterceptor. The former logs just the payload of the - message to the Commons Logging Log; the latter logs the entire SOAP envelope, including SOAP - headers. This example shows you how to define them in an endpoint mapping: + When developing a Web service, it can be useful to log the incoming and outgoing XML messages. + SWS facilitates this with the PayloadLoggingInterceptor and + SoapEnvelopeLoggingInterceptor classes. The former logs just the payload of + 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: ]]> - Both of these interceptors have two properties: logRequest and - logResponse, which can be set to false to disable logging + Both of these interceptors have two properties: 'logRequest' and + 'logResponse', which can be set to false to disable logging for either request or response messages.
@@ -725,13 +765,15 @@ public class AnnotationOrderEndpoint { Note that request validation may sound like a good idea, but makes the resulting Web service very strict. Usually, it is not really important whether the request validates, only if the endpoint can get sufficient information to fullfill a request. Validating the response - is a good idea, because the endpoint should adhere to adhere to its schema. + is a good idea, because the endpoint should adhere to its schema. Remember Postel's Law: Be conservative in what you do; be liberal in what you accept from others. - Here is an example that uses the PayloadValidatingInterceptor: + Here is an example that uses the PayloadValidatingInterceptor; in this + example, we use the schema in /WEB-INF/orders.xsd to validate the response, but + not the request. @@ -739,10 +781,6 @@ public class AnnotationOrderEndpoint { ]]> - - In this example, we use the schema in /WEB-INF/orders.xsd to validate the - response, but not the request. -
<classname>PayloadTransformingInterceptor</classname> @@ -750,8 +788,8 @@ 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: - you simply can transform the older message format to the newer format. - Here is an example to use the PayloadTransformingInterceptor: + you can transform the older message format to the newer format. Here is an example to use the + PayloadTransformingInterceptor: @@ -793,7 +831,7 @@ public class AnnotationOrderEndpoint { creates a SOAP 1.1 Server or SOAP 1.2 Receiver Fault, and uses the exception message as the fault string. - A more sophisticated implementation is the SoapFaultMappingExceptionResolver. + The SoapFaultMappingExceptionResolver is a more sophisticated implementation. 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: @@ -803,11 +841,7 @@ public class AnnotationOrderEndpoint { - - - CLIENT,Invalid request - - + org.springframework.oxm.ValidationFailureException=CLIENT,Invalid request ]]>