diff --git a/spring-modulith-api/pom.xml b/spring-modulith-api/pom.xml index dc8392ef..13001a3e 100644 --- a/spring-modulith-api/pom.xml +++ b/spring-modulith-api/pom.xml @@ -23,6 +23,20 @@ true + + + + org.springframework + spring-tx + true + + + + org.springframework + spring-context + true + + diff --git a/spring-modulith-api/src/main/java/org/springframework/modulith/ApplicationModuleIntegrationListener.java b/spring-modulith-api/src/main/java/org/springframework/modulith/ApplicationModuleIntegrationListener.java new file mode 100644 index 00000000..735de209 --- /dev/null +++ b/spring-modulith-api/src/main/java/org/springframework/modulith/ApplicationModuleIntegrationListener.java @@ -0,0 +1,57 @@ +/* + * Copyright 2022 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.modulith; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import org.springframework.core.annotation.AliasFor; +import org.springframework.scheduling.annotation.Async; +import org.springframework.transaction.annotation.Propagation; +import org.springframework.transaction.annotation.Transactional; +import org.springframework.transaction.event.TransactionalEventListener; + +/** + * An {@link ApplicationModuleIntegrationListener} is an {@link Async} Spring {@link TransactionalEventListener} that + * runs in a transaction itself. Thus, the annotation serves as syntactic sugar for the generally recommend setup to + * integrate application modules via events. The setup makes sure that an original business transaction completes + * successfully and the integration asynchronously runs in a transaction itself to decouple the integration as much as + * possible from the original unit of work. + *

+ * It is advisable that you use these integration listeners in combination with the Spring Modulith Event Publication + * Registry to make sure that the event publication does not get lost in case of an application or listener failure. + * + * @author Oliver Drotbohm + * @see Spring + * Modulith Event Publication Registry - Reference Documentation + */ +@Async +@Transactional(propagation = Propagation.REQUIRES_NEW) +@TransactionalEventListener +@Documented +@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE }) +@Retention(RetentionPolicy.RUNTIME) +public @interface ApplicationModuleIntegrationListener { + + /** + * Whether the transaction to be run for the event listener is supposed to be read-only (default {@literal false}). + */ + @AliasFor(annotation = Transactional.class, attribute = "readOnly") + boolean readOnlyTransaction() default false; +} diff --git a/spring-modulith-example/src/main/java/example/inventory/InventoryManagement.java b/spring-modulith-example/src/main/java/example/inventory/InventoryManagement.java index 6d301534..78d33f96 100644 --- a/spring-modulith-example/src/main/java/example/inventory/InventoryManagement.java +++ b/spring-modulith-example/src/main/java/example/inventory/InventoryManagement.java @@ -19,9 +19,8 @@ import example.order.OrderCompleted; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; -import org.springframework.scheduling.annotation.Async; +import org.springframework.modulith.ApplicationModuleIntegrationListener; import org.springframework.stereotype.Service; -import org.springframework.transaction.event.TransactionalEventListener; /** * A Spring {@link Service} exposed by the inventory module. @@ -35,8 +34,7 @@ public class InventoryManagement { private final InventoryInternal dependency; - @Async - @TransactionalEventListener + @ApplicationModuleIntegrationListener void on(OrderCompleted event) throws InterruptedException { var orderId = event.getOrderId(); diff --git a/spring-modulith-example/src/test/java/example/order/EventPublicationRegistryTests.java b/spring-modulith-example/src/test/java/example/order/EventPublicationRegistryTests.java index c93b8895..b971a641 100644 --- a/spring-modulith-example/src/test/java/example/order/EventPublicationRegistryTests.java +++ b/spring-modulith-example/src/test/java/example/order/EventPublicationRegistryTests.java @@ -22,11 +22,10 @@ import lombok.RequiredArgsConstructor; import org.junit.jupiter.api.Test; import org.springframework.context.annotation.Import; +import org.springframework.modulith.ApplicationModuleIntegrationListener; import org.springframework.modulith.events.EventPublicationRegistry; import org.springframework.modulith.test.ApplicationModuleTest; -import org.springframework.scheduling.annotation.Async; import org.springframework.test.annotation.DirtiesContext; -import org.springframework.transaction.event.TransactionalEventListener; /** * A show case for how the Spring Modulith application event publication registry keeps track of incomplete publications @@ -57,8 +56,7 @@ class EventPublicationRegistryTests { static class FailingAsyncTransactionalEventListener { - @Async - @TransactionalEventListener + @ApplicationModuleIntegrationListener void foo(OrderCompleted event) { throw new IllegalStateException(); } diff --git a/src/docs/asciidoc/40-events.adoc b/src/docs/asciidoc/40-events.adoc index 2fc516f1..64e3c4e4 100644 --- a/src/docs/asciidoc/40-events.adoc +++ b/src/docs/asciidoc/40-events.adoc @@ -78,6 +78,43 @@ This now effectively decouples the original transaction from the execution of th While this avoids the expansion of the original business transaction, it also creates a risk: if the listener fails for whatever reason, the event publication is lost, unless each listener actually implements its own safety net. Even worse, that doesn't even fully work, as the system might fail before the method is even invoked. +[[events.amil]] +== Application Module Integration Listener + +To run a transactional event listener in a transaction itself, it would need to be annotated with `@Transactional` itself. + +.An async, transactional event listener running in a transaction itself +[source, java] +---- +@Service +@RequiredArgsConstructor +public class InventoryManagement { + + @Async + @Transactional + @TransactionalEventListener + void on(OrderCompleted event) { + + } +} +---- + +To ease the declaration of what is supposed to describe the default way of integrating modules via events, Spring Modulith provides `@ApplicationModuleIntegrationListener` to shortcut the declaration + +.An application module integration listener +[source, java] +---- +@Service +@RequiredArgsConstructor +public class InventoryManagement { + + @ApplicationModuleIntegrationListener + void on(OrderCompleted event) { + + } +} +---- + [[events.publication-registry]] == The Event Publication Registry