From 352801d7615a06ba66bd21d70c48ed3e66eecc57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Nicoll?= Date: Mon, 7 Apr 2025 13:02:01 +0200 Subject: [PATCH 1/2] Fix indentation --- spring-ws-docs/src/docs/asciidoc/server.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spring-ws-docs/src/docs/asciidoc/server.adoc b/spring-ws-docs/src/docs/asciidoc/server.adoc index ef21feba..ba274688 100644 --- a/spring-ws-docs/src/docs/asciidoc/server.adoc +++ b/spring-ws-docs/src/docs/asciidoc/server.adoc @@ -670,7 +670,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 +697,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 +808,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 +860,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. From 5d5bd57f7965d8ced311d483c807317cd0de70b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Nicoll?= Date: Mon, 7 Apr 2025 12:59:37 +0200 Subject: [PATCH 2/2] Clarify how to apply advanced endpoint configuration Closes gh-1209 --- .../ws/config/annotation/EnableWs.java | 67 ++++++++++--------- spring-ws-docs/src/docs/asciidoc/server.adoc | 35 ++++++++-- 2 files changed, 65 insertions(+), 37 deletions(-) diff --git a/spring-ws-core/src/main/java/org/springframework/ws/config/annotation/EnableWs.java b/spring-ws-core/src/main/java/org/springframework/ws/config/annotation/EnableWs.java index 9761922a..e5643c00 100644 --- a/spring-ws-core/src/main/java/org/springframework/ws/config/annotation/EnableWs.java +++ b/spring-ws-core/src/main/java/org/springframework/ws/config/annotation/EnableWs.java @@ -22,68 +22,71 @@ import java.lang.annotation.Retention; 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: * * 

  * @Configuration
  * @EnableWs
- * @ComponentScan(basePackageClasses = { MyConfiguration.class })
- * public class MyWsConfiguration {
+ * @ComponentScan(basePackageClasses = MyConfiguration.class)
+ * public class MyConfiguration {
  *
  * }
*

- * 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: * * 


  * @Configuration
  * @EnableWs
- * @ComponentScan(basePackageClasses = { MyConfiguration.class })
+ * @ComponentScan(basePackageClasses = MyConfiguration.class)
  * public class MyConfiguration extends WsConfigurerAdapter {
  *
- * 	@Override
- * 	public void addInterceptors(List<EndpointInterceptor> interceptors) {
- * 		interceptors.add(new MyInterceptor());
- * 	}
+ *     @Override
+ *     public void addInterceptors(List<EndpointInterceptor> interceptors) {
+ *         interceptors.add(new MyInterceptor());
+ *     }
  *
- * 	@Override
- * 	public void addArgumentResolvers(List<MethodArgumentResolver> argumentResolvers) {
- * 		argumentResolvers.add(new MyArgumentResolver());
- * 	}
+ *     @Override
+ *     public void addArgumentResolvers(List<MethodArgumentResolver> argumentResolvers) {
+ *         argumentResolvers.add(new MyArgumentResolver());
+ *     }
  *
- * 	// More overridden methods ...
  * }
*

- * 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: + * Note: 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. + *

+ * 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: * * 


  * @Configuration
  * @ComponentScan(basePackageClasses = { MyConfiguration.class })
  * public class MyConfiguration extends WsConfigurationSupport {
  *
- * 	@Override
- * 	public void addInterceptors(List<EndpointInterceptor> interceptors) {
- * 		interceptors.add(new MyInterceptor());
- * 	}
+ *     @Override
+ *     public void addInterceptors(List<EndpointInterceptor> interceptors) {
+ *         interceptors.add(new MyInterceptor());
+ *     }
  *
- * 	@Bean
- * 	@Override
- * 	public DefaultMethodEndpointAdapter defaultMethodEndpointAdapter() {
- * 		// Create or delegate to "super" to create and
- * 		// customize properties of DefaultMethodEndpointAdapter
- * 	}
+ *     @Bean
+ *     @Override
+ *     public PayloadRootAnnotationMethodEndpointMapping payloadRootAnnotationMethodEndpointMapping() {
+ *         // Create or delegate to "super" to create and
+ *         // customize properties of PayloadRootAnnotationMethodEndpointMapping
+ *     }
  * }
* * @author Arjen Poutsma + * @author Stephane Nicoll * @since 2.2 * @see WsConfigurer * @see WsConfigurerAdapter diff --git a/spring-ws-docs/src/docs/asciidoc/server.adoc b/spring-ws-docs/src/docs/asciidoc/server.adoc index ba274688..125e3677 100644 --- a/spring-ws-docs/src/docs/asciidoc/server.adoc +++ b/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 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 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 <>. -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 <>. As explained in <>, 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