GH-2818: DSL support for -ws module

Resolves #2818

* Rework to improve fluency
* reduce the number of factory methods and use a different spec when
  an external WST is provided.
* Docs and address comments

Author: garyrussell

spring-integration-ws/src/main/java/org/springframework/integration/ws/AbstractWebServiceOutboundGateway.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -165,10 +165,14 @@ public void setFaultMessageResolver(FaultMessageResolver faultMessageResolver) {
 		this.webServiceTemplate.setFaultMessageResolver(faultMessageResolver);
 	}
 
+	/**
+	 * Specify the {@link WebServiceMessageSender} to use.
+	 * @param messageSender the sender.
+	 * @deprecated in favor of {@link #setMessageSenders(WebServiceMessageSender...)}
+	 */
+	@Deprecated
 	public void setMessageSender(WebServiceMessageSender messageSender) {
-		Assert.state(!this.webServiceTemplateExplicitlySet,
-				() -> "'messageSender' must be specified on the provided: " + this.webServiceTemplate);
-		this.webServiceTemplate.setMessageSender(messageSender);
+		setMessageSenders(messageSender);
 	}
 
 	public void setMessageSenders(WebServiceMessageSender... messageSenders) {

spring-integration-ws/src/main/java/org/springframework/integration/ws/MarshallingWebServiceInboundGateway.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,13 +30,14 @@
 /**
  * @author Mark Fisher
  * @author Oleg Zhurakousky
+ * @author Gary Russell
  * @since 1.0.2
  */
 public class MarshallingWebServiceInboundGateway extends AbstractWebServiceInboundGateway {
 
-	private volatile Marshaller marshaller;
+	private Marshaller marshaller;
 
-	private volatile Unmarshaller unmarshaller;
+	private Unmarshaller unmarshaller;
 
 	/**
 	 * Creates a new <code>MarshallingWebServiceInboundGateway</code>.
@@ -58,7 +59,7 @@ public MarshallingWebServiceInboundGateway() {
 	 * @see #MarshallingWebServiceInboundGateway(Marshaller, Unmarshaller)
 	 */
 	public MarshallingWebServiceInboundGateway(Marshaller marshaller) {
-		Assert.notNull(marshaller, "'marshaller' must no be null");
+		Assert.notNull(marshaller, "'marshaller' must not be null");
 		Assert.isInstanceOf(Unmarshaller.class, marshaller, "When using this constructor the provided " +
 				"Marshaller must also implement Unmarshaller");
 		this.marshaller = marshaller;
@@ -72,19 +73,19 @@ public MarshallingWebServiceInboundGateway(Marshaller marshaller) {
 	 * @param unmarshaller The unmarshaller.
 	 */
 	public MarshallingWebServiceInboundGateway(Marshaller marshaller, Unmarshaller unmarshaller) {
-		Assert.notNull(marshaller, "'marshaller' must no be null");
-		Assert.notNull(unmarshaller, "'unmarshaller' must no be null");
+		Assert.notNull(marshaller, "'marshaller' must not be null");
+		Assert.notNull(unmarshaller, "'unmarshaller' must not be null");
 		this.marshaller = marshaller;
 		this.unmarshaller = unmarshaller;
 	}
 
 	public void setMarshaller(Marshaller marshaller) {
-		Assert.notNull(marshaller, "'marshaller' must no be null");
+		Assert.notNull(marshaller, "'marshaller' must not be null");
 		this.marshaller = marshaller;
 	}
 
 	public void setUnmarshaller(Unmarshaller unmarshaller) {
-		Assert.notNull(unmarshaller, "'unmarshaller' must no be null");
+		Assert.notNull(unmarshaller, "'unmarshaller' must not be null");
 		this.unmarshaller = unmarshaller;
 	}
 

spring-integration-ws/src/main/java/org/springframework/integration/ws/dsl/BaseWsInboundGatewaySpec.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2020 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.ws.dsl;
+
+import org.springframework.integration.dsl.MessagingGatewaySpec;
+import org.springframework.integration.ws.AbstractWebServiceInboundGateway;
+import org.springframework.integration.ws.SoapHeaderMapper;
+
+/**
+ * Base {@link MessagingGatewaySpec} for web services.
+ *
+ * @param <S> the target {@link BaseWsInboundGatewaySpec} implementation type.
+ * @param <E> the target {@link AbstractWebServiceInboundGateway} implementation type.
+ *
+ * @author Gary Russell
+ * @since 5.3
+ *
+ */
+public abstract class BaseWsInboundGatewaySpec<
+		S extends BaseWsInboundGatewaySpec<S, E>, E extends AbstractWebServiceInboundGateway>
+	extends MessagingGatewaySpec<S, E> {
+
+	/**
+	 * Construct an instance.
+	 */
+	protected BaseWsInboundGatewaySpec() {
+		super(null);
+	}
+
+	/**
+	 * Configure the header mapper.
+	 * @param headerMapper the mapper.
+	 * @return the spec.
+	 */
+	public S headerMapper(SoapHeaderMapper headerMapper) {
+		this.target.setHeaderMapper(headerMapper);
+		return _this();
+	}
+
+	@Override
+	protected E doGet() {
+		return assemble(create());
+	}
+
+	protected abstract E create();
+
+	protected E assemble(E gateway) {
+		return gateway;
+	}
+
+}

spring-integration-ws/src/main/java/org/springframework/integration/ws/dsl/BaseWsOutboundGatewaySpec.java

@@ -0,0 +1,167 @@
+/*
+ * Copyright 2020 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.ws.dsl;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import org.springframework.expression.Expression;
+import org.springframework.integration.dsl.MessageHandlerSpec;
+import org.springframework.integration.util.JavaUtils;
+import org.springframework.integration.ws.AbstractWebServiceOutboundGateway;
+import org.springframework.integration.ws.SoapHeaderMapper;
+import org.springframework.ws.WebServiceMessageFactory;
+import org.springframework.ws.client.core.FaultMessageResolver;
+import org.springframework.ws.client.core.WebServiceMessageCallback;
+import org.springframework.ws.client.core.WebServiceTemplate;
+import org.springframework.ws.client.support.destination.DestinationProvider;
+import org.springframework.ws.client.support.interceptor.ClientInterceptor;
+import org.springframework.ws.transport.WebServiceMessageSender;
+
+/**
+ * The base {@link MessageHandlerSpec} for {@link AbstractWebServiceOutboundGateway}s.
+ *
+ * @param <S> the target {@link BaseWsOutboundGatewaySpec} implementation type.
+ * @param <E> the target {@link AbstractWebServiceOutboundGateway} implementation type.
+ *
+ * @author Gary Russell
+ * @since 5.3
+ *
+ */
+public abstract class BaseWsOutboundGatewaySpec<
+		S extends BaseWsOutboundGatewaySpec<S, E>, E extends AbstractWebServiceOutboundGateway>
+	extends MessageHandlerSpec<S, E> {
+
+	private final Map<String, Expression> uriVariableExpressions = new HashMap<>();
+
+	protected WebServiceTemplate template; // NOSONAR
+
+	protected DestinationProvider destinationProvider; // NOSONAR
+
+	protected String uri; // NOSONAR
+
+	protected WebServiceMessageFactory webServiceMessageFactory; // NOSONAR
+
+	private SoapHeaderMapper headerMapper;
+
+	private boolean encodeUri = true;
+
+	private boolean ignoreEmptyResponses = true;
+
+	private WebServiceMessageCallback requestCallback;
+
+	protected FaultMessageResolver faultMessageResolver; // NOSONAR
+
+	protected WebServiceMessageSender[] messageSenders; // NOSONAR
+
+	protected ClientInterceptor[] gatewayInterceptors; // NOSONAR
+
+	protected boolean extractPayload = true; // NOSONAR
+
+	/**
+	 * Configure with a destination provider;
+	 * @param destinationProvider the destination provider.
+	 * @return the spec.
+	 */
+	public S destinationProvider(DestinationProvider destinationProvider) {
+		this.destinationProvider = destinationProvider;
+		return _this();
+	}
+
+	/**
+	 * Configure with a URI.
+	 * @param uri the uri.
+	 * @return the spec.
+	 */
+	public S uri(String uri) {
+		this.uri = uri;
+		return _this();
+	}
+
+	/**
+	 * Configure the header mapper.
+	 * @param headerMapper the mapper.
+	 * @return the spec.
+	 */
+	public S headerMapper(SoapHeaderMapper headerMapper) {
+		this.headerMapper = headerMapper;
+		return _this();
+	}
+
+	/**
+	 * Set the Map of URI variable expressions to evaluate against the outbound message
+	 * when replacing the variable placeholders in a URI template.
+	 * @param uriVariableExpressions The URI variable expressions.
+	 * @return the spec.
+	 */
+	public S uriVariableExpressions(Map<String, Expression> uriVariableExpressions) {
+		this.uriVariableExpressions.putAll(uriVariableExpressions);
+		return _this();
+	}
+
+	/**
+	 * Specify whether the URI should be encoded after any <code>uriVariables</code>
+	 * are expanded and before sending the request. The default value is <code>true</code>.
+	 * @param encodeUri true if the URI should be encoded.
+	 * @return the spec.
+	 * @see org.springframework.web.util.UriComponentsBuilder
+	 */
+	public S encodeUri(boolean encodeUri) {
+		this.encodeUri = encodeUri;
+		return _this();
+	}
+
+	/**
+	 * Specify whether empty String response payloads should be ignored.
+	 * The default is <code>true</code>. Set this to <code>false</code> if
+	 * you want to send empty String responses in reply Messages.
+	 * @param ignoreEmptyResponses true if empty responses should be ignored.
+	 * @return the spec.
+	 */
+	public S ignoreEmptyResponses(boolean ignoreEmptyResponses) {
+		this.ignoreEmptyResponses = ignoreEmptyResponses;
+		return _this();
+	}
+
+	/**
+	 * Specify the {@link WebServiceMessageCallback} to use.
+	 * @param requestCallback the call back.
+	 * @return the spec.
+	 */
+	public S requestCallback(WebServiceMessageCallback requestCallback) {
+		this.requestCallback = requestCallback;
+		return _this();
+	}
+
+	@Override
+	protected E doGet() {
+		return assemble(create());
+	}
+
+	protected abstract E create();
+
+	protected E assemble(E gateway) {
+		gateway.setUriVariableExpressions(this.uriVariableExpressions);
+		JavaUtils.INSTANCE
+			.acceptIfNotNull(this.headerMapper, gateway::setHeaderMapper);
+		gateway.setEncodeUri(this.encodeUri);
+		gateway.setIgnoreEmptyResponses(this.ignoreEmptyResponses);
+		gateway.setRequestCallback(this.requestCallback);
+		return gateway;
+	}
+
+}

spring-integration-ws/src/main/java/org/springframework/integration/ws/dsl/MarshallingWsInboundGatewaySpec.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2020 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.ws.dsl;
+
+import org.springframework.integration.ws.MarshallingWebServiceInboundGateway;
+import org.springframework.oxm.Marshaller;
+import org.springframework.oxm.Unmarshaller;
+
+/**
+ * The spec for a {@link MarshallingWebServiceInboundGateway}.
+ *
+ * @author Gary Russell
+ * @since 5.3
+ *
+ */
+public class MarshallingWsInboundGatewaySpec extends BaseWsInboundGatewaySpec<MarshallingWsInboundGatewaySpec,
+	MarshallingWebServiceInboundGateway> {
+
+	protected Marshaller gatewayMarshaller; // NOSONAR
+
+	protected Unmarshaller gatewayUnmarshaller; // NOSONAR
+
+	/**
+	 * Specify a marshaller to use.
+	 * @param marshaller the marshaller.
+	 * @return the spec.
+	 */
+	public MarshallingWsInboundGatewaySpec marshaller(Marshaller marshaller) {
+		this.gatewayMarshaller = marshaller;
+		return this;
+	}
+
+	/**
+	 * Specify an unmarshaller to use. Required if the {@link #gatewayMarshaller} is not also
+	 * an {@link Unmarshaller}.
+	 * @param unmarshaller the unmarshaller.
+	 * @return the spec.
+	 */
+	public MarshallingWsInboundGatewaySpec unmarshaller(Unmarshaller unmarshaller) {
+		this.gatewayUnmarshaller = unmarshaller;
+		return this;
+	}
+
+	@Override
+	protected MarshallingWebServiceInboundGateway create() {
+		if (this.gatewayUnmarshaller != null) {
+			return new MarshallingWebServiceInboundGateway(this.gatewayMarshaller, this.gatewayUnmarshaller);
+		}
+		else {
+			return new MarshallingWebServiceInboundGateway(this.gatewayMarshaller);
+		}
+	}
+
+}