GH-6656: Add JmsTemplate overloads to JMS DSL channel specs

Fixes: #6656

- Allow `JmsChannelFactoryBean` to accept an externally provided `JmsTemplate`
- Add `Jms.pollableChannel(JmsTemplate)` and `Jms.pollableChannel(String, JmsTemplate)` factory methods
- Add `Jms.channel(JmsTemplate)` factory method
- Add protected constructors to `JmsPollableMessageChannelSpec` and `JmsMessageChannelSpec` accepting `JmsTemplate`
- Add integration test verifying the polling flow with a `JmsTemplate`

* Guard `JmsChannelFactoryBean` against mixed template config

Add a validation guard to `JmsChannelFactoryBean` that prevents
users from mixing an externally provided `JmsTemplate` with
individual template configuration options set on the factory
bean itself.

Update the What's New documentation to describe the new
`JmsTemplate` support in the JMS DSL.

* Simplify error message when setting properties

If a user sets an external JmsTemplate, they can not set the properties via the factory.
This PR simplifies the logic behind this determination

Author: cppwfs

spring-integration-jms/src/main/java/org/springframework/integration/jms/config/JmsChannelFactoryBean.java

@@ -55,6 +55,7 @@
  * @author Oleg Zhurakousky
  * @author Gary Russell
  * @author Artem Bilan
+ * @author Glenn Renfro
  *
  * @since 2.0
  */
@@ -68,7 +69,11 @@ public class JmsChannelFactoryBean extends AbstractFactoryBean<AbstractJmsChanne
 
 	private final boolean messageDriven;
 
-	private final JmsTemplate jmsTemplate = new DynamicJmsTemplate();
+	private JmsTemplate jmsTemplate = new DynamicJmsTemplate();
+
+	private boolean jmsTemplateExplicitlySet;
+
+	private boolean defaultTemplatePropertySet;
 
 	private @Nullable Class<? extends AbstractMessageListenerContainer> containerType;
 
