In previous posts, we discussed the new JdbcClient and RestClient which used to replace the existing JdbcTemplate and RestTemplate. We are all impressed by these developer-friendly APIs.

Spring 7 introduces JmsClient, a more modern and fluent API to interact with JMS(Jakarta Message Service) brokers, which is intended to replace the existing JmsTemplate and JmsMessagingTemplate.

Getting Started

Start by creating a Maven project and including the spring-core, spring-context, spring-context-support dependencies to provide the basic Spring container support.

Add the following dependencies to your pom.xml file:

// add spring core, context, context support dependencies if not already present
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jms</artifactId>
</dependency>

<dependency>
    <groupId>org.apache.activemq</groupId>
    <artifactId>artemis-jakarta-client</artifactId>
    <version>2.44.0</version>
</dependency>

Create a configuration class and declare a JMS ConnectionFactory, MessageConverter and JmsListenerContainerFactory bean to enable JMS support:

@Configuration
@EnableJms
public class JmsConfig{

    @Autowired
    Environment environment;

    @Bean
    public CachingConnectionFactory connectionFactory() {
        return new CachingConnectionFactory(
                new ActiveMQConnectionFactory(environment.getProperty("activemq.brokerUrl"), "user", "password")
        );
    }

    // The legacy messageconveter is from: org.springframework.jms.support.converter
    @Bean
    public MessageConverter messageConverter() {
        JacksonJsonMessageConverter messageConverter = new JacksonJsonMessageConverter();
        messageConverter.setTypeIdPropertyName("_type");
        return messageConverter;
    }

    @Bean
    public DefaultJmsListenerContainerFactory jmsListenerContainerFactory() {
        DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory();
        factory.setConnectionFactory(connectionFactory());
        factory.setMessageConverter(messageConverter());
        return factory;
    }
}

The MessageConverter bean here is used to convert between POJO objects and JMS messages.

Declare a JmsTemplate bean directly with the ConnectionFactory bean.

@Bean
public JmsTemplate jmsTemplate() {
    JmsTemplate jmsTemplate = new JmsTemplate(connectionFactory());
    jmsTemplate.setMessageConverter(messageConverter());
    return jmsTemplate;
}

With the messageConverter property set, you can use jmsTemplate to send a POJO object, as well as a text message.

Spring JMS also embraces the Spring Messaging abstraction, which provides a JmsMessagingTemplate which is based on Spring Messaging API.

Declare a JmsMessagingTemplate in the configuration class, and configure the messageConverter property with Spring Messaging specific MessageConverter.

// The spring messaging specific message converter is from org.springframework.messaging.
import org.springframework.messaging.converter.JacksonJsonMessageConverter;
import org.springframework.messaging.converter.MessageConverter;
//...

@Bean
public MessageConverter messagingMessageConverter() {
    return new JacksonJsonMessageConverter();
}

@Bean
public JmsMessagingTemplate jmsMessagingTemplate() {
    JmsMessagingTemplate jmsMessagingTemplate = new JmsMessagingTemplate(connectionFactory());
    jmsMessagingTemplate.setMessageConverter(messagingMessageConverter());
    return jmsMessagingTemplate;
}

You can create JmsClient from the existing ConnectionFactory bean or JmsOperations (eg. JmsTemplate) bean.

@Bean
public JmsClient jmsClient() {
    return JmsClient.create(jmsTemplate());
}

Alternatively, declare JmsClient with JmsClient.Builder to customize with a global MessageConverter and MessagePostProcessor.

public JmsClient jmsClient() {
    return JmsClient.builder(jmsTemplate())
        .messageConverter(...)
        .messagePostProcessor(...)
        .build();
}

Sending and Receiving Messages

To bootstrap an ActiveMQ Artimes server at runtime, add the following testcontainers dependencies in your pom.xml file:

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers-junit-jupiter</artifactId>
    <version>${testcontainers.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers-activemq</artifactId>
    <version>${testcontainers.version}</version>
    <scope>test</scope>
</dependency>

Create a ApplicationContextInitializer to start the Artimes container before Spring context is initialized:

class ArtemisContainerInitializer implements ApplicationContextInitializer<@NotNull ConfigurableApplicationContext> {
    private static final Logger log = LoggerFactory.getLogger(ArtemisContainerInitializer.class);
    final static String DOCKER_IMAGE_NAME = "apache/activemq-artemis:latest-alpine";
    final static Integer DEFAULT_EXPOSED_PORT = 61616;
    final ArtemisContainer container = new ArtemisContainer(DOCKER_IMAGE_NAME)
            .withUser("user")
            .withPassword("password")
            .withExposedPorts(DEFAULT_EXPOSED_PORT);


    @Override
    public void initialize(ConfigurableApplicationContext applicationContext) {
        container.start();
        applicationContext.addApplicationListener((e) -> {
            if (e instanceof ContextClosedEvent) {
                container.stop();
            }
        });

        var brokerUrlFormat = "tcp://%s:%d";
        var brokerUrl = brokerUrlFormat.formatted(container.getHost(), container.getFirstMappedPort());
        log.debug("connection url is {}", brokerUrl);

        applicationContext.getEnvironment()
                .getPropertySources()
                .addLast(
                        new MapPropertySource("activemqProps",
                                Map.of("activemq.brokerUrl", brokerUrl)
                        )
                );
    }
}

Create a test to verify sending and receiving messages with the classic JmsTemplate.

@SpringJUnitConfig(value = {JmsTemplateTest.TestConfig.class})
@ContextConfiguration(initializers = {ArtemisContainerInitializer.class})
public class JmsTemplateTest {
    private final static Logger log = LoggerFactory.getLogger(JmsTemplateTest.class);

    @Configuration
    @Import(value = {JmsConfig.class})
    static class TestConfig {
    }

    @Autowired
    JmsTemplate jmsTemplate;

    @Test
    public void testSendAndReceive() {
        jmsTemplate.convertAndSend("test", "hello");

        // wait to verify.
        await().atMost(Duration.ofMillis(1_500))
                .untilAsserted(() -> assertThat(jmsTemplate.receiveAndConvert("test")).isEqualTo("hello"));
    }

    @Test
    public void testSendAndReceive_GreetingObject() {
        jmsTemplate.convertAndSend("testObject", new Greeting("Hello", Instant.now()));

        // wait to verify.
        await().atMost(Duration.ofMillis(1_500))
                .untilAsserted(() -> {
                    Object receivedObject = jmsTemplate.receiveAndConvert("testObject");
                    log.debug("received object: {}", receivedObject);

                    var greetingObject = (Greeting) receivedObject;
                    assertThat(greetingObject.body()).isEqualTo("Hello");
                });
    }
}

Alternatively, you can send and receive messages with Spring Messaging specific JmsMessagingTemplate.

@Autowired
JmsMessagingTemplate jmsMessagingTemplate;

@Test
public void testSendAndReceive() {
    jmsMessagingTemplate.convertAndSend("test", "hello");

    // wait to verify.
    await().atMost(Duration.ofMillis(1_500))
            .untilAsserted(() -> assertThat(jmsMessagingTemplate.receiveAndConvert("test", String.class)).isEqualTo("hello"));
}

@Test
public void testSendAndReceive_GreetingObject() {
    jmsMessagingTemplate.convertAndSend("testObject", new Greeting("Hello JmsClient!", Instant.now()));

    // wait one second to verify.
    await().atMost(Duration.ofMillis(1_500))
            .untilAsserted(() -> {
                var receivedMessage = jmsMessagingTemplate.receiveAndConvert("testObject", Greeting.class);
                assertThat(receivedMessage).isNotNull();
                log.info("Greeting messages received via JmsMessagingTemplate: {}", receivedMessage);
                assertThat(receivedMessage.body()).isEqualTo("Hello JmsClient!");
            });
}

As you see, the jmsMessagingTemplate improved payload type resolves when receiving messages.

The following is the example testing code using the new JmsClient:

@Test
public void testSendAndReceive() {
    jmsClient.destination("test").send( "Hello");

    // wait to verify.
    await().atMost(Duration.ofMillis(1_500))
            .untilAsserted(() -> {
                Optional<String> received = jmsClient.destination("test").receive(String.class);
                assertThat(received.isPresent()).isTrue();

                log.debug("Received message: {}", received.get());
                assertThat(received.get()).isEqualTo("Hello");
            });
}

@Test
public void testSendAndReceive_GreetingObject() {
    jmsClient.destination("testObject")
            .withTimeToLive(2_000)
            .withReceiveTimeout(1_000)
            .withPriority(1)
            .withDeliveryDelay(100)
            .withDeliveryPersistent(false)
            .send(new Greeting("Hello JmsClient!", Instant.now()));

    // wait to verify.
    await().atMost(Duration.ofMillis(1_500))
            .untilAsserted(() -> {
                var received = jmsClient.destination("testObject")
                        .receive(Greeting.class);
                assertThat(received).isPresent();
                
                log.info("Greeting messages received: {}", received.get());
                assertThat(received.get().body()).isEqualTo("Hello JmsClient!");
            });
}

In the JmsClient example, the traditional method parameters are replaced with intuitive fluent methods. You can configure the destination properties using the withXXX methods before sending operations.

With jmsListenerContainerFactory bean, both JmsTemplate and JmsMessagingTamplate work well with the listener methods, which are annotated with @JmsListener. The new JmsClient also works seamlessly with the listener methods.

For example, create a GreetingListener to consume messages with a payload type Greeting.

@Component
public class GreetingListener {
    private final Logger log = LoggerFactory.getLogger(GreetingListener.class);

    public List<Greeting> received = new ArrayList<>();

    @JmsListener(destination = "greeting")
    public void onMessage(Greeting message) {
        log.debug("receiving body: {}", message);
        received.add(message);
    }
}

Use jmsClient to send a Greeting message to the destination greeting, then check the received messages in the GreetingListener.

@Autowired
JmsClient jmsClient;

@Autowired
GreetingListener receiver;

@Test
public void testGreetingListener() {
    jmsClient.destination("greeting").send(new Greeting("Hello", Instant.now()));

    // wait to verify.
    await().atMost(Duration.ofMillis(1_500))
            .untilAsserted(() -> {
                List<Greeting> received = receiver.received;
                log.debug(">>> received: {}", received);

                assertThat(received.size()).isEqualTo(1);
                assertThat(received.getFirst().body()).isEqualTo("Hello");
            });
}

Spring Boot

Generate your project skeleton from https://start.spring.io, add Spring for Apache ActiveMQ Artemis and Testcontainers in the Dependencies, it will include the following dependencies in your pom.xml to enable JMS autoconfiguration support with ActiveMQ Artemis.

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-artemis</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-artemis-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Additionally, it will add a Testcontainers configuration to start an Artemis server in Docker for development and test environments. The transitive dependency tree includes ativemq-artemis-client which is responsible for connecting to the running Artemis server.

Now you can inject JmsTempalate, JmsMessagingTemplate and JmsClient freely in your Spring components.

Add a JmsTemplate compatible MessageConverter to send and receive POJO messages.

// from org.springframework.jms.support.converter
@Bean
JacksonJsonMessageConverter jacksonMessageConverter() {
    JacksonJsonMessageConverter messageConverter = new JacksonJsonMessageConverter();
    messageConverter.setTypeIdPropertyName("_type");
    return messageConverter;
}

Do not forget to add spring-boot-starter-jackson and spring-boot-starter-jackson-test to the project dependencies to enable Jackson autoconfiguration.

Check the example code for demonstrating JmsTemplate, JmsMessagingTemplate, JmsClient, and all-in-one Spring Boot from my Github account.

An Introduction to Spring JmsClient API was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

Spring AMQP 4.0 brings a new module spring-rabbitmq-client which is based on the new RabbitMQ official Java client com.rabbitmq.client:amqp-client, which is aligned with AMQP 1.0 protocol. When using spring-rabbitmq-client in your projects, it is better to upgrade to RabbitMQ 4.0 to get native AMQP 1.0 support.

Note

AMQP 0.9.1 and AMQP 1.0 are two different protocols, and RabbitMQ 3.x supports both protocols, but enabling AMQP 1.0 support requires installing an extra plugin rabbitmq_amqp1_0, RabbitMQ 4.0 switches to use AMQP 1.0 as the core protocol by default. The previous Spring RabbitMQ module spring-rabbit is still based on AMQP 0.9.1 protocol. Spring AMQP 4.1 will introduce a new generic spring-amqp-client to implement AMQP 1.0 protocol, see: spring-amqp#3271

Getting Started

Create a new simple Maven project with the basic spring-core and spring-context as dependencies, or generate a simple Spring Boot project via https://start.spring.io as the previous post.

Note

To date, Spring Boot 4.0 does not include a starter for autoconfiguring the Spring RabbitMQ Client; you need to add the dependency and configuration manually.

Then add the following dependencies to your pom.xml file:

<dependencyManagement>
    <dependencies>
        ...
        <dependency>
            <groupId>org.springframework.amqp</groupId>
            <artifactId>spring-amqp-bom</artifactId>
            <version>${spring-amqp.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    ...
    <dependency>
        <groupId>org.springframework.amqp</groupId>
        <artifactId>spring-rabbitmq-client</artifactId>
    </dependency>
</dependencies>

Next let’s create a simple configuration class:

@Configuration
@EnableRabbit
public class RabbitClientConfig {

    @Value("${rabbitmq.port:5672}")
    private int port;

    @Bean
    Environment environment() {
        return new AmqpEnvironmentBuilder()
                .connectionSettings()
                .port(port)
                .environmentBuilder()
                .build();
    }

    @Bean
    AmqpConnectionFactory amqpConnectionFactory(Environment environment) {
        return new SingleAmqpConnectionFactory(environment);
    }

    @Bean
    RabbitAmqpAdmin rabbitAmqpAdmin(AmqpConnectionFactory connectionFactory) {
        return new RabbitAmqpAdmin(connectionFactory);
    }
    
    @Bean
    RabbitAmqpTemplate rabbitAmqpTemplate(AmqpConnectionFactory connectionFactory) {
        RabbitAmqpTemplate rabbitAmqpTemplate = new RabbitAmqpTemplate(connectionFactory);
        return rabbitAmqpTemplate;
    }

    @Bean(RabbitListenerAnnotationBeanPostProcessor.DEFAULT_RABBIT_LISTENER_CONTAINER_FACTORY_BEAN_NAME)
    RabbitAmqpListenerContainerFactory rabbitAmqpListenerContainerFactory(AmqpConnectionFactory connectionFactory) {
        RabbitAmqpListenerContainerFactory factory = new RabbitAmqpListenerContainerFactory(connectionFactory);
        return factory;
    }
}

In the above configuration class, we create the enssential beans, eg. AmqpConnectionFactory, RabbitAmqpAdmin, RabbitAmqpTemplate, and RabbitAmqpListenerContainerFactory for Spring RabbitMQ client. Make sure the Environment and AmqpEnvironmentBuilder is from package com.rabbitmq.client.amqp.

With RabbitAmqpAdmin, you can declare exchanges, queues, and bindings as usual:

public class RabbitClientConfig {
    public final static String HELLO_EXCHANGE_NAME = "e1";
    public final static String HELLO_QUEUE_NAME = "q1";
    public final static String HELLO_ROUTING_KEY = "k1";
    //...
    @Bean
    DirectExchange helloExchange() {
        return ExchangeBuilder
                .directExchange(HELLO_EXCHANGE_NAME)
                .durable(true)
                .build();
    }

    @Bean
    Queue helloQueue() {
        return QueueBuilder.durable(HELLO_QUEUE_NAME)
                .deadLetterExchange("dlx1")
                .build();
    }

    @Bean
    Binding helloBinding() {
        return BindingBuilder
                .bind(helloQueue())
                .to(helloExchange())
                .with(HELLO_ROUTING_KEY);
    }
}

To boostrap a RabbitMQ server at runtime, add the following testcontainers dependencies in your pom.xml:

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers-junit-jupiter</artifactId>
    <version>${testcontainers.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers-rabbitmq</artifactId>
    <version>${testcontainers.version}</version>
    <scope>test</scope>
</dependency>

Create a ApplicationContextInitializer to start the RabbitMQ container before Spring context is initialized:

class RabbitContainerInitializer implements ApplicationContextInitializer<@NotNull ConfigurableApplicationContext> {
    private static final Logger log = LoggerFactory.getLogger(RabbitContainerInitializer.class);
    final static String DOCKER_IMAGE_NAME = "rabbitmq:4-management-alpine";
    final RabbitMQContainer container = new RabbitMQContainer(DockerImageName.parse(DOCKER_IMAGE_NAME))
            .withExposedPorts(5672, 15672, 5552);

    @Override
    public void initialize(ConfigurableApplicationContext applicationContext) {
        container.start();
        applicationContext.addApplicationListener(e -> {
            if (e instanceof ContextClosedEvent) {
                container.stop();
            }
        });
        log.debug("RabbitMQ container exposed ports:" + container.getFirstMappedPort());
        applicationContext.getEnvironment()
                .getPropertySources()
                .addLast(
                        new MapPropertySource("rabbitProps",
                                Map.of("rabbitmq.port", container.getFirstMappedPort())
                        )
                );
    }
}

Note

Make sure you are using RabittMQ 4.x image to get AMQP 1.0 protocol support by default.

Now create a test to verify sending and receiving messages:

@SpringJUnitConfig(classes = {
        RabbitAmqpTemplateTest.TestConfig.class
})
@ContextConfiguration(initializers = {RabbitContainerInitializer.class})
public class RabbitAmqpTemplateTest {

    @Configuration
    @Import({RabbitClientConfig.class})
    static class TestConfig {
    }

    @Autowired
    RabbitAmqpTemplate rabbitAmqpTemplate;

    @Test
    void testSendAndReceive() throws Exception {
        assertThat(this.rabbitAmqpTemplate.convertAndSend(HELLO_EXCHANGE_NAME, HELLO_ROUTING_KEY, "test1"))
                .succeedsWithin(Duration.ofSeconds(10));

        assertThat(this.rabbitAmqpTemplate.receiveAndConvert(HELLO_QUEUE_NAME))
                .succeedsWithin(Duration.ofSeconds(10))
                .isEqualTo("test1");
    }
}

The RabbitAmqpTemplate imeplemnets AsyncAmqpTemplate, so all send and receive operations are asynchronous and return CompletableFuture.

The RabbitAmqpTempalte also supports RPC-style messaging via convertSendAndReceive method:

@Test
void verifyRpc() {
    String testRequest = "rpc-request";
    String testReply = "rpc-reply";

    CompletableFuture<Object> rpcClientResult = this.rabbitAmqpTemplate.convertSendAndReceive("e1", "k1", testRequest);

    AtomicReference<String> receivedRequest = new AtomicReference<>();
    CompletableFuture<Boolean> rpcServerResult =
            this.rabbitAmqpTemplate.<String, String>receiveAndReply("q1",
                    payload -> {
                        receivedRequest.set(payload);
                        return testReply;
                    });

    assertThat(rpcServerResult).succeedsWithin(Duration.ofSeconds(10)).isEqualTo(true);
    assertThat(rpcClientResult).succeedsWithin(Duration.ofSeconds(10)).isEqualTo(testReply);
    assertThat(receivedRequest.get()).isEqualTo(testRequest);
}

We have configured a listener container bean RabbitAmqpListenerContainerFactory in the configuration class, now you can use @RabbitListener to consume messages as usual:

@Component
class HelloListener {
    private static final Logger log = LoggerFactory.getLogger(HelloListener.class);
    final List<String> received = Collections.synchronizedList(new ArrayList<>());

    @RabbitListener(queues = {HELLO_QUEUE_NAME}, id = "testHelloListener")
    void processHello(String data) {
        log.debug(":: received data: [{}]", data);
        this.received.add(data);
    }
}

The HelloListener component will receive messages sent to the HELLO_QUEUE_NAME queue, and save them in the received list.

Let’s write a test to verify the listener works as expected:

@SpringJUnitConfig(classes = {
        HelloListenerContainerTest.TestConfig.class
})
@ContextConfiguration(initializers = {RabbitContainerInitializer.class})
public class HelloListenerContainerTest {
    private final Logger log = LoggerFactory.getLogger(HelloListenerContainerTest.class);

    @Configuration
    @Import({
            RabbitClientConfig.class,
            HelloListener.class
    })
    static class TestConfig {
    }

    @Autowired
    RabbitAmqpTemplate rabbitAmqpTemplate;

    @Autowired
    HelloListener listener;

    @Test
    void testHello() {
        log.debug("Start sending message...");
        var initialFuture = CompletableFuture.completedFuture(true);
        var words = List.of(
                "the",
                "quick",
                "dog",
                "jumped",
                "over",
                "the",
                "lazy",
                "fox");
        for (String word : words) {
            initialFuture = initialFuture
                    .thenComposeAsync(_ -> rabbitAmqpTemplate
                            .convertAndSend(HELLO_EXCHANGE_NAME, HELLO_ROUTING_KEY, word)
                            .whenComplete((res, ex) -> log.debug("sent: [{}]", word))
                    );
        }

        initialFuture.join();

        Awaitility.await().atMost(Duration.ofMillis(1_000))
                .untilAsserted(() -> {
                    List<String> received = this.listener.received;
                    log.debug(">>> ackListener received: {}", received);

                    Map<String, Long> wordCount = received.stream().collect(Collectors.groupingBy(Function.identity(), Collectors.counting()));
                    log.debug("word count: {}", wordCount);

                    assertThat(wordCount.get("the")).isEqualTo(2);
                });

    }
}

By default, the message is sent and acknowledged automatically. You can add fine-grained acknowledgement control in your listener method.

Manual Acknowledgement

You can set the @RabbitListener attribute ackMode to MANUAL, and customize the acknowledgement mode with listener method parameters: AmqpAcknowledgment and Consumer.Context.

@Component
class AckListener {
    private static final Logger log = LoggerFactory.getLogger(AckListener.class);
    final List<String> received = Collections.synchronizedList(new ArrayList<>());

    CountDownLatch consumeIsDone = new CountDownLatch(11);

    @RabbitListener(queues = {HELLO_QUEUE_NAME},
              ackMode = "#{T(org.springframework.amqp.core.AcknowledgeMode).MANUAL}",
            concurrency = "2",
            id = "testAmqpListener")
    void processAckManually(String data, AmqpAcknowledgment acknowledgment, Consumer.Context context) {
        log.debug(":: received data: [{}]", data);
        try {
            if ("discard".equals(data)) {
                if (!this.received.contains(data)) {
                    log.debug(":: ack with discard");
                    context.discard();
                } else {
                    log.debug(":: throw new MessageConversionException");
                    throw new MessageConversionException("Test message is rejected");
                }
            } else if ("requeue".equals(data) && !this.received.contains(data)) {
                log.debug(":: ack with requeue");
                acknowledgment.acknowledge(AmqpAcknowledgment.Status.REQUEUE);
            } else {
                log.debug(":: ack with accept");
                acknowledgment.acknowledge();
            }
            this.received.add(data);
            log.debug(":: current received:{}", this.received);
        } finally {
            this.consumeIsDone.countDown();
        }
    }
}

When the message payload is discard, the message is discarded without requeueing; when the payload is requeue, the message is requeued for redelivery; otherwise the message is accepted.

You can write a test to verify the manual acknowledgment works as expected:

@SpringJUnitConfig(classes = {
        AckListenerContainerTest.TestConfig.class
})
@ContextConfiguration(initializers = {RabbitContainerInitializer.class})
public class AckListenerContainerTest {
    private final Logger log = LoggerFactory.getLogger(AckListenerContainerTest.class);

    @Configuration
    @Import({
            RabbitClientConfig.class,
            AckListener.class
    })
    static class TestConfig {
    }

    @Autowired
    RabbitAmqpTemplate rabbitAmqpTemplate;

    @Autowired
    AckListener ackListener;

    @Test
    void testAck() {
        log.debug("Start sending message...");
        var initialFuture = CompletableFuture.completedFuture(true);
        var words = List.of(
                "the",
                "discard",
                "quick",
                "dog",
                "jumped",
                "over",
                "the",
                "requeue",
                "lazy",
                "discard",
                "fox");
        for (String word : words) {
            initialFuture = initialFuture
                    .thenComposeAsync(_ -> rabbitAmqpTemplate
                            .convertAndSend(HELLO_EXCHANGE_NAME, HELLO_ROUTING_KEY, word)
                            .whenComplete((res, ex) -> log.debug("sent: [{}]", word))
                    );
        }

        initialFuture.join();

        Awaitility.await().atMost(Duration.ofMillis(1_5000))
                .untilAsserted(() -> {
                    List<String> received = this.ackListener.received;
                    log.debug(">>> ackListener received: {}", received);

                    Map<String, Long> wordCount = received.stream().collect(Collectors.groupingBy(Function.identity(), Collectors.counting()));
                    log.debug("word count: {}", wordCount);

                    assertThat(wordCount.get("discard")).isEqualTo(1);
                    assertThat(wordCount.get("the")).isEqualTo(2);
                });

    }
}

The test similarly sends a list of words to the queue, and verifies that the discard message is only received once, and the second discard message is rejected and caused an exception.

Messaging Conversion

Finally, to use a POJO class as the message payload, you can configure a JSON message converter with Jackson to convert the message payload between JSON strings and type-safe objects.

Add the following dependencies to your pom.xml:

<dependencies>
    ...
    <dependency>
        <groupId>tools.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
</dependencies>

Then delcare a JsonMapper bean in your configuration class:

@Configuration(proxyBeanMethods = false)
class JacksonJsonMapperConfig {

    @Bean
    JsonMapper jacksonJsonMapper() {
        var builder = JsonMapper.builder();

        builder.changeDefaultPropertyInclusion(include -> include.withValueInclusion(JsonInclude.Include.NON_NULL))
                .disable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
                .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES,
                        DeserializationFeature.FAIL_ON_IGNORED_PROPERTIES)
                .enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
                .findAndAddModules();

        return builder.build();
    }
}

Then configure a JacksonJsonMessageConverter bean and set it to the RabbitAmqpTemplate:

public class RabbitClientConfig {
    //...
    @Bean
    public MessageConverter jsonMessageConverter(JsonMapper jsonMapper) {
        return new JacksonJsonMessageConverter(jsonMapper);
    }

    @Bean
    RabbitAmqpTemplate rabbitAmqpTemplate(AmqpConnectionFactory connectionFactory,
                                          MessageConverter jsonMessageConverter) {
        //...
        rabbitAmqpTemplate.setMessageConverter(jsonMessageConverter);
        return rabbitAmqpTemplate;
    }
}

Now create a simple record class to present the message payload:

public record Greeting(String body, Instant sentAt) {
}

Create a test to verify sending and receiving JSON messages:

@SpringJUnitConfig(classes = {
        RabbitAmqpTemplateTest.TestConfig.class
})
@ContextConfiguration(initializers = {RabbitContainerInitializer.class})
public class RabbitAmqpTemplateTest {

    @Configuration
    @Import({
            JacksonJsonMapperConfig.class,
            RabbitClientConfig.class
    })
    static class TestConfig {
    }

    @Autowired
    RabbitAmqpTemplate rabbitAmqpTemplate;

    @Test
    void testSendAndReceive_JSON() throws Exception {
        assertThat(this.rabbitAmqpTemplate.convertAndSend(HELLO_EXCHANGE_NAME, HELLO_ROUTING_KEY, new Greeting("test", Instant.now())))
                .succeedsWithin(Duration.ofSeconds(10));

        assertThat(this.rabbitAmqpTemplate.receiveAndConvert(HELLO_QUEUE_NAME, ParameterizedTypeReference.<Greeting>forType(Greeting.class)))
                .succeedsWithin(Duration.ofSeconds(10))
                .matches(it -> it.body().equals("test"));
    }
}

You can also create a listener to receive JSON messages:

@Component
class GreetingListener {
    private static final Logger log = LoggerFactory.getLogger(GreetingListener.class);
    final List<Greeting> received = new ArrayList<>();

    @RabbitListener(queues = RabbitClientConfig.HELLO_QUEUE_NAME,
            concurrency = "2",
            id = "helloListener",
            messageConverter = "jsonMessageConverter"
    )
    void handleGreeting(/*Message data*/ Greeting greeting) {
        log.info("Converted message payload: {}", greeting);
        received.add(greeting);
    }
}

In the @RabbitListener, you have to set the messageConverter attribute to refer to the JacksonJsonMessageConverter bean. Then the payload will be converted to a Greeting object and available for automatic injection as method parameters. Otherwise, you would have to use the generic Message object and manually extract the payload data.

Note

Unlike other rabbit listener containers, there is no messageConverter property in the RabbitAmqpListenerContainerFactory bean to apply the message conversion globally, see: spring-projects/spring-amqp#3274

Create a test to verify the JSON listener works as expected:

@SpringJUnitConfig(classes = {
        RabbitAmqpListenerContainerTest.TestConfig.class
})
@ContextConfiguration(initializers = {RabbitContainerInitializer.class})
public class RabbitAmqpListenerContainerTest {
    private final Logger log = LoggerFactory.getLogger(RabbitAmqpListenerContainerTest.class);

    @Configuration
    @Import({JacksonJsonMapperConfig.class,
            RabbitClientConfig.class,
            GreetingListener.class
    })
    static class TestConfig {
    }

    @Autowired
    RabbitAmqpTemplate rabbitAmqpTemplate;

    @Autowired
    GreetingListener greetingListener;

    @Test
    void testGreetingListener() {
        log.debug("Start sending message...");
        rabbitAmqpTemplate.convertAndSend(HELLO_EXCHANGE_NAME, HELLO_ROUTING_KEY, new Greeting("Hello", Instant.now()))
                .whenComplete((aBoolean, throwable) -> log.debug("Sending message is completed!!!"));

        Awaitility.await().atMost(Duration.ofMillis(1_000))
                .untilAsserted(() -> {
                    List<Greeting> received = greetingListener.received;
                    assertThat(received.size()).isEqualTo(1);
                    assertThat(received.getFirst().body()).isEqualTo("Hello");
                });
    }
}

Grab the example code from the spring7-sandbox/rabbit-client and spring7-sandbox/rabbit-client-json projects on GitHub.

An Introduction to New Spring RabbitMQ Client was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

Jackson is the defacto standard for JSON processing in Spring applications. With Spring 7 and Spring Boot 4, Jackson 3 is now the default — it modernizes the codebase for Java 17+ and also brings some breaking changes. Let’s walk through what changed and what you need to do when come to Spring 7 and Spring Boot 4.

Note

More details about the changes in Jackson 3, refer to the official Jackson 3 Release Notes and the Migration Guide.

If you’re migrating from Spring 6 to Spring 7, you’ll probably need to update your Jackson configuration — here’s one example of Jackson 2 configuration in Spring 6:

@Configuration
public class Jackson2ObjectMapperConfig {

    @Bean
    public ObjectMapper objectMapper() {

        var builder = Jackson2ObjectMapperBuilder.json();
        builder.serializationInclusion(JsonInclude.Include.NON_EMPTY);
        builder.featuresToDisable(
                SerializationFeature.WRITE_DATES_AS_TIMESTAMPS,
                SerializationFeature.FAIL_ON_EMPTY_BEANS,
                DeserializationFeature.FAIL_ON_IGNORED_PROPERTIES,
                DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
        builder.featuresToEnable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY);
        builder.modulesToInstall(JavaTimeModule.class)

        return builder.build();
    }
}

The above code can be replaced with the following code using Jackson 3 in Spring 7:

@Configuration(proxyBeanMethods = false)
class JacksonJsonMapperConfig {

    @Bean
    JsonMapper jacksonJsonMapper() {
        var builder = JsonMapper.builder();

        builder.changeDefaultPropertyInclusion(include -> include.withValueInclusion(JsonInclude.Include.NON_NULL))
                .disable(SerializationFeature.FAIL_ON_EMPTY_BEANS)
                .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES,
                        DeserializationFeature.FAIL_ON_IGNORED_PROPERTIES)
                .enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
                .findAndAddModules();

        return builder.build();
    }
}

A few notes on the example:

• In Spring 7 you’ll use the Jackson Builder to build up the configuration.
• Jackson 3 reworks ObjectMapper and introduces JsonMapper for JSON work. There are also specialized mappers like YamlMapper and XmlMapper for other formats.
• Dates and times are serialized as ISO‑8601 strings by default, so you don’t need to turn off WRITE_DATES_AS_TIMESTAMPS.

Note

Although Jackson 3 uses tools.jackson, it still shares the jackson-annotations module with Jackson 2, which uses the legacy namespace com.fasterxml.jackson. It looks odd, but this is intentional for backward compatibility.

Like the Jackson 2 Jackson2ObjectMapperBuilderCustomizer in Spring Boot 3.x, Spring Boot 4 gives you a JsonMapperBuilderCustomizer hook to tweak Jackson 3's configuration.

Let’s kick off a simple Spring Boot 4 project to try out Jackson 3.

Start a new project at Spring Initializr with these selections:

• Project: Maven
• Language: Java
• Spring Boot: 4.0.0
• Project Metadata/Java: 25
• Leave the other fields as-is.

Download and unzip the project, then open it in your favorite IDE.

Add spring-boot-starter-jackson and spring-boot-starter-jackson-test dependencies to your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jackson</artifactId>    
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jackson-test</artifactId>
    <scope>test</scope> 
</dependency>

The spring-boot-starter-jackson gives you a Jackson 3 JsonMapper with default settings. If you want to change those defaults, create a JsonMapperBuilderCustomizer bean.

@Bean
JsonMapperBuilderCustomizer jsonMapperBuilderCustomizer() {
    return builder -> builder
            .changeDefaultPropertyInclusion(value -> value.withContentInclusion(Include.NON_NULL))
            .enable(SerializationFeature.INDENT_OUTPUT)
            .build();
}

Alternatively, configure these settings in application.properties

spring.jackson.default-property-inclusion=non_null
spring.jackson.serialization.indent-output=true

The spring-boot-starter-jackson-test sets up a minimal JSON test context for use with @JsonTest. Inject JacksonTester into your tests to assert JSON serialization and deserialization.

Here’s a simple Person example class will be used in our tests.

record Person(
        String name,
        LocalDate birthDate,
        Gender gender
) {
}

enum Gender {
    MALE,
    FEMALE
}

@JacksonComponent
class CustomLocalDateSerializer {

    static DateTimeFormatter LOCAL_DATE_FORMAT = DateTimeFormatter.ofPattern("dd/MM/yyyy");

    static class LocalDateSerializer extends ValueSerializer<LocalDate> {

        @Override
        public void serialize(LocalDate value, JsonGenerator gen, SerializationContext ctxt) throws JacksonException {
            gen.writeString(value.format(LOCAL_DATE_FORMAT));
        }
    }

    static class LocalDateDeserializer extends ValueDeserializer<LocalDate> {

        @Override
        public LocalDate deserialize(JsonParser p, DeserializationContext ctxt) throws JacksonException {
            return LocalDate.parse(ctxt.readValue(p, String.class), LOCAL_DATE_FORMAT);
        }
    }
}

@JacksonMixin(Person.class)
record MyPerson(@JsonProperty("fullName") String name) {
}

The example defines a custom serializer and deserializer for LocalDate and a mixin that maps the name property to fullName in JSON.

Now let’s create a test class to verify serialization and deserialization of Person.

@JsonTest
class JacksonTests {
    private static final Logger log = LoggerFactory.getLogger(JacksonTests.class);

    @Autowired
    JacksonTester<Person> tester;

    @Autowired
    JsonMapper jsonMapper;

    @Test
    void testPersonSerialAndDeserial() throws IOException {
        var data = new Person(
                "Hantsy Bai",
                LocalDate.of(1970, 1, 1),
                Gender.MALE
        );

        var jsonData = jsonMapper.writeValueAsString(data);
        log.debug("serialized json string: {} ", jsonData);

        var testContents = tester.parse(jsonData);
        testContents.assertThat()
                .matches(person -> person.name().equals("Hantsy Bai"));
    }
}

The test serializes a Person to JSON string with JsonMapper, and parses it with JacksonTester, and then asserts the name property.

The subsequent test verifies that the mixin is applied during deserialization and that the name field is populated as expected.

@Test
void deserializedWithFullName() throws IOException {
    var jsonData = """
            {
                "fullName":"Hantsy Bai",
                "birthDate":"01/01/1970",
                "gender":"MALE"
            }
            """.trim();

    tester.parse(jsonData)
            .assertThat()
            .hasFieldOrProperty("name")
            .matches(person -> person.name().equals("Hantsy Bai"));

}

If you still need Jackson 2, that’s fine — add the Jackson 2 modules (jackson-module-parameter-names, jackson-datatype-jdk8, jackson-datatype-jsr310) and set spring.http.converters.preferred-json-mapper=jackson2 (Web MVC) or spring.http.codecs.preferred-json-mapper=jackson2 (WebFlux) to return back to use Jackson 2 for JSON serialization and deserialization.

One issue I encountered during the migration of my projects: Locale serialization changed. For example, Locale.CHINA used to serialize as zh_CN in Jackson 2 but is zh-CN in Jackson 3 — Jackson 3 now uses the LanguageTag format, so be aware of the difference when you parse or compare locale values.

Grab the complete example on GitHub: spring7-sandbox/boot-jackson.

An Introduction to Jackson 3 in Spring 7 and Spring Boot 4 was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

Before Spring Boot 4, Spring Boot provided JSON serialization and deserialization support via Jackson, Gson, and Jakarta JSON-B; these libraries were auto-configured and worked out of the box. Kotlinx Serialization JSON was an exception — Spring Boot did not provide comparable auto-configuration. Kotlinx Serialization was only enabled when Kotlin classes were annotated with @Serializable and the kotlinx-serialization-json dependency was present on the classpath. When Jackson and Kotlinx Serialization were both present, Spring Boot generally used Jackson as the default JSON processor; however, for certain types (for example, enums or collections of enums) processing could unexpectedly switch to Kotlinx Serialization (see: spring-boot#24238).

With Spring Boot 4, Kotlinx Serialization JSON is now a first-class citizen. As with Jackson, Gson, and Jakarta JSON-B, the modularized Spring Boot distribution provides a standalone starter spring-boot-starter-kotlinx-serialization-json. Including this starter in a Kotlin project causes Spring Boot to enable Kotlinx Serialization support and expose the kotlinx.serialization.json.Json bean with default settings.

Let’s create a simple Spring Boot 4 Kotlin project to demonstrate Kotlinx Serialization support.

Create a Spring Boot project via https://start.spring.io/ with the following options:

• Language: Kotlin
• Spring Boot: 4.0.1
• Project type: Maven
• Project metadata:
• Java version: 25
• Keep the other fields at their default values.

Generate the project, extract the downloaded ZIP, and import it into your IDE.

Next, add the spring-boot-starter-kotlinx-serialization-json and spring-boot-starter-kotlinx-serialization-json-test to your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-kotlinx-serialization-json</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-kotlinx-serialization-json-test</artifactId>
    <scope>test</scope>
</dependency>

The spring-boot-starter-kotlinx-serialization-json starter includes an auto-configuration class that registers a Json bean preconfigured with sensible defaults.

In your pom.xml, find the kotlin-maven-plugin and add the kotlinx-serialization plugin to its configuration section, then add the org.jetbrains.kotlin:kotlin-maven-serialization dependency to the plugin's dependencies section:

<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-maven-plugin</artifactId>
    <version>${kotlin.version}</version>
    <configuration>
        <compilerPlugins>
            ...
            <plugin>kotlinx-serialization</plugin>
        </compilerPlugins>
    </configuration>
    <dependencies>
        ...
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-serialization</artifactId>
            <version>${kotlin.version}</version>
        </dependency>
    </dependencies>
</plugin>

With this plugin, the Kotlin compiler processes @Serializable annotations at compile time.

Note

For Gradle users, refer to the Kotlinx Serialization documentation to configure the corresponding Gradle plugin.

Now, let’s create a simple data class annotated with @Serializable:

@Serializable
data class Message(val body: String)

Build the project (on Unix-like systems):

./mvnw clean compile

On Windows, use mvnw.cmd clean compile.

Check the compiled class for Message, open it in your IDE, or using javap command to see the contents:

@kotlinx.serialization.Serializable public final data class Message public constructor(body: kotlin.String) {
    public companion object {
        public final fun serializer(): kotlinx.serialization.KSerializer<com.example.demo.Message> { /* compiled code */ }
    }
    //...

    @kotlin.Deprecated public object `$serializer` : kotlinx.serialization.internal.GeneratedSerializer<com.example.demo.Message> {
        public final val descriptor: kotlinx.serialization.descriptors.SerialDescriptor /* compiled code */

        public final fun childSerializers(): kotlin.Array<kotlinx.serialization.KSerializer<*>> { /* compiled code */ }

        public final fun deserialize(decoder: kotlinx.serialization.encoding.Decoder): com.example.demo.Message { /* compiled code */ }\\

        public final fun serialize(encoder: kotlinx.serialization.encoding.Encoder, value: com.example.demo.Message): kotlin.Unit { /* compiled code */ }
    }
}

As shown, the Kotlin compiler generates a companion object with a serializer() method and a $serializer object that implements KSerializer. These artifacts handle serialization and deserialization for the Message class.

Next, let’s create a simple test to use Json bean to serialize and deserialize the Message class:

@SpringBootTest
class DemoApplicationTests {

    @Autowired
    lateinit var json: Json

    @Test
    fun testMessage() {
        val encodedMessage = json.encodeToString(Message("hello world"))
        println("encoded message: $encodedMessage")
        assertEquals(
            """
            {
                "body": "hello world"
            }
        """.trimIndent(),
            encodedMessage
        )

        val decodedMessage = json.decodeFromString<Message>(encodedMessage)
        println("decoded message: $decodedMessage")
    }
}

Spring Boot also provides a KotlinxSerializationJsonBuilderCustomizer interface to customize kotlinx.serialization.json.JsonBuilder, which is used to construct the Json bean.

For example, you can create a KotlinxSerializationJsonBuilderCustomizer bean like this:

@OptIn(ExperimentalSerializationApi::class)
@Configuration(proxyBeanMethods = false)
class CustomConfig {

    @Bean
    fun kotlinxSerializationJsonBuilderCustomizer(): KotlinxSerializationJsonBuilderCustomizer {
        return KotlinxSerializationJsonBuilderCustomizer { builder ->
            builder.apply {
                namingStrategy = JsonNamingStrategy.SnakeCase
                prettyPrint = true
                explicitNulls = false
                encodeDefaults = true
                ignoreUnknownKeys = false
            }
        }
    }

}

In this example, the Json bean is configured to use a snake_case naming strategy, enable pretty printing, and set other serialization options.

Alternatively, you can also set these properties via application.properties or application.yml:

spring.kotlinx.serialization.json.naming-strategy=snake_case
spring.kotlinx.serialization.json.pretty-print=true
spring.kotlinx.serialization.json.explicit-nulls=false
spring.kotlinx.serialization.json.encode-defaults=true
spring.kotlinx.serialization.json.ignore-unknown-keys=false

Note

All available configuration properties can be found in the KotlinxSerializationJsonProperties class.

Let’s have a look at another example.

@OptIn(ExperimentalSerializationApi::class)
@Serializable
data class Person(
    @JsonNames("full_name") val name: String,

    @Serializable(LocalDateSerializer::class)
    val birthDate: LocalDate,

    val gender: Gender = Gender.MALE
)

enum class Gender {
    MALE, FEMALE;
}

class LocalDateSerializer : KSerializer<LocalDate> {
    private val formatter = DateTimeFormatter.ISO_LOCAL_DATE

    override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("LocalDate", PrimitiveKind.STRING)
   
    override fun deserialize(decoder: Decoder): LocalDate {
        val string = decoder.decodeString()
        return LocalDate.parse(string, formatter)
    }

    override fun serialize(encoder: Encoder, value: LocalDate) {
        val result = value.format(formatter)
        encoder.encodeString(result)
    }
}

In this example we define a Person data class, the birthDate type is LocalDate, which is from the Java Date and Time API and not supported by Kotlinx Serialization. Here we create a custom LocalDateSerializer to overcome this issue. While @SerialName renames a property in the JSON output, @JsonNames("full_name") specifies alternative field names to accept during deserialization.

Note

Kotlinx Serialization is designed for Kotlin multiplatform, it has built-in support for Kotlin/kotlinx-datetime.

Create a test to verify Person serialization and deserialization:

@Test
fun testKotlinxSerializationJson() {
    val encodedPerson = json.encodeToString(Person("Hantsy Bai", LocalDate.of(1970, 1, 1)))
    println("encoded person: $encodedPerson")

    assertEquals(
        """
        {
            "name": "Hantsy Bai",
            "birth_date": "1970-01-01",
            "gender": "MALE"
        }
    """.trimIndent(), encodedPerson
    )

    val decodedPerson = json.decodeFromString<Person>(encodedPerson)
    println("decoded person: $decodedPerson")
    assertEquals(Gender.MALE, decodedPerson.gender)
}

The following test verifies deserialization when alternative field names are used and default values are applied:

@Test
fun testWithFullnameAndDefault() {

    val jsonPerson = """
         {
            "full_name": "Hantsy Bai",
            "birth_date": "1970-01-01"
        }
    """.trimIndent()

    val decodedPerson2 = json.decodeFromString<Person>(jsonPerson)
    println("decoded person: $decodedPerson2")
    assertEquals("Hantsy Bai", decodedPerson2.name)
    assertEquals(Gender.MALE, decodedPerson2.gender)
}

In this test we provide full_name instead of name and omit gender to verify that the default is applied during deserialization.

In Spring Boot 3.x Web MVC and WebFlux applications, mixing multiple JSON libraries sometimes required explicitly selecting the preferred mapper via spring.http.converters.preferred-json-mapper (for MVC) or spring.http.codecs.preferred-json-mapper (for WebFlux). Spring Boot 4's modular starters largely resolve these conflicts: unless the corresponding starter is present on the classpath, its auto-configuration will not be imported.

First-Class Kotlin Serialization Support in Spring Boot 4 was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

Prior to Spring Framework 7, beans could be registered programmatically in several ways — for example, by implementing BeanDefinitionRegistryPostProcessor or ImportBeanDefinitionRegistrar, or by manipulating the ApplicationContext directly.

A custom BeanDefinitionRegistryPostProcessor might look like this:

public class MyBeanRegistryPostProcessor implements BeanDefinitionRegistryPostProcessor {

    @Override
    public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException {
        BeanDefinitionBuilder postRepositoryBeanDef = BeanDefinitionBuilder.genericBeanDefinition(PostRepository.class);
        registry.registerBeanDefinition("posts", postRepositoryBeanDef.getBeanDefinition());
    }
}

This approach is somewhat verbose and requires familiarity with Spring internals.

Another example is to register beans directly with an AnnotationConfigApplicationContext which is introduced in Spring 5:

AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext();
PostRepository posts = new PostRepository();
PostHandler postHandler = new PostHandler(posts);
Routes routesBean = new Routes(postHandler);

context.registerBean(PostRepository.class, () -> posts);
context.registerBean(PostHandler.class, () -> postHandler);
context.registerBean(Routes.class, () -> routesBean);
context.registerBean(WebHandler.class, () -> RouterFunctions.toWebHandler(routesBean.routes(), HandlerStrategies.builder().build()));
context.refresh();

Here is the complete project of the above code snippet, see spring-reactive-sample/register-bean.

However, this technique also entails considerable boilerplate.

Spring Framework 7 introduces a more concise API for programmatic bean registration via a BeanRegistrar interface. For example, you might have two implementations of a PostRepository interface — one backed by R2DBC and another using an in-memory alternative.

The following example demonstrates conditional registration based on the active profile using BeanRegistrar:

class MyBeanRegistrar implements BeanRegistrar {

    @Override
    public void register(BeanRegistry registry, Environment env) {
        if (env.matchesProfiles("h2")) {
            // registry.registerBean(R2dbcConfig.class);
            registry.registerBean(
                    PostRepository.class,
                    (BeanRegistry.Spec<PostRepository> spec) -> spec
                            .supplier(ctx -> new H2PostRepository(ctx.bean(DatabaseClient.class)))
            );
        } else {
            registry.registerBean(
                    PostRepository.class,
                    (BeanRegistry.Spec<PostRepository> spec) -> spec
                            .supplier(ctx -> new InMemoryPostRepository())
            );
        }

        registry.registerBean(PostHandler.class,
                (BeanRegistry.Spec<PostHandler> spec) -> spec
                        .supplier(ctx -> new PostHandler(ctx.bean(PostRepository.class)))
        );

        registry.registerBean(Routes.class,
                (BeanRegistry.Spec<Routes> spec) -> spec
                        .supplier(ctx -> new Routes(ctx.bean(PostHandler.class))));

        registry.registerBean("webHandler", WebHandler.class,
                (BeanRegistry.Spec<WebHandler> spec) -> spec
                        .prototype()
                        .supplier(ctx -> RouterFunctions.toWebHandler(ctx.bean(Routes.class).routes(), HandlerStrategies.builder().build()))
        );
    }
}

Import this custom MyBeanRegistrar into a configuration class to activate it:

@Configuration
@Import(MyBeanRegistrar.class)
public class CustomConfig {
}

BeanRegistrar provides fine-grained control over bean registration, including scope (singleton, prototype, etc.), lazy initialization, and custom suppliers for instantiation. It is also compatible with native-image compilation using GraalVM.

Annotating the test class with @ActiveProfiles("h2") activates the h2 profile, causing the H2PostRepository implementation to be registered and injected.

@SpringJUnitConfig(classes = {CustomConfig.class, R2dbcConfig.class})
@ActiveProfiles("h2")
class H2ApplicationTest {

    @Autowired
    PostRepository postRepository;

    @Test
    void testPostRepository() {
        assertThat(this.postRepository).isInstanceOf(H2PostRepository.class);
    }

    @Test
    void testCurdOperations() {
        Post post = new Post(null, "Test Title", "Test Content");
        Mono<UUID> savedPostId = this.postRepository.save(post);

        savedPostId.flatMap(id -> this.postRepository.findById(id))
                .as(StepVerifier::create)
                .consumeNextWith(p -> {
                    assertThat(p.title()).isEqualTo("Test Title");
                    assertThat(p.content()).isEqualTo("Test Content");
                })
                .verifyComplete();

        savedPostId.flatMap(id ->
                        this.postRepository.update(id, new Post(null, "Updated Title", "Updated Content"))
                )
                .subscribe(updatedCount -> System.out.println("Updated rows: " + updatedCount));

        this.postRepository.findAll().subscribe(System.out::println);

        savedPostId.flatMap(id -> this.postRepository.deleteById(id))
                .subscribe(System.out::println);

        this.postRepository.findAll().subscribe(System.out::println);
    }
}

Elsewhere, the InMemoryPostRepository will be used instead.

@SpringJUnitConfig(CustomConfig.class)
class ApplicationTest {

    @Autowired
    PostRepository postRepository;

    @Test
    void testPostRepository() {
        assertThat(this.postRepository).isInstanceOf(InMemoryPostRepository.class);
    }
}

Spring 7 additionally offers BeanRegistrarDsl, a Kotlin extension that enables a more fluent registration style with Kotlin DSL.

Here is an example written in Kotlin and utilizing BeanRegistrarDsl:

@Configuration
@Import(MyBeanRegistrar::class)
class CustomConfig

class MyBeanRegistrar : BeanRegistrarDsl({
    registerBean { InMemoryPostRepository() }
    registerBean { PostHandler(bean()) }
    registerBean { Routes(bean()) }

    registerBean(
        name = "webHandler",
        backgroundInit = true,
        prototype = false,
        supplier = {
            RouterFunctions.toWebHandler(bean<Routes>().routes(), HandlerStrategies.builder().build())
        }
    )
    register(FoobarRegistrar())
})

class FoobarRegistrar : BeanRegistrarDsl({
    profile("foo") {
        registerBean<Bar> { Bar(bean<Foo>()) }
        registerBean { Foo() }
    }
})

class Bar(foo: Foo)
class Foo

See the repository examples for complete samples:

• https://github.com/hantsylabs/spring7-sandbox/tree/main/bean-registrar
• https://github.com/hantsylabs/spring7-sandbox/tree/main/bean-registrar-kotlin-dsl

Programmatic Bean Registration with BeanRegistrar was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

In a previous post — Integrating Jakarta Data with Spring — we discussed how to integrate Jakarta Data with the Spring Framework. In that post, we extracted Hibernate’s StatelessSession from Spring's LocalContainerEntityManagerFactoryBean and registered it as a Spring bean. That approach worked, but it didn't allow us to use Spring's transaction manager to control transactions. We also noted a few ad-hoc workarounds, for example, this gist and Vlad Mihalcea's writeup — How to integrate Jakarta Data with Spring and Hibernate.

In Spring 7, the long-awaited support for Hibernate’s StatelessSession (see issue spring-projects/spring-framework#7184) has been resovled finally. This means we can now use Spring's transaction manager to manage Jakarta Data transactions seamlessly.

The code snippets below target Spring 7.0 and Hibernate 7.2. See the complete example project at spring7-sandbox/hibernate-jakarta-data.

Add the following Hibernate configuration to your Spring project:

@Configuration
@EnableTransactionManagement
@PropertySource(value = "classpath:/hibernate.properties", ignoreResourceNotFound = true)
public class JakartaDataConfig {

    public static final Logger log = LoggerFactory.getLogger(JakartaDataConfig.class);

    private static final String ENV_HIBERNATE_DIALECT = "hibernate.dialect";
    private static final String ENV_HIBERNATE_HBM2DDL_AUTO = "hibernate.hbm2ddl.auto";
    private static final String ENV_HIBERNATE_SHOW_SQL = "hibernate.show_sql";
    private static final String ENV_HIBERNATE_FORMAT_SQL = "hibernate.format_sql";

    @Autowired
    Environment env;

    @Bean
    LocalSessionFactoryBean sessionFactoryBean(DataSource dataSource) {
        LocalSessionFactoryBean sessionFactory = new LocalSessionFactoryBean();
        sessionFactory.setDataSource(dataSource);
        sessionFactory.setPackagesToScan("com.example.demo");
        sessionFactory.setHibernateProperties(hibernateProperties());
        return sessionFactory;
    }

    private Properties hibernateProperties() {
        Properties extraProperties = new Properties();
        extraProperties.put(ENV_HIBERNATE_FORMAT_SQL, env.getProperty(ENV_HIBERNATE_FORMAT_SQL));
        extraProperties.put(ENV_HIBERNATE_SHOW_SQL, env.getProperty(ENV_HIBERNATE_SHOW_SQL));
        extraProperties.put(ENV_HIBERNATE_HBM2DDL_AUTO, env.getProperty(ENV_HIBERNATE_HBM2DDL_AUTO));

        if (env.getProperty(ENV_HIBERNATE_DIALECT) != null) {
            log.debug("Hibernate Dialect: {}", env.getProperty(ENV_HIBERNATE_DIALECT));
            extraProperties.put(ENV_HIBERNATE_DIALECT, env.getProperty(ENV_HIBERNATE_DIALECT));
        }

        return extraProperties;
    }

    @Bean
    public HibernateTransactionManager hibernateTransactionManager(SessionFactory sessionFactory) {
        return new HibernateTransactionManager(sessionFactory);
    }

}

In the configuration above we declare a LocalSessionFactoryBean and a HibernateTransactionManager, which is the same pattern used for standard Hibernate integration with Spring. Behind the scenes, LocalSessionFactoryBean provides both Session and StatelessSession. The @EnableTransactionManagement annotation together with HibernateTransactionManager enables Spring's transaction management support.

Now create a Jakarta Data repository interface as follows:

@jakarta.data.repository.Repository
@Transactional
public interface JakartaDataPostRepository {

    @Delete
    int deleteAll();

    @Save
    Post save(Post post);

    @Transactional(readOnly = true)
    @Find
    List<Post> findAll();

    @Transactional(readOnly = true)
    @Query("from Post p where p.title like :s and p.status=:status")
    List<Post> findByKeyword(@Param("s") String s, @Param("status") Status status, Limit limit);

    @Transactional(readOnly = true)
    @Find
    Optional<Post> findById(UUID id);
}

We add Jakarta Data’s @Repository to mark the interface as a repository and use Spring's @Transactional to enable transaction management. We do not extend any Jakarta Data base interface; instead we use Jakarta Data's lifecycle-aware annotations on the methods.

Note

Adding @Transactional at the repository interface level binds an active session to the current transaction. Alternatively, in a web application you can enable "Open Session In View" globally to keep the session open for the duration of the request.

When the interface is compiled, the generated implementation looks like this:

@Component
public class JakartaDataPostRepository_ implements JakartaDataPostRepository {
	/**
	 * @see #findByKeyword(String,Status,Limit)
	 **/
	static final String FIND_BY_KEYWORD_String_Status = "from Post p where p.title like :s and p.status=:status";

	protected ObjectProvider<StatelessSession> session;
	
	public JakartaDataPostRepository_(ObjectProvider<StatelessSession> session) {
		this.session = session;
	}
	
	public StatelessSession session() {
		return session.getObject();
	}
	
	@Override
	public Post save(Post post) {
		requireNonNull(post, "Null post");
		try {
			if (session.getObject().getIdentifier(post) == null)
				session.getObject().insert(post);
			else
				session.getObject().upsert(post);
		}
		catch (StaleStateException _ex) {
			throw new OptimisticLockingFailureException(_ex.getMessage(), _ex);
		}
		catch (PersistenceException _ex) {
			throw new DataException(_ex.getMessage(), _ex);
		}
		return post;
	}
//... other methods
}

The generated implementation JakartaDataPostRepository_ is annotated with Spring's @Component, so it will be discovered and registered as a bean. The StatelessSession is injected via Spring's ObjectProvider, which supplies the current active session.

Note

Don’t forget to add hibernate-processor to the compiler's annotation-processor path to enable code generation.

The following test uses Spring Test and Testcontainers to verify the integration:

@SpringJUnitConfig(classes = {
        JakartaDataPostRepositoryWithTestcontainersTest.TestConfig.class
})
@ContextConfiguration(initializers = PostgresContainerInitializer.class)
public class JakartaDataPostRepositoryWithTestcontainersTest {
    private final static Logger log = LoggerFactory.getLogger(JakartaDataPostRepositoryWithTestcontainersTest.class);

    @Autowired
    JakartaDataPostRepository posts;

    @BeforeEach
    public void setup() {
        var deleted = this.posts.deleteAll();
        log.debug("deleted posts: {}", deleted);
    }

    @Test
    public void testSaveAll() {
        var data = List.of(
                Post.of("test", "content", Status.PENDING_MODERATION),
                Post.of("test1", "content1", Status.DRAFT)
        );
        data.forEach(this.posts::save);

        var results = posts.findAll();
        assertThat(results.size()).isEqualTo(2);

        var resultsByKeyword = posts.findByKeyword("%", Status.PENDING_MODERATION, new Limit(10, 1));
        assertThat(resultsByKeyword.size()).isEqualTo(1);
    }

    @Test
    public void testInsertAndQuery() {
        var data = Post.of("test1", "content1", Status.DRAFT);
        var saved = this.posts.save(data);

        var byId = this.posts.findById(saved.getId());
        assertThat(byId.isPresent()).isTrue();

        var p = byId.get();
        assertThat(p.getStatus()).isEqualTo(Status.DRAFT);
    }

    @Configuration
    @ComponentScan(basePackageClasses = JakartaDataPostRepository.class)
    @Import({DataSourceConfig.class, JakartaDataConfig.class})
    static class TestConfig {
    }

}

In the test class we use @SpringJUnitConfig to load the Spring context and @ContextConfiguration to initialize the PostgreSQL Testcontainer. The tests verify the repository's basic CRUD operations.

For brevity we omitted the Post entity and the DataSourceConfig class, and we didn't list project dependencies. For the full example, see spring7-sandbox/hibernate-jakarta-data.

Integrating Jakarta Data with Spring: Rinse and Repeat was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

Jakarta Data is a new specification in Jakarta EE 11 that simplifies data access across different storage technologies. It is storage-agnostic — not limited to Jakarta Persistence or relational databases — and is designed so providers can adapt it to a variety of backends. The Eclipse JNoSQL project also implements this specification, bringing the same API surface to the NoSQL ecosystem.

Exploring Jakarta Data

Similar to Spring Data Commons, Micronaut Data, and Quarkus Panache, Jakarta Data introduces a Repository abstraction. This includes a basic DataRepository interface to indicate a repository, as well as two interfaces, BasicRepository and CrudRepository, which provide common CRUD operations for underlying data storage. It also introduces a new annotation, @Repository, to mark an interface as a repository, whether it is derived from the common interfaces or is a pure interface that does not extend any existing interface.

For example, the following PostRepository interface is for the entity Post.

@Repository
public interface PostRepository extends CrudRepository<Post, UUID> {
}

In addition, Jakarta Data supports derived queries by method name conventions, pagination, and custom queries using @Query annotations. If you have experience with Spring Data or Micronaut, you will be familiar with these features.

@Repository
public interface PostRepository extends CrudRepository<Post, UUID> {
    Optional<Post> findByTitle(String title);

    Page<Post> findByTitleLike(String titleLike, PageRequest pageRequest);

    @Query("where title like :title")
    @OrderBy("title")
    Post[] byTitleLike(@Param("title") String title);
}

Additionally, Jakarta Data provides a collection of lifecycle annotations (Find, Insert, Update, Delete) that allow you to write operation methods more freely in your own interfaces. The entity type can be determined from the method parameters or the return type.

@Repository
public interface Blogger {
    @Query("""
            SELECT p.id, p.title FROM Post AS p
            WHERE p.title LIKE :title
            ORDER BY p.createdAt DESC
            """)
    Page<PostSummary> allPosts(@Param("title") String title, PageRequest page);

    @Find
    @OrderBy("createdAt")
    List<Post> byStatus(Status status, Order<Post> order, Limit limit);

    @Find
    Optional<Post> byId(UUID id);

    @Insert
    Post insert(Post post);

    @Update
    Post update(Post post);

    @Delete
    void delete(Post post);
}

Currently, Quarkus and Micronaut have already integrated Jakarta Data as an alternative persistence solution for developers. I have written articles introducing the integration of Jakarta Data with Quarkus and Micronaut. Spring and Spring Data have no plans to integrate Jakarta Data, but that does not mean integrating Jakarta Data with Spring is difficult. I also wrote a post about integrating Hibernate Data Repositories with Spring.

Unlike Jakarta Persistence, Spring Data, and Micronaut Data, Jakarta Data 1.0 does not provide specific annotations to define entity types. As a result, it relies heavily on each provider’s implementation details. For example, Micronaut Data reuses Jakarta Persistence annotations as well as its own data annotations, both of which work seamlessly with Jakarta Data. Quarkus and WildFly integrate Jakarta Data via Hibernate Data repositories, so in these environments, Jakarta Persistence entities are used to represent Jakarta Data entities.

Currently, open-source Jakarta EE implementors such as GlassFish, WildFly, and Open Liberty are working on their own Jakarta Data implementations, typically leveraging entities defined with Jakarta Persistence. However, their approaches vary. WildFly (with Hibernate) translates Jakarta Data queries into Java code and generates repository implementations at compile time. In contrast, GlassFish reuses the effort from Eclipse JNoSQL and dynamically processes queries at runtime.

In this post, we’ll focus on demonstrating Jakarta Data features on standard Jakarta EE-compatible application servers, such as GlassFish, WildFly, and others.

You can get the example project from my GitHub and explore it yourself.

WildFly

WildFly has provided Jakarta Data as a preview feature since version 34. In the latest WildFly 37 preview, Jakarta Data support has been updated to align with Hibernate 7 and Jakarta Persistence 3.2.

To use Jakarta Data in WildFly, configure the hibernate-processor in your Maven compiler plugin. This processes your Repository interfaces and generates implementation classes at compile time.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>${maven-compiler-plugin.version}</version>
    <configuration>
        <annotationProcessorPaths>
            <annotationProcessorPath>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>${lombok.version}</version>
            </annotationProcessorPath>
            <annotationProcessorPath>
                <groupId>org.hibernate.orm</groupId>
                <artifactId>hibernate-processor</artifactId>
                <version>${hibernate.version}</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Open a terminal window, navigate to the project root folder, run the following command to compile the project. This will generate repository source code using the configured Hibernate Processor:

mvn clean compile -Pwildfly

The generated repository implementation classes use Hibernate’s StatelessSession to implement all methods. For example, the generated target/generated-sources/annotations/com/example/repository/PostRepository_.java file looks like this:

/**
 * Implements Jakarta Data repository {@link com.example.repository.PostRepository}
 **/
@Dependent
@Generated("org.hibernate.processor.HibernateProcessor")
public class PostRepository_ implements PostRepository {
    protected @Nonnull StatelessSession session;

    public PostRepository_(@Nonnull StatelessSession session) {
        this.session = session;
    }

    public @Nonnull StatelessSession session() {
        return session;
    }

    @PersistenceUnit
    private EntityManagerFactory sessionFactory;

    @PostConstruct
    private void openSession() {
        session = sessionFactory.unwrap(SessionFactory.class).openStatelessSession();
    }

    @PreDestroy
    private void closeSession() {
        session.close();
    }

    @Inject
    PostRepository_() {
    }

    //... other methods
    /**
     * Find {@link Post}.
     *
     * @see com.example.repository.PostRepository#findAll(PageRequest,Order)
     **/
    @Override
    public Page<Post> findAll(PageRequest pageRequest, Order<Post> sortBy) {
        var _builder = session.getCriteriaBuilder();
        var _query = _builder.createQuery(Post.class);
        var _entity = _query.from(Post.class);
        _query.where(
        );
        var _spec = SelectionSpecification.create(_query);
        for (var _sort : sortBy.sorts()) {
            _spec.sort(asc(Post.class, _sort.property())
                        .reversedIf(_sort.isDescending())
                        .ignoringCaseIf(_sort.ignoreCase()));
        }
        try {
            long _totalResults =
                    pageRequest.requestTotal()
                            ? _spec.createQuery(session)
                                    .getResultCount()
                            : -1;
            var _results = _spec.createQuery(session)
                .setFirstResult((int) (pageRequest.page()-1) * pageRequest.size())
                .setMaxResults(pageRequest.size())
                .getResultList();
            return new PageRecord<>(pageRequest, _results, _totalResults);
        }
        catch (PersistenceException _ex) {
            throw new DataException(_ex.getMessage(), _ex);
        }
    }
}

To run the project on a managed WildFly server, execute the following command:

mvn clean package wildfly:run -Pwildfly

You can find Jakarta Data usage examples in the testing codes.

The tests are written with Arquillian and JUnit 5, to run the tests on the managed WildFly with the Arquillian WildFly adapter:

mvn clean verify -Parq-wildfly-managed

GlassFish

Since GlassFish 8.0.0-M14, initial Jakarta Data support has been included. But unfortunately, I still encountered some issues running these examples on GlassFish.

Firstly, we used a query result projection to a Record class for Blogger.allPosts, which is a preview feature of the future Jakarta Data 1.1. It is not available in GlassFish. We have to change it to use an entity class in the return type or wrapped type.

@Repository
public interface Blogger {
    @Query("""
            SELECT p FROM Post AS p
            WHERE p.title LIKE :title
            ORDER BY p.createdAt DESC
            """)
    Page<Post> allPosts(@Param("title") String title, PageRequest page);
}

Unlike WildFly, which generates implementation code at compile time via the Hibernate processor, the Jakarta Data implementation on GlassFish is provided by the JNoSQL extension JNoSQL Jakarta Persistence, which handles Jakarta Data facilities at runtime.

To run the project on a managed GlassFish server, execute the following command:

mvn clean package cargo:run -Pglassfish

To run the integration tests on a managed GlassFish server with the Arquillian GlassFish adapter, execute the following command:

mvn clean verify -Parq-glassfish-managed

Note

Currently, several tests are still failing because some fixes from the upstream JNoSQL Jakarta Persistence project have not been applied to the GlassFish repository. I have created some GitHub issues for the GlassFish project to track future updates.

Meet Jakarta Data: The Newest Member of the Jakarta EE 11 Ecosystem was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

Jakarta Concurrency provides a standard API for managing concurrent tasks in Jakarta EE applications. It exposes managed executor services, thread factories, and context propagation helpers so that concurrent work runs with container-managed concurrency resources.

Jakarta Concurrency 3.1 introduces several notable improvements:

• Integration with Java 21 virtual threads
• Improved CDI support for injecting concurrency resources
• A new @Schedule annotation for task scheduling
• Java 9 Flow / Reactive Streams support

We covered virtual threads in an earlier post — Virtual Thread Support in Jakarta EE 11 — and showed how to define concurrency resources with CDI @Qualifiers so they can be injected like regular CDI beans.

In this post, we’ll skip those topics and focus on the new @Schedule annotation and the Reactive Streams support.

New @Schedule Annotation

Legacy task scheduling has long been tied to the EJB container. Porting EJB functionalities to CDI-compatible APIs has been a long-standing effort (see discussion). The new @Schedule annotation aims to replace the EJB scheduling annotation and provide a more portable, CDI-friendly mechanism.

The example below demonstrates a simple usage of @Schedule.

Suppose we need to notify team members about a recurring project meeting. The bean below uses @Schedule to trigger those notifications.

@ApplicationScoped
public class StandUpMeeting {
    private static final Logger LOGGER = Logger.getLogger(StandUpMeeting.class.getName());

    private static final Map<String, String> members = Map.of(
            "jack", "jack@example.com",
            "ross", "ross@example.com"
    );

    @Inject
    ManagedThreadFactory threadFactory;

    @Inject
    NotificationService notificationService;

    @PostConstruct
    public void init() {
        LOGGER.log(Level.ALL, "init from scheduled tasks...");
    }

    @Asynchronous(
            runAt = {
                    @Schedule(
                            daysOfWeek = {
                                    DayOfWeek.MONDAY,
                                    DayOfWeek.TUESDAY,
                                    DayOfWeek.WEDNESDAY,
                                    DayOfWeek.THURSDAY,
                                    DayOfWeek.FRIDAY
                            },
                            hours = 8
                    ), // daily standup
                    @Schedule(daysOfMonth = {1}, hours = {12}), // monthly meeting
                    @Schedule(cron = "*/5 * * * * *") // every 5 seconds (test)
            }
    )
    void sendInviteNotifications() {
        LOGGER.log(Level.ALL, "running scheduled tasks...");
        try (ForkJoinPool pool = new ForkJoinPool(
                Runtime.getRuntime().availableProcessors(),
                threadFactory,
                (t, e) -> LOGGER.log(Level.INFO, "Thread: {0}, error: {1}", new Object[]{t.getName(), e.getMessage()}),
                true
        )) {

            var callables = members.keySet().stream()
                    .map(
                            name -> (Callable<Void>) () -> {
                                LOGGER.info("calling invite:" + name);
                                notificationService.send(name, members.get(name));
                                return null;
                            }
                    )
                    .toList();

            var futures = pool.invokeAll(callables)
                    .stream()
                    .map(
                            r -> {
                                try {
                                    return CompletableFuture.completedFuture(r.get(100, TimeUnit.MILLISECONDS));
                                } catch (InterruptedException | ExecutionException | TimeoutException e) {
                                    throw new CompletionException(e);
                                }
                            }
                    )
                    .toList();

            var result = CompletableFuture.allOf(futures.toArray(CompletableFuture[]::new));
            result.join();
        }
    }
}

As you can see, the new @Schedule is currently declared inside the @Asynchronous(runAt = ...) attribute, which some developers find awkward.

The NotificationService below is a simple test service used in the example.

@ApplicationScoped
public class NotificationService {
    private static final Logger LOGGER = Logger.getLogger(NotificationService.class.getName());
    private final List<String> names = new CopyOnWriteArrayList<>();

    public void send(String name, String email) {
        LOGGER.log(Level.INFO, "sending invite to:[{0}] via {1}", new Object[]{name, email});
        this.names.add(name);
    }

    public List<String> getNames() {
        return Collections.unmodifiableList(names);
    }

}

Create a REST resource that triggers the scheduled tasks:

@RequestScoped
@Path("schedule")
public class ScheduleResources {

    @Inject
    NotificationService notificationService;

    @Inject
    StandUpMeeting meeting;

    @POST
    public Response invite() {
        meeting.sendInviteNotifications();
        return Response.ok().build();
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<String> getInvitedNames() {
        return notificationService.getNames();
    }
}

After deployment, you can trigger notifications with POST /schedule and view invited names with GET /schedule.

See the test ScheduleTest for a runnable example: ScheduleTest.

Unfortunately, the current @Schedule design has a few rough edges:

• It requires an external invocation to trigger scheduled tasks. That means it can not start automatically. see: jakartaee/concurrency#624
• It is expressed as a nested runAt attribute inside @Asynchronous, which some find unintuitive.
• Its attributes are not aligned with modern equivalents in frameworks such as Quarkus and Spring.
• There is no clear replacement for the legacy timeout callback pattern for handling schedule timeouts.

A cleaner, top-level scheduling annotation that adopts community best practices would be preferable. See the proposal for a standalone @Scheduled annotation: jakartaee/concurrency#684

Reactive Streams Support

Jakarta Concurrency 3.1 adds first-class support for the Java 9 Flow (Reactive Streams) API, making it easier to build asynchronous, back-pressured pipelines that interoperate with other reactive libraries.

The ContextService contains two helper methods such as contextualSubscriber and contextualProcessor. They are used to wrap standard Flow Subscriber and Processor implementations so they execute with proper Jakarta EE context propagation (CDI, JTA, Security).

The example below demonstrates these concepts with a simple chat application that uses CDI events and Server-Sent Events (SSE) to publish messages and Redis as a backing store. A contextual subscriber is used to asynchronously process and count messages.

First, define the sample subscriber — RequestCountSubscriber:

@ApplicationScoped
public class RequestCountSubscriber implements Flow.Subscriber<Long> {
    private Logger LOGGER = Logger.getLogger(RequestCountSubscriber.class.getName());
    final public static int MAX_REQUESTS = 2;

    Flow.Subscription subscription;
    int requestCount = 0;

    @Override
    public void onSubscribe(Flow.Subscription subscription) {
        LOGGER.info("onSubscribe:" + subscription);
        this.subscription = subscription;
        this.subscription.request(1);
        this.requestCount++;
    }

    @Override
    public void onNext(Long item) {
        LOGGER.info("onNext:" + item);
        if (requestCount % MAX_REQUESTS == 0) {
            this.subscription.request(MAX_REQUESTS);
        }
        requestCount++;
    }

    @Override
    public void onError(Throwable throwable) {
        LOGGER.info("onError:" + throwable.getMessage());
        this.subscription.cancel();
    }

    @Override
    public void onComplete() {
        LOGGER.log(Level.INFO, "onComplete: request count:{0}", new Object[]{this.requestCount});
    }
}

Next, create a REST resource to publish messages and subscribe the message via SSE:

@ApplicationScoped
@Path("chat")
public class ChatResource {

    @Inject
    ChatService chatService;

    @Context
    Sse sse;

    @PostConstruct
    public void init() {
        chatService.setSse(this.sse);
    }

    @GET
    @Produces(MediaType.SERVER_SENT_EVENTS)
    public void join(@Context SseEventSink sink) {
        var userId = UUID.randomUUID();
        chatService.register(userId, sink);
    }

    @DELETE
    @Path("{id}")
    public void quit(@PathParam("id") UUID id) {
        chatService.deregister(id);
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public void send(@Valid NewMessageCommand message) {
        chatService.send(ChatMessage.of(message.body()));
    }

    @GET
    @Path("sync")
    @Produces(MediaType.APPLICATION_JSON)
    public Response latestMessages() {
        return Response.ok(chatService.latest10Messages()).build();
    }

    @GET
    @Path("async")
    @Produces(MediaType.APPLICATION_JSON)
    public Response latestMessagesAsync() {
        return Response.ok(chatService.latest10MessagesFuture()).build();
    }

    @GET
    @Path("flow")
    @Produces(MediaType.APPLICATION_JSON)
    public Flow.Publisher<ChatMessage> latestMessagesFlow() {
        return chatService.latest10MessagesFlowPublisher();
    }
}

Finally, implement the ChatService to handle incoming messages, store them in Redis, and use the contextual subscriber to subscribe to them. It is also responsible for sending SSE events to connected clients.

@ApplicationScoped
public class ChatService {
    @Inject
    private ManagedExecutorService executor;

    @Inject
    private ContextService contextService;

    @Inject
    StatefulRedisConnection<String, String> redisConnection;

    @Inject
    Jsonb jsonb;

    @Inject
    Logger LOG;

    @Inject
    RequestCountSubscriber requestCountSubscriber;

    @Inject
    Event<ChatMessage> chatMessageEvent;

    private Sse sse;

    private final Map<UUID, SseEventSink> sinks = new ConcurrentHashMap<>();

    public void register(UUID id, SseEventSink request) {
        LOG.log(Level.FINEST, "register request:{0}", id);
        sinks.put(id, request);
    }

    public void deregister(UUID uuid) {
        LOG.log(Level.FINEST, "deregister request:{0}", uuid);
        SseEventSink eventSink = sinks.remove(uuid);
        try {
            eventSink.close();
            LOG.log(Level.FINEST, "closing sink: {0}", eventSink);
        } catch (Exception e) {
            throw new RuntimeException(e);
        } finally {
            LOG.log(Level.ALL, "closed SSE event sink");
        }
    }

    public void send(ChatMessage message) {
        RedisReactiveCommands<String, String> commands = redisConnection.reactive();
        commands.lpush("chat", jsonb.toJson(message))
                .doOnSuccess(
                        inserted -> {
                            LOG.log(Level.FINEST, "inserted items into redis:" + inserted);
                            chatMessageEvent.fire(message);
                        }
                )
                .subscribe(
                        FlowAdapters.toSubscriber(
                                contextService.contextualSubscriber(requestCountSubscriber)
                        )
                );
    }

    public void onMessage(@Observes ChatMessage msg) {
        sinks.values()
                .forEach(sink -> {
                            OutboundSseEvent outboundSseEvent = this.sse.newEventBuilder()
                                    .mediaType(MediaType.APPLICATION_JSON_TYPE)
                                    .id(UUID.randomUUID().toString())
                                    .name("message from cdi")
                                    .data(msg)
                                    .build();
                            sink.send(outboundSseEvent);
                        }
                );
    }

    public List<ChatMessage> latest10Messages() {
        RedisCommands<String, String> commands = redisConnection.sync();

        return commands.lpop("chat", 10)
                .stream()
                .map(it -> jsonb.fromJson(it, ChatMessage.class))
                .toList();
    }

    public CompletableFuture<List<ChatMessage>> latest10MessagesFuture() {
        RedisAsyncCommands<String, String> commands = redisConnection.async();

        return commands.lpop("chat", 10)
                .thenApplyAsync(
                        msg -> msg.stream()
                                .map(it -> jsonb.fromJson(it, ChatMessage.class))
                                .toList(),
                        executor
                )
                .toCompletableFuture();
    }

    public Flow.Publisher<ChatMessage> latest10MessagesFlowPublisher() {
        RedisReactiveCommands<String, String> commands = redisConnection.reactive();

        Flux<ChatMessage> messageFlux = commands.lpop("chat", 10)
                .map(it -> jsonb.fromJson(it, ChatMessage.class))
                .subscribeOn(Schedulers.fromExecutor(executor));

        return FlowAdapters.toFlowPublisher(messageFlux);
    }

    public void setSse(Sse sse) {
        this.sse = sse;
    }
}

The RedisConnection bean is defined as follows:

@ApplicationScoped
public class RedisClientProducer {
    private static final Logger LOGGER = Logger.getLogger(RedisClientProducer.class.getName());

    // Producer method for RedisClient
    @Produces
    @ApplicationScoped
    public RedisClient createRedisClient() {
        return RedisClient.create("redis://localhost:6379");
    }

    // Disposer method to close the RedisClient
    public void closeRedisClient(@Disposes RedisClient redisClient) {
        LOGGER.finest("shutdown redis client...");
        redisClient.shutdown();
    }

    @Produces
    @ApplicationScoped
    public StatefulRedisConnection<String, String> redisConnection(RedisClient redisClient) {
        return redisClient.connect();
    }

    public void closeConnection(@Disposes StatefulRedisConnection<String, String> redisConnection) {
        LOGGER.finest("closing redis connection...");
        redisConnection.close();
    }
}

The NewMessageCommand and ChatMessage classes are simple POJOs:

public record NewMessageCommand(
        @NotBlank String body
) {
}

public record ChatMessage(String body, LocalDateTime sentAt) {
    static ChatMessage of(String body) {
        return new ChatMessage(body, LocalDateTime.now());
    }
}

With this setup, messages sent to the chat service are stored in Redis and broadcast to connected clients via SSE. The RequestCountSubscriber processes messages asynchronously, demonstrating Jakarta Concurrency's Reactive Streams support.

After deployment, you can interact with the service using the REST endpoints: e.g., GET /chat to join a chat conversation and track the new messages via SSE, POST /chat to send new messages, and GET /chat/sync or GET /chat/async to retrieve the latest 10 messages.

Warning

Jakarta REST does not yet provide native Flow/Reactive Streams support, so GET /chat/flow may not work reliably on some application servers.

See the complete example in this test class: ChatResourceTest.

What’s New in Jakarta Concurrency 3.1? was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

The Jakarta Security specification offers a set of user-friendly APIs for managing authentication and authorization in Jakarta EE applications. It builds upon Jakarta Authentication and Jakarta Authorization, while providing developers with enhanced control and flexibility.

Version 4.0 brings several notable improvements, including:

• A standardized in-memory IdentityStore
• CDI qualifiers for built-in authentication mechanisms
• A handler for processing multiple authentication mechanisms

In-Memory IdentityStore

Earlier versions of the Jakarta Security implementation — Eclipse Soteria already included an in-memory identity store. With version 4.0, this feature is now officially standardized as part of the Jakarta Security specification.

Here’s how you can use the in-memory IdentityStore:

@InMemoryIdentityStoreDefinition(
    value = {
        @Credentials(callerName = "admin", password = "password", groups = {"web", "rest"}),
        @Credentials(callerName = "webuser", password = "password", groups = {"web"}),
        @Credentials(callerName = "restuser", password = "password", groups = {"rest"})
    }
)
@DeclareRoles({"web", "rest"})
@ApplicationScoped
public class SecurityConfig {
}

In this example, two roles — web and rest are defined, along with three users: admin, webuser, and restuser. All credentials are stored in memory.

Note

The in-memory IdentityStore is intended for testing only, as it keeps user credentials in memory. For production, it’s recommended to use a database-backed IdentityStore to securely persist user credentials.

CDI Qualifiers for Built-in Authentication Mechanisms

To enhance CDI integration, Jakarta Security 4.0 introduces a qualifiers attribute to the built-in XXXAuthenticationMechanismDefinition annotations. This allows you to identify authentication mechanism resources as CDI beans and inject them using custom qualifiers.

For example, if you want to use both the basic authentication mechanism and a custom form-based authentication mechanism in your CDI beans, start by creating two custom qualifiers: WebAuthenticationQualifier and RestAuthenticationQualifier.

// WebAuthenticationQualifier.java
@Documented
@Target({ElementType.TYPE, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public @interface WebAuthenticationQualifier {
}

// RestAuthenticationQualifier.java
@Documented
@Target({ElementType.TYPE, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public @interface RestAuthenticationQualifier {
}

Next, declare both @BasicAuthenticationMechanismDefinition and @CustomFormAuthenticationMechanismDefinition in your SecurityConfig class, setting the qualifiers attribute to the custom qualifiers you defined:

@BasicAuthenticationMechanismDefinition(
    realmName = "BasicAuth",
    qualifiers = {RestAuthenticationQualifier.class}
)
@CustomFormAuthenticationMechanismDefinition(
    loginToContinue = @LoginToContinue(
        loginPage = "/login.faces",
        errorPage = "/login.faces?error",
        useForwardToLogin = false // use redirect
    ),
    qualifiers = {WebAuthenticationQualifier.class}
)
// ...
@ApplicationScoped
public class SecurityConfig {
}

Now, you can inject the declared XXXAuthenticationMechanism as qualified CDI beans in your CDI beans:

@ApplicationScoped
public class MultipleHttpAuthenticationMechanismHandler implements HttpAuthenticationMechanismHandler {
    @Inject
    @RestAuthenticationQualifier
    private HttpAuthenticationMechanism restAuthenticationMechanism;

    @Inject
    @WebAuthenticationQualifier
    private HttpAuthenticationMechanism webAuthenticationMechanism;
    // ...
}

Handling Multiple Authentication Mechanisms

Previously, combining different authentication mechanisms in a Jakarta EE application was challenging using the Jakarta Security APIs. Version 4.0 introduces a new API, HttpAuthenticationMechanismHandler, which lets you handle incoming requests more flexibly.

@Alternative
@Priority(APPLICATION)
@ApplicationScoped
public class MultipleHttpAuthenticationMechanismHandler implements HttpAuthenticationMechanismHandler {
    private static final Logger LOGGER = Logger.getLogger(MultipleHttpAuthenticationMechanismHandler.class.getName());

    @Inject
    @RestAuthenticationQualifier
    private HttpAuthenticationMechanism restAuthenticationMechanism;

    @Inject
    @WebAuthenticationQualifier
    private HttpAuthenticationMechanism webAuthenticationMechanism;

    @Override
    public AuthenticationStatus validateRequest(HttpServletRequest request, HttpServletResponse response, HttpMessageContext httpMessageContext) throws AuthenticationException {
        String path = request.getRequestURI().substring(request.getContextPath().length());
        LOGGER.log(Level.INFO, "Request path (without context path): {0}", path);
        if (path.startsWith("/api")) {
            LOGGER.log(Level.INFO, "Handling authentication using RestAuthenticationQualifier HttpAuthenticationMechanism...");
            return restAuthenticationMechanism.validateRequest(request, response, httpMessageContext);
        }

        LOGGER.log(Level.INFO, "Handling authentication using WebAuthenticationQualifier HttpAuthenticationMechanism...");
        return webAuthenticationMechanism.validateRequest(request, response, httpMessageContext);
    }
}

In this example, authentication handling is delegated to the injected HttpAuthenticationMechanism instances. Basic authentication is applied to URIs starting with /api, while form-based authentication is used for other web pages.

The @Alternative annotation indicates that this bean is an alternative of the built-in bean HttpAuthenticationMechanismHandler provided by the Jakarta EE container, and can replace the existing one at runtime.

To activate the MultipleHttpAuthenticationMechanismHandler bean at runtime, you can use the @Priority(APPLICATION) annotation as shown above, or configure it in the CDI beans.xml file as follow:

<beans ...>
    <!-- ... -->
    <alternatives>
        <class>com.example.MultipleHttpAuthenticationMechanismHandler</class>
    </alternatives>
</beans>

Example Project

The example project demonstrates all the samples covered in this article and also includes additional code snippets, such as @Authenticated and @Authorized(roles), to illustrate real-world class and method level security protection.

To build and run the example project on GlassFish, use the following command:

mvn clean package cargo:run -Pglassfish

To test the web pages, open your browser and navigate to http://localhost:8080/security-examples/test-servlet.

You’ll be redirected to the /login page. After logging in with either webuser or admin (as defined earlier), you’ll be taken back to the protected page.

To verify that REST API protection works as expected, open a terminal and run:

curl -X GET http://localhost:8080/security-examples/api/hello

You should receive a 401 Unauthorized error.

Then, try with the predefined restuser/password credentials:

curl -X GET http://localhost:8080/security-examples/api/hello -u "restuser:password"

You should see a 200 status code and the response from the /hello endpoint.

The example project also includes a simple test written in JUnit 5 and Arquillian.

Open a terminal and run the following command to execute the test:

mvn clean verify -P"arq-glassfish-managed"

You can find the complete example project on my GitHub and explore the code locally.

What’s New in Jakarta Security 4.0? was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

Jakarta REST 4.0 is a major update in Jakarta EE 11, with much of the work focused on housekeeping. For example, there has been significant effort to modernize the Jakarta REST TCK. Additionally, support for the ManagedBean and JAXB specifications has been removed.

For developers, there are a few notable API changes:

• New convenient methods for checking a header value, especially which contains a token-separated list, including HttpHeaders#containsHeaderString, ClientRequestContext#containsHeaderString, ClientResponseContext#containsHeaderString, ContainerRequestContext#containsHeaderString, and ContainerResponseContext#containsHeaderString.
• A new method, UriInfo#getMatchedResourceTemplate, to retrieve the URI template for all paths of the current request.
• Added support for JSON Merge Patch.

The first two are minor improvements. Let’s take a closer look at JSON Merge Patch.

An Introduction to JSON Merge Patch

JSON Merge Patch is defined in RFC 7386 as follows:

This specification defines the JSON merge patch format and processing rules. The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of modifications to a target resource’s content.

Consider the following example JSON document:

{
    "title": "My second article",
    "author": {
        "givenName": "Hantsy",
        "familyName": "Bai"
    },
    "tags": ["second", "article"],
    "content": "The content of my second article"
}

Suppose you want to update the tags to "JAX-RS", "RESTEasy", "Jersey" and change the author to "Jack", "Ma". You would send a request like this:

PATCH /articles/2 HTTP/1.1
Host: localhost
Content-Type: application/merge-patch+json

{
    "author": {
        "givenName": "Jack",
        "familyName": "Ma"
    },
    "tags": ["JAX-RS", "RESTEasy", "Jersey"]
}

The resulting JSON document would be:

{
    "title": "My second article",
    "author": {
        "givenName": "Jack",
        "familyName": "Ma"
    },
    "tags": ["JAX-RS", "RESTEasy", "Jersey"],
    "content": "The content of my second article"
}

Let’s walk through a simple REST resource example to demonstrate this process in code.

Example Project

Assume we need to manage a collection of articles, represented by an Article class:

// Article.java
public record Article(
        Integer id,
        String title,
        Author author,
        String content,
        List<String> tags,
        LocalDateTime publishedAt
) {
    public Article withId(int id) {
        return new Article(id, title, author, content, tags, publishedAt);
    }

    public Article withTags(List<String> tags) {
        return new Article(id, title, author, content, tags, publishedAt);
    }

    public Article withAuthor(Author author) {
        return new Article(id, title, author, content, tags, publishedAt);
    }
}

// Author.java
public record Author(String givenName, String familyName) {
}

As mentioned in Java SE Record support in Jakarta EE 11, although JSON-B did not fully align with Record support in Jakarta EE 11, Eclipse Yasson already supports serialization and deserialization of records.

The ArticleRepository is a simple in-memory repository:

@ApplicationScoped
public class ArticleRepository {
    private static final ConcurrentHashMap<Integer, Article> articles = new ConcurrentHashMap<>();
    private static final AtomicInteger ID_GEN = new AtomicInteger(1);

    static {
        var id1 = ID_GEN.getAndIncrement();
        articles.put(
            id1,
            new Article(id1, "My first article",
                new Author("Hantsy", "Bai"),
                "This is my first article",
                List.of("first", "article"),
                LocalDateTime.now())
        );
        var id2 = ID_GEN.getAndIncrement();
        articles.put(id2,
            new Article(id2, "My second article",
                new Author("Hantsy", "Bai"),
                "This is my second article",
                List.of("second", "article"),
                LocalDateTime.now())
        );
    }

    public List<Article> findAll() {
        return List.copyOf(articles.values());
    }

    public Article findById(int id) {
        return articles.get(id);
    }

    public Article save(Article article) {
        if (article.id() == null) {
            var id = ID_GEN.getAndIncrement();
            article = article.withId(id);
        }
        articles.put(article.id(), article);
        return article;
    }
}

Now, let’s look at the ArticleResource:

@Path("articles")
@RequestScoped
public class ArticleResource {

    @Inject
    ArticleRepository repository;

    Jsonb jsonb;

    @PostConstruct
    public void init() {
        jsonb = JsonbBuilder.create();
    }

    @GET
    public Response getArticles() {
        return Response.ok(repository.findAll()).build();
    }

    @GET
    @Path("{id}")
    public Response getArticle(@PathParam("id") Integer id) {
        return Response.ok(repository.findById(id)).build();
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public Response createArticle(Article article) {
        var saved = repository.save(article);
        return Response.created(URI.create("/articles/" + saved.id())).build();
    }

    @PATCH
    @Consumes(MediaType.APPLICATION_JSON_PATCH_JSON)
    public Response saveOrUpdateAllArticles(JsonArray patch) {
        var all = repository.findAll();
        var result = Json.createPatch(patch)
            .apply(Json.createReader(new StringReader(jsonb.toJson(all))).readArray());
        List<Article> articles = jsonb.fromJson(
            jsonb.toJson(result),
            new ArrayList<Article>() {}.getClass().getGenericSuperclass()
        );
        articles.forEach(repository::save);

        return Response.noContent().build();
    }

    @PATCH
    @Path("{id}")
    @Consumes(MediaType.APPLICATION_JSON_PATCH_JSON)
    public Response updateArticle(@PathParam("id") Integer id, JsonArray patch) {
        var target = repository.findById(id);
        var patchedResult = Json.createPatch(patch)
            .apply(Json.createReader(new StringReader(jsonb.toJson(target))).readObject());
        var article = jsonb.fromJson(jsonb.toJson(patchedResult), Article.class);
        repository.save(article);

        return Response.noContent().build();
    }

    @PATCH
    @Path("{id}")
    //@Consumes(MediaType.APPLICATION_MERGE_PATCH_JSON) // added in 4.0
    @Consumes("application/merge-patch+json")
    public Response mergeArticle(@PathParam("id") Integer id, JsonObject patch) {
        var targetArticle = repository.findById(id);
        var mergedResult = Json.createMergePatch(patch)
            .apply(Json.createReader(new StringReader(jsonb.toJson(targetArticle))).readObject());
        var article = jsonb.fromJson(jsonb.toJson(mergedResult), Article.class);
        repository.save(article);

        return Response.noContent().build();
    }
}

For comparison, we also include two JSON Patch (defined by RFC 6902 and implemented in Java EE 8/JAX-RS 2.1) example endpoints: one for processing an array of operations, and another for handling a single resource entity.

Let’s create an Arquillian test to verify the functionality:

@ExtendWith(ArquillianExtension.class)
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
public class ArticleResourceTest {

    private static final Logger LOGGER = Logger.getLogger(ArticleResourceTest.class.getName());

    @Deployment(testable = false)
    public static WebArchive createDeployment() {
        File[] extraJars = Maven
            .resolver()
            .loadPomFromFile("pom.xml")
            .importCompileAndRuntimeDependencies()
            .resolve("org.assertj:assertj-core")
            .withTransitivity()
            .asFile();
        var war = ShrinkWrap.create(WebArchive.class, "test.war")
            .addAsLibraries(extraJars)
            .addClasses(
                ArticleResource.class,
                Article.class,
                Author.class,
                ArticleRepository.class,
                // jaxrs config
                JsonbContextResolver.class,
                RestActivator.class
            )
            .addAsWebInfResource(EmptyAsset.INSTANCE, "beans.xml");
        LOGGER.log(Level.INFO, "war deployment: {0}", war.toString(true));
        return war;
    }

    @ArquillianResource
    private URL baseUrl;

    Client client;

    private Jsonb jsonb = JsonbBuilder.create();

    @BeforeEach
    public void before() {
        LOGGER.log(Level.INFO, "baseURL: {0}", baseUrl.toExternalForm());
        client = ClientBuilder.newClient();
        client.register(JsonbContextResolver.class);
    }

    @AfterEach
    public void after() {
        client.close();
    }

    @Test
    @RunAsClient
    @Order(1)
    public void testGetArticles() {
        var target = client.target(URI.create(baseUrl.toExternalForm() + "api/articles"));
        List<Article> articleList;
        try (Response r = target.request().accept(MediaType.APPLICATION_JSON_TYPE).get()) {
            LOGGER.log(Level.INFO, "Get response status: {0}", r.getStatus());
            assertEquals(200, r.getStatus());
            articleList = r.readEntity(new GenericType<>() {});
            LOGGER.log(Level.INFO, "all articles: {0}", articleList);
            assertThat(articleList.size()).isEqualTo(2);
        }

        // Apply JSON Patch
        var patch = Json.createPatchBuilder()
            .replace("/1/content", "Updated by JsonPatch")
            .remove("/1/author/familyName")
            .add("/1/tags/1", "JAX-RS")
            .build().toJsonArray();

        var target2 = client
            .property(HttpUrlConnectorProvider.SET_METHOD_WORKAROUND, true)
            .target(URI.create(baseUrl.toExternalForm() + "api/articles"));
        try (Response r2 = target2
            .request()
            .method("PATCH", Entity.entity(patch, MediaType.APPLICATION_JSON_PATCH_JSON_TYPE))) {
            LOGGER.log(Level.INFO, "patch response status: {0}", r2.getStatus());
            assertEquals(204, r2.getStatus());
        }

        // Verify the patched result
        try (Response r = target.request().accept(MediaType.APPLICATION_JSON_TYPE).get()) {
            LOGGER.log(Level.INFO, "Get response status after applying patch: {0}", r.getStatus());
            assertEquals(200, r.getStatus());
            articleList = r.readEntity(new GenericType<>() {});
            LOGGER.log(Level.INFO, "all articles after applying patch: {0}", articleList);
            assertThat(articleList.size()).isEqualTo(2);
        }
    }

    @Test
    @RunAsClient
    @Order(2)
    public void testGetArticleById() {
        var target = client.target(URI.create(baseUrl.toExternalForm() + "api/articles/1"));
        try (Response r = target.request().accept(MediaType.APPLICATION_JSON_TYPE).get()) {
            LOGGER.log(Level.INFO, "Get response status: {0}", r.getStatus());
            assertEquals(200, r.getStatus());
            Article article = r.readEntity(Article.class);
            LOGGER.log(Level.INFO, "get article by id: {0}", article);
            assertThat(article.title()).isEqualTo("My first article");
        }

        var patch = Json.createPatchBuilder()
            .replace("/title", "My title updated by JsonPatch")
            .build().toJsonArray();

        var target2 = client
            .property(HttpUrlConnectorProvider.SET_METHOD_WORKAROUND, true)
            .target(URI.create(baseUrl.toExternalForm() + "api/articles/1"));
        try (Response r2 = target2
            .request()
            .method("PATCH", Entity.entity(patch, MediaType.APPLICATION_JSON_PATCH_JSON_TYPE))) {
            LOGGER.log(Level.INFO, "patch response status: {0}", r2.getStatus());
            assertEquals(204, r2.getStatus());
        }

        // Verify the patched result
        try (Response r = target.request().accept(MediaType.APPLICATION_JSON_TYPE).get()) {
            LOGGER.log(Level.INFO, "Get response status after applying patch: {0}", r.getStatus());
            assertEquals(200, r.getStatus());
            Article article = r.readEntity(Article.class);
            LOGGER.log(Level.INFO, "get article by id after applying patch: {0}", article);
            assertThat(article.title()).isEqualTo("My title updated by JsonPatch");
        }
    }

    @Test
    @RunAsClient
    @Order(3)
    public void testGetArticleByIdAndMergePatch() {
        var target = client.target(URI.create(baseUrl.toExternalForm() + "api/articles/2"));
        Article article = null;
        try (Response r = target.request().accept(MediaType.APPLICATION_JSON_TYPE).get()) {
            LOGGER.log(Level.INFO, "Get response status: {0}", r.getStatus());
            assertEquals(200, r.getStatus());
            article = r.readEntity(Article.class);
            LOGGER.log(Level.INFO, "get article by id: {0}", article);
            assertThat(article.title()).isEqualTo("My second article");
        }

        var updated = article.withTags(List.of("JAX-RS", "RESTEasy", "Jersey"))
            .withAuthor(new Author("Jack", "Ma"));
        var patch = Json.createMergeDiff(
            Json.createReader(new StringReader(jsonb.toJson(article))).readObject(),
            Json.createReader(new StringReader(jsonb.toJson(updated))).readObject()
        ).toJsonValue();

        var target2 = client
            .property(HttpUrlConnectorProvider.SET_METHOD_WORKAROUND, true)
            .target(URI.create(baseUrl.toExternalForm() + "api/articles/2"));
        try (Response r2 = target2
            .request()
            .method("PATCH", Entity.entity(patch, "application/merge-patch+json"))) {
            LOGGER.log(Level.INFO, "patch response status: {0}", r2.getStatus());
            assertEquals(204, r2.getStatus());
        }

        // Verify the patched result
        try (Response r = target.request().accept(MediaType.APPLICATION_JSON_TYPE).get()) {
            LOGGER.log(Level.INFO, "Get response status after applying patch: {0}", r.getStatus());
            assertEquals(200, r.getStatus());
            article = r.readEntity(Article.class);
            LOGGER.log(Level.INFO, "get article by id after applying patch: {0}", article);
            assertThat(article.title()).isEqualTo("My second article");
            assertThat(article.tags()).isEqualTo(List.of("JAX-RS", "RESTEasy", "Jersey"));
            assertThat(article.author()).isEqualTo(new Author("Jack", "Ma"));
        }
    }
}

In the above test:

• The deployment is marked as testable, meaning the test runs as a client and interacts with the service deployed in the test archive.
• After deployment, the @ArquillianResource-annotated URL provides the application's base URL, including the ApplicationPath defined in the Application class, ending with a /.
• We set .property(HttpUrlConnectorProvider.SET_METHOD_WORKAROUND, true) to ensure the custom PATCH method works correctly with the current Jakarta REST Client API.

Let’s focus on the testGetArticleByIdAndMergePatch test method, which demonstrates the JSON Merge Patch functionality:

• First, retrieve the resource.
• Modify it and use Json.createMergeDiff to create a patch JsonObject.
• Apply the patch to the remote resource.
• Finally, retrieve the resource again to verify that the patch was applied successfully.

Warning

The Jakarta REST Client API does not provide a patch() method, similar to the existing get() or post(). See the related discussion: jakartaee/rest#1276.

Get the complete example project from my GitHub repository.

Final Thoughts

Over the past decade, I have developed many backend RESTful API applications. However, I have noticed a growing trend: more customers are choosing Spring WebMvc or WebFlux as their preferred frameworks over Jakarta REST. While libraries and frameworks like RESTEasy and Quarkus help fill some gaps, Jakarta REST itself has evolved slowly. Features like JSON Patch and the new JSON Merge Patch introduced in this version are rarely used in real-world RESTful API development. Even Spring once incubated a project called Spring Sync to address similar needs, but it has since been abandoned.

In my view, since version 2.1, Jakarta REST has not delivered significant features that boost developer productivity. The following is my wishlist for the next generation of Jakarta REST.

• Deprecating Resource/Context injection in favor of CDI @Inject (jakartaee/rest#951, jakartaee/rest#569), and replacing @Provider with CDI @Produces or programmatic configuration in the Application class.
• Supporting async/reactive return types natively, as has been available in Quarkus for years, and moving @Suspended AsyncResponse handling to background concurrency and context propagation (jakartaee/rest#1281).
• Providing default values for query, form, and path parameter names (jakartaee/rest#579).
• Adding support for Problem Details (jakartaee/rest#1150).
• Adding support for API Versioning (jakartaee/rest#1317).
• Adding support for Hypermedia, eg, HAL, HAL Form, etc. (jakartaee/rest#1323).
• Supporting Java records in FormBeans and related areas (jakartaee/rest#955, jakartaee/rest#913), especially since records are a major feature in EE 11.
• Enabling functional programming styles for both client and server code (jakartaee/rest#1301).
• Defining HTTP service interfaces as contracts between client and server (jakartaee/rest#1294).
• Modernizing the client API to use Java 8+ syntax and making the HTTP client engine easily switchable (jakartaee/rest#1282).
• …

I hope the Jakarta REST expert group will focus more on features that improve developer productivity and address real-world needs.

What’s New in Jakarta REST 4.0 was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.