GH-156 - Polish example.

Add sample documentation. Reintroduce Lombok to avoid boilerplate. Use jMolecules DDD abstractions to represent aggregates. Use Scenario API in test cases.

Author: odrotbohm

spring-modulith-example/pom.xml

@@ -72,6 +72,11 @@
 
 		<!-- jMolecules -->
 
+		<dependency>
+			<groupId>org.jmolecules</groupId>
+			<artifactId>jmolecules-ddd</artifactId>
+		</dependency>
+
 		<dependency>
 			<groupId>org.jmolecules</groupId>
 			<artifactId>jmolecules-events</artifactId>
@@ -112,6 +117,12 @@
 			<optional>true</optional>
 		</dependency>
 
+		<dependency>
+			<groupId>org.projectlombok</groupId>
+			<artifactId>lombok</artifactId>
+			<scope>provided</scope>
+		</dependency>
+
 	</dependencies>
 
 	<repositories>

spring-modulith-example/src/main/asciidoc/index.adoc

@@ -0,0 +1,16 @@
+= Spring Modulith Example Documentation
+:modulith-docs: ../../../target/spring-modulith-docs
+
+== Overview
+
+plantuml::{modulith-docs}/components.puml[format="svg"]
+
+== Inventory
+
+plantuml::{modulith-docs}/module-inventory.puml[format="svg"]
+include::{modulith-docs}/module-inventory.adoc[]
+
+== Orders
+
+plantuml::{modulith-docs}/module-order.puml[format="svg"]
+include::{modulith-docs}/module-order.adoc[]

spring-modulith-example/src/main/java/example/inventory/InventoryManagement.java

@@ -16,6 +16,7 @@
 package example.inventory;
 
 import example.order.OrderCompleted;
+import lombok.RequiredArgsConstructor;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -28,15 +29,12 @@
  * @author Oliver Drotbohm
  */
 @Service
-public class InventoryManagement {
+@RequiredArgsConstructor
+class InventoryManagement {
 
 	private static final Logger LOG = LoggerFactory.getLogger(InventoryManagement.class);
 
-	final InventoryInternal dependency;
-
-	InventoryManagement(InventoryInternal dependency) {
-		this.dependency = dependency;
-	}
+	private final InventoryInternal dependency;
 
 	@ApplicationModuleListener
 	void on(OrderCompleted event) throws InterruptedException {

spring-modulith-example/src/main/java/example/inventory/package-info.java

@@ -4,4 +4,5 @@
  *
  * @see example.inventory.InventoryInternal
  */
+@org.springframework.lang.NonNullApi
 package example.inventory;

spring-modulith-example/src/main/java/example/order/Order.java

@@ -15,18 +15,20 @@
  */
 package example.order;
 
+import example.order.Order.OrderIdentifier;
+import lombok.Getter;
+
 import java.util.UUID;
 
+import org.jmolecules.ddd.types.AggregateRoot;
+import org.jmolecules.ddd.types.Identifier;
+
 /**
  * @author Oliver Drotbohm
  */
-public class Order {
-
-	private OrderIdentifier id = new OrderIdentifier(UUID.randomUUID());
+public class Order implements AggregateRoot<Order, OrderIdentifier> {
 
-	public OrderIdentifier getId() {
-		return id;
-	}
+	private @Getter OrderIdentifier id = new OrderIdentifier(UUID.randomUUID());
 
-	public static record OrderIdentifier(UUID id) {}
+	public static record OrderIdentifier(UUID id) implements Identifier {}
 }

spring-modulith-example/src/main/java/example/order/OrderManagement.java

@@ -16,6 +16,8 @@
 package example.order;
 
 import example.order.internal.OrderInternal;
+import lombok.NonNull;
+import lombok.RequiredArgsConstructor;
 
 import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.stereotype.Service;
@@ -25,16 +27,11 @@
  * @author Oliver Drotbohm
  */
 @Service
+@RequiredArgsConstructor
 public class OrderManagement {
 
-	final ApplicationEventPublisher events;
-	final OrderInternal dependency;
-
-	OrderManagement(ApplicationEventPublisher events, OrderInternal dependency) {
-
-		this.events = events;
-		this.dependency = dependency;
-	}
+	private final @NonNull ApplicationEventPublisher events;
+	private final @NonNull OrderInternal dependency;
 
 	@Transactional
 	public void complete(Order order) {

spring-modulith-example/src/main/java/example/order/internal/OrderInternal.java

@@ -18,7 +18,8 @@
 import org.springframework.stereotype.Component;
 
 /**
- * Some order-internal application component.
+ * Some order-internal application component. Referring to it from the inventory module would be captured by
+ * {@link example.ModularityTests}.
  *
  * @author Oliver Drotbohm
  */

spring-modulith-example/src/main/java/example/order/package-info.java

@@ -4,4 +4,5 @@
  *
  * @see example.ModularityTests
  */
+@org.springframework.lang.NonNullApi
 package example.order;

spring-modulith-example/src/test/java/example/order/EventPublicationRegistryTests.java

@@ -18,12 +18,15 @@
 import static org.assertj.core.api.Assertions.*;
 
 import example.order.EventPublicationRegistryTests.FailingAsyncTransactionalEventListener;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
 
 import org.junit.jupiter.api.Test;
 import org.springframework.context.annotation.Import;
 import org.springframework.modulith.ApplicationModuleListener;
 import org.springframework.modulith.events.EventPublicationRegistry;
 import org.springframework.modulith.test.ApplicationModuleTest;
+import org.springframework.modulith.test.Scenario;
 import org.springframework.test.annotation.DirtiesContext;
 
 /**
@@ -35,37 +38,41 @@
 @ApplicationModuleTest
 @Import(FailingAsyncTransactionalEventListener.class)
 @DirtiesContext
+@RequiredArgsConstructor
 class EventPublicationRegistryTests {
 
 	private final OrderManagement orders;
 	private final EventPublicationRegistry registry;
-
-	/**
-	 * @param orders
-	 * @param registry
-	 */
-	EventPublicationRegistryTests(OrderManagement orders, EventPublicationRegistry registry) {
-		this.orders = orders;
-		this.registry = registry;
-	}
+	private final FailingAsyncTransactionalEventListener listener;
 
 	@Test
-	void leavesPublicationIncompleteForFailingListener() throws Exception {
+	void leavesPublicationIncompleteForFailingListener(Scenario scenario) throws Exception {
 
 		var order = new Order();
 
-		orders.complete(order);
-
-		Thread.sleep(40);
-
-		assertThat(registry.findIncompletePublications()).hasSize(1);
+		scenario.stimulate(() -> orders.complete(order))
+				.andWaitForStateChange(() -> listener.getEx())
+				.andVerify(__ -> {
+					assertThat(registry.findIncompletePublications()).hasSize(1);
+				});
 	}
 
 	static class FailingAsyncTransactionalEventListener {
 
+		@Getter Exception ex;
+
 		@ApplicationModuleListener
 		void foo(OrderCompleted event) {
-			throw new IllegalStateException();
+
+			var exception = new IllegalStateException("¯\\_(ツ)_/¯");
+
+			try {
+
+				throw exception;
+
+			} finally {
+				this.ex = exception;
+			}
 		}
 	}
 }

spring-modulith-example/src/test/java/example/order/OrderIntegrationTests.java

@@ -15,42 +15,29 @@
  */
 package example.order;
 
-import static org.assertj.core.api.Assertions.*;
+import lombok.RequiredArgsConstructor;
 
 import org.junit.jupiter.api.Test;
 import org.springframework.modulith.test.ApplicationModuleTest;
-import org.springframework.modulith.test.AssertablePublishedEvents;
+import org.springframework.modulith.test.Scenario;
 
 /**
  * @author Oliver Drotbohm
  */
 @ApplicationModuleTest
+@RequiredArgsConstructor
 class OrderIntegrationTests {
 
 	private final OrderManagement orders;
 
-	OrderIntegrationTests(OrderManagement orders) {
-		this.orders = orders;
-	}
-
 	@Test
-	void publishesOrderCompletion(AssertablePublishedEvents events) {
+	void publishesOrderCompletion(Scenario scenario) {
 
 		var reference = new Order();
 
-		orders.complete(reference);
-
-		// Verification
-
-		var matchingMapped = events.ofType(OrderCompleted.class)
-				.matching(OrderCompleted::orderId, reference.getId());
-
-		assertThat(matchingMapped).hasSize(1);
-
-		// AssertJ
-
-		assertThat(events)
-				.contains(OrderCompleted.class)
-				.matching(OrderCompleted::orderId, reference.getId());
+		scenario.stimulate(() -> orders.complete(reference))
+				.andWaitForEventOfType(OrderCompleted.class)
+				.matchingMappedValue(OrderCompleted::orderId, reference.getId())
+				.toArrive();
 	}
 }