@@ -164,30 +169,37 @@ public void setInterceptors(List<ChannelInterceptor> interceptors) {
 	 */
 
 	public void setDeliveryPersistent(boolean deliveryPersistent) {
+		recordJmsTemplateOption();
 		this.jmsTemplate.setDeliveryPersistent(deliveryPersistent);
 	}
 
 	public void setExplicitQosEnabled(boolean explicitQosEnabled) {
+		recordJmsTemplateOption();
 		this.jmsTemplate.setExplicitQosEnabled(explicitQosEnabled);
 	}
 
 	public void setMessageConverter(MessageConverter messageConverter) {
+		recordJmsTemplateOption();
 		this.jmsTemplate.setMessageConverter(messageConverter);
 	}
 
 	public void setMessageIdEnabled(boolean messageIdEnabled) {
+		recordJmsTemplateOption();
 		this.jmsTemplate.setMessageIdEnabled(messageIdEnabled);
 	}
 
 	public void setMessageTimestampEnabled(boolean messageTimestampEnabled) {
+		recordJmsTemplateOption();
 		this.jmsTemplate.setMessageTimestampEnabled(messageTimestampEnabled);
 	}
 
 	public void setPriority(int priority) {
+		recordJmsTemplateOption();
 		this.jmsTemplate.setPriority(priority);
 	}
 
 	public void setTimeToLive(long timeToLive) {
+		recordJmsTemplateOption();
 		this.jmsTemplate.setTimeToLive(timeToLive);
 	}
 
@@ -236,6 +248,7 @@ public void setConcurrentConsumers(int concurrentConsumers) {
 
 	public void setConnectionFactory(ConnectionFactory connectionFactory) {
 		this.connectionFactory = connectionFactory;
+		recordJmsTemplateOption();
 		this.jmsTemplate.setConnectionFactory(this.connectionFactory);
 	}
 
@@ -254,6 +267,7 @@ public void setDestinationName(String destinationName) {
 
 	public void setDestinationResolver(DestinationResolver destinationResolver) {
 		this.destinationResolver = destinationResolver;
+		recordJmsTemplateOption();
 		this.jmsTemplate.setDestinationResolver(destinationResolver);
 	}
 
@@ -302,16 +316,19 @@ public void setPhase(int phase) {
 
 	public void setPubSubDomain(boolean pubSubDomain) {
 		this.pubSubDomain = pubSubDomain;
+		recordJmsTemplateOption();
 		this.jmsTemplate.setPubSubDomain(pubSubDomain);
 	}
 
 	public void setPubSubNoLocal(boolean pubSubNoLocal) {
 		this.pubSubNoLocal = pubSubNoLocal;
+		recordJmsTemplateOption();
 		this.jmsTemplate.setPubSubNoLocal(pubSubNoLocal);
 	}
 
 	public void setReceiveTimeout(long receiveTimeout) {
 		this.receiveTimeout = receiveTimeout;
+		recordJmsTemplateOption();
 		this.jmsTemplate.setReceiveTimeout(receiveTimeout);
 	}
 
@@ -322,11 +339,30 @@ public void setRecoveryInterval(long recoveryInterval) {
 
 	public void setSessionAcknowledgeMode(int sessionAcknowledgeMode) {
 		this.sessionAcknowledgeMode = sessionAcknowledgeMode;
+		recordJmsTemplateOption();
 		this.jmsTemplate.setSessionAcknowledgeMode(sessionAcknowledgeMode);
 	}
 
+	/**
+	 * The template to be used by the Factory.
+	 * When an external {@link JmsTemplate} is provided, none of the individual template options
+	 * (e.g. {@code deliveryPersistent}, {@code connectionFactory}, {@code receiveTimeout}, etc.)
+	 * may be set on this factory bean — configure them directly on the provided template instead.
+	 * @param jmsTemplate the {@link JmsTemplate} to build on
+	 * @since 7.1
+	 */
+	public void setJmsTemplate(JmsTemplate jmsTemplate) {
+		this.jmsTemplate = jmsTemplate;
+		this.jmsTemplateExplicitlySet = true;
+	}
+
+	private void recordJmsTemplateOption() {
+		this.defaultTemplatePropertySet = true;
+	}
+
 	public void setSessionTransacted(boolean sessionTransacted) {
 		this.sessionTransacted = sessionTransacted;
+		recordJmsTemplateOption();
 		this.jmsTemplate.setSessionTransacted(sessionTransacted);
 	}
 
@@ -406,6 +442,9 @@ protected AbstractJmsChannel createInstance() {
 	private void initializeJmsTemplate() {
 		Assert.isTrue(this.destination != null ^ this.destinationName != null,
 				"Exactly one of destination or destinationName is required.");
+		Assert.isTrue(!this.jmsTemplateExplicitlySet || !this.defaultTemplatePropertySet,
+				() -> "JmsTemplate properties must be configured on the externally supplied JmsTemplate, " +
+						"not on the factory bean.");
 		JavaUtils.INSTANCE
 				.acceptIfNotNull(this.destination, this.jmsTemplate::setDefaultDestination)
 				.acceptIfNotNull(this.destinationName, this.jmsTemplate::setDefaultDestinationName);

spring-integration-jms/src/main/java/org/springframework/integration/jms/dsl/Jms.java

@@ -30,6 +30,7 @@
  * @author Artem Bilan
  * @author Gary Russell
  * @author Artem Vozhdayenko
+ * @author Glenn Renfro
  *
  * @since 5.0
  */
@@ -46,6 +47,18 @@ public static JmsPollableMessageChannelSpec<?, PollableJmsChannel> pollableChann
 		return new JmsPollableMessageChannelSpec<>(connectionFactory);
 	}
 
+	/**
+	 * The factory to produce a {@link JmsPollableMessageChannelSpec}.
+	 * @param jmsTemplate the {@link JmsTemplate} to build on
+	 * @return the {@link JmsPollableMessageChannelSpec} instance
+	 * @since 7.1
+	 */
+	public static JmsPollableMessageChannelSpec<?, PollableJmsChannel> pollableChannel(
+			JmsTemplate jmsTemplate) {
+
+		return new JmsPollableMessageChannelSpec<>(jmsTemplate);
+	}
+
 	/**
 	 * The factory to produce a {@link JmsPollableMessageChannelSpec}.
 	 * @param id                the bean name for the target {@code PollableChannel} component
@@ -60,6 +73,20 @@ public static JmsPollableMessageChannelSpec<?, PollableJmsChannel> pollableChann
 		return spec.id(id);
 	}
 
+	/**
+	 * The template to produce a {@link JmsPollableMessageChannelSpec}.
+	 * @param id the bean name for the target {@code PollableChannel} component
+	 * @param jmsTemplate the {@link JmsTemplate} to build on
+	 * @return the {@link JmsPollableMessageChannelSpec} instance
+	 * @since 7.1
+	 */
+	public static JmsPollableMessageChannelSpec<?, PollableJmsChannel> pollableChannel(String id,
+			JmsTemplate jmsTemplate) {
+
+		JmsPollableMessageChannelSpec<?, PollableJmsChannel> spec = new JmsPollableMessageChannelSpec<>(jmsTemplate);
+		return spec.id(id);
+	}
+
 	/**
 	 * The factory to produce a {@link JmsMessageChannelSpec}.
 	 * @param connectionFactory the JMS ConnectionFactory to build on
@@ -69,6 +96,16 @@ public static JmsPollableMessageChannelSpec<?, PollableJmsChannel> pollableChann
 		return new JmsMessageChannelSpec<>(connectionFactory);
 	}
 
+	/**
+	 * The factory to produce a {@link JmsMessageChannelSpec}.
+	 * @param jmsTemplate the {@link JmsTemplate} to build on
+	 * @return the {@link JmsMessageChannelSpec} instance
+	 * @since 7.1
+	 */
+	public static JmsMessageChannelSpec<?, ?> channel(JmsTemplate jmsTemplate) {
+		return new JmsMessageChannelSpec<>(jmsTemplate);
+	}
+
 	/**
 	 * The factory to produce a {@link JmsMessageChannelSpec}.
 	 * @param id                the bean name for the target {@code MessageChannel} component

spring-integration-jms/src/main/java/org/springframework/integration/jms/dsl/JmsMessageChannelSpec.java

@@ -23,6 +23,7 @@
 import org.springframework.integration.jms.channel.AbstractJmsChannel;
 import org.springframework.integration.jms.channel.SubscribableJmsChannel;
 import org.springframework.integration.jms.config.JmsChannelFactoryBean;
+import org.springframework.jms.core.JmsTemplate;
 import org.springframework.jms.listener.AbstractMessageListenerContainer;
 import org.springframework.transaction.PlatformTransactionManager;
 import org.springframework.util.ErrorHandler;
@@ -37,6 +38,7 @@
  * @author Artem Bilan
  * @author Gary Russell
  * @author Artem Vozhdayenko
+ * @author Glenn Renfro
  *
  * @since 5.0
  */
@@ -47,6 +49,10 @@ protected JmsMessageChannelSpec(ConnectionFactory connectionFactory) {
 		super(new JmsChannelFactoryBean(true), connectionFactory);
 	}
 
+	protected JmsMessageChannelSpec(JmsTemplate jmsTemplate) {
+		super(new JmsChannelFactoryBean(true), jmsTemplate);
+	}
+
 	/**
 	 * Configure the type of the container.
 	 * {@link AbstractMessageListenerContainer}. Defaults to

spring-integration-jms/src/main/java/org/springframework/integration/jms/dsl/JmsPollableMessageChannelSpec.java

@@ -24,6 +24,7 @@
 import org.springframework.integration.dsl.MessageChannelSpec;
 import org.springframework.integration.jms.channel.AbstractJmsChannel;
 import org.springframework.integration.jms.config.JmsChannelFactoryBean;
+import org.springframework.jms.core.JmsTemplate;
 import org.springframework.jms.support.converter.MessageConverter;
 import org.springframework.jms.support.destination.DestinationResolver;
 
@@ -36,6 +37,7 @@
  * @author Artem Bilan
  * @author Gary Russell
  * @author Artem Vozhdayenko
+ * @author Glenn Renfro
  *
  * @since 5.0
  */
@@ -48,13 +50,22 @@ protected JmsPollableMessageChannelSpec(ConnectionFactory connectionFactory) {
 		this(new JmsChannelFactoryBean(false), connectionFactory);
 	}
 
+	protected JmsPollableMessageChannelSpec(JmsTemplate jmsTemplate) {
+		this(new JmsChannelFactoryBean(false), jmsTemplate);
+	}
+
 	protected JmsPollableMessageChannelSpec(JmsChannelFactoryBean jmsChannelFactoryBean,
 			ConnectionFactory connectionFactory) {
 
 		this.jmsChannelFactoryBean = jmsChannelFactoryBean;
 		this.jmsChannelFactoryBean.setConnectionFactory(connectionFactory);
-		this.jmsChannelFactoryBean.setSingleton(false);
-		this.jmsChannelFactoryBean.setBeanFactory(new DefaultListableBeanFactory());
+	}
+
+	protected JmsPollableMessageChannelSpec(JmsChannelFactoryBean jmsChannelFactoryBean,
+			JmsTemplate jmsTemplate) {
+
+		this.jmsChannelFactoryBean = jmsChannelFactoryBean;
+		this.jmsChannelFactoryBean.setJmsTemplate(jmsTemplate);
 	}
 
 	@Override
@@ -220,6 +231,8 @@ public S sessionTransacted(boolean sessionTransacted) {
 	@SuppressWarnings("unchecked")
 	protected T doGet() {
 		try {
+			this.jmsChannelFactoryBean.setSingleton(false);
+			this.jmsChannelFactoryBean.setBeanFactory(new DefaultListableBeanFactory());
 			this.channel = (T) this.jmsChannelFactoryBean.getObject();
 		}
 		catch (Exception e) {

spring-integration-jms/src/test/java/org/springframework/integration/jms/config/JmsChannelFactoryBeanTests.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2026-present 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.jms.config;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.beans.factory.support.StaticListableBeanFactory;
+import org.springframework.jms.core.JmsTemplate;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatIllegalArgumentException;
+
+/**
+ * @author Glenn Renfro
+ */
+
+class JmsChannelFactoryBeanTests {
+
+	@Test
+	void optionSetBeforeExternalTemplateAlsoThrows() {
+		JmsChannelFactoryBean fb = new JmsChannelFactoryBean(false);
+		fb.setBeanName("testChannel");
+		fb.setDestinationName("testQueue");
+		fb.setSessionTransacted(true);
+		fb.setJmsTemplate(new JmsTemplate());
+		fb.setBeanFactory(new StaticListableBeanFactory());
+
+		assertThatIllegalArgumentException()
+				.isThrownBy(fb::createInstance)
+				.withMessageContaining("JmsTemplate properties must be configured on the externally supplied " +
+						"JmsTemplate, not on the factory bean.");
+	}
+
+	@Test
+	void externalTemplateAloneDoesNotThrowGuard() {
+		JmsChannelFactoryBean fb = new JmsChannelFactoryBean(false);
+		fb.setBeanName("testChannel");
+		fb.setJmsTemplate(new JmsTemplate());
+		fb.setDestinationName("testQueue");
+		fb.setBeanFactory(new StaticListableBeanFactory());
+		assertThat(fb.createInstance()).isNotNull();
+	}
+
+}