Clarify how to apply advanced endpoint configuration

Closes gh-1209

Author: snicoll

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

@@ -22,68 +22,71 @@
 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
- * or more likely by extending the {@link WsConfigurerAdapter} base class and overriding
- * individual methods:
+ * To customize the imported configuration, implement the {@link WsConfigurer} interface
+ * or more likely extend the {@link WsConfigurerAdapter} base class and override
+ * individual methods, for example:
  *
  * <pre><code class='java'>
  * &#064;Configuration
  * &#064;EnableWs
- * &#064;ComponentScan(basePackageClasses = { MyConfiguration.class })
+ * &#064;ComponentScan(basePackageClasses = MyConfiguration.class)
  * public class MyConfiguration extends WsConfigurerAdapter {
  *
- * 	&#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 WsConfigurerAdapter

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

@@ -633,14 +633,14 @@ public class EchoConfig {
 ----
 ====
 
-To customize the `@EnableWs` configuration, you can implement `WsConfigurer` or, better yet, extend the `WsConfigurerAdapter`:
+To customize the `@EnableWs` configuration, you can implement `WsConfigurer` and override individual methods:
 
 ====
 [source,java]
 ----
 @Configuration
 @EnableWs
-public class MyConfiguration extends WsConfigurerAdapter {
+public class EchoConfig extends WsConfigurerAdapter {
 
   @Override
   public void addInterceptors(List<EndpointInterceptor> interceptors) {
@@ -652,7 +652,30 @@ public class MyConfiguration extends WsConfigurerAdapter {
     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
+  }
+
 }
 ----
 ====
@@ -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