Merge branch '4.0.x'

Closes gh-1518

Author: snicoll

spring-ws-core/src/main/java/org/springframework/ws/config/annotation/EnableWs.java

@@ -22,65 +22,70 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-import org.springframework.context.annotation.Configuration;
 import org.springframework.context.annotation.Import;
 
 /**
- * Add this annotation to an {@link Configuration @Configuration} class to have the Spring
- * Web Services configuration defined in {@link WsConfigurationSupport} imported. For
- * instance:
+ * Adding this annotation to an {@code @Configuration} class imports the Spring Web
+ * Services configuration from {@link WsConfigurationSupport}, for example:
  *
  * <pre><code class='java'>
  * &#064;Configuration
  * &#064;EnableWs
- * &#064;ComponentScan(basePackageClasses = { MyConfiguration.class })
- * public class MyWsConfiguration {
+ * &#064;ComponentScan(basePackageClasses = MyConfiguration.class)
+ * public class MyConfiguration {
  *
  * }</code></pre>
  * <p>
- * Customize the imported configuration by implementing the {@link WsConfigurer}
- * interface: <pre><code class='java'>
+ * Customize the imported configuration by implementing the {@link WsConfigurer} interface
+ * and overriding individual methods:
+ *
+ * <pre><code class='java'>
  * &#064;Configuration
  * &#064;EnableWs
- * &#064;ComponentScan(basePackageClasses = { MyConfiguration.class })
+ * &#064;ComponentScan(basePackageClasses = MyConfiguration.class)
  * public class MyConfiguration implements WsConfigurer {
  *
- * 	&#064;Override
- * 	public void addInterceptors(List&lt;EndpointInterceptor&gt; interceptors) {
- * 		interceptors.add(new MyInterceptor());
- * 	}
+ *     &#064;Override
+ *     public void addInterceptors(List&lt;EndpointInterceptor&gt; interceptors) {
+ *         interceptors.add(new MyInterceptor());
+ *     }
  *
- * 	&#064;Override
- * 	public void addArgumentResolvers(List&lt;MethodArgumentResolver&gt; argumentResolvers) {
- * 		argumentResolvers.add(new MyArgumentResolver());
- * 	}
+ *     &#064;Override
+ *     public void addArgumentResolvers(List&lt;MethodArgumentResolver&gt; argumentResolvers) {
+ *         argumentResolvers.add(new MyArgumentResolver());
+ *     }
  *
- * 	// More overridden methods ...
  * }</code></pre>
  * <p>
- * If the customization options of {@link WsConfigurer} do not expose something you need
- * to configure, consider removing the {@code @EnableWs} annotation and extending directly
- * from {@link WsConfigurationSupport} overriding selected {@code @Bean} methods:
+ * <strong>Note:</strong> only one {@code @Configuration} class may have the
+ * {@code @EnableWs} annotation to import the Spring Web Services configuration. There can
+ * however be multiple {@code @Configuration} classes implementing {@code WsConfigurer} in
+ * order to customize the provided configuration.
+ * <p>
+ * If {@link WsConfigurer} does not expose some more advanced setting that needs to be
+ * configured, consider removing the {@code @EnableWs} annotation and extending directly
+ * from {@link WsConfigurationSupport} or {@link DelegatingWsConfiguration}, for example:
  *
  * <pre><code class='java'>
  * &#064;Configuration
  * &#064;ComponentScan(basePackageClasses = { MyConfiguration.class })
  * public class MyConfiguration extends WsConfigurationSupport {
  *
- * 	&#064;Override
- * 	public void addInterceptors(List&lt;EndpointInterceptor&gt; interceptors) {
- * 		interceptors.add(new MyInterceptor());
- * 	}
+ *     &#064;Override
+ *     public void addInterceptors(List&lt;EndpointInterceptor&gt; interceptors) {
+ *         interceptors.add(new MyInterceptor());
+ *     }
  *
- * 	&#064;Bean
- * 	&#064;Override
- * 	public DefaultMethodEndpointAdapter defaultMethodEndpointAdapter() {
- * 		// Create or delegate to "super" to create and
- * 		// customize properties of DefaultMethodEndpointAdapter
- * 	}
+ *     &#064;Bean
+ *     &#064;Override
+ *     public PayloadRootAnnotationMethodEndpointMapping payloadRootAnnotationMethodEndpointMapping() {
+ *         // Create or delegate to "super" to create and
+ *         // customize properties of PayloadRootAnnotationMethodEndpointMapping
+ *     }
  * }</code></pre>
  *
  * @author Arjen Poutsma
+ * @author Stephane Nicoll
  * @since 2.2
  * @see WsConfigurer
  * @see WsConfigurationSupport

spring-ws-docs/src/docs/asciidoc/server.adoc

@@ -633,14 +633,14 @@ public class EchoConfig {
 ----
 ====
 
-To customize the `@EnableWs` configuration, you can implement `WsConfigurer`:
+To customize the `@EnableWs` configuration, you can implement `WsConfigurer` and override individual methods:
 
 ====
 [source,java]
 ----
 @Configuration
 @EnableWs
-public class MyConfiguration implements WsConfigurer {
+public class EchoConfig implements WsConfigurer {
 
   @Override
   public void addInterceptors(List<EndpointInterceptor> interceptors) {
@@ -652,7 +652,30 @@ public class MyConfiguration implements WsConfigurer {
     argumentResolvers.add(new MyArgumentResolver());
   }
 
-  // More overridden methods ...
+}
+----
+====
+
+If `WsConfigurer` does not expose some more advanced setting that needs to be configured, consider removing `@EnableWs`  and extending directly from `WsConfigurationSupport` or `DelegatingWsConfiguration`.
+
+====
+[source,java]
+----
+@Configuration
+public class EchoConfig extends WsConfigurationSupport {
+
+  @Override
+  public void addInterceptors(List<EndpointInterceptor> interceptors) {
+    interceptors.add(new MyInterceptor());
+  }
+
+  @Bean
+  @Override
+  public PayloadRootAnnotationMethodEndpointMapping payloadRootAnnotationMethodEndpointMapping() {
+      // Create or delegate to "super" to create and
+      // customize properties of PayloadRootAnnotationMethodEndpointMapping
+  }
+
 }
 ----
 ====
@@ -670,7 +693,7 @@ If you want to use a different scope, such as prototype, see the {spring-framewo
 Note that all abstract base classes provided in Spring-WS are thread safe, unless otherwise indicated in the class-level Javadoc.
 
 [[server-atEndpoint-methods]]
-=== `@Endpoint` handling methods
+== `@Endpoint` handling methods
 
 For an endpoint to actually handle incoming XML messages, it needs to have one or more handling methods.
 Handling methods can take wide range of parameters and return types.
@@ -697,7 +720,7 @@ The `order` method takes an `Element` (annotated with `@RequestPayload`) as a pa
 This means that the payload of the message is passed on this method as a DOM element.
 The method has a `void` return type, indicating that no response message is sent.
 
-==== Handling Method Parameters
+=== Handling Method Parameters
 
 The handling method typically has one or more parameters that refer to various parts of the incoming XML message.
 Most commonly, the handling method has a single parameter that maps to the payload of the message, but it can also map to other parts of the request message, such as a SOAP header.
@@ -808,7 +831,7 @@ You can even extend this mechanism to support your own parameter types.
 See the Javadoc of {spring-ws-api}/server/endpoint/adapter/DefaultMethodEndpointAdapter.html[`DefaultMethodEndpointAdapter`] and {spring-ws-api}/server/endpoint/adapter/method/MethodArgumentResolver.html[`MethodArgumentResolver`] to see how.
 
 [[server-xpath-param]]
-===== `@XPathParam`
+==== `@XPathParam`
 
 One parameter type needs some extra explanation: `@XPathParam`.
 The idea here is that you annotate one or more method parameters with an XPath expression and that each such annotated parameter is bound to the evaluation of the expression.
@@ -860,7 +883,7 @@ By using the `@XPathParam`, you can bind to all the data types supported by XPat
 
 In addition to this list, you can use any type that can be converted from a `String` by a Spring {spring-framework-docs}/core/validation/convert.html#core-convert-ConversionService-API[conversion service].
 
-==== Handling method return types
+=== Handling method return types
 
 To send a response message, the handling needs to specify a return type.
 If no response message is required, the method can declare a `void` return type.
@@ -942,8 +965,8 @@ The concept of configurable endpoint mappings that can optionally contain interc
 A lot of supporting functionality can be built into custom `EndpointMapping` implementations.
 For example, a custom endpoint mapping could choose an endpoint based not only 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 <<server-endpoint-interceptor>>.
-Additionally, there is the `defaultEndpoint`, which is the default endpoint to use when this endpoint mapping does not result in a matching endpoint.
+Most endpoint mappings inherit from the `AbstractEndpointMapping`, which offers an '`interceptors`' property, which is the list of interceptors to use.
+`EndpointInterceptors` are discussed in <<server-endpoint-interceptor>>.
 
 As explained in <<server-endpoints>>, the `@Endpoint` style lets you handle multiple requests in one endpoint class.
 This is the responsibility of the `MethodEndpointMapping`.
@@ -957,6 +980,8 @@ Whenever a message comes in with this qualified name for the payload root elemen
 Alternatively, the `SoapActionAnnotationMethodEndpointMapping` uses the `@SoapAction` annotation to mark methods with a particular SOAP Action.
 Whenever a message comes in with this `SOAPAction` header, the method is invoked.
 
+`AbstractEndpointMapping` implementations provides a `defaultEndpoint` property that configures the endpoint to use when a configured mapping does not result in a matching endpoint.
+
 [[server-ws-addressing]]
 === WS-Addressing