Spring blog

Let us have a look at a concrete example. Assume we need to develop an e-commerce application, for which we start with two logical modules. An order module deals with order processing, and an inventory keeps track of the stock for the products we sell. Our primary focus for this post is the use case that the inventory needs to be updated once an order is completed. Our project structure would look something like this (○ denotes a public type, - a private one):

□ Example
└─ □ src/main/java
   ├─ □ example
   │  └─ ○ Application.java
   │
   ├─ □ example.inventory
   │  ├─ ○ InventoryManagement.java
   │  └─ - InventoryInternal.java
   │
   ├─ □ example.order
   │  └─ ○ OrderManagement.java
   └─ □ example.order.internal
      └─ ○ OrderInternal.java

This arrangement starts with the usual skeleton, a base package that contains the Spring Boot application class. Our two business modules are reflected by direct sub-packages: inventory and order. The inventory uses a rather simple arrangement. It consists of only a single package. Thus, we can use Java visibility modifiers to hide internal components from access by code residing in other modules, such as InventoryInternal, as the Java compiler restricts access to non-public types.

The order package, on the contrary, contains a sub-package that exposes a Spring bean which—​in our case—​needs to be public, because OrderManagement refers to it. This arrangement of types, unfortunately, rules out the compiler as a helper to prevent illegal access to OrderInternal, because, in plain Java, packages are not hierarchical. A sub-package is not hidden inside a parent one. Spring Modulith, however, establishes the notion of application modules, that—​by default—​consist of an API package (the ones directly located under the application’s main package—​in our case inventory and order) and, optionally, nested ones (order.internal). The latter are considered internal, and the code residing in those modules is inaccessible to other modules. This application module model can be tweaked to your liking, but let us stick with this default arrangement for this post.

class ModularityTests {

  @Test
  void verifyModularity() {
    ApplicationModules.of(Application.class).verify();
  }
}

\- Module 'inventory' depends on non-exposed type ….internal.OrderInternal within module 'order'!
InventoryManagement declares constructor InventoryManagement(InventoryInternal, OrderInternal) in (InventoryManagement.java:0)

package example.order;

@ApplicationModuleTest
class OrderIntegrationTests {

  // Test methods go here
}

… - Bootstrapping @ApplicationModuleTest for example.order in mode STANDALONE (class example.Application)…
…
… - ## example.order ##
… - > Logical name: order
… - > Base package: example.order
… - > Direct module dependencies: none
… - > Spring beans:
… -   + ….OrderManagement
… -   + ….internal.OrderInternal
…
… - Re-configuring auto-configuration and entity scan packages to: example.order.

@ApplicationModuleTest
@RequiredArgsConstructor
class OrderIntegrationTests {

  private final OrderManagement orders;

  @Test
  void publishesOrderCompletion(PublishedEvents events) {

    var reference = new Order();

    orders.complete(reference);

    // Find all OrderCompleted events referring to our reference order
    var matchingMapped = events.ofType(OrderCompleted.class)
        .matchingMapped(OrderCompleted::getOrderId, reference.getId()::equals);

    assertThat(matchingMapped).hasSize(1);
  }
}