Add reference documentation for JmsClient next to JmsTemplate

See gh-32501

Author: jhoeller

framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc

@@ -7,8 +7,8 @@ This describes how to receive messages with JMS in Spring.
 [[jms-receiving-sync]]
 == Synchronous Receipt
 
-While JMS is typically associated with asynchronous processing, you can
-consume messages synchronously. The overloaded `receive(..)` methods provide this
+While JMS is typically associated with asynchronous processing, you can consume messages
+synchronously. The `receive(..)` methods on `JmsTemplate` and `JmsClient` provide this
 functionality. During a synchronous receive, the calling thread blocks until a message
 becomes available. This can be a dangerous operation, since the calling thread can
 potentially be blocked indefinitely. The `receiveTimeout` property specifies how long

framework-docs/modules/ROOT/pages/integration/jms/sending.adoc

@@ -59,8 +59,8 @@ If you created the `JmsTemplate` and specified a default destination, the
 `send(MessageCreator c)` sends a message to that destination.
 
 
-[[jms-msg-conversion]]
-== Using Message Converters
+[[jms-sending-conversion]]
+== Using JMS Message Converters
 
 To facilitate the sending of domain model objects, the `JmsTemplate` has
 various send methods that take a Java object as an argument for a message's data
@@ -87,7 +87,7 @@ following example shows how to modify a message header and a property after a
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
 	public void sendWithConversion() {
-		Map map = new HashMap();
+		Map<String, String> map = new HashMap<>();
 		map.put("Name", "Mark");
 		map.put("Age", new Integer(47));
 		jmsTemplate.convertAndSend("testQueue", map, new MessagePostProcessor() {
@@ -120,15 +120,43 @@ MapMessage={
 }
 ----
 
+NOTE: This JMS-specific `org.springframework.jms.support.converter.MessageConverter`
+arrangement operates on JMS message types and is responsible for immediate conversion
+to `jakarta.jms.TextMessage`, `jakarta.jms.BytesMessage`, etc. For a contract supporting
+generic message payloads, use `org.springframework.messaging.converter.MessageConverter`
+with `JmsMessagingTemplate` or preferably `JmsClient` as your central delegate instead.
 
-[[jms-callbacks]]
-== Using `SessionCallback` and `ProducerCallback`
+
+[[jms-sending-jmsclient]]
+== Sending a Message with `JmsClient`
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+// Reusable handle, typically created through JmsClient.create(ConnectionFactory)
+// For custom conversion, use JmsClient.create(ConnectionFactory, MessageConverter)
+private JmsClient jmsClient;
+
+public void sendWithConversion() {
+    this.jmsClient.destination("myQueue")
+            .withTimeToLive(1000)
+            .send("myPayload");  // optionally with a headers Map next to the payload
+}
+
+public void sendCustomMessage() {
+    Message<?> message =
+            MessageBuilder.withPayload("myPayload").build();  // optionally with headers
+    this.jmsClient.destination("myQueue")
+            .withTimeToLive(1000)
+            .send(message);
+}
+----
+
+
+[[jms-sending-callbacks]]
+== Using `SessionCallback` and `ProducerCallback` on `JmsTemplate`
 
 While the send operations cover many common usage scenarios, you might sometimes
 want to perform multiple operations on a JMS `Session` or `MessageProducer`. The
 `SessionCallback` and `ProducerCallback` expose the JMS `Session` and `Session` /
 `MessageProducer` pair, respectively. The `execute()` methods on `JmsTemplate` run
 these callback methods.
-
-
-

framework-docs/modules/ROOT/pages/integration/jms/using.adoc

@@ -4,13 +4,20 @@
 This section describes how to use Spring's JMS components.
 
 
-[[jms-jmstemplate]]
-== Using `JmsTemplate`
+[[jms-jmstemplate-jmsclient]]
+== `JmsTemplate` and `JmsClient`
 
 The `JmsTemplate` class is the central class in the JMS core package. It simplifies the
 use of JMS, since it handles the creation and release of resources when sending or
 synchronously receiving messages.
 
+`JmsClient` is a new API variant in Spring Framework 7.0, following the design of
+`JdbcClient` and co. `JmsClient` builds on `JmsTemplate` for straightforward send
+and receive operations with customization options per operation.
+
+[[jms-jmstemplate]]
+=== Using `JmsTemplate`
+
 Code that uses the `JmsTemplate` needs only to implement callback interfaces that give them
 a clearly defined high-level contract. The `MessageCreator` callback interface creates a
 message when given a `Session` provided by the calling code in `JmsTemplate`. To
@@ -43,10 +50,23 @@ and then safely inject this shared reference into multiple collaborators. To be
 clear, the `JmsTemplate` is stateful, in that it maintains a reference to a
 `ConnectionFactory`, but this state is not conversational state.
 
+[[jms-jmsclient]]
+=== Using `JmsClient`
+
 As of Spring Framework 4.1, `JmsMessagingTemplate` is built on top of `JmsTemplate`
-and provides an integration with the messaging abstraction -- that is,
-`org.springframework.messaging.Message`. This lets you create the message to
-send in a generic manner.
+and provides an integration with the Spring's common messaging abstraction -- that is,
+handling `org.springframework.messaging.Message` for sending and receiving,
+throwing `org.springframework.messaging.MessagingException` and with payload conversion
+going through `org.springframework.messaging.converter.MessageConverter` (with many
+common converter implementations available).
+
+As of Spring Framework 7.0, a fluent API called `JmsClient` is available. This provides
+customizable operations around `org.springframework.messaging.Message` and throwing
+`org.springframework.messaging.MessagingException`, similar to `JmsMessagingTemplate`,
+as well as integration with `org.springframework.messaging.converter.MessageConverter`.
+A `JmsClient can either be created for a given `ConnectionFactory` or for a given
+`JmsTemplate`, in the latter case reusing its settings by default. See
+{spring-framework-api}/jms/core/JmsClient.html[`JmsClient`] for usage examples.
 
 
 [[jms-connections]]
@@ -293,6 +313,3 @@ in an unmanaged environment, you can specify these values through the use of the
 properties `sessionTransacted` and `sessionAcknowledgeMode`. When you use a
 `PlatformTransactionManager` with `JmsTemplate`, the template is always given a
 transactional JMS `Session`.
-
-
-