diff --git a/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc b/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc index ddd9c43d2e8..1f19db89752 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc +++ b/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 diff --git a/framework-docs/modules/ROOT/pages/integration/jms/sending.adoc b/framework-docs/modules/ROOT/pages/integration/jms/sending.adoc index a5f479b0ea6..5ad13d40b18 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/sending.adoc +++ b/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 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. - - - diff --git a/framework-docs/modules/ROOT/pages/integration/jms/using.adoc b/framework-docs/modules/ROOT/pages/integration/jms/using.adoc index 01babeefac6..5e3247ef332 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/using.adoc +++ b/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`. - - -