Post process outgoing messages in JMS clients

Prior to this commit, the `JmsTemplate` would use `MessagePostProcessor`
for mutating JMS messages before they are being sent, but only if the
method takes a post processor as an argument.
The main use case so far is to mutate messages after they've been
created by a `MessageConverter` from a payload.

This commit updates the `JmsClient` to use `MessagePostProcessor` more
broadly, for all outgoing messages (converted or not). This brings an
interception-like mechanism for clients to enrich the message before
being sent.

This change also updates the `JmsClient` static factories and
introduces a Builder, allowing for more configuration options: multiple
message converters and message post processors.

Closes gh-35271

Author: bclozel

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

@@ -9,39 +9,7 @@ that takes no destination argument uses the default destination.
 The following example uses the `MessageCreator` callback to create a text message from the
 supplied `Session` object:
 
-[source,java,indent=0,subs="verbatim,quotes"]
-----
-	import jakarta.jms.ConnectionFactory;
-	import jakarta.jms.JMSException;
-	import jakarta.jms.Message;
-	import jakarta.jms.Queue;
-	import jakarta.jms.Session;
-
-	import org.springframework.jms.core.MessageCreator;
-	import org.springframework.jms.core.JmsTemplate;
-
-	public class JmsQueueSender {
-
-		private JmsTemplate jmsTemplate;
-		private Queue queue;
-
-		public void setConnectionFactory(ConnectionFactory cf) {
-			this.jmsTemplate = new JmsTemplate(cf);
-		}
-
-		public void setQueue(Queue queue) {
-			this.queue = queue;
-		}
-
-		public void simpleSend() {
-			this.jmsTemplate.send(this.queue, new MessageCreator() {
-				public Message createMessage(Session session) throws JMSException {
-					return session.createTextMessage("hello queue world");
-				}
-			});
-		}
-	}
-----
+include-code::./JmsQueueSender[]
 
 In the preceding example, the `JmsTemplate` is constructed by passing a reference to a
 `ConnectionFactory`. As an alternative, a zero-argument constructor and
@@ -84,21 +52,7 @@ gives you access to the message after it has been converted but before it is sen
 following example shows how to modify a message header and a property after a
 `java.util.Map` is converted to a message:
 
-[source,java,indent=0,subs="verbatim,quotes"]
-----
-	public void sendWithConversion() {
-		Map<String, String> map = new HashMap<>();
-		map.put("Name", "Mark");
-		map.put("Age", new Integer(47));
-		jmsTemplate.convertAndSend("testQueue", map, new MessagePostProcessor() {
-			public Message postProcessMessage(Message message) throws JMSException {
-				message.setIntProperty("AccountID", 1234);
-				message.setJMSCorrelationID("123-00001");
-				return message;
-			}
-		});
-	}
-----
+include-code::./JmsSenderWithConversion[]
 
 This results in a message of the following form:
 
@@ -126,32 +80,6 @@ to `jakarta.jms.TextMessage`, `jakarta.jms.BytesMessage`, etc. For a contract su
 generic message payloads, use `org.springframework.messaging.converter.MessageConverter`
 with `JmsMessagingTemplate` or preferably `JmsClient` as your central delegate instead.
 
-
-[[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`
 
@@ -160,3 +88,21 @@ 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.
+
+
+[[jms-sending-jmsclient]]
+== Sending a Message with `JmsClient`
+
+include-code::./JmsClientSample[]
+
+
+[[jms-sending-postprocessor]]
+== Post-processing outgoing messages
+
+Applications often need to intercept messages before they are sent out, for example to add message properties to all outgoing messages.
+The `org.springframework.messaging.core.MessagePostProcessor` based on the spring-messaging `Message` can do that,
+when configured on the `JmsClient`. It will be used for all outgoing messages sent with the `send` and `sendAndReceive` methods.
+
+Here is an example of an interceptor adding a "tenantId" property to all outgoing messages.
+
+include-code::./JmsClientWithPostProcessor[]

framework-docs/src/main/java/org/springframework/docs/integration/jms/jmssending/JmsQueueSender.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2002-2024 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.docs.integration.jms.jmssending;
+
+import jakarta.jms.ConnectionFactory;
+import jakarta.jms.JMSException;
+import jakarta.jms.Message;
+import jakarta.jms.Queue;
+import jakarta.jms.Session;
+
+import org.springframework.jms.core.MessageCreator;
+import org.springframework.jms.core.JmsTemplate;
+
+public class JmsQueueSender {
+
+	private JmsTemplate jmsTemplate;
+	private Queue queue;
+
+	public void setConnectionFactory(ConnectionFactory cf) {
+		this.jmsTemplate = new JmsTemplate(cf);
+	}
+
+	public void setQueue(Queue queue) {
+		this.queue = queue;
+	}
+
+	public void simpleSend() {
+		this.jmsTemplate.send(this.queue, new MessageCreator() {
+			public Message createMessage(Session session) throws JMSException {
+				return session.createTextMessage("hello queue world");
+			}
+		});
+	}
+}

framework-docs/src/main/java/org/springframework/docs/integration/jms/jmssendingconversion/JmsSenderWithConversion.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2002-2024 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.docs.integration.jms.jmssendingconversion;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import jakarta.jms.JMSException;
+import jakarta.jms.Message;
+
+import org.springframework.jms.core.JmsTemplate;
+import org.springframework.jms.core.MessagePostProcessor;
+
+public class JmsSenderWithConversion {
+
+	private JmsTemplate jmsTemplate;
+
+	public void sendWithConversion() {
+		Map<String, Object> map = new HashMap<>();
+		map.put("Name", "Mark");
+		map.put("Age", 47);
+		jmsTemplate.convertAndSend("testQueue", map, new MessagePostProcessor() {
+			public Message postProcessMessage(Message message) throws JMSException {
+				message.setIntProperty("AccountID", 1234);
+				message.setJMSCorrelationID("123-00001");
+				return message;
+			}
+		});
+	}
+
+}

framework-docs/src/main/java/org/springframework/docs/integration/jms/jmssendingjmsclient/JmsClientSample.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2002-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.docs.integration.jms.jmssendingjmsclient;
+
+import jakarta.jms.ConnectionFactory;
+
+import org.springframework.jms.core.JmsClient;
+import org.springframework.messaging.Message;
+import org.springframework.messaging.support.MessageBuilder;
+
+public class JmsClientSample {
+
+	private final JmsClient jmsClient;
+
+	public JmsClientSample(ConnectionFactory connectionFactory) {
+		// For custom options, use JmsClient.builder(ConnectionFactory)
+		this.jmsClient = JmsClient.create(connectionFactory);
+	}
+
+	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);
+	}
+}

framework-docs/src/main/java/org/springframework/docs/integration/jms/jmssendingpostprocessor/JmsClientWithPostProcessor.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2002-2024 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.docs.integration.jms.jmssendingpostprocessor;
+
+
+import jakarta.jms.ConnectionFactory;
+
+import org.springframework.jms.core.JmsClient;
+import org.springframework.messaging.Message;
+import org.springframework.messaging.core.MessagePostProcessor;
+import org.springframework.messaging.support.MessageBuilder;
+
+public class JmsClientWithPostProcessor {
+
+	private final JmsClient jmsClient;
+
+	public JmsClientWithPostProcessor(ConnectionFactory connectionFactory) {
+		this.jmsClient = JmsClient.builder(connectionFactory)
+				.messagePostProcessor(new TenantIdMessageInterceptor("42"))
+				.build();
+	}
+
+	public void sendWithPostProcessor() {
+		this.jmsClient.destination("myQueue")
+				.withTimeToLive(1000)
+				.send("myPayload");
+	}
+
+	static class TenantIdMessageInterceptor implements MessagePostProcessor {
+
+		private final String tenantId;
+
+		public TenantIdMessageInterceptor(String tenantId) {
+			this.tenantId = tenantId;
+		}
+
+		@Override
+		public Message<?> postProcessMessage(Message<?> message) {
+			return MessageBuilder.fromMessage(message)
+					.setHeader("tenantId", this.tenantId)
+					.build();
+		}
+	}
+}