Document limitations for MessageProducer/Consumer caching with WebLogic JMS

Closes gh-28500

Author: jhoeller

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -49,8 +49,8 @@
 import org.springframework.util.ObjectUtils;
 
 /**
- * {@link SingleConnectionFactory} subclass that adds {@link javax.jms.Session}
- * caching as well {@link javax.jms.MessageProducer} caching. This ConnectionFactory
+ * {@link SingleConnectionFactory} subclass that adds {@link Session} caching as well as
+ * {@link MessageProducer} and {@link MessageConsumer} caching. This ConnectionFactory
  * also switches the {@link #setReconnectOnException "reconnectOnException" property}
  * to "true" by default, allowing for automatic recovery of the underlying Connection.
  *
@@ -82,8 +82,19 @@
  * Re-registering a durable consumer for the same subscription on the same
  * Session handle is not supported; close and reobtain a cached Session first.
  *
+ * <p>Last but not least, MessageProducers and MessageConsumers for temporary
+ * queues and topics (TemporaryQueue/TemporaryTopic) will never be cached.
+ * Unfortunately, WebLogic JMS happens to implement the temporary queue/topic
+ * interfaces on its regular destination implementation, mis-indicating that
+ * none of its destinations can be cached. Please use a different connection
+ * pool/cache on WebLogic, or customize this class for WebLogic purposes.
+ *
  * @author Juergen Hoeller
  * @since 2.5.3
+ * @see Connection
+ * @see Session
+ * @see MessageProducer
+ * @see MessageConsumer
  */
 public class CachingConnectionFactory extends SingleConnectionFactory {
 

src/docs/asciidoc/integration.adoc

@@ -1605,17 +1605,26 @@ takes a reference to a standard `ConnectionFactory` that would typically come fr
 ===== Using `CachingConnectionFactory`
 
 The `CachingConnectionFactory` extends the functionality of `SingleConnectionFactory`
-and adds the caching of `Session`, `MessageProducer`, and `MessageConsumer` instances. The initial
-cache size is set to `1`. You can use the `sessionCacheSize` property to increase the number of
-cached sessions. Note that the number of actual cached sessions is more than that
-number, as sessions are cached based on their acknowledgment mode, so there can be up to
-four cached session instances (one for each
-acknowledgment mode) when `sessionCacheSize` is set to one. `MessageProducer` and `MessageConsumer` instances are cached within their
-owning session and also take into account the unique properties of the producers and
-consumers when caching. MessageProducers are cached based on their destination.
-MessageConsumers are cached based on a key composed of the destination, selector,
+and adds the caching of `Session`, `MessageProducer`, and `MessageConsumer` instances.
+The initial cache size is set to `1`. You can use the `sessionCacheSize` property to
+increase the number of cached sessions. Note that the number of actual cached sessions
+is more than that number, as sessions are cached based on their acknowledgment mode,
+so there can be up to four cached session instances (one for each acknowledgment mode)
+when `sessionCacheSize` is set to one. `MessageProducer` and `MessageConsumer` instances
+are cached within their owning session and also take into account the unique properties
+of the producers and consumers when caching. MessageProducers are cached based on their
+destination. MessageConsumers are cached based on a key composed of the destination, selector,
 noLocal delivery flag, and the durable subscription name (if creating durable consumers).
 
+[NOTE]
+====
+MessageProducers and MessageConsumers for temporary queues and topics
+(TemporaryQueue/TemporaryTopic) will never be cached. Unfortunately, WebLogic JMS happens
+to implement the temporary queue/topic interfaces on its regular destination implementation,
+mis-indicating that none of its destinations can be cached. Please use a different connection
+pool/cache on WebLogic, or customize `CachingConnectionFactory` for WebLogic purposes.
+====
+
 
 [[jms-destinations]]
 ==== Destination Management