Explicit documentation notes on JMS 2.0 vs 1.1 compatibility

Issue: SPR-17583

(cherry picked from commit 7b9c30f26e)

spring-jms/src/main/java/org/springframework/jms/connection/CachingConnectionFactory.java

@@ -63,6 +63,11 @@ import org.springframework.util.ObjectUtils;
  * lead to queue/topic mode, respectively; generic {@code createConnection}
  * calls will lead to a JMS 1.1 connection which is able to serve both modes.
  *
+ * <p>As of Spring Framework 5, this class supports JMS 2.0 {@code JMSContext}
+ * calls and therefore requires the JMS 2.0 API to be present at runtime.
+ * It may nevertheless run against a JMS 1.1 driver (bound to the JMS 2.0 API)
+ * as long as no actual JMS 2.0 calls are triggered by the application's setup.
+ *
  * <p><b>NOTE: This ConnectionFactory requires explicit closing of all Sessions
  * obtained from its shared Connection.</b> This is the usual recommendation for
  * native JMS access code anyway. However, with this ConnectionFactory, its use

spring-jms/src/main/java/org/springframework/jms/connection/DelegatingConnectionFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -36,6 +36,11 @@ import org.springframework.util.Assert;
  * if necessary (e.g. when running JMS 1.0.2 API based code against a generic
  * JMS 1.1 ConnectionFactory, such as ActiveMQ's PooledConnectionFactory).
  *
+ * <p>As of Spring Framework 5, this class supports JMS 2.0 {@code JMSContext}
+ * calls and therefore requires the JMS 2.0 API to be present at runtime.
+ * It may nevertheless run against a JMS 1.1 driver (bound to the JMS 2.0 API)
+ * as long as no actual JMS 2.0 calls are triggered by the application's setup.
+ *
  * <p>This class allows for being subclassed, with subclasses overriding only
  * those methods (such as {@link #createConnection()}) that should not simply
  * delegate to the target ConnectionFactory.

spring-jms/src/main/java/org/springframework/jms/connection/SingleConnectionFactory.java

@@ -61,6 +61,11 @@ import org.springframework.util.ClassUtils;
  * lead to queue/topic mode, respectively; generic {@code createConnection}
  * calls will lead to a JMS 1.1 connection which is able to serve both modes.
  *
+ * <p>As of Spring Framework 5, this class supports JMS 2.0 {@code JMSContext}
+ * calls and therefore requires the JMS 2.0 API to be present at runtime.
+ * It may nevertheless run against a JMS 1.1 driver (bound to the JMS 2.0 API)
+ * as long as no actual JMS 2.0 calls are triggered by the application's setup.
+ *
  * <p>Useful for testing and standalone environments in order to keep using the
  * same Connection for multiple {@link org.springframework.jms.core.JmsTemplate}
  * calls, without having a pooling ConnectionFactory underneath. This may span

spring-jms/src/main/java/org/springframework/jms/connection/TransactionAwareConnectionFactoryProxy.java

@@ -72,6 +72,11 @@ import org.springframework.util.ClassUtils;
  * (e.g. to perform manual transaction control). For typical application purposes,
  * simply use the standard JMS Session interface.
  *
+ * <p>As of Spring Framework 5, this class delegates JMS 2.0 {@code JMSContext}
+ * calls and therefore requires the JMS 2.0 API to be present at runtime.
+ * It may nevertheless run against a JMS 1.1 driver (bound to the JMS 2.0 API)
+ * as long as no actual JMS 2.0 calls are triggered by the application's setup.
+ *
  * @author Juergen Hoeller
  * @since 2.0
  * @see UserCredentialsConnectionFactoryAdapter

spring-jms/src/main/java/org/springframework/jms/connection/UserCredentialsConnectionFactoryAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -63,6 +63,11 @@ import org.springframework.util.StringUtils;
  * definition just for the <i>option</i> of implicitly passing in user credentials
  * if the particular target ConnectionFactory requires it.
  *
+ * <p>As of Spring Framework 5, this class delegates JMS 2.0 {@code JMSContext}
+ * calls and therefore requires the JMS 2.0 API to be present at runtime.
+ * It may nevertheless run against a JMS 1.1 driver (bound to the JMS 2.0 API)
+ * as long as no actual JMS 2.0 calls are triggered by the application's setup.
+ *
  * @author Juergen Hoeller
  * @since 1.2
  * @see #createConnection
@@ -320,7 +325,7 @@ public class UserCredentialsConnectionFactoryAdapter
 	/**
 	 * Inner class used as ThreadLocal value.
 	 */
-	private static class JmsUserCredentials {
+	private static final class JmsUserCredentials {
 
 		public final String username;
 

src/docs/asciidoc/integration.adoc

@@ -38,8 +38,7 @@ usual (Spring) POJOs. Currently, Spring supports the following remoting technolo
 * __Hessian__. By using Spring's `HessianProxyFactoryBean` and the
   `HessianServiceExporter` you can transparently expose your services using the
   lightweight binary HTTP-based protocol provided by Caucho.
-* __JAX-WS__. Spring provides remoting support for web services via JAX-WS (the
-  successor of JAX-RPC, as introduced in Java EE 5 and Java 6).
+* __JAX-WS__. Spring provides remoting support for web services via JAX-WS.
 * __JMS__. Remoting using JMS as the underlying protocol is supported via the
   `JmsInvokerServiceExporter` and `JmsInvokerProxyFactoryBean` classes.
 * __AMQP__. Remoting using AMQP as the underlying protocol is supported by the Spring
@@ -1568,6 +1567,19 @@ implementation of Spring's `PlatformTransactionManager` for JMS (the cunningly n
 `JmsTransactionManager`). This allows for seamless integration of JMS as a transactional
 resource into Spring's transaction management mechanisms.
 
+[NOTE]
+====
+As of Spring Framework 5, Spring's JMS package fully supports JMS 2.0 and requires the
+JMS 2.0 API to be present at runtime. We recommend the use of a JMS 2.0 compatible provider.
+
+If you happen to use an older message broker in your system, you may try upgrading to a
+JMS 2.0 compatible driver for your existing broker generation. Alternatively, you may also
+try to run against a JMS 1.1 based driver, simply putting the JMS 2.0 API jar on the
+classpath but only using JMS 1.1 compatible API against your driver. Spring's JMS support
+adheres to JMS 1.1 conventions by default, so with corresponding configuration it does
+support such a scenario. However, please consider this for transition scenarios only.
+====
+
 
 
 [[jms-using]]