A Guide to JmsClient in Spring Boot

1. Overview

Spring Framework 7.0 introduced JmsClient, a new fluent API for interacting with JMS destinations. It serves as a modern alternative to JmsTemplate, offering a cleaner way to send messages.

In this tutorial, we’ll build a simple application that sends messages via JmsClient and consumes them using a @JmsListener. Also, we’ll set up a custom MessageConverter to handle JSON serialization, and discuss testing strategies.

2. Sending Messages

For the code samples in this article, we assume we’re building the backend of a blogging website, similar to Baeldung. As the JMS broker, we use ActiveMQ Artemis.

Let’s start with a simple docker-compose.yml to spin it up locally:

services:
  activemq:
    image: apache/activemq-artemis:2.37.0
    container_name: activemq-artemis
    ports:
      - "61616:61616"   # JMS
      - "8161:8161"     # Web Console
    environment:
      - ARTEMIS_USER=admin
      - ARTEMIS_PASSWORD=admin

Then, we can add the spring-boot-starter-activemq dependency to pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-activemq</artifactId>
</dependency>

With this dependency in place, Spring Boot instantiates a JmsClient bean and adds it to the application context.

Let’s inject this client into one of the components and use it for sending messages to articles-queue:

@Component
class ArticlePublisher {

    private final JmsClient jmsClient;

    // constructor, logger

    public void publish(String title, String author) {
        var article = new Article(title, author);
        log.info("Publishing article: {}", article);

        jmsClient.destination("articles-queue")
          .send(article);
    }

    record Article(String title, String author) {
    }
}

Additionally, we configure the connection to the ActiveMQ Artemis broker in application.yml:

spring:
  artemis:
    mode: native
    broker-url: tcp://localhost:61616
    user: admin
    password: admin

Thus, we’re almost there! The last thing we need to configure is a way to serialize the message.

3. Message Converters

By default, Spring JMS uses a SimpleMessageConverter that handles String, byte[], and Map. To send POJOs – such as the Article record – as JSON, we register a custom MessageConverter.

The MessageConverter interface has two methods: one for converting a POJO into a JMS Message, and one for the reverse. In this implementation, we delegate both to Jackson’s JsonMapper:

@Component
class JsonMessageConverter implements MessageConverter {

    private final JsonMapper jsonMapper = JsonMapper.builder().build();

    @Override
    @SneakyThrows
    public Message toMessage(Object object, Session session) 
      throws JMSException, MessageConversionException {

        String json = jsonMapper.writeValueAsString(object);
        TextMessage msg = session.createTextMessage(json);
        msg.setStringProperty("_type", object.getClass().getName());
        return msg;
    }

    @Override
    @SneakyThrows
    public Object fromMessage(Message message) 
      throws JMSException, MessageConversionException {

        if (message instanceof TextMessage msg) {
            var clazz = Class.forName(msg.getStringProperty("_type"));
            return jsonMapper.readValue(msg.getText(), clazz);
        }
        throw new MessageConversionException("Message is not of type TextMessage");
    }
}

When we serialize the object to a JSON TextMessage, we also store the fully qualified class name in a _type property. During deserialization, we read the property back to reconstruct the correct type.

That’s it! Spring Boot detects the MessageConverter bean and automatically wires it into JmsTemplate, JmsClient, and the @JmsListener container.

4. Consuming Messages

At this point, Spring automatically performs several actions:

1. detects the @JmsListener annotation
2. creates a message listener container that connects to the broker
3. polls the queue
4. invokes the method for each incoming message, passing the deserialized POJO directly as the method argument

Let’s use this annotation to create an ArticleListener component and consume messages from the articles-queue:

@Component
class ArticleListener {

    private List<Article> receivedArticles = new CopyOnWriteArrayList<>();

    // getter, logger

    @JmsListener(destination = "articles-queue")
    void onArticleReceived(ArticlePublisher.Article article) {
        log.info("Received article: {}", article);
        receivedArticles.add(article);
    }
}

Finally, let’s tie everything together with an integration test. Specifically, we use Testcontainers to spin up a real ActiveMQ Artemis broker and verify the full flow – end to end:

@Testcontainers
@SpringBootTest(classes = SampleApplication.class)
class ArticleListenerLiveTest {

    @Container
    static ArtemisContainer activeMq = new ArtemisContainer(
      DockerImageName.parse("apache/activemq-artemis:2.37.0"))
        .withUser("admin")
        .withPassword("admin");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.artemis.broker-url", activeMq::getBrokerUrl);
    }

    @Autowired
    ArticlePublisher articlePublisher;

    @Autowired
    ArticleListener articleListener;

    @Test
    void shouldReceivePublishedArticle() {
        articlePublisher.publish("Foo", "John Doe");
        articlePublisher.publish("Bar", "Jane Doe");

        await().untilAsserted(() ->
          assertThat(articleListener.getReceivedArticles())
            .map(Article::title)
            .containsExactly("Foo", "Bar"));
    }
}

As we can see, the test uses ArticlePublisher to send two articles, then asserts that both are eventually received by ArticleListener.

5. Conclusion

In this article, we explored JmsClient, the new fluent API for sending JMS messages in Spring 7.0, and @JmsListener for consuming them.

In practice, we also covered how to wire in a custom MessageConverter to handle JSON serialization, and verified the full flow with a Testcontainers integration test.
As always, all the code samples can be found over on GitHub.