Why DDD, and the service we build#

The problem DDD solvesnew#

The shop has a rule. An order ships only when it is paid and every line is picked. In a usual ASP.NET Core service, the rule is an if in a service method. Months later, a second team adds a batch job that ships orders. The job sets the status directly, and the rule is skipped. Nothing fails until a customer receives an order that nobody paid for.

DDD solves this problem with one idea. Each business rule is written once, inside the object whose data it protects. The object has no setter for that data. So the only way to change the status is the method that checks the rule.

The code below shows both designs. On the left, the rule is in a service, and the status has a public setter. On the right, the rule is a method of the order, from the companion service of this part.

public class OrderService(ShopDb db, TimeProvider clock)
{
    public async Task ShipAsync(long orderId)
    {
        var order = await db.Orders.Include(o => o.Lines).SingleAsync(o => o.Id == orderId);
        if (order.Status != OrderStatus.Paid)
            throw new InvalidOperationException("The order is not paid.");
        if (order.Lines.Any(line => line.PickedAt is null))
            throw new InvalidOperationException("A line is not picked.");

        order.Status = OrderStatus.Shipped;
        order.ShippedAt = clock.GetUtcNow();
        await db.SaveChangesAsync();
    }
}

public void ship(Clock clock) {
    requireNotFinished();
    if (status != OrderStatus.PAID) {
        throw new OrderNotPaidException(id());
    }
    if (lines.stream().anyMatch(line -> !line.isPicked())) {
        throw new UnpickedLinesException(id());
    }
    status = OrderStatus.SHIPPED;
    shippedAt = clock.instant();
    raise(new OrderShipped(id(), shippedAt));
}

The two designs check the same rule. The difference is who can skip it. In the C# design, the rule protects one entry point. In the Java design, the rule protects the data itself. A batch job, a message listener and a controller all call order.ship(clock), because no other way exists.

In the companion, a test runs on every build. ArchitectureTest fails if an entity has a public setter. For more about these tests, see the section What keeps a DDD service readable.

What DDD is, in this book's wordsnew#

Eric Evans described DDD in his book Domain-Driven Design, with the subtitle Tackling Complexity in the Heart of Software. Addison-Wesley published it in August 2003. DDD works at two levels. This part uses words from both levels, and each word is introduced where the service first needs it.

The first level is about the business and its boundaries. It is called strategic design.

• The domain is the business that the software serves. Here it is the shop.
• The words that the business experts use are called the ubiquitous language. This book calls them the business words. The code uses the same words. An order is placed, paid, shipped or cancelled, and its lines are picked. An order is never "processed" or "updated".
• A bounded context is a part of the business with its own model and its own meaning for each word. In the shop, the order service is one bounded context. The stock service is another one. Each owns its data.

The second level is about the code inside one bounded context. It is called tactical design. Its building blocks are the aggregate, the entity, the value object, the domain event, the repository and the services. The table shows where each one appears in the order service.

A bounded context has its own words for the things of another context. The stock service has its own model of stock. The order service needs one answer from it, and it keeps that answer in its own words:

/**
 * The stock service's answer, in this service's words: either every product is held for the
 * order, or some are not available.
 *
 * <p>The domain decides what the answer means: an order is placed only if everything is available.
 *
 * @param available           whether every product is held
 * @param unavailableProducts the products that are not available; empty when {@code available}
 */
public record StockAvailability(boolean available, List<ProductCode> unavailableProducts) implements ValueObject {

    public StockAvailability {
        unavailableProducts = List.copyOf(unavailableProducts);
    }

StockAvailability is a record with two components. It says whether the stock service holds every product, and which products it does not have. The order service never sees the stock service's own classes. A class that translates another service's model into this service's words is called an anti-corruption layer. For how the service calls the stock service, see the chapter Calling other services.

What to use, and what to keep lightnew#

DDD has many parts, and a team does not need all of them. This book uses the parts that find the rules and the boundaries. It keeps the rest light, or leaves it out.

Use these parts:

• Event storming. EventStorming is a workshop format. Its official book is by Alberto Brandolini. Its site describes it as a flexible workshop in which people explore a complex business together. In the workshop, developers and business experts look at what happens in the business together. Then the team looks for the rules, and for the boundaries between the parts of the business.
• Bounded contexts. Each service owns one part of the business and its data. Other services use its API or its events, never its database.
• Business words, not jargon. A class, a method and an exception use the word that a business expert would use. A business expert says "ship". Nobody in the warehouse says "update the status to 3".
• Aggregates as consistency boundaries. An aggregate is the group of data that one rule must see at once, and that is saved together. For how to find one, see the chapter Finding the aggregates.
• The full model only where there are rules. Lookup data and simple features use simpler code. For the three levels of the order service, see the chapter How much DDD: three levels in one service.

The business words reach every name, even the values of an enum. The companion stores the status of an order as its name, so the names are business words that never change:

/**
 * Where an order is in its life. It is stored as its name, so never rename a value.
 *
 * <p>NEW becomes PAID when the payment arrives, and PAID becomes SHIPPED. NEW or PAID may become
 * CANCELLED. SHIPPED and CANCELLED are final.
 */
public enum OrderStatus {
    NEW, PAID, SHIPPED, CANCELLED
}

The comment above OrderStatus names every allowed change of state. A business expert can read it and correct it.

Leave these parts out, unless one bounded context clearly needs them:

• Event sourcing. With event sourcing, a service stores the list of events of an aggregate instead of its current state. It is useful when the business needs the full history of every change, as an audit or for replay. The order service stores the current state, and it keeps an audit log beside it.
• Full CQRS. Command query responsibility segregation (CQRS) uses one model for changes and another model, often another database, for reads. It is useful when reads and changes need very different shapes or scale. The order service reads and changes the same documents. For the choice, see the chapter Features, layers and the rules.

Do you need DDD? The conditions that make it worth its costnew#

DDD costs time and code. It is worth that cost when the rules are the hard part of the software. Look for these conditions. The more of them a service has, the more DDD is worth.

Two conditions need a closer look. Both appear when a new service replaces an old system.

Rules to recover from an old system. An old system often holds rules that nobody wrote down. They are in stored procedures, in screens and in the memory of its users. DDD gives each recovered rule a place and a name. Write it as a method of the aggregate. Then write a test whose name a business expert can read. The order tests of the companion read like a list of rules:

@Test
void refusesAnUnpaidOrder() {
    assertThatThrownBy(() -> newOrder().ship(CLOCK)).isInstanceOf(OrderNotPaidException.class);
}

@Test
void refusesAnOrderWithAnUnpickedLine() {
    Order order = newOrder();
    order.recordPayment(payment(NOW));

    assertThatThrownBy(() -> order.ship(CLOCK)).isInstanceOf(UnpickedLinesException.class);
}
// ...
@Test
void aRepeatedOrEarlierPaymentChangesNothing() {
    Order order = newOrder();
    order.recordPayment(payment(NOW));
    order.pullEvents();

    assertThat(order.recordPayment(payment(NOW))).isFalse();
    assertThat(order.recordPayment(payment(NOW.minusSeconds(60)))).isFalse();
    assertThat(order.pullEvents()).isEmpty();
}

The tests use plain JUnit, with no Spring and no mocks. Each one runs in a few milliseconds. newOrder(), payment(NOW) and CLOCK come from a shared class of test data. assertThatThrownBy is from AssertJ. It runs the code and checks the exception that it throws. Show the test names to a business expert, and ask which rule is missing.

Data that breaks rules during a migration. Old data was written under old rules, or under no rules. In the order service, loading a stored order applies no business rules. But the loader still builds each value object, and each value object checks its own value:

@Override
public Order toDomain(OrderDocument document) {
    return Order.rehydrate(
            OrderId.of(document.getId()),
            document.getVersion(),
            new CustomerContact(document.customerName, document.customerEmail),
            new DeliveryMethod(document.deliveryMethod),
            document.placedAt,
            document.lines.stream().map(OrderDocumentMapper::line).toList(),
            OrderStatus.valueOf(document.status),
            payment(document.lastPayment),
            document.shippedAt,
            document.cancelledAt);
}

Order.rehydrate rebuilds an order without checking the rules of the order, because loading is not a business action. But new CustomerContact(...) checks the format of the e-mail address. So a migrated order with a broken address fails to load. That is the right result, but the wrong time to find it. Before the new service takes traffic, run a check that loads every migrated document through the mapper. Fix or set aside each document that fails. For how the service runs migrations, see the chapter Migrations, indexes and seed data.

When DDD is not worth itnew#

DDD is not worth its cost when a service has few rules. Microsoft's guide to .NET microservices says the same. Its page "Designing a microservice domain model" discusses a very simple CRUD service. CRUD means create, read, update and delete. For such a service, the page says, entities that hold only data may be good enough. The guide's sample shop uses DDD for its ordering service, but not for its catalog service.

Do not use DDD in these cases:

• A service that stores and returns data, with no rules beyond the format of each field.
• Read-only lookup data, such as the delivery methods of the shop.
• Reports and search pages, which read data and change nothing.
• Code that connects two systems, and only translates and forwards messages.
• A prototype that will be thrown away. Write it simply, and model the rules in the real service.

The choice is made per feature, not per service. The order service itself has a feature with no DDD building blocks. Its package description says why:

/**
 * Lookup values, such as delivery methods and note categories, for drop-down lists and for
 * checking codes. The data changes only with a deployment, through a seed migration.
 *
 * <p>This feature uses the simple level: no aggregate, no domain model and no events. A
 * document record, a Spring Data repository, and the logic in the application service. Read-only
 * lookup data has no business behaviour, so DDD's building blocks would only add files.
 */
package com.acme.orderservice.reference;

A file named package-info.java holds the comment and the annotations of a whole package. Here the line package com.acme.orderservice.reference; names the package it describes. The reference feature has a document, a repository and a service, and nothing else. For the three levels side by side, see the chapter How much DDD: three levels in one service.

What DDD costsnew#

A team that chooses DDD should know the costs before it starts. There are three.

The learning curve. DDD has its own words, and a new developer needs weeks to use them well. A developer from a usual ASP.NET Core service expects public setters, rules in services and one class for each table. Each habit must change. The chapters of this part teach each change with its reason.

More types and more mapping. The full style keeps the model and the stored shape apart. So one order has a domain class, a document class and a mapper between them. A view and two data transfer objects (DTOs), one for the request and one for the response, carry it in and out. In the companion, the delivery method of an order appears in 13 files of the order feature. Here is half of the mapper that copies an order to its stored document:

@Override
public OrderDocument toDocument(Order order) {
    OrderDocument document = new OrderDocument();
    document.customerName = order.customer().name();
    document.customerEmail = order.customer().email();
    document.deliveryMethod = order.deliveryMethod().code();
    document.status = order.status().name();
    document.placedAt = order.placedAt();
    document.shippedAt = order.shippedAt();
    document.cancelledAt = order.cancelledAt();
    document.lines = order.lines().stream().map(OrderDocumentMapper::lineDocument).toList();
    document.lastPayment = paymentDocument(order.lastPayment());
    return document;
}

Each new field of an order needs a line in toDocument, and a line in the method that reads the document. The light style of the note feature has no mapper at all. It has other costs, which the chapter How much DDD: three levels in one service explains.

Modelling time with experts. The model is only as good as the team's understanding of the business. That understanding comes from hours with the people who do the work. A team without access to business experts gets the extra types, but not the better model.

Easier to reason about: the questions answered in one placenew#

The value of DDD shows when someone asks a question about the code. In a service where the rules are spread over controllers, services and jobs, each answer needs a search. In the order service, each answer has one place. The table lists the usual questions and where the answer is.

Here is the use case that ships an order. It names its steps, and it holds no rule:

/** Ships the order. The rule across the order and its notes is checked by the domain service. */
@Transactional
public void ship(OrderId orderId) {
    Order order = orders.get(orderId);                                         // load
    long notesNeedingAction = notes.countNeedingAction(orderId.value());       // ask the note feature
    shippingPolicy.assertCanShip(order, notesNeedingAction);                   // rule across aggregates
    order.ship(clock);                                                         // rule and change
    saveAndPublish(order, AuditActions.ORDER_SHIPPED);                         // save, publish, audit
}

@Transactional runs the method in one database transaction. The four steps load the order, ask the note feature for a count, check the rule across the order and its notes, and ship. The last line saves the order, publishes its events and records the audit. A reader learns what shipping does from five lines. For the steps of every use case, see the chapter Use cases: the application service.

What gets hardertrap#

DDD does not make everything easier. An honest team says what gets harder, and works against it. Four things get harder.

More indirection. A request passes through a controller, an application service, an aggregate, a repository port, an adapter and a mapper. In a usual ASP.NET Core service, the same request passes through a controller, a service and a DbContext. Each extra layer is one more file to open.

Events hide the flow. When a method raises an event, the code that reacts to it is in another class. The IDE does not lead you there with one click. In the companion, two classes react to OrderShipped. One counts the shipped orders. The other decides which events leave the service:

/**
 * Decides which order events leave the service. Placed, shipped and cancelled orders are
 * published; picked lines and recorded payments stay internal. Every published event is a
 * contract to maintain, so publish only what another service needs.
 */
@Component
class OrderIntegrationEventMapper implements IntegrationEventMapper {

    @Override
    public Optional<IntegrationEvent> toIntegrationEvent(DomainEvent event) {
        return switch (event) {
            case OrderPlaced placed -> Optional.of(new OrderPlacedV1(newEventId(), placed.occurredAt(),
                    placed.orderId().value(), placed.deliveryMethod().code(),
                    placed.items().stream()
                            .map(item -> new OrderPlacedV1.Line(item.product().value(), item.quantity()))
                            .toList()));
            case OrderShipped shipped -> Optional.of(new OrderShippedV1(newEventId(), shipped.occurredAt(),
                    shipped.orderId().value()));
            case OrderCancelled cancelled -> Optional.of(new OrderCancelledV1(newEventId(), cancelled.occurredAt(),
                    cancelled.orderId().value()));
            default -> Optional.empty();
        };
    }

The switch matches the type of the event, as a switch with type patterns does in C#. It turns three domain events into the public events of the service, and keeps the others inside. This one class answers the question "which events leave the order feature?". Without it, the answer would need a search through every listener.

The learning curve. The words and the rules of DDD take time to learn, as the section What DDD costs says. A team of beginners writes DDD slowly at first.

DDD done badly is worse than no DDD. A team can copy the layers without the idea.

What keeps a DDD service readablenew#

The costs of the section What gets harder grow with each developer who does things differently. These practices keep a DDD service readable.

• The same structure everywhere. Every feature has the same folders, and every service has the same features layout. A developer who knows one feature finds the code of another one at once.
• Steps-only application services. A use case loads, lets the domain decide, saves, publishes and audits. It holds no rule.
• Business names. A class is named after the business idea, such as ShippingPolicy. It is never named after a pattern alone, such as OrderDomainService.
• Simple where simple. A feature with no rules uses the simple level. The full model is only where it protects a rule.
• Traceable events. One mapper per feature decides which events leave it. Give every log line and message a trace ID, so one request can be followed across services. A flow that spans many steps and days uses a workflow engine or a process manager. Either one keeps the state of the flow in one place. For trace IDs, see the chapter Logging, tracing and health.
• Architecture tests. The rules of the design are tests, so the build fails when someone breaks one.
• Docs and decision records beside the code. Each service has a README with its rules, its events and its decisions. A decision that a team may question later is written as an architecture decision record (ADR). An ADR is a short file that states a decision, its reason and its consequences.

Here are two of the architecture tests of the companion:

@Test
void entitiesHaveNoPublicSetters() {
    ArchitectureRules.entitiesHaveNoPublicSetters().check(CLASSES);
}

@Test
void featuresUseEachOtherOnlyThroughApplication() {
    ArchitectureRules.featuresUseEachOtherOnlyThroughApplication(BASE).check(CLASSES);
}

Each test calls a rule from the platform library, and check fails the test when a compiled class breaks it. The rules use ArchUnit, a Java library that reads the compiled classes and checks their dependencies. ArchUnitNET is a separate library for .NET. Its README calls it the C# fork of ArchUnit. The first rule finds a public setter on an entity. The second one finds a feature that uses the inside of another feature. For all the rules, see the chapter Testing in depth.

An anaemic model with an outbox, compared fairlytwist#

A model whose entities hold data but no rules is called an anaemic domain model. Martin Fowler described it in an article of November 2003. He said that its objects are hardly more than getters and setters. Many good .NET services use this design. With an outbox, they also publish their events reliably. An outbox is a table or collection that stores each event in the same transaction as the change. A background process sends it after the commit. So this design deserves a fair comparison.

public async Task ShipWithOutboxAsync(long orderId)
{
    var order = await db.Orders.Include(o => o.Lines).SingleAsync(o => o.Id == orderId);
    // ... the same two checks as in ShipAsync

    order.Status = OrderStatus.Shipped;
    order.ShippedAt = clock.GetUtcNow();
    db.OutboxMessages.Add(OutboxMessage.For(new OrderShippedV1(order.Id, order.ShippedAt.Value)));
    await db.SaveChangesAsync();   // the order and the message, in one transaction
}

/**
 * Saves the order, publishes its events and records the audit, all in the caller's
 * transaction.
 *
 * <p>The events are pulled before saving, because the saved copy that the repository returns
 * is rebuilt from the database and has none. The caller continues with the returned copy,
 * which holds the new version.
 */
private Order saveAndPublish(Order order, String auditAction) {
    List<DomainEvent> raised = order.pullEvents();
    Order saved = orders.save(order);
    events.publish(raised);
    audit.record(auditAction, AuditActions.ORDER, saved.id().value());
    return saved;
}

In C#, the service sets the fields, writes the outbox row and saves. In Java, the order has already recorded its events, inside ship. saveAndPublish pulls them, saves the order and publishes the events in the same transaction. Every use case of the feature calls this one method. So no use case can save a change and forget its event.

The table compares what the anaemic design keeps and what it loses.

The anaemic design breaks down in four ways, and each one grows with the size of the team.

• The same rule is copied. The controller checks that the order is paid. The batch job checks it too, a little differently. A year later, the two checks disagree.
• A loader bypasses everything. An import or a data fix writes entities directly. It sets a status that no rule would allow.
• Events are forgotten. The outbox sends every row that a service writes. It cannot send a row that a new endpoint forgot to write.
• Proof of correctness is slow. To prove that no order ships unpaid, a reviewer must find every line that sets the status. In the rich model, a reviewer reads Order.ship and its tests.

So the outbox fixes the delivery of events, and only that. It does not fix where the rules are, or who may skip them.

The middle groundnew#

A team does not need the full style to get most of the value. Four practices give most of it, and each one is cheap.

1. State-change methods with their rules, and no state setters. An entity changes only through methods such as ship and resolveAction.
2. The entity records its events. The method that changes the state also records what happened. The use case publishes the recorded events when it saves.
3. Value objects for IDs, money, dates and codes. A value that has a format or a rule is a small type that checks itself, such as Money or ProductCode.
4. Boundaries decided by the strongest people. The boundaries of the services and of the aggregates are the hardest decisions to change later. A small group of the most experienced developers makes them, with the business experts. The team writes everything else.

The note feature of the companion uses exactly this middle ground. Its entity is also its stored document, and it has no mapper. But it keeps its rules:

public void resolveAction(String actorId, Clock clock) {
    if (!actionRequired) {
        throw new NoteHasNoActionException(id);
    }
    if (actionResolvedAt != null) {
        throw new NoteActionAlreadyResolvedException(id);
    }
    if (actorId.equals(createdBy)) {
        throw new NoteResolvedByItsAuthorException(id);
    }
    actionResolvedAt = clock.instant();
    events.add(new NoteActionResolved(id, orderId, actionResolvedAt));
}

resolveAction checks three rules, changes one field and records the event NoteActionResolved. The third rule depends on who acts, so the use case passes the actor's ID in as a plain value. No setter exists for actionResolvedAt. For what this light style drops and what it keeps, see the chapter How much DDD: three levels in one service. For who decides what in a team, see the chapter DDD for a team: the playbook.

Rules engines and decision tablesnew#

Some rules are calculations with many cases. A delivery charge, for example, can depend on the delivery method, the zone and the weight. Thirty cases written as if statements are hard to read and hard to check. A table of the cases is easier, and a business expert can check it.

Decision Model and Notation (DMN) is a standard for such tables. The Object Management Group (OMG) publishes it. Its page says that DMN lets a team define business rules simply and exactly, in decision tables. Among the Java libraries that evaluate DMN tables are these two, as of October 2026.

• The Camunda DMN engine is a Java library that evaluates DMN decision tables. Its page for Camunda 7.24 says that it implements DMN 1.3, and that it can be embedded in an application.
• Drools is a group of projects for decision management, mostly in Java. Its user guide for version 8.44.0.Final lists a decision engine for DMN.

A decision table has one row for each case. Here is an example for the shop. The order service has no delivery charges, so this table is only an illustration:

Keep the rule's place in the model, even when an engine calculates it. The domain names the rule as a class, and the class asks a port for the answer. The order service has a rule class of this kind, without a port:

/**
 * The rule that needs two aggregates: an order cannot ship while a note on it needs action.
 *
 * <p>It is a domain service because neither aggregate holds the data alone. It is named after
 * the rule, not {@code OrderDomainService}, so unrelated code does not collect in it. It takes a
 * number, not the notes, so the order feature never sees note objects. It has no state, no
 * repository and no Spring annotation, and the order feature's configuration creates it.
 *
 * <p>The guarantee holds only at the moment of shipping. An agent may add a note that needs
 * action a second after the order shipped. The service accepts that, and the README records the
 * decision.
 */
public class ShippingPolicy {

    public void assertCanShip(Order order, long notesNeedingAction) {
        if (notesNeedingAction > 0) {
            throw new OrderHasOpenActionsException(order.id(), notesNeedingAction);
        }
    }
}

A delivery charge would get a class such as DeliveryChargeCalculator, beside ShippingPolicy. Its port would be an interface in the domain. An adapter outside the domain would implement the port, and evaluate the DMN file with the engine. So the domain stays plain Java, and a unit test can replace the table.

Use an engine when the table is large, or when business experts change it more often than the code is released. Keep the rule in code when it has a few cases. An engine adds a library, a file format and a second kind of test.

The order service: its features and its rulesnew#

The rest of this part builds one service, the shop's order service. It keeps the orders that customers place, the lines that warehouse staff pick, and the payment that the payment service reports. It also keeps the notes that customer-service agents write on orders. The package description of the order feature states its rules:

/**
 * Orders: what a customer bought, the lines that warehouse staff pick, the payment, and shipping.
 *
 * <p>This feature uses the full style. Its {@code domain} package is plain Java with typed IDs.
 * The {@code persistence} package stores the aggregate as a separate document through a mapper,
 * behind the {@code OrderRepository} port. The stock service is called through the
 * {@code StockChecker} port.
 *
 * <p>The rules: an order is placed only if the stock service confirms and holds the products.
 * An order ships only when it is paid, every line is picked, and no note on it needs action. A
 * payment is recorded from the payment service's event, and a repeated or late one changes nothing.
 */
package com.acme.orderservice.order;

The comment describes the package com.acme.orderservice.order. The service has five top-level packages. Each of the first four is a business feature.

These are the rules that the README of the service lists:

• An order is placed only if the stock service confirms and holds every product.
• An order has 1 to 50 lines. A line is picked once.
• An order ships only when it is paid, every line is picked, and no note on it needs action.
• A shipped or cancelled order cannot change. A payment for it is still recorded, because the money was received. The payment service handles refunds.
• A payment is recorded from the event PaymentReceivedV1. A repeated or earlier payment changes nothing.
• Only a note that needs action can be resolved, and only once. The text of a note never changes.
• Delivery methods and note categories must be active lookup values.

The packages of each feature follow one layout. Here are the folders of the order service:

com/acme/orderservice/
  order/
    api/            the controller, its DTOs and their mapper
    application/    the use cases, the views, and the port to the stock service
    client/         the HTTP client of the stock service
    domain/         plain Java: the model, events, exceptions, repository port, domain service
    messaging/      the events that leave, and the listener of payments
    persistence/    the stored document, its mapper, and the repository adapter
  note/
    api/
    application/
    model/          the entity that is also its stored document, and its repository
  reference/
    api/
    application/
    persistence/
  migration/
  shared/

Each folder name says what the classes in it do. For example, only the domain/ folder of a feature holds its business rules. In the note feature, the model/ folder holds them. For the reasons behind this layout, see the chapter Features, layers and the rules.

The earlier chapters of this book give an order a long id. This part gives it a typed OrderId, which holds a universally unique identifier (UUID) as text. The service needs the ID before it saves the order, because it sends the ID to the stock service first. A database cannot generate an ID that the service needs before the first save. For the typed ID in full, see the chapter The domain model in plain Java.

Its events and the services it talks tonew#

The diagram shows every call and every message of the order service. The service sends and receives messages through Amazon Simple Notification Service (SNS) and Amazon Simple Queue Service (SQS).

SNS and SQS are two messaging services of Amazon Web Services (AWS). A topic of SNS sends each message to every subscriber. A queue of SQS holds messages until one consumer takes them. The table lists the events of the service. Each event has a JSON schema in the folder contracts/events.

A public event is a contract, so its fields change only with care. Here is the schema of OrderShippedV1:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "order-service/OrderShippedV1",
  "title": "OrderShippedV1",
  "description": "An order was shipped. Published to the order-events SNS topic.",
  "type": "object",
  "required": ["eventId", "occurredAt", "orderId"],
  "properties": {
    "eventId": { "type": "string", "format": "uuid" },
    "occurredAt": { "type": "string", "format": "date-time" },
    "orderId": { "type": "string", "format": "uuid" }
  },
  "additionalProperties": true
}

The event carries only its own ID, its time and the order ID. A consumer that needs more asks the order service. The suffix V1 is the version of the contract. For event schemas and their versions, see the chapter API and event contracts.

The service depends on five other systems. The README says what happens when each one is down.

For each of these, the part has a chapter. For the outbox, see the chapter Publishing events: the outbox. For the payment queue, see the chapter Consuming events: SQS and the inbox.

Three repositories: platform, service and local environmentnew#

The companion is in one folder, but in real life it is three repositories. Each one has its own release cycle.

A service names the platform's parent and one dependency, with no version. The parent manages every version. Here is the start of the order service's Project Object Model (POM):

<!--
  The platform parent sets Java, the plugins and every dependency version.
  In this service's own repository, remove <relativePath>: the parent then comes from the
  company's artifact repository.
-->
<parent>
    <groupId>com.acme.platform</groupId>
    <artifactId>shop-platform-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <relativePath>../shop-platform/shop-platform-parent/pom.xml</relativePath>
</parent>

<groupId>com.acme</groupId>
<artifactId>order-service</artifactId>
<version>1.0.0-SNAPSHOT</version>

<dependencies>
    <!-- Everything cross-cutting. No version: the parent manages it. -->
    <dependency>
        <groupId>com.acme.platform</groupId>
        <artifactId>shop-platform</artifactId>
    </dependency>

The element parent names the platform's parent POM. A POM is the build file of Maven. It has the same purpose as a .csproj file in .NET. The platform holds no domain classes. Services share contracts, such as OpenAPI files and event schemas, but never domain classes. A shared domain library would tie the release of every service to the others. For the parent and the library, see the chapter The build: a parent POM and a platform library. For how to write the library, see the chapter Writing the platform library.

The local environment is started once, and then each service runs from its own repository. The README of the service gives the two commands:

cd ../local-environment && docker compose up -d
cd ../order-service && mvn package && docker compose up --build

The first command, docker compose up -d, starts the shared containers in the background. The second one builds the service and starts it in a container. For the local environment in full, see the chapter Running locally and shipping.

A map of the partnew#

Each chapter of the part adds one layer or one concern to the order service. Read them in order the first time. Later, use this list to find a topic.

• Design. Finding the aggregates, How much DDD: three levels in one service, Features, layers and the rules.
• Build. The build: a parent POM and a platform library.
• The domain. The domain model in plain Java, Where each rule goes.
• Spring itself. Wiring the service: the container in depth, Configuration in depth.
• The way in. Use cases: the application service, The web layer in depth, API and event contracts, Security in depth.
• Storage. Storing aggregates in DocumentDB, Migrations, indexes and seed data, Transactions in depth.
• Other services. Calling other services, Publishing events: the outbox, Consuming events: SQS and the inbox.
• Running it. Logging, tracing and health, Caching and scheduling, Writing the platform library, Testing in depth, Running locally and shipping.
• Living with it. Changing the service, DDD for a team: the playbook.

Finding the aggregates#

What an aggregate is fornew#

An agent cancels an order. At the same moment, warehouse staff ship it. Each change checks that the order is not finished, and each check passes. If nothing connects the two saves, both succeed, and a cancelled order leaves the warehouse. The rules need the status, the lines and the payment to be checked and saved as one thing.

The answer is to treat the order, its lines and its payment as one unit. The unit is loaded whole, changed by one method that checks the rules, and saved whole in one transaction. It has one version. So when the agent and the warehouse save the same version, the second save fails. This unit is called an aggregate. The object that outside code holds, here Order, is called the root of the aggregate.

So an aggregate is a consistency boundary. Everything inside it is checked and saved together. Everything outside it is checked and saved on its own. Vaughn Vernon wrote a series of three essays, Effective Aggregate Design, in 2011. Part I says that an aggregate and a transactional consistency boundary are the same thing. Microsoft's guide to .NET microservices gives the same advice. It says that the best way to find the aggregates is to think about the transactions.

The platform's base class of every root states the same idea in its comment:

/**
 * The base class of an aggregate root: the only object of an aggregate that outside code may
 * hold. Every change to the aggregate goes through the root, which checks the rules.
 *
 * <p>The root carries two things for the layers around it. The first is the version, which
 * optimistic locking needs: the version comes from storage and goes back to storage unchanged,
 * and no rule ever reads it. The second is the list of domain events the root raised. The
 * application service pulls the events after saving and publishes them in the same transaction.
 *
 * @param <ID> the typed identifier of the aggregate
 */
public abstract class AggregateRoot<ID extends Identifier> extends Entity<ID> {

AggregateRoot is generic in its ID type. <ID extends Identifier> means that the ID must be a typed identifier, such as OrderId. It is like a constraint where TId : Identifier in C#. The class holds only the version and the recorded events. It holds no business idea.

In a document database, an aggregate maps well to one document. The order service stores each order, with its lines and its last payment, as one document in the collection orders. One save writes the whole document, so the lines and the status are stored together. For how the service stores it, see the chapter Storing aggregates in DocumentDB.

In a usual EF Core model, each table is an entity, and each entity can be loaded and saved on its own. Nothing in the model says which entities must change together. The aggregate is the decision that the model of EF Core leaves to each service method.

The root is the only way intwist#

public class Order
{
    public long Id { get; set; }
    public OrderStatus Status { get; set; }
    public List<OrderLine> Lines { get; set; } = [];
}

// in a service, or in any other class
order.Lines.Single(line => line.Id == lineId).PickedAt = clock.GetUtcNow();

public void pickLine(LineId lineId, Clock clock) {
    requireNotFinished();
    OrderLine line = lines.stream()
            .filter(candidate -> candidate.id().equals(lineId))
            .findFirst()
            .orElseThrow(() -> new LineNotFoundException(id(), lineId));
    line.pick(clock);
    raise(new LinePicked(id(), lineId, line.pickedAt()));
}

In C#, any class can find a line and set its pick time. Nothing checks that the order is still open, or that the line was not picked before. In Java, pickLine is the only way to pick a line. It refuses a finished order, finds the line by its typed ID, picks it and adds the event LinePicked. An unknown line ID throws LineNotFoundException, which the platform answers with 404.

The line itself cannot be changed from outside its package. Its methods that change it are package-private:

/**
 * One line of an order: a product and a quantity that warehouse staff pick.
 *
 * <p>A line is an entity inside the order aggregate. It has its own identity, so a picker can
 * name it, but only the order may change it. That is why {@link #add} and {@link #pick} are
 * package-private: code outside this package goes through {@link Order}.
 */
public class OrderLine extends Entity<LineId> {
    // ...
    /** Creates a new line for an item. Only {@link Order} calls it. */
    static OrderLine add(OrderItem item) {
        return new OrderLine(LineId.newId(), item.product(), item.quantity(), null);
    }

    /** Rebuilds a stored line. Only persistence calls it. */
    public static OrderLine rehydrate(LineId id, ProductCode product, int quantity, Instant pickedAt) {
        return new OrderLine(id, product, quantity, pickedAt);
    }

    void pick(Clock clock) {
        if (isPicked()) {
            throw new LineAlreadyPickedException(id());
        }
        pickedAt = clock.instant();
    }

add and pick have no access modifier. In Java, no modifier means that only classes of the same package can call the method. Order is in the same package, order.domain.model, so it can call line.pick(clock). A controller or a use case cannot. rehydrate is public, because the mapper in the persistence package rebuilds stored lines. It applies no rule. For the access levels of Java, see the section The mapping.

The getter lines() of the order returns a read-only copy. So outside code cannot add or remove a line either. For the full set of these protections, see the chapter The domain model in plain Java.

Art or science? Questions you can applynew#

Is finding an aggregate an art or a science? The honest answer is both. It is not a calculation, because it depends on the business. The business decides how long two pieces of data may disagree. Only a business expert can say that. But it is not guessing either. A small set of questions and tests decides most cases. Judgement decides the rest, and the reasons for each judgement can be written down.

Ask these questions about each piece of data, and each rule.

1. Which rule must hold after every change? Write the rule in business words, such as "an order ships only when every line is picked". A rule of this kind is called an invariant. Vernon's first rule is "Model True Invariants In Consistency Boundaries". A rule that the business can check later is not an invariant.
2. Does the rule need this data at every change? Shipping needs every line. So the lines are inside. Shipping needs only the number of notes that need action, not the notes. So the notes stay outside.
3. Is the data small and bounded? An order has at most 50 lines. Notes have no limit. Data inside an aggregate is loaded and saved with every change, so it must have a maximum.
4. Whose job is it to make the data consistent? Vaughn Vernon gives a guideline that he learned from Eric Evans, in Part II. If it is the job of the user who runs the use case, make the data consistent in the same transaction. If it is the job of another user, or of the system, let the data become consistent later.
5. Do different people change the parts at the same time? Warehouse staff pick lines while agents write notes. Parts that different people change at once conflict if they are saved together.
6. Do the parts have the same life? A line is created with its order and never exists without it. A note is written later, by someone else, and is resolved on its own.
7. What does outside code need to find? The root is the object that the business names, and that outside code refers to by its ID. Nobody refers to a line without its order. So the order is the root, and the line is inside.

Then test the answer. Each test takes a few minutes.

• Write the rule as a method of the root. If the method needs data that the aggregate does not hold, the boundary is wrong, or the rule belongs to a domain service.
• Count the maximum size. Multiply the largest list by the size of one item. Compare it with the limit of a document, and with what a save should write.
• Draw two users at the same moment. Name two use cases that change the aggregate at once. If they are common and unrelated, they will conflict.
• List the use cases that save it. If most of them also save another aggregate, the two may be one.

The comment of Order writes down the result of these questions, so the next developer can see the reasons:

/**
 * An order: the aggregate root of the order feature.
 *
 * <p>The aggregate holds what its rules need at every change: the status, the lines and the last
 * payment. Notes are a separate aggregate, because no order rule needs every note, and they can
 * grow without limit.
 *
 * <p>The rules on the order's own data:
 * <ul>
 *   <li>An order is placed only if every product is available, with 1 to {@value #MAX_LINES} lines.</li>
 *   <li>A shipped or cancelled order cannot change, except that payments are still recorded.</li>
 *   <li>A line is picked once.</li>
 *   <li>An order ships only when it is paid and every line is picked.</li>
 *   <li>A payment is recorded only if it is later than the last one, so repeated and late
 *       messages change nothing. The first payment makes a new order paid.</li>
 * </ul>
 *
 * <p>The rule that no note may need action is across two aggregates, so it lives in
 * {@code ShippingPolicy}.
 *
 * <p>State changes only through these methods. There are no setters, and the time always comes
 * from the {@link Clock} the caller passes.
 */

The comment names what is inside, what is outside and why. The last paragraph says that every time comes from the Clock that the caller passes. Keep a comment like this on every root. It is the shortest note of the boundary decision.

These questions come from two principles. One principle says that a transaction protects one place. The other principle says that some rules must hold now and others may hold a little later. For both principles in full, see the chapter The principles.

The order aggregate, piece by piecenew#

Here are the fields of the order:

public class Order extends AggregateRoot<OrderId> {

    public static final int MAX_LINES = 50;

    private final CustomerContact customer;
    private final DeliveryMethod deliveryMethod;
    private final Instant placedAt;
    private final List<OrderLine> lines;
    private OrderStatus status;
    private Payment lastPayment;
    private Instant shippedAt;
    private Instant cancelledAt;

extends AggregateRoot<OrderId> makes Order a root with a typed ID. The final fields never change after the order is placed. The other fields change only through the methods of the order. The table says why each piece is inside.

Two pieces have no rule but are still inside. The customer and the delivery method are part of what an order is. They are created with it, they never change, and they are small. A piece with no rule may be inside when it has the same life as the root.

Signs of an aggregate that is too bigtrap#

The easiest model of an order puts everything about it inside. In EF Core, an order would get a navigation property public List<Note> Notes { get; set; }. In a document database, the notes would be embedded in the order document. It works in the first demo, and it fails a year later.

Watch for four signs.

• A list with no limit. Notes, comments, history entries and messages grow for as long as the root exists. Ask for the maximum. If nobody can name one, the list does not belong inside.
• The size limit of a document. Amazon DocumentDB limits a document to 16 MiB, as of October 2026. A save of a larger document fails. Long before that limit, each save writes a large document. Spring Data MongoDB saves a document with @Version as a full replacement, not as a change of one field.
• Conflicts on save. The aggregate has one version. Two saves of the same version conflict, and the second one fails. Spring Data throws OptimisticLockingFailureException. Inside a transaction, MongoDB usually reports a write conflict, which Spring turns into DataIntegrityViolationException. The platform answers both with 409. If unrelated work often gets 409, the aggregate is too big.
• Rules that do not need the data. If shipping loads two thousand notes to count three of them, the notes are inside for no rule.

The stored document of the order says why its lines are inside and its notes are not:

/**
 * How an order is stored: one document per aggregate, with its lines and last payment embedded.
 *
 * <p>The lines are embedded because they are few (at most 50) and every order rule needs them.
 * Notes are not: they have no limit, and embedding them would rewrite the whole order for each
 * new note. A document must stay under 16 MB.
 *
 * <p>Only plain types are stored. Enums and codes are strings, so renaming a Java class never
 * breaks stored data. Money is DECIMAL128, so it is exact. The class and its fields are
 * package-private: nothing outside this package knows the storage shape.
 */
@Document("orders")
class OrderDocument extends BaseDocument {

@Document("orders") names the collection. BaseDocument is the platform's base class of a stored document, with the ID and the version. For the version and the conflicts in full, see the chapter Storing aggregates in DocumentDB.

Signs of an aggregate that is too smalltrap#

The opposite mistake splits data that one rule needs. Suppose that each order line were an aggregate of its own, saved as its own document. Picking a line would then be simple. But shipping must check every line of the order, and these checks would read up to 50 separate documents. A line picked a moment after the check would not be seen.

The rule that the order checks today needs its lines in the same aggregate:

public void ship(Clock clock) {
    requireNotFinished();
    if (status != OrderStatus.PAID) {
        throw new OrderNotPaidException(id());
    }
    if (lines.stream().anyMatch(line -> !line.isPicked())) {
        throw new UnpickedLinesException(id());
    }
    status = OrderStatus.SHIPPED;
    shippedAt = clock.instant();
    raise(new OrderShipped(id(), shippedAt));
}

lines.stream().anyMatch(line -> !line.isPicked()) checks every line, inside the same object and the same save. anyMatch does the same as Any in LINQ. If a line were outside, this check would need a query, and it would hold only at the moment of the query.

Watch for these signs of an aggregate that is too small.

• A rule must change several aggregates together, every time. That is the main sign.
• Most use cases save the same two aggregates in one transaction.
• A rule reads many aggregates, and a change between the reads would break it.
• Someone proposes a lock across two aggregates, to make a rule hold.

One use case that saves two aggregates is not a sign by itself. The order service does it once, for a reason. See the section Why order and note are separate aggregates.

How to split or merge an aggregatenew#

A boundary can be wrong, and it can be changed. To split an aggregate that is too big, follow these steps.

1. Move the part with no limit into an aggregate of its own, with its own root, its own ID and its own version.
2. Give the new aggregate the ID of the old root. Remove the list from the old root.
3. Keep each rule that needed the moved part. Give it a number or a yes or no answer, not the objects. A domain service checks the rule, as ShippingPolicy does.
4. If a rule can wait, react to an event of the other aggregate instead.
5. Write a migration that moves the embedded items into the new collection. For migrations, see the chapter Migrations, indexes and seed data.

In the order service, the shipping rule needs one number from the note feature. The note feature answers with a count, and never returns the notes:

/** For the order feature's shipping rule: a plain number, so no note crosses the boundary. */
public long countNeedingAction(String orderId) {
    return notes.countByOrderIdAndActionRequiredTrueAndActionResolvedAtIsNull(orderId);
}

countNeedingAction returns a long, so no note crosses into the order feature. The repository method behind it is a derived query:

public interface NoteRepository extends MongoRepository<Note, String> {

    Page<Note> findByOrderId(String orderId, Pageable pageable);

    /** Counts the notes on an order that still need action. Spring Data reads the rule from the name. */
    long countByOrderIdAndActionRequiredTrueAndActionResolvedAtIsNull(String orderId);
}

Spring Data reads the method name countByOrderIdAndActionRequiredTrueAndActionResolvedAtIsNull and builds the query from it. It counts the notes of one order that need action and are not resolved. For derived queries, see the section Repositories and derived queries.

To merge two aggregates that are too small, do the opposite. Make one root the owner. Turn the other root into an entity or a value object inside it, and give the owner the methods that change it. Then write a migration that embeds the old documents into their owners.

Why order and note are separate aggregatesnew#

A note is an agent's text about an order, such as "the customer asked us to leave the parcel with a neighbour". Some notes need action. An order cannot ship while one of its notes needs action. So the note and the order are linked by a rule. They are still two aggregates, for four reasons.

1. Notes have no limit. An order with a problem can collect hundreds of notes. Inside the order, they would grow the document toward the 16 MiB limit.
2. No order rule needs every note. The shipping rule needs one number, the count of notes that need action.
3. Fewer conflicts. Each note has its own version. An agent who adds a note does not change the order's version. So the agent never blocks the warehouse, and the warehouse never blocks the agent.
4. A different life. An order is placed by the customer and finished by the warehouse. A note is written by an agent at any time, and resolved later by another agent.

One use case saves both kinds of aggregate. An agent can place an order together with its first notes, and the agent sees that as one action. So the order service stores the order and its first notes in one transaction:

public PlacedOrder place(CustomerContact customer, DeliveryMethod deliveryMethod, List<OrderItem> items,
                         List<NewNote> firstNotes) {
    referenceData.requireActive(ReferenceTypes.DELIVERY_METHOD, deliveryMethod.code(), "deliveryMethod");
    OrderId orderId = OrderId.newId();
    StockAvailability availability = stock.reserve(orderId, items);           // outside the transaction

    return transaction.execute(status -> {
        Order order = Order.place(orderId, customer, deliveryMethod, items, availability, clock);
        Order saved = saveAndPublish(order, AuditActions.ORDER_PLACED);        // aggregate 1
        List<String> noteIds = notes.addNotes(saved.id().value(), firstNotes); // aggregate 2, same transaction
        return new PlacedOrder(saved.id().value(), noteIds);
    });
}

transaction.execute runs the lambda in one transaction. The order is saved first, and then notes.addNotes saves each note in the same transaction. If a note is invalid, the whole transaction rolls back, and the order is not stored either. The test OrderJourneyIT.anOrderAndItsNotesAreStoredTogetherOrNotAtAll shows it against a real MongoDB. For TransactionTemplate and why the stock call is outside it, see the chapter Transactions in depth.

Saving two aggregates in one transaction departs from a strict rule. Vernon's Part I says that a well designed bounded context changes only one aggregate in each transaction. His Part II also names reasons to break the rule. One of them is creating several new aggregates in one request, when that means the same as creating them one by one. The order and its first notes are new aggregates of that kind. For the callout of this choice, see the section One request that saves the order and its first notes.

Refer to another aggregate by its IDtwist#

public class Note
{
    public long Id { get; set; }
    public long OrderId { get; set; }
    public Order Order { get; set; } = null!;
    public string Text { get; set; } = "";
}

@Document("notes")
public final class Note {

    public static final int MAX_TEXT_LENGTH = 2000;

    @Id
    private final String id;

    @Version
    private Long version;

    private final String orderId;
    private final String text;
    private final String category;
    private final boolean actionRequired;
    private final Instant createdAt;
    private final String createdBy;
    private Instant actionResolvedAt;

    @Transient
    private final List<DomainEvent> events = new ArrayList<>();

In C#, the note has an Order navigation property, so code can reach the order through the note and change it. In Java, the note holds only orderId. It cannot reach the order. The order holds nothing about its notes. Vernon's Part II names this rule "Reference Other Aggregates By Identity". Microsoft's guide recommends the same for EF Core. It calls it a good practice to keep only the foreign key of the other aggregate, with no navigation property to it.

A reference by ID keeps the boundaries real.

• Loading a note never loads an order, and loading an order never loads its notes.
• Saving a note never saves an order. So a change to a note never changes the data of the order.
• Each aggregate keeps its own version, so a note and its order never conflict.
• The note feature never sees the Order class. It asks the order feature, which checks its own rules.

The annotations on Note are from Spring Data. @Document("notes") names its collection, @Id marks its ID, and @Version marks the version that detects conflicts. @Transient keeps the list of events out of the stored document. The note is its own stored document, in the light style. For that style, see the chapter How much DDD: three levels in one service.

A type for a foreign ID, or plain texttwist#

The note holds the ID of its order as a String. The strict full style would give it a type of its own, such as OrderRef. It would not reuse OrderId from the order feature. With its own type, the note's model would depend on nothing in the order feature. The note feature could change, or move to another service, without the order's classes.

The order service keeps the text, and lets the owner of the ID check it. When a note is added, the note feature asks the order feature whether the order exists:

/**
 * For other features: checks that an order exists. IDs cross between features as text, and
 * the owner of the ID checks it, so a bad ID gives the order feature's own 400 or 404.
 */
public void requireExists(String orderId) {
    OrderId id = OrderId.of(orderId);
    if (!orders.exists(id)) {
        throw new OrderNotFoundException(id);
    }
}

OrderId.of(orderId) checks the format of the text. A bad ID gives the order feature's own 400, and an unknown one gives its 404. So the check is in one place, the feature that owns the ID.

Inside the aggregate: entities and value objectstwist#

public record Money(decimal Amount, string Currency);
public record PaymentReference(string Value);
public record Payment(PaymentReference Reference, Money Amount, DateTimeOffset PaidAt);

/**
 * A payment that the payment service received for an order. It is a value object made of value
 * objects.
 *
 * @param reference the payment service's reference
 * @param amount    the amount paid
 * @param paidAt    when it was paid, which decides which payment is the latest
 */
public record Payment(PaymentReference reference, Money amount, Instant paidAt) implements ValueObject {

    public Payment {
        Guard.notNull(reference, "paymentReference");
        Guard.notNull(amount, "amount");
        Guard.notNull(paidAt, "paidAt");
    }
}

Both panes build a payment from other values, and both compare by value. The Java record checks its values in a compact constructor, the block public Payment { ... }. Guard.notNull throws an error that names the field, and the platform answers it with 400. implements ValueObject marks the intent. The C# records check nothing until you add a constructor.

An aggregate holds two kinds of objects besides its root. An object with an identity of its own is called an entity. An object that is only its values is called a value object.

To decide, ask whether anyone must name the object. A picker must name the line that was picked, so a line is an entity with a LineId. Nobody names a payment. A newer payment replaces the last one, so a payment is a value object. A payment is built from three values, a reference, an amount and a time. Two of them are value objects too.

The platform's base class of an entity defines equality by identity:

/**
 * The base class of an entity: an object with its own identity.
 *
 * <p>Two entities are equal when they have the same class and the same ID, even if their other
 * data differs. The methods are final, so a subclass cannot change what identity means.
 *
 * @param <ID> the typed identifier of the entity
 */
public abstract class Entity<ID extends Identifier> {
    // ...
    @Override
    public final boolean equals(Object other) {
        if (this == other) {
            return true;
        }
        if (other == null || getClass() != other.getClass()) {
            return false;
        }
        return id.equals(((Entity<?>) other).id);
    }

    @Override
    public final int hashCode() {
        return id.hashCode();
    }

equals is final, so no subclass can change what identity means. Two lines with the same ID are the same line, even if one was loaded before it was picked. The marker of a value object is an empty interface:

/**
 * Marks a class as a value object: it is defined only by its values, it never changes, and it
 * checks its own values when it is created.
 *
 * <p>The interface has no methods. It documents the intent, and it lets architecture tests find
 * value objects. Write value objects as records, so Java generates {@code equals} and
 * {@code hashCode} from the values.
 */
public interface ValueObject {
}

ValueObject has no methods. A record generates equals and hashCode from its values, as a C# record does. For value objects and the Guard checks in full, see the chapter The domain model in plain Java.

Typed IDs inside the aggregatetwist#

public readonly record struct OrderId(Guid Value)
{
    public static OrderId New() => new(Guid.NewGuid());
}

public readonly record struct LineId(Guid Value);

/** The identity of an order: a UUID that the compiler cannot mix up with another ID. */
public final class OrderId extends Identifier {

    private OrderId(String value) {
        super(value, "orderId");
    }

    public static OrderId of(String value) {
        return new OrderId(value);
    }

    public static OrderId newId() {
        return new OrderId(newValue());
    }
}

Both panes give each ID its own type, so a method that takes an OrderId refuses a LineId. In C#, the call does not compile. The compiler gives error CS1503, and says that it cannot convert from LineId to OrderId. In Java, the compiler gives error: incompatible types: LineId cannot be converted to OrderId. Both messages were produced by compiling the call.

The Java ID is a class, not a record. Its constructor is private, and OrderId.of and OrderId.newId create it. The base class Identifier checks that the text is a universally unique identifier (UUID), so every OrderId is valid. The C# record struct accepts any Guid, including an empty one. For the base class and why the ID holds text, see the chapter The domain model in plain Java.

What holds between two aggregates, and what does nottrap#

The shipping rule needs an order and its notes. They are two aggregates, so the rule is checked by a domain service, ShippingPolicy, when the order ships:

/**
 * The rule that needs two aggregates: an order cannot ship while a note on it needs action.
 *
 * <p>It is a domain service because neither aggregate holds the data alone. It is named after
 * the rule, not {@code OrderDomainService}, so unrelated code does not collect in it. It takes a
 * number, not the notes, so the order feature never sees note objects. It has no state, no
 * repository and no Spring annotation, and the order feature's configuration creates it.
 *
 * <p>The guarantee holds only at the moment of shipping. An agent may add a note that needs
 * action a second after the order shipped. The service accepts that, and the README records the
 * decision.
 */
public class ShippingPolicy {

    public void assertCanShip(Order order, long notesNeedingAction) {
        if (notesNeedingAction > 0) {
            throw new OrderHasOpenActionsException(order.id(), notesNeedingAction);
        }
    }
}

assertCanShip takes the order and a number, not the notes. Its comment already names the problem. Here is the question that every team must answer. Does the rule still hold a second later?

It does not. Agent A ships an order. At the same moment, agent B adds a note that needs action to the same order. MongoDB detects a write conflict when two transactions write the same document. These two transactions write different documents. So both commit, and a shipped order has a note that needs action.

This is the general rule. Separate aggregates give no lasting guarantee across them. A rule across two aggregates holds at the moment it is checked, and only then. The table lists what the order service guarantees, and what it does not.

Four ways to handle the gap, and how to record the choicenew#

The time between the check and a later change is called the gap in this book. A team has four options. Choose with the business owner, because each one changes what users see.

Option B narrows the gap, but does not close it. Two transactions at the same moment can still both pass. Option C closes the gap, because both transactions write the order. Its cost is the cost of an aggregate that is too big. Option D accepts the gap and adds a safety net.

The companion chose option A. The chance is small, and the result is harmless, because the note is still seen and handled. Closing the gap would need a lock across the two aggregates. The README records the decision:

**The shipping rule holds only at the moment of shipping.** An agent can add a note that needs
action to an order a moment after it shipped. The business owner accepted this: the note is
still seen and handled, and closing the gap would need a lock across the two aggregates.
`NoteServiceTest.aNoteNeedingActionCanStillBeAddedAfterTheOrderShipped` records it. Revisit it
if such notes ever need to stop a shipment.

The record names the decision and its reason. It names the test that shows the behaviour, NoteServiceTest.aNoteNeedingActionCanStillBeAddedAfterTheOrderShipped, and when to look at it again. A test records the decision in code:

/**
 * Records a decision. The shipping rule holds only at the moment of shipping: an agent can
 * still add a note that needs action to an order that has shipped, because the note feature
 * checks only that the order exists. The team accepted this gap; the README explains why and
 * when to close it.
 */
@Test
void aNoteNeedingActionCanStillBeAddedAfterTheOrderShipped() {
    String noteId = service.addNote(ORDER_ID, new NewNote("Customer says the parcel is damaged", "COMPLAINT", true));

    assertThat(noteId).isNotNull();
    verify(orders).requireExists(ORDER_ID);
    verify(notes).save(any(Note.class));
}

The test adds a note that needs action and checks that it is saved. It also checks that the note feature asks only requireExists, whatever the status of the order. The test does not run the race. It records the decision in the code that a change would touch. A developer who adds option B must change this test, and its comment points to the decision and the business owner.

For a bigger decision, write an architecture decision record (ADR) beside the code. An ADR is a short file with a title, the context, the decision, and its consequences. Its test is the same kind of test as above.

Between services: no shared transactionnew#

An aggregate is a boundary inside one service. Between two services, the boundary is wider. No transaction spans two services, because each one has its own database. When the order service places an order, it asks the stock service to hold the products. The two changes cannot commit together.

So each step that crosses services must be safe to repeat, and the flow must end in a known state if a step fails. The order service makes the stock call before its own transaction, and sends the order ID as an idempotency key:

/**
 * The port to the stock service, in this service's types. The use case does not know that the
 * answer comes over HTTP, and a unit test replaces it with a mock.
 *
 * <p>It lives in {@code application/port}, not in the domain: calling another service is a step
 * of the use case, and the domain only judges the answer.
 */
public interface StockChecker {

    /**
     * Asks the stock service to confirm that the items are available, and to hold them for the
     * order. The stock service keeps the hold until it sees {@code OrderPlacedV1}, or releases it
     * after a timeout if the order is never placed.
     *
     * <p>Calling it twice for the same order holds nothing twice, because the order ID is the
     * idempotency key.
     */
    StockAvailability reserve(OrderId order, List<OrderItem> items);
}

reserve may be called twice for the same order, and the stock service holds the products once. If the order's transaction fails after the call, no OrderPlacedV1 is published. The stock service then releases the hold after its timeout. Each service stays consistent on its own, and the services agree after a while. This is called eventual consistency.

A flow with several such steps, each with its own undo, is called a saga. The order service has none, because one hold with a timeout is enough. Consider a saga, or a workflow engine that runs it, when a flow crosses several services and each failure needs its own undo. For the stock call in full, see the chapter Calling other services.

Two features that call each othertrap#

The shipping rule makes the order feature ask the note feature for a count. Adding a note makes the note feature ask the order feature whether the order exists. So each feature's service needs the other one. With constructor injection alone, Spring cannot create either bean first.

The companion breaks the cycle with @Lazy:

public NoteService(NoteRepository notes, @Lazy OrderService orders, ReferenceDataService referenceData,
                   DomainEventPublisher events, AuditLog audit, CurrentActor currentActor, Clock clock) {
    this.notes = notes;
    this.orders = orders;
    this.referenceData = referenceData;
    this.events = events;
    this.audit = audit;
    this.currentActor = currentActor;
    this.clock = clock;
}

@Lazy on the parameter makes Spring inject a proxy in place of the real OrderService. The proxy finds the real bean at its first call. So Spring can create NoteService before OrderService exists. For how Spring resolves such cycles, see the chapter Wiring the service: the container in depth.

There are three ways out.

• Make one dependency one-way. The note controller could ask the order feature whether the order exists, before it calls the note service. Then the note service needs nothing from the order feature.
• React to an event. A feature that only needs to know that something happened can listen to an event, instead of calling.
• Merge the two features. If the two features always change together, they are one feature.

The companion keeps the cycle, and its README lists these ways out. A test of the architecture fails when a feature uses anything of another feature except its application package. For the rules of the layers, see the chapter Features, layers and the rules.

How much DDD: three levels in one service#

Three levels in one servicenew#

A team that learns DDD often uses the full model everywhere. It makes every feature an aggregate. A lookup list then gets an aggregate root, a typed ID, a document class, a mapper and a port. That is five files for a list that never changes. The opposite mistake gives the core business object no protection at all.

The answer is to choose the level for each feature. A feature gets the least DDD that still protects its rules. The order service shows three levels side by side, so a reader can compare them in one codebase.

The architecture tests of the platform know the three levels. The comment of the rules says so:

* <p>The rules allow three styles of feature. A full-style feature has a plain-Java
* {@code domain} package with ports and adapters. A light-style feature keeps a rich entity that
* is also its stored document, in a {@code model} package. A simple feature has no domain model
* at all. Rules about the {@code domain} package therefore affect only full-style features, and
* the rules that keep the application layer free of adapters take the full-style features as a
* parameter.

The package name tells the level. A full-style feature has a domain package. A light-style feature has a model package. A simple feature has no package of either kind. So one rule can check that every domain package is plain Java, and it does not touch the light or simple features.

The full level: the order featuretwist#

public interface IOrderRepository
{
    Task<Order?> FindAsync(OrderId id);
    Task<Order> SaveAsync(Order order);
    Task<bool> ExistsAsync(OrderId id);
    Task<IReadOnlyList<Order>> FindByStatusAsync(OrderStatus status, int page, int size);
}

/**
 * The port for storing orders, in the domain's own types. The persistence package implements it.
 * Lists are sorted newest first.
 */
public interface OrderRepository extends Repository<Order, OrderId> {

    /** Loads the order, or throws the 404 exception, so a use case loads in one line. */
    default Order get(OrderId id) {
        return findById(id).orElseThrow(() -> new OrderNotFoundException(id));
    }

    PageResult<Order> findAll(PageQuery page);

    PageResult<Order> findByStatus(OrderStatus status, PageQuery page);
}

Both panes declare a repository in the types of the domain, with no database type. The Java interface extends the platform's Repository<Order, OrderId>. That interface declares the three methods that every aggregate needs, to find, save and check one. The default method get loads an order or throws the 404 exception, so a use case loads in one line.

An interface that the inner code declares, and the outer code implements, is called a port. The class that implements it with a real technology is called an adapter. Here is the adapter of the order repository:

/**
 * Implements the domain's {@link OrderRepository} port with MongoDB. The base class supplies
 * load, save and exists. This class adds only the order's own queries, each backed by an index
 * in migration {@code V001}.
 */
@Component
class OrderPersistenceAdapter extends MongoAggregateRepository<Order, OrderId, OrderDocument> implements OrderRepository {

    private static final Sort NEWEST_FIRST = Sort.by(Sort.Direction.DESC, "placedAt");

    private final OrderMongoRepository orderDocuments;

    OrderPersistenceAdapter(OrderMongoRepository orderDocuments, OrderDocumentMapper mapper) {
        super(orderDocuments, mapper);
        this.orderDocuments = orderDocuments;
    }

    @Override
    public PageResult<Order> findAll(PageQuery page) {
        return toPageResult(orderDocuments.findAll(pageable(page, NEWEST_FIRST)));
    }

    @Override
    public PageResult<Order> findByStatus(OrderStatus status, PageQuery page) {
        return toPageResult(orderDocuments.findByStatus(status.name(), pageable(page, NEWEST_FIRST)));
    }
}

MongoAggregateRepository is the platform's base class of an adapter. It implements findById, save and exists with a Spring Data repository and the mapper. The adapter adds only the order's own queries. It is package-private, so nothing outside the persistence package can use it. The use case sees only OrderRepository.

The full level separates the model from its stored shape. The domain class Order holds the rules. The class OrderDocument holds what is stored, as plain types. The mapper copies one into the other. So each side can change without the other. A field can be renamed in the domain, and the stored name stays. Money can be stored as Decimal128, and the domain keeps its Money type with a currency. For the document and the mapper in full, see the chapter Storing aggregates in DocumentDB.

The light level: the note featuretwist#

public class Note
{
    private Note(Guid id, Guid orderId, string text, bool actionRequired)
    {
        Id = id;
        OrderId = orderId;
        Text = text;
        ActionRequired = actionRequired;
    }

    public Guid Id { get; private set; }
    public Guid OrderId { get; private set; }
    public string Text { get; private set; }
    public bool ActionRequired { get; private set; }
    public DateTimeOffset? ActionResolvedAt { get; private set; }

    [NotMapped]
    public List<object> Events { get; } = [];

    public static Note Create(Guid orderId, string text, bool actionRequired) =>
        new(Guid.NewGuid(), orderId, text, actionRequired);

    public void ResolveAction(TimeProvider clock)
    {
        if (!ActionRequired)
            throw new InvalidOperationException("The note needs no action.");
        if (ActionResolvedAt is not null)
            throw new InvalidOperationException("The action is already resolved.");
        ActionResolvedAt = clock.GetUtcNow();
        Events.Add(new NoteActionResolved(Id, OrderId, ActionResolvedAt.Value));
    }
}

@Document("notes")
public final class Note {

    public static final int MAX_TEXT_LENGTH = 2000;

    @Id
    private final String id;

    @Version
    private Long version;

    private final String orderId;
    private final String text;
    private final String category;
    private final boolean actionRequired;
    private final Instant createdAt;
    private final String createdBy;
    private Instant actionResolvedAt;

    @Transient
    private final List<DomainEvent> events = new ArrayList<>();

    @PersistenceCreator
    Note(String id, Long version, String orderId, String text, String category, boolean actionRequired,
         Instant createdAt, String createdBy, Instant actionResolvedAt) {
        this.id = id;
        this.version = version;
        this.orderId = orderId;
        this.text = text;
        this.category = category;
        this.actionRequired = actionRequired;
        this.createdAt = createdAt;
        this.createdBy = createdBy;
        this.actionResolvedAt = actionResolvedAt;
    }

    /**
     * Writes a new note on an order. The caller has checked that the order exists and that the
     * category is an active lookup value. {@code createdBy} is the ID of the agent who writes it.
     */
    public static Note create(String orderId, String text, String category, boolean actionRequired,
                              String createdBy, Clock clock) {
        Guard.notBlank(orderId, "orderId");
        Guard.notBlank(text, "text");
        Guard.maxLength(text, MAX_TEXT_LENGTH, "text");
        Guard.matches(category, "[A-Z_]{1,50}", "category");
        Guard.notBlank(createdBy, "createdBy");
        Note note = new Note(UUID.randomUUID().toString(), null, orderId, text, category, actionRequired,
                clock.instant(), createdBy, null);
        note.events.add(new NoteAdded(note.id, orderId, note.createdAt));
        return note;
    }

    /**
     * Resolves the action. The agent who wrote the note may not resolve it, so a second person
     * checks the work. The use case passes the actor's ID in as a plain value, so the note never
     * reads the security context.
     */
    public void resolveAction(String actorId, Clock clock) {
        if (!actionRequired) {
            throw new NoteHasNoActionException(id);
        }
        if (actionResolvedAt != null) {
            throw new NoteActionAlreadyResolvedException(id);
        }
        if (actorId.equals(createdBy)) {
            throw new NoteResolvedByItsAuthorException(id);
        }
        actionResolvedAt = clock.instant();
        events.add(new NoteActionResolved(id, orderId, actionResolvedAt));
    }

Both panes are one class that is the model and the stored shape at once. EF Core can do the same, and its documentation says how. EF Core calls a constructor with parameters when their names and types match mapped properties. The page says that the constructor may be private, or have any other access level. It also says that EF Core treats a property with a private setter as one it can write, so the property is still mapped. The code above was run with EF Core 10.0.8. EF Core mapped the five properties with private setters, and left out Events.

So the light style has a close match in .NET. The C# developer who writes entities with private setters and methods already writes it. The Java version marks the constructor with @PersistenceCreator. C# relies on a naming convention. Java also marks each field that is not stored.

The full level keeps the document and the model apart, so storage and domain can change independently. The light level gives that up. It is the right trade when the stored shape and the model are the same, and the rules are few. The note has nine stored fields, all of plain types.

The simple level: the reference featuretwist#

public record ReferenceItem(string Id, string Type, string Code, string Label, bool Active);

/**
 * One lookup value, as stored in {@code reference_data}. A record is enough: the data is
 * read-only, so it needs no version and no behaviour.
 *
 * @param type   the list it belongs to, such as {@code DELIVERY_METHOD}
 * @param code   the value that other data stores, such as {@code EXPRESS}
 * @param label  the text a user sees
 * @param active whether new data may use it; old values stay, because stored orders still use them
 */
@Document("reference_data")
public record ReferenceItemDocument(@Id String id, String type, String code, String label, boolean active) {
}

Both panes are one record with five values. The Java record is the stored document, with @Document and @Id. It has no version, because nothing changes it, and no methods, because it has no behaviour. Lookup values change only with a deployment, through a seed migration.

A feature at this level has no aggregate, no domain model and no events. The repository reads each list and caches it:

/**
 * Reads lookup values, and caches each list by its type.
 *
 * <p>The cache is on the repository, not on the service, for a reason. {@code @Cacheable} works
 * through a proxy around the bean, so only calls from another bean pass through it. The service
 * calls this method from two of its own methods; if the cache were on the service, the call from
 * {@code requireActive} to {@code list} would skip the proxy and the cache.
 *
 * <p>The cached list is shared by every caller, so callers must not change it.
 */
public interface ReferenceItemRepository extends MongoRepository<ReferenceItemDocument, String> {

    @Cacheable("reference-data")
    List<ReferenceItemDocument> findByTypeOrderByCodeAsc(String type);
}

@Cacheable("reference-data") keeps the result of each call in the cache reference-data, keyed by the type. The comment explains why the cache is on the repository and not on the service. For caching in full, see the chapter Caching and scheduling.

The feature still has one rule. A code that another feature stores must be an active lookup value. The rule is written once, in the application service:

/**
 * Throws a 400 for the field unless the code is an active value of the list.
 *
 * @param field the request field the client must correct, such as {@code deliveryMethod}
 */
public void requireActive(String type, String code, String field) {
    boolean known = items.findByTypeOrderByCodeAsc(type).stream()
            .anyMatch(item -> item.code().equals(code) && item.active());
    if (!known) {
        throw new InvalidValueException(field, "is not a known value");
    }
}

requireActive throws an InvalidValueException that names the field, so the client gets a 400 that says which value to correct. The order and note features call it before they create anything. A rule about input in one place, with no state to protect, needs no aggregate.

What the light style dropsnew#

The light style drops four parts of the full style. Each part protects against something, so each drop has a cost.

A domain service is never a default. The full style also has one only where a rule needs two aggregates. So the fourth row is not a real drop. It shows that the light style does not add a service out of habit.

The use case of the note feature uses the Spring Data repository directly. Its test mocks that interface:

/**
 * The note use cases. In the light style the service uses a Spring Data repository directly,
 * so the test mocks that interface instead of a port.
 */
class NoteServiceTest {

    private static final String ORDER_ID = UUID.randomUUID().toString();
    private static final String AUTHOR = "agent-1";

    private final NoteRepository notes = mock(NoteRepository.class);
    private final OrderService orders = mock(OrderService.class);
    private final ReferenceDataService referenceData = mock(ReferenceDataService.class);
    private final DomainEventPublisher events = mock(DomainEventPublisher.class);
    private final AuditLog audit = mock(AuditLog.class);
    private String actingAgent = "agent-2";
    private final CurrentActor currentActor = () -> actingAgent;

    private final NoteService service = new NoteService(notes, orders, referenceData, events, audit, currentActor, CLOCK);

mock(NoteRepository.class) creates a Mockito mock of the Spring Data interface. The test needs no Spring context and no database. So the missing port costs little in testing. The real cost is that the service depends on MongoRepository, a type of Spring Data, and on its paging types.

What the light style keepsnew#

The light style keeps every part that protects a rule. These parts are cheap, and they are the reason to use DDD at all.

• State-change methods with their rules. A note is resolved only through resolveAction, which checks that the note needs action and that it is not resolved yet.
• No state setters. The fields that never change are final. The two that change, the version and the time of resolution, have no setter.
• The entity records its events. create records NoteAdded. The method resolveAction records NoteActionResolved. The use case publishes them when it saves.
• Checked values. create checks the text and the category with Guard, so no new note has a blank text or a bad code.

A test of the architecture keeps the second point true. It treats a light-style entity like a domain entity:

/**
 * An entity changes only through methods that apply its rules, so it has no public setter.
 * This covers domain entities and the entities of light-style features, which are documents
 * outside a persistence package. A persistence document, which only holds stored data, may
 * have setters.
 */
public static ArchRule entitiesHaveNoPublicSetters() {
    DescribedPredicate<JavaClass> entities = assignableTo(Entity.class)
            .or(DescribedPredicate.describe("light-style entities",
                    (JavaClass type) -> type.isAnnotatedWith(Document.class)
                            && !type.getPackageName().contains(".persistence")));
    return methods().that().areDeclaredInClassesThat(entities)
            .and().haveNameMatching("set[A-Z].*")
            .should().notBePublic()
            .allowEmptyShould(true)
            .as("Entities have no public setter");
}

The rule finds every class that extends Entity, and every class with @Document outside a persistence package. Then it fails for a public method whose name starts with set. A persistence document such as OrderDocument may have setters, because it holds no rule.

The middle ground of the chapter Why DDD, and the service we build also names value objects for IDs, money, dates and codes. The note keeps only part of that. Its category is a plain String that create checks. Its time is an Instant, which is already a value. A code that is used in one place may stay text with a check. A code that is used in several places becomes a value object, as ProductCode is in the order feature. So does a code with a rule of its own.

Versions after a savetrap#

The light style forces four differences from the full style. The first one is about the version. In the full style, the version of an aggregate is final. A save returns a new object with the new version, and the use case continues with that object. The platform's repository port says so:

/**
 * Saves the aggregate and returns the stored copy, which holds the new version.
 *
 * <p>Continue with the returned instance. The instance you passed in keeps the old version,
 * so saving it a second time fails. For a new aggregate it fails as a duplicate insert, with
 * {@code DuplicateKeyException}; for a loaded one, as a concurrent update. Saving also fails
 * with Spring's {@code OptimisticLockingFailureException} when someone else saved the
 * aggregate after you loaded it; that exception is unchecked, so this plain-Java interface
 * can only name it here.
 * Inside a transaction, MongoDB usually reports the same conflict as a write conflict, which
 * Spring translates to {@code DataIntegrityViolationException}. The platform answers both with 409.
 *
 * <p>Never retry a failed save with the same instance. Load the aggregate again, apply the
 * change again, and save that.
 */
A save(A aggregate);

The comment of A save(A aggregate) says to continue with the returned instance. In the light style, Spring Data saves the note in place. It writes the new version into the same object. The note service relies on that:

/**
 * Saves, publishes and audits. Spring Data saves this mutable object in place and sets its
 * new version, so the same instance stays usable. The events are pulled first, because they
 * are not stored.
 */
private void saveAndPublish(Note note, String auditAction) {
    List<DomainEvent> raised = note.pullEvents();
    notes.save(note);
    events.publish(raised);
    audit.record(auditAction, AuditActions.NOTE, note.id());
}

notes.save(note) returns the same object for Note, and sets the new version on it. So the service ignores the result. The test NoteRepositoryIT.saveWritesTheNewVersionIntoTheSameInstance checks this against a real MongoDB.

A test of the companion shows the trap against a real MongoDB:

@Test
void rejectsAStaleCopyAndStillChangesItsVersion() {
    Note saved = notes.save(Note.create(ORDER_ID, "Call back", "DELIVERY", true, "agent-1", CLOCK));
    Note firstCopy = notes.findById(saved.id()).orElseThrow();
    Note secondCopy = notes.findById(saved.id()).orElseThrow();
    firstCopy.resolveAction("agent-2", CLOCK);
    notes.save(firstCopy);
    secondCopy.resolveAction("agent-2", CLOCK);

    assertThatThrownBy(() -> notes.save(secondCopy)).isInstanceOf(OptimisticLockingFailureException.class);
    // Spring Data wrote the next version into the object before the update failed, so the
    // failed copy must not be saved again: load the note afresh instead.
    assertThat(secondCopy.version()).isEqualTo(1L);
}

Two copies of the same note are loaded, and the first one is saved. The save of secondCopy fails with OptimisticLockingFailureException. But secondCopy.version() is now 1, the version that the first save stored. A second save of that object would match the stored version. So it would overwrite the first change without an error. The comment of NoteService warns about this too. For versions and conflicts in full, see the chapter Storing aggregates in DocumentDB.

Events: a base class or a list that is not storedtwist#

In the full style, the base class AggregateRoot keeps the list of events, with raise and pullEvents. The light entity has no base class. It keeps its own list, marked @Transient, and its own pullEvents. A test checks the stored shape without a database:

@Test
void theRaisedEventsAreNotStored() {
    Note note = Note.create(UUID.randomUUID().toString(), "Call back", "DELIVERY", true, "agent-1", CLOCK);   // has an event

    Document stored = new Document();
    converter.write(note, stored);

    assertThat(stored).containsKeys("_id", "orderId", "text", "category", "actionRequired", "createdAt", "createdBy")
            .doesNotContainKey("events");
}

converter.write(note, stored) runs the same converter that Spring Data uses to store a note. The test then checks the keys of the result. The stored document has _id and the other fields, and no key events. In C#, [NotMapped] has the same purpose for EF Core. The run of the C# example above showed that EF Core left Events out of the model.

Equality: a base class or its own equalstwist#

In the full style, the base class Entity compares the class and the typed ID, and its equals is final. The light entity writes its own:

/** Two notes are the same note when they have the same ID, as for any entity. */
@Override
public boolean equals(Object other) {
    return other instanceof Note note && id.equals(note.id);
}

@Override
public int hashCode() {
    return Objects.hash(id);
}

other instanceof Note note checks the type and names the cast value note in one step, as a type pattern does in C#. Two notes with the same ID are the same note. NoteTest.twoNotesWithTheSameIdAreEqual builds a second copy of a note, as loading would, with another version. It checks that the two copies are equal. The class is final, so no subclass can break the comparison.

Creating and loadingtwist#

In the full style, an aggregate has two factory methods. place or create is a business action. It applies the rules and records an event. rehydrate rebuilds a stored aggregate for the mapper. It applies no rules and records nothing.

The light entity has create too. For loading, it has a constructor marked @PersistenceCreator, which Spring Data calls. This test loads a note from a stored document:

@Test
void loadingUsesThePersistenceCreatorAndRaisesNoEvents() {
    String orderId = UUID.randomUUID().toString();
    Document stored = new Document("_id", "note-1").append("version", 4L).append("orderId", orderId)
            .append("text", "Call back").append("category", "DELIVERY").append("actionRequired", true)
            .append("createdAt", java.util.Date.from(NOW)).append("createdBy", "agent-1");

    Note loaded = converter.read(Note.class, stored);

    assertThat(loaded.id()).isEqualTo("note-1");
    assertThat(loaded.version()).isEqualTo(4L);
    assertThat(loaded.needsAction()).isTrue();
    assertThat(loaded.pullEvents()).isEmpty();
}

converter.read(Note.class, stored) builds a note through the constructor. The loaded note has the stored ID and version, and it has no events. So loading through @PersistenceCreator works like rehydrate. The constructor is package-private, so code outside note.model cannot call it to skip create. EF Core finds such a constructor by convention. Spring Data uses the one that @PersistenceCreator marks.

Choosing the level for each featurenew#

Choose the level when a feature is designed, and write it down. Ask these questions in order.

1. Does the feature change state under business rules? If not, use the simple level. Lookup lists, reports and read-only views are in this group.
2. Are its rules about its own data, and is its stored shape the same as its model? If yes, use the light level. In the book's view, many features of a service are here.
3. Does any of these apply? The stored shape and the model differ. The model needs types that Spring Data cannot store as they are. The feature calls another service, or holds the most important rules of the business. If yes, use the full level.

In the order service, the order is the core of the business. It holds money, it calls the stock service, and its stored shape differs from its model. So it is full. The note has three rules about its own data. So it is light. The reference feature only lists and checks values. So it is simple.

The architecture test names the full-style features, so the build checks the level:

/** The features in the full style, whose application layer must use ports only. */
private static final String ORDER = BASE + ".order";
// ...
@Test
void applicationOfFullStyleFeaturesUsesNoAdapter() {
    ArchitectureRules.applicationDoesNotUseAdapters(ORDER).check(CLASSES);
}

ORDER names the one full-style feature. The rule applicationDoesNotUseAdapters then fails if the order's application package uses an adapter, HTTP or MongoDB. A feature that moves to the full style is added to this list. For who decides the level in a team, see the chapter DDD for a team: the playbook.

The sign that a feature needs the next levelnew#

A level is not chosen forever. Each one has a sign that the feature has outgrown it. The comment of the note package names the sign for the light style:

/**
 * Notes that customer-service agents keep on an order. Some notes need action, and an order
 * cannot ship until every such note is resolved.
 *
 * <p>This feature uses the light style, to compare with the full style of the order feature.
 * {@code Note} is still a rich entity: it holds its rules, changes only through its methods and
 * raises its events. But it is also the stored document, with Spring Data annotations on it, and
 * the application service uses a Spring Data repository directly. There is no port, no adapter
 * and no mapper, and IDs are plain strings. The package is called {@code model}, not
 * {@code domain}, because it is not plain Java.
 *
 * <p>The light style fits a small aggregate whose stored shape and model are the same, and whose
 * rules are few. Move to the full style when the stored shape starts to bend the model, or the
 * model needs types that Spring Data cannot store as they are.
 */
package com.acme.orderservice.note;

The last paragraph of the comment above package com.acme.orderservice.note; names two signs. The table gives the signs for each move.

Move a feature to the next level in one change, with its tests. The domain tests stay the same, because the rules do not change. Only the persistence and its tests change. A feature can also move down. If every line of a mapper copies a field to a field of the same name, the separate document protects nothing.

Features, layers and the rules#

The service's foldersnew#

A developer moves from the order service to the invoice service. They need the class that stores an invoice. If both services have the same folders, they know where to look before they open the project. So every shop service uses the same layout.

Here is the order service's repository, with the main folders only:

order-service/
├── pom.xml                      ← the build: a parent and one dependency
├── Dockerfile                   ← the image, built from the jar
├── docker-compose.yml           ← runs the service against the local environment
├── README.md                    ← purpose, rules, endpoints, events, dependencies, configuration
├── contracts/
│   ├── openapi.yaml             ← the generated API contract, committed
│   └── events/                  ← one JSON schema per event, sent or consumed
└── src/
    ├── main/
    │   ├── java/com/acme/orderservice/
    │   │   ├── OrderServiceApplication.java
    │   │   ├── order/           ← a feature
    │   │   ├── note/            ← a feature
    │   │   ├── reference/       ← a feature
    │   │   ├── migration/       ← database changes, not a feature
    │   │   └── shared/          ← small helpers for every feature
    │   └── resources/
    │       ├── application.yml
    │       ├── application-local.yml
    │       └── seed/            ← lookup values that a migration loads
    └── test/
        ├── java/com/acme/orderservice/   ← the same packages as main
        └── resources/

The file pom.xml is the service's Project Object Model (POM), the build file of Maven. It names the shop's parent POM, which sets every version. For the standard Maven folders, see the section The standard layout. The folders contracts and seed belong to the shop. For the contracts, see the chapter API and event contracts. For the seed files, see the chapter Migrations, indexes and seed data.

The base package is com.acme.orderservice. The platform library uses com.acme.platform. Both start with the company's reversed domain, com.acme. The class that starts the service is in the base package:

/**
 * Starts the order service, like {@code Program.cs} in ASP.NET Core.
 *
 * <p>{@code @SpringBootApplication} scans this package and every package below it for
 * components. The platform's beans come from its auto-configuration instead, because the
 * platform's packages are not below this one.
 */
@SpringBootApplication
public class OrderServiceApplication {

    public static void main(String[] args) {
        SpringApplication.run(OrderServiceApplication.class, args);
    }
}

The class does what Program.cs does in ASP.NET Core. It starts the application. It registers nothing itself, because component scanning finds the service's own classes. For why the class must be in the base package, see the section Which packages are scanned. The platform's beans come from auto-configuration. For how, see the chapter Writing the platform library.

The test tree has the same packages as the main tree. A test of com.acme.orderservice.order.domain.model.Order is com.acme.orderservice.order.domain.model.OrderTest. So the test sees the package-private members of the class it tests. The name of a test class also decides when it runs:

For how Maven chooses the tests by name, see the section Fast tests and integration tests.

Features at the top, never technologiesnew#

A product owner asks for a new rule. A note in the category DELIVERY must name a delivery date. In a service organised by technology, the change touches four folders, one for each technology. They are the controllers, the services, the repositories and the data transfer objects (DTOs). Four folders change for one business change. Each of those folders also holds the classes of every other business area.

The rule of the shop is that the top-level packages are features, never technologies. A feature is a business capability that a business user recognises. The order service has three features. Each one uses a different level of Domain-Driven Design (DDD):

Two packages at the top are not features. migration holds the database changes, and shared holds a few small helpers. For both, see the section The same sub-packages in every feature.

Each package says what it holds in its own documentation. Here is the order feature's:

/**
 * Orders: what a customer bought, the lines that warehouse staff pick, the payment, and shipping.
 *
 * <p>This feature uses the full style. Its {@code domain} package is plain Java with typed IDs.
 * The {@code persistence} package stores the aggregate as a separate document through a mapper,
 * behind the {@code OrderRepository} port. The stock service is called through the
 * {@code StockChecker} port.
 *
 * <p>The rules: an order is placed only if the stock service confirms and holds the products.
 * An order ships only when it is paid, every line is picked, and no note on it needs action. A
 * payment is recorded from the payment service's event, and a repeated or late one changes nothing.
 */
package com.acme.orderservice.order;

The comment stands before the line package com.acme.orderservice.order;, so it documents that package. For the file package-info.java, see the section Documenting a package. For the levels, see the chapter How much DDD: three levels in one service.

The shop has three reasons for this rule:

• One change touches one folder. The new rule about delivery notes changes the note package only. A reviewer quickly sees which business area changed.
• A feature can become a service. If the notes grow into a product of their own, the note package moves to a new repository as it is. Its dependencies on other features are already few and visible.
• Engineers move between services. A company with eight or ten services has the same layout in each. A developer who knows one service can work in the next one from the first day.

The rule holds even for a service with one feature. A service that only keeps invoices still has the package com.acme.invoiceservice.invoice. The extra level costs one folder. In return, the second feature has a place to go, and the layout matches every other service.

A layout by technology has a strong version too. Its best argument is that a developer who looks for "the controllers" finds them in one place. Many ASP.NET Core projects start this way, with folders such as Controllers and Services. For a small service with one business area, the layout works well. It stops working when the service has several business areas. Then each technology folder mixes them, and any class can call any other class in the same folder. The shop has many services that grow, so it chooses features from the start.

The same sub-packages in every featurenew#

Inside a feature, the sub-packages are always the same, and each has one job. Here is the order feature, the most complete one:

order/
├── OrderConfig.java          ← the feature's wiring, for beans without @Component
├── package-info.java         ← what the feature is, and its rules
├── domain/                   ← plain Java: the model and its rules
│   ├── model/                ← Order, OrderLine, OrderId, Money and the other value objects
│   ├── event/                ← OrderPlaced, OrderShipped and the other domain events
│   ├── exception/            ← OrderNotPaidException and the other rule violations
│   ├── repository/           ← OrderRepository, the port for storing orders
│   └── service/              ← ShippingPolicy, a rule across two aggregates
├── application/              ← the use cases: OrderService, OrderView, PlacedOrder
│   └── port/                 ← StockChecker, the port to the stock service
├── api/                      ← OrderController, OrderApiMapper
│   └── dto/                  ← PlaceOrderRequest, OrderResponse, OrderPlacedResponse
├── persistence/              ← OrderDocument, OrderDocumentMapper, OrderPersistenceAdapter
├── client/                   ← StockHttpClient, StockAdapter, StockClientConfig
│   └── dto/                  ← ReservationRequest, ReservationResponse
└── messaging/                ← OrderIntegrationEventMapper, PaymentReceivedListener
    └── event/                ← OrderPlacedV1, OrderShippedV1, OrderCancelledV1

The folders inside domain tell quickly what a class is. A class in domain/event is something that happened. A class in domain/exception is a broken rule. Without the folders, the domain package of a large feature holds thirty classes in one list.

A feature leaves out the sub-packages it does not need. The note feature calls no other service and sends no event to other services. So it has no client and no messaging. It also uses the light style, so it has a model package in place of domain and persistence:

note/
├── package-info.java
├── model/          ← Note, which is also the stored document, NoteRepository, its events and exceptions
├── application/    ← NoteService, NoteView, NewNote
└── api/            ← NoteController, NoteApiMapper
    └── dto/        ← AddNoteRequest, NoteResponse, NoteAddedResponse

So NoteRepository is in model/, next to Note, and no mapper exists. The reference feature uses the simple level. It has no domain model at all:

reference/
├── ReferenceConfig.java    ← turns on caching
├── package-info.java
├── application/            ← ReferenceDataService, ReferenceItemView, ReferenceTypes
├── api/                    ← ReferenceDataController
│   └── dto/
└── persistence/            ← ReferenceItemDocument, ReferenceItemRepository

So the three features do not have exactly the same sub-packages. The names are the same wherever a feature has the part. A persistence package always stores data, and an api package always translates HTTP. The rules of the platform rely on the names, so a name that means something else in one feature would break a rule. For why the levels differ, see the section Choosing the level for each feature.

Two top-level packages are not features. The migration package holds the database changes. It changes the storage of every feature, so it is next to the features:

/**
 * The service's database changes: indexes and seed data, as {@code MongoMigration} beans. The
 * platform's runner applies each one once, in ID order, before the service takes traffic.
 *
 * <p>This is not a feature. It changes the storage of every feature, so it sits beside them.
 * Never edit a migration that has run anywhere; add the next one.
 */
package com.acme.orderservice.migration;

Each migration is a MongoMigration bean. For the migrations, see the chapter Migrations, indexes and seed data. The shared package has its own section, The shared package, and what stays out of it.

What goes wherenew#

A developer writes a class that turns a PlaceOrderRequest into domain values. Does it go into api or into application? The shop answers such questions with one table. Each kind of class has one package. The last column says which other packages a class there may use:

A DTO is a class that only carries data across a boundary, such as the JSON body of a request. The class that turns a PlaceOrderRequest into domain values reads a DTO, so it belongs in api. In the order service, that class is OrderApiMapper.

The domain model has a base class for each kind of concept. The order is the root of an aggregate, called an aggregate root:

public class Order extends AggregateRoot<OrderId> {

OrderLine extends Entity<LineId>. OrderId and LineId extend Identifier. Money and DeliveryMethod are records that implement ValueObject. For each base class, see the chapter The domain model in plain Java.

An exception in the domain extends one of three kinds. The kind decides the HTTP status that the platform answers with:

For the problem responses, see the chapter The web layer in depth.

The OrderConfig class at the feature's root creates the beans that cannot carry @Component:

/**
 * Creates the order feature's beans that cannot carry {@code @Component}: the domain is plain
 * Java, so its classes have no Spring annotation.
 *
 * <p>{@code proxyBeanMethods = false} tells Spring not to wrap this class in a proxy. The bean
 * methods never call each other, so the proxy would only cost startup time.
 */
@Configuration(proxyBeanMethods = false)
class OrderConfig {

    @Bean
    ShippingPolicy shippingPolicy() {
        return new ShippingPolicy();
    }
}

ShippingPolicy is a domain service, so it may not import Spring. The feature's root package is the one place where Spring meets the domain. For @Bean methods, see the chapter Wiring the service: the container in depth.

The direction of the dependenciesnew#

The table in the section above has a pattern. The outer packages use the inner ones, and never the other way round. The domain is at the centre, and it depends on nothing. The use cases are in the application package. The integration events are in the messaging package:

Each box holds one kind of building block. The order feature has one of each:

A port points inwards. The domain declares OrderRepository in its own types, such as Order and OrderId. The persistence package implements it with MongoDB. So the domain needs no MongoDB type, and a test of the domain needs no database.

The anti-corruption layer is one adapter with an extra job. The stock service speaks of a sku and an answer INSUFFICIENT_STOCK. Those words stop in StockAdapter:

/**
 * Implements the {@link StockChecker} port over HTTP. It is the anti-corruption layer: the stock
 * service's words, such as {@code sku} and {@code INSUFFICIENT_STOCK}, stop here, and the rest
 * of the service sees only {@link StockAvailability}.

The rest of the service sees only StockAvailability, a value object of the order's domain. For the adapter in full, see the chapter Calling other services.

A view protects the aggregate from its callers:

/**
 * What callers of the order feature see of an order: plain data, never the aggregate. A caller
 * therefore cannot call {@code order.ship()} and skip the use case's steps.
 *
 * <p>The customer's contact is left out. A view carries personal data only when a use case
 * needs it.
 */
public record OrderView(String orderId, String status, String deliveryMethod, Instant placedAt, Instant shippedAt,
                        Instant cancelledAt, List<Line> lines, LastPayment lastPayment) {

If the controller got an Order, it could call order.ship() directly. Then nothing would check the notes, publish an event or write an audit record. A view has no such method. For the steps of a use case, see the chapter Use cases: the application service.

The light and simple features have fewer boxes. The note feature has no ports and no adapters. Its application service uses a Spring Data repository directly. So the diagram fits the full style exactly, and the other styles drop the adapter column.

Repositories in the domain, other services in the applicationnew#

Both OrderRepository and StockChecker are ports. Both are interfaces in the service's own types, and both have an adapter. But they are in different packages. The repository is in domain/repository:

/**
 * The port for storing orders, in the domain's own types. The persistence package implements it.
 * Lists are sorted newest first.
 */
public interface OrderRepository extends Repository<Order, OrderId> {

    /** Loads the order, or throws the 404 exception, so a use case loads in one line. */
    default Order get(OrderId id) {
        return findById(id).orElseThrow(() -> new OrderNotFoundException(id));
    }

The default method get loads an order or throws the 404 exception. The port to the stock service is in application/port:

/**
 * The port to the stock service, in this service's types. The use case does not know that the
 * answer comes over HTTP, and a unit test replaces it with a mock.
 *
 * <p>It lives in {@code application/port}, not in the domain: calling another service is a step
 * of the use case, and the domain only judges the answer.
 */
public interface StockChecker {

Both interfaces, OrderRepository and StockChecker, use only the service's own types. The reason for the two places is what each port means. Storage is part of the model. An order that cannot be stored and loaded again is not a useful order. So the domain declares what it needs from storage, and the persistence package decides how to do it.

A call to another service is a step of a use case. The use case asks the stock service, and then gives the answer to Order.place. The domain judges the answer, a StockAvailability, but never makes the call. So the port belongs to the application.

The placement has a second effect. A domain service such as ShippingPolicy may use only the domain. If StockChecker were in the domain, a domain service could call the stock service in the middle of a rule. A slow HTTP call would then hide inside the model, and perhaps inside a transaction. With the port in the application, only a use case can make the call, and it makes it before the transaction starts.

A careful team often puts every port in one place, either all in the domain or all in the application. Its argument is simple. A port is a port, so one rule should place them all. That works, and it is easier to explain. The shop separates the two kinds because the separation stops domain services from calling other services. If a team has no domain services, the benefit is small, and one place for all ports is a fine choice.

The rules a service followsnew#

The layout is not enough on its own. A developer can put a correct class in the correct package, and still read another feature's repository from it. So the shop writes its design as twelve rules. Each rule has a reason and a home chapter:

The last column names the chapter that teaches each rule. For example, rule 9 is taught in the chapter Transactions in depth. Rule 11 needs an outbox and an inbox. It is taught in the chapter Publishing events: the outbox and in the chapter Consuming events: SQS and the inbox.

Rule 1 is visible in the stored documents. Each collection, such as orders, belongs to this service alone:

@Document("orders")
class OrderDocument extends BaseDocument {

No other service reads the collection orders. The invoice service learns about an order from OrderPlacedV1, or asks the API. For the events, see the chapter API and event contracts.

A strict form of rule 6 also says that the application layer checks permissions. The order service does not follow that part. It checks permissions on the controllers, where users enter. For the reasons and the measured options, see the section Choosing the place by the shape of the service.

Rule 9 names one exception. Placing an order saves the order and its first notes in one transaction. For that exception, see the chapter Use cases: the application service. For why IDs cross as String in rule 7, see the section A type for a foreign ID, or plain text.

The rules as tests that fail the buildnew#

A rule that only a review checks is broken sooner or later. A reviewer is tired, or does not see an import at the top of a file. So the platform states the rules as ArchUnit rules. ArchUnit is a library that reads the compiled classes and checks their dependencies. Each service calls the rules from one plain JUnit test:

class ArchitectureTest {

    private static final String BASE = "com.acme.orderservice";
    /** The features in the full style, whose application layer must use ports only. */
    private static final String ORDER = BASE + ".order";

    private static final JavaClasses CLASSES = new ClassFileImporter()
            .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
            .importPackages(BASE);

    @Test
    void domainIsPlainJava() {
        ArchitectureRules.domainIsPlainJava().check(CLASSES);
    }

    @Test
    void applicationOfFullStyleFeaturesUsesNoAdapter() {
        ArchitectureRules.applicationDoesNotUseAdapters(ORDER).check(CLASSES);
    }
    // ...
    @Test
    void featuresUseEachOtherOnlyThroughApplication() {
        ArchitectureRules.featuresUseEachOtherOnlyThroughApplication(BASE).check(CLASSES);
    }

The test has ten rules. Each one guards a rule from the section above:

The rule for rule 4 lists what a domain package must not use:

/** A {@code domain} package uses no framework, no adapter and no other layer. */
public static ArchRule domainIsPlainJava() {
    return noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage(
                    "org.springframework..", "com.mongodb..", "org.bson..", "jakarta..",
                    "tools.jackson..", "com.fasterxml..", "io.awspring..",
                    "..application..", "..api..", "..persistence..", "..client..", "..messaging..",
                    "com.acme.platform.core..", "com.acme.platform.mongo..")
            .as("A domain package is plain Java");
}

The rule matches packages named domain. Only the order feature has one. The light note feature names its package model, because its entity carries Spring Data annotations. So the rule does not touch it, on purpose.

Rule 7 needs a condition of its own. ArchUnit has no ready rule for "a feature uses another feature only through its application package". So the platform writes it:

for (Dependency dependency : origin.getDirectDependenciesFromSelf()) {
    String target = dependency.getTargetClass().getBaseComponentType().getPackageName();
    String targetFeature = featureOf(basePackage, target);
    if (targetFeature == null || targetFeature.equals(feature) || targetFeature.equals("shared")) {
        continue;
    }
    String inFeature = target.substring((basePackage + "." + targetFeature).length());
    boolean allowed = inFeature.startsWith(".application") && !inFeature.startsWith(".application.port");
    if (!allowed) {
        events.add(SimpleConditionEvent.violated(dependency, dependency.getDescription()));
    }
}

So the note feature may call OrderService.requireExists. It may not import Order, OrderRepository or OrderDocument. The order feature may pass a NewNote to the note feature, because NewNote is in the note feature's application package:

/**
 * A note to add, in plain values. The order feature passes it when it places an order with its
 * first notes, so no note type crosses into the order feature.
 */
public record NewNote(String text, String category, boolean actionRequired) {
}

NewNote holds plain values, so no type of the note's model reaches the order feature. A rule that never fails proves nothing. So the service also has tests that feed each rule a class that breaks it, and expect the rule to fail. For those tests, for the freezing of old violations, and for the other ArchUnit rules, see the chapter Testing in depth.

Package-private classes hide the adapterstwist#

In the order service, the adapters, the stored documents, the controllers and the configuration classes have no access modifier. Here is the stored document of an order, beside an internal class in C#:

internal sealed class OrderDocument
{
    public string? CustomerName { get; set; }
}

/**
 * How an order is stored: one document per aggregate, with its lines and last payment embedded.
 *
 * <p>The lines are embedded because they are few (at most 50) and every order rule needs them.
 * Notes are not: they have no limit, and embedding them would rewrite the whole order for each
 * new note. A document must stay under 16 MB.
 *
 * <p>Only plain types are stored. Enums and codes are strings, so renaming a Java class never
 * breaks stored data. Money is DECIMAL128, so it is exact. The class and its fields are
 * package-private: nothing outside this package knows the storage shape.
 */
@Document("orders")
class OrderDocument extends BaseDocument {

    String customerName;
    String customerEmail;

A class with no access modifier is package-private in Java. Only classes in the same package can use it. For the access levels, see the section The mapping.

The C# class is internal, so the whole assembly can use it. The Java class is narrower. Only the package com.acme.orderservice.order.persistence can use it. Even the package com.acme.orderservice.order, which looks like its parent, cannot. For that trap, see the section A package inside a package.

The service makes these classes package-private:

Spring creates beans of package-private classes. The adapter's class and its constructor are both package-private:

@Component
class OrderPersistenceAdapter extends MongoAggregateRepository<Order, OrderId, OrderDocument> implements OrderRepository {
    // ...
    OrderPersistenceAdapter(OrderMongoRepository orderDocuments, OrderDocumentMapper mapper) {

The use case asks for an OrderRepository. Spring finds the one bean that implements it and injects it. The use case never names the adapter, and the compiler would stop it if it tried. The companion's ApplicationWiringTest starts the whole service, so it shows that Spring builds these beans.

So package-private does a second job. It is a rule that the compiler checks. No class outside order.persistence can depend on the storage shape, because it cannot see it.

Some classes must stay public, because another package uses them:

• The domain classes, because the application, api, persistence and client packages use them.
• The ports, OrderRepository and StockChecker, because their adapters are in other packages.
• The application services and views, because the controllers and other features call them.
• The DTO records in api.dto, because the controller in api uses them. A sub-package is a different package.
• In the light note feature, Note and NoteRepository, because NoteService in the application package uses them directly.
• In the reference feature, ReferenceItemDocument and ReferenceItemRepository, because ReferenceDataService uses them directly.

The last two items are part of what the lighter levels give up. Without a port, the application uses the storage types, so they cannot hide.

Documenting a packagetwist#

A new developer opens the reference package and wonders why it has no domain. The answer is in a file in the package itself:

/// <summary>The building blocks of a domain model.</summary>
namespace Shop.Platform.Domain
{
    /// <summary>A marker for value objects.</summary>
    public interface IValueObject { }
}

/**
 * Lookup values, such as delivery methods and note categories, for drop-down lists and for
 * checking codes. The data changes only with a deployment, through a seed migration.
 *
 * <p>This feature uses the simple level: no aggregate, no domain model and no events. A
 * document record, a Spring Data repository, and the logic in the application service. Read-only
 * lookup data has no business behaviour, so DDD's building blocks would only add files.
 */
package com.acme.orderservice.reference;

The C# compiler does not accept an XML comment on a namespace. It warns with CS1587, "XML comment is not placed on a valid language element". In Java, a file named package-info.java holds the package declaration and one documentation comment for the whole package. The javadoc tool shows that comment on the package's page.

The service has a package-info.java in each feature and in shared and migration. The platform has one in its domain package. Each says what the package is for and what it must not hold. A rule such as "this package is plain Java" is then written beside the code it governs.

A documentation comment in Java is called a Javadoc comment. It starts with /**. The comments in the companion use four tags:

Here {@value} keeps a comment true when the constant changes:

/**
 * Which page of a list to return, without any Spring type. Pages count from zero.
 *
 * @param page the page number, from 0
 * @param size the number of items on a page, from 1 to {@value #MAX_SIZE}
 */
public record PageQuery(int page, int size) implements ValueObject {

    public static final int MAX_SIZE = 100;

javadoc writes "from 1 to 100" on the page of PageQuery. If someone changes MAX_SIZE, the page changes with it. @param documents one parameter. On a record, it documents a component.

A block of example code uses <pre>{@code ... }</pre>:

* <p>A service calls them from a plain JUnit test:
*
* <pre>{@code
* ArchitectureRules.domainIsPlainJava().check(classes);
* }</pre>

{@code} stops javadoc from reading the angle brackets as HTML. The tag <pre> keeps the line breaks. <p> starts a new paragraph, because javadoc joins the lines of a comment into one paragraph otherwise.

Why not adapter/in and adapter/outnew#

Hexagonal architecture is also called ports and adapters. It is a well-known layout for services like this one. A careful hexagonal service has packages such as these:

order/
├── domain/
├── application/
│   └── port/
│       ├── in/       ← the use-case interfaces that the outside calls
│       └── out/      ← the interfaces that the use cases need
└── adapter/
    ├── in/
    │   ├── web/      ← the controllers
    │   └── messaging/
    └── out/
        ├── persistence/
        └── stock/

This layout gets a lot right. It names the direction of every port. It makes the adapters look alike, so a reader quickly sees that the web and the queue both drive the use cases. Each use case also gets an interface of its own, so a controller depends on an interface, not on a class.

The shop has the same ports and adapters, with fewer folders. api and messaging are the driving adapters. persistence and client are the driven adapters. The shop leaves out the extra folders for three reasons:

• The protection comes from the direction of the dependencies. A folder named adapter/out stops nothing. A test that fails when the domain imports MongoDB stops the mistake. The shop has that test, so the folder names add little.
• An interface for every use case has a cost and little benefit here. The order service has one implementation of each use case. A controller test mocks the class OrderService as easily as an interface. So port/in would double the files and protect nothing.
• The names match what developers say. A developer says "the API" and "the persistence". The packages use those words.

The hexagonal layout is the better choice in two cases. One is a team that already knows it well, across many services. Then the familiar names are worth more than the shorter tree. The other is a use case with several implementations, such as a product sold to customers who each add their own storage. Then port/in and port/out carry real meaning.

Why not one folder per use casenew#

Vertical slice architecture is another popular layout, and many .NET teams use it. Each use case gets a folder with everything it needs. A careful version looks like this:

orders/
├── placeorder/      ← the endpoint, the request, the handler, the validator
├── shiporder/       ← the same parts for shipping
├── cancelorder/
└── getorder/

The folder placeorder/ holds every class of one use case. Its best argument is strong. A change to one use case touches one folder, which is even narrower than one feature. Each slice can choose its own way to store and to read. A simple read can query the database directly, and a complex write can use a rich model. There is no shared layer that every change must pass through.

The difficulty is the aggregate. Placing, shipping and cancelling all change an order, and the rules of an order must hold in all three. In a strict slice layout, each slice changes the order in its own code. The rule "a shipped order cannot change" is then written in two slices, and the third slice can forget it. The shop's rule 5 says each business rule has one home. So the shop keeps one domain model per aggregate, shared by all its use cases.

A careful slice team solves this too. It keeps a shared domain folder, and the slices call the aggregate's methods. That is close to the shop's layout, with the application service split into one class per use case. The shop keeps one application service per feature. The steps of every use case are the same, and one class shows them side by side. For when to split that class, see the section Splitting a large application service.

Slices are the better choice for a feature with many independent use cases and few shared rules. Reports and searches are good examples. Each one reads differently, and no rule ties them together. A feature of that kind can use slices inside the shop's layout, under its application package.

One model for reads and writes: CQRS or notnew#

Command Query Responsibility Segregation (CQRS) splits a feature into two sides. The write side changes the aggregate and checks its rules. The read side answers queries from a separate model, which is shaped for the screens that read it. An event from the write side usually keeps the read model up to date.

The order service uses one model for both. A read loads the aggregate and turns it into a view. Here are the two read use cases of the order feature:

public OrderView get(OrderId orderId) {
    return OrderView.from(orders.get(orderId));
}

public PageResult<OrderView> list(OrderStatus status, PageQuery page) {
    PageResult<Order> result = status == null ? orders.findAll(page) : orders.findByStatus(status, page);
    return result.map(OrderView::from);
}

get loads one order and returns a view. list loads a page of orders, and map turns each one into a view. The same collection and the same documents serve reads and writes.

A careful CQRS design gets several things right. The read model has exactly the shape a screen needs, so a read is one fast query. Reads and writes can scale apart. And the write model never grows fields that only a screen uses. When those benefits are real, CQRS is worth its cost.

The cost is also real. The read model is a second copy of the data, kept up to date by events. So it is briefly out of date after every change, and every screen must allow for that. The team writes and tests the code that keeps the copy right. A replay is needed when the read model's shape changes. For a feature whose reads look like its aggregate, the team does all of that work and gains nothing.

CQRS has a second use, which matters here. The order feature and the note feature call each other. The order service asks the note service how many notes need action. The note service asks the order service whether an order exists. Both services take the other one in their constructors, and the companion breaks the cycle with @Lazy. For the cycle and its first three ways out, see the section Two features that call each other.

A query side gives a fourth way out. The count of notes that need action is a query. A small query class in the note feature could answer it, with no dependency on the order feature. The order feature would call the query class, and the note service would call the order service. Each dependency would then point one way. The companion does not do this, because it has no CQRS. Its README calls the cycle a warning sign, and it lists the other three ways out.

Splitting a large application servicenew#

An application service grows with its feature. OrderService has eight public methods today. A year later it may have fifteen, and its constructor may take twelve dependencies. The class is then hard to read, and every test builds all its dependencies. The class says how to split it:

 * <p>The class has no permission annotation. Permissions are checked on the controllers, where
 * users enter. Every method here can therefore be called by another feature or by a message
 * listener without a second, unprotected copy of the method.
 *
 * <p>With about ten use cases, split the class by area, such as {@code OrderFulfilmentService},
 * not into a read side and a write side.
 */
@Service
public class OrderService {

The name OrderFulfilmentService is an example of a class for one area. An area is a part of the business that the users recognise. The order feature has three. Placing an order is one. Fulfilment, which means picking, shipping and cancelling, is another. Payment is the third. Each area becomes one class in the application package, with the same steps in each method. The companion does not split the class yet, because it has only eight public methods.

A split into a read side and a write side looks tidy, but it is a weaker cut. Every change to fulfilment would touch both classes. It also makes the read class look like a read model, when it is not one. If a real read model is needed, see the section One model for reads and writes: CQRS or not.

Three points keep a split safe:

• The private helper saveAndPublish saves, publishes the events and records the audit. After a split, each class needs it. Move it to a package-private class in the same package, so no other feature can call it.
• Other features call the new class that owns the use case. The rule featuresUseEachOtherOnlyThroughApplication still holds, because every new class is in the application package.
• A split is not a reason to add a rule to the application service. The rules stay in the domain, whatever the number of application classes.

A split is a sign to check the aggregate too. Fifteen use cases on one aggregate can mean that the aggregate holds two things. For those signs, see the section Signs of an aggregate that is too big.

The shared package, and what stays out of itnew#

Every feature needs the permission annotations @OrdersRead and @OrdersWrite. Every feature writes the same names to the audit log. Those classes belong to no single feature. They are in shared:

/**
 * Small helpers that every feature of this service uses: the permission annotations, the audit
 * names and the OpenAPI description. It holds no business logic. Code that several services
 * need belongs in the platform instead.
 */
package com.acme.orderservice.shared;

The comment names the three kinds of helper and says that shared holds no business logic. Here are the audit names:

/** The names this service writes to the audit log, kept in one place so they stay consistent and searchable. */
public final class AuditActions {

    public static final String ORDER = "order";
    public static final String NOTE = "note";

    public static final String ORDER_PLACED = "ORDER_PLACED";

The class is final, so no class can extend it. It holds only constants. A search for ORDER_PLACED then finds every place that writes the action, and the audit log always uses the same spelling.

The package has three parts:

A shared package often grows until it holds anything. So it has two limits. It holds no business logic, because a rule belongs in a feature's domain. And it holds nothing that other services need, because that belongs in the platform. For the permission annotations, see the section Permission annotations: each scope string written once.

The three repositories in real lifenew#

The companion is one folder with three sub-folders. Its root pom.xml builds the platform and the service together:

<!--
  Builds the platform and the order service together, for the book only.

  In a real company, shop-platform, order-service and local-environment are three separate
  repositories. This file lets one command build and test everything:

      mvn verify           unit, slice, wiring and architecture tests (no Docker needed)
      mvn verify -Pit      also the integration tests (*IT), which start containers in Docker
-->
<!-- ... -->
    <modules>
        <module>shop-platform</module>
        <module>order-service</module>
    </modules>

The two <module> lines name the two folders that Maven builds. mvn verify -Pit also runs the tests that need Docker. In real life, nothing builds the platform and a service together. The platform team releases a version of the library. Each service names that version and builds alone. The local environment is a third repository, with no Java at all. For the repositories and who uses each one, see the section Three repositories: platform, service and local environment. For the POMs, see the chapter The build: a parent POM and a platform library.

The separation has a reason. If the order service built against the platform's source, a change in the platform would reach every service at once, untested. With a released version, each service chooses when to upgrade. For the rules of that upgrade, see the section Versions, and the rules for upgrading.

Rule 12 is kept by the local environment. WireMock answers for each HTTP service, with one folder of stubs per service. Floci emulates the AWS resources. So every dependency runs on a laptop:

# Imitates the HTTP services that shop services call. The stubs are in wiremock/mappings/<service>/.
wiremock:
  image: wiremock/wiremock:3.13.0
  command: ["--global-response-templating", "--verbose"]
  volumes: ["./wiremock:/home/wiremock"]
  ports: ["8089:8080"]

# Local SNS and SQS: Floci, a free emulator with LocalStack's API, on port 4566.
floci:
  image: floci/floci:2.3.0
  ports: ["4566:4566"]

The container wiremock serves the stubs, and the container floci answers the calls to Amazon Simple Notification Service (SNS) and Amazon Simple Queue Service (SQS). The folder wiremock/mappings/stock-service holds the stubs of the stock service. For the local environment in full, see the chapter Running locally and shipping.

A reader new to the companion can read it in this order. Each step builds on the one before it:

1. The order service's README.md, for the rules and the decisions.
2. The package order/domain/model, with Order, and its test OrderTest.
3. OrderService, for the steps of every use case.
4. The adapters, OrderPersistenceAdapter and StockAdapter.
5. The note feature, to compare the light style with the full style.
6. The platform library, for everything the service gets without writing it.

The service's READMEnew#

An engineer on call is woken at night. The order service answers 503 for new orders. They need to know what the service depends on, and what happens when each dependency is down. That fact must be in a known place in every service. So every shop service has a README with the same headings:

Here is the section that the engineer on call needs:

| Dependency | Used for | When it is down |
|---|---|---|
| DocumentDB | all data | readiness is DOWN, so no traffic arrives; liveness stays UP, so instances are not restarted |
| stock service | placing an order | only `POST /orders` answers 503; everything else works |
| SNS | publishing events | events wait in the outbox and are resent |
| SQS | payments | payments wait in the queue |
| token issuer | checking tokens, and the stock call's own token | requests get 401; placing an order gets 503 |

The answer is in the second row. Only POST /orders depends on the stock service. Every other endpoint works, so the incident is smaller than it looks.

The section "Decisions" is the most useful one for a reviewer. Each entry states a choice, such as "Permissions are checked on the controllers", with its reason and its limits. A team that writes architecture decision records can link them from here. The README keeps the short version beside the code.

internal sealed class OrderDocument
{
    public string? Status { get; set; }
}

@Document("orders")
class OrderDocument extends BaseDocument {

    String customerName;
    String customerEmail;
    String deliveryMethod;
    String status;

The build: a parent POM and a platform library#

Five build files, five jobsnew#

A developer opens the companion and finds five files named pom.xml. Some of them build code, and some only list other folders. Each POM has one job:

Two kinds of POM appear here. They are easy to mix up, because both have <packaging>pom</packaging>:

• An aggregator lists folders in <modules>. Maven builds each folder when the aggregator builds. The children do not inherit anything from the aggregator.
• A parent is named in a child's <parent> element. The child inherits the parent's properties, dependencies, managed versions and plugins. The parent does not know its children.

The platform's aggregator lists the parent and the library:

<!--
  Builds the parent POM and the platform library together. It is never published.
  In the platform's own repository, this file is the root pom.xml.
-->
<!-- ... -->
    <groupId>com.acme.platform</groupId>
    <artifactId>shop-platform-build</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <modules>
        <module>shop-platform-parent</module>
        <module>shop-platform</module>
    </modules>

The file is never published, because no project depends on shop-platform-build. It only lets one command build both modules. The parent and the library are published, because services name them. For aggregators in general, see the section Multi-module: your solution file.

The root pom.xml of the companion is an aggregator of the same kind, with the modules shop-platform and order-service. It exists only so that one command builds and tests the book's code. For why real services never build together, see the section The three repositories in real life.

The parent POM, on top of Spring Boot's parenttwist#

The shop's parent has a parent of its own. It is the parent POM of Spring Boot:

<!--
  The parent POM of every shop service and of the platform library.

  It sets the Java release, the build plugins and the version of every dependency.
  A service never writes a version number itself. To upgrade Spring Boot for every service,
  change the parent below and release a new platform version.
-->
<!-- ... -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.2</version>
        <relativePath/>
    </parent>

    <groupId>com.acme.platform</groupId>
    <artifactId>shop-platform-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <properties>
        <java.version>25</java.version>
        <shop-platform.version>1.0.0-SNAPSHOT</shop-platform.version>

The chain has three levels. A service inherits from shop-platform-parent, which inherits from spring-boot-starter-parent. A setting in a lower level replaces the same setting in a higher level. So a service could set java.version itself. It should leave the setting alone, so that every service runs on the same Java release.

The closest match in .NET is a Directory.Build.props file. MSBuild finds it in a folder above the project and applies it. A run for this book put the target framework in such a file, and the project built with it:

<Project>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>12</LangVersion>
    <Nullable>enable</Nullable>
  </PropertyGroup>
</Project>

<properties>
    <java.version>25</java.version>

The C# pane sets TargetFramework for every project below the file. The Java pane sets java.version for every child. The two files differ in how a project finds them. Directory.Build.props is found by its folder. So it works only when the project is in a folder below it, in the same repository. The shop's parent is found by its coordinates, a group, an artifact and a version. So a service in a repository of its own still gets it from the company's artifact repository.

One place for every version: managed versions and BOMstwist#

The shop uses libraries that Spring Boot does not manage, such as Spring Modulith and Resilience4j. Their versions are properties in the parent. Each property is used once, in the section dependencyManagement:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Shop.Platform" Version="1.0.0" />
  </ItemGroup>
</Project>

    <!-- Libraries that Spring Boot does not manage -->
    <spring-modulith.version>2.1.2</spring-modulith.version>
    <spring-cloud-aws.version>4.1.0</spring-cloud-aws.version>
    <resilience4j.version>2.4.0</resilience4j.version>
    <shedlock.version>7.10.1</shedlock.version>
    <springdoc.version>3.2.0</springdoc.version>
    <archunit.version>1.5.1</archunit.version>
    // ...
<dependencyManagement>
    <dependencies>
        <!-- Each BOM fixes the versions of a family of artifacts, like Directory.Packages.props -->
        <dependency>
            <groupId>org.springframework.modulith</groupId>
            <artifactId>spring-modulith-bom</artifactId>
            <version>${spring-modulith.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

The versions are the ones the companion builds with, as of October 2026. Upgrading Resilience4j means changing one property.

A bill of materials (BOM) is a POM that only lists managed versions. The element <scope>import</scope>, on a dependency of type pom, copies the BOM's managed versions into this POM. Spring Modulith publishes a BOM for all its modules. So the platform library can add spring-modulith-events-core and spring-modulith-events-mongodb with no version, and both get 2.1.2. For the basics of BOMs, see the section Profiles and BOMs.

The parent imports four BOMs. They are the BOMs of Spring Modulith, Spring Cloud AWS, Resilience4j and ShedLock. If two imported BOMs manage the same artifact, the BOM declared first wins. An entry written directly in dependencyManagement wins over every import. So the order of the imports matters, and a direct entry is the way to settle a clash.

Both sides of the comparison manage versions in one place. In the run for this book, the project then referenced Shop.Platform with no version, and the build used 1.0.0. A POM's dependencyManagement has the same effect. It adds no dependency by itself. It only gives a version to a dependency that a POM declares without one.

Some artifacts are in no imported BOM. Each of them needs an entry of its own:

<!-- Artifacts that no imported BOM covers, so they are pinned one by one -->
<dependency>
    <groupId>io.awspring.cloud</groupId>
    <artifactId>spring-cloud-aws-modulith-events-sns</artifactId>
    <version>${spring-cloud-aws.version}</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>${springdoc.version}</version>
</dependency>
<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit</artifactId>
    <version>${archunit.version}</version>
</dependency>
<dependency>
    <groupId>com.networknt</groupId>
    <artifactId>json-schema-validator</artifactId>
    <version>${json-schema-validator.version}</version>
</dependency>

<!-- The platform library itself -->
<dependency>
    <groupId>com.acme.platform</groupId>
    <artifactId>shop-platform</artifactId>
    <version>${shop-platform.version}</version>
</dependency>

spring-cloud-aws-modulith-events-sns belongs to Spring Cloud AWS, but the spring-cloud-aws-dependencies BOM does not list it. So the parent pins it with the same version property. springdoc-openapi, ArchUnit and the JSON Schema validator have no BOM that the parent imports. The last entry is the platform library. Because of it, a service names shop-platform with no version.

Test libraries for every service, from the parentnew#

Every shop service tests with the same libraries. A service that forgets one cannot use the platform's test support. So the parent declares the test libraries as real dependencies, not only as managed versions:

<!--
  Test libraries for every service. Each child inherits them with the test scope,
  so they never reach a production jar, and a service declares only shop-platform.
-->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webmvc-test</artifactId>
        <scope>test</scope>
    </dependency>
    // ...
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-mongodb</artifactId>
        <scope>test</scope>
    </dependency>

A <dependencies> section in a parent is inherited by every child. So each service has these libraries, though its own POM does not name them. The scope test puts a library on the test classpath only. The run for this book listed the order service's dependency tree:

[INFO] com.acme:order-service:jar:1.0.0-SNAPSHOT
[INFO] +- com.acme.platform:shop-platform:jar:1.0.0-SNAPSHOT:compile
[INFO] +- org.springframework.boot:spring-boot-starter-cache:jar:4.1.2:compile
[INFO] +- org.springframework.boot:spring-boot-starter-test:jar:4.1.2:test
[INFO] +- org.springframework.boot:spring-boot-starter-webmvc-test:jar:4.1.2:test
[INFO] +- org.springframework.boot:spring-boot-starter-data-mongodb-test:jar:4.1.2:test
[INFO] +- org.springframework.boot:spring-boot-starter-security-test:jar:4.1.2:test
[INFO] +- org.springframework.boot:spring-boot-testcontainers:jar:4.1.2:test
[INFO] +- org.testcontainers:testcontainers-mongodb:jar:2.0.5:test
[INFO] +- com.tngtech.archunit:archunit:jar:1.5.1:test
[INFO] +- org.awaitility:awaitility:jar:4.3.0:test
[INFO] \- com.networknt:json-schema-validator:jar:3.0.8:test

The service's own POM names only the first two. Every line after them ends in test, so none of these libraries is in the executable jar. The same run listed the jar's contents. It held 196 libraries, and none of them was a test library.

The parent has nine test dependencies:

The MongoDB artifact has a Testcontainers 2 name, testcontainers-mongodb. Its class is org.testcontainers.mongodb.MongoDBContainer. The old class in org.testcontainers.containers still exists and is deprecated. The new class starts a replica set only after withReplicaSet(), and transactions need a replica set. For the trap in that change, see the chapter Testing in depth.

The name of a test class decides whether it runstrap#

A developer adds a test class for the shipping rules. The name OrderCheck seems clear. The test fails on purpose, to see it fail. The developer runs the build:

class OrderCheck {

    @Test
    void anOrderShipsOnlyWhenPaid() {
        fail("this should fail the build");
    }
}

The shop names a test by what it tests, plus Test or IT. OrderTest tests Order, and OrderPersistenceAdapterIT tests the adapter against a database. A test class that matches no pattern is the more dangerous mistake, because a green build hides it.

Fast tests and integration testsnew#

The order service has two kinds of test. Most of them need nothing but the Java Virtual Machine (JVM), and they run in seconds. A few start MongoDB or an AWS emulator in Docker, and Docker is not always running. So the build runs the two kinds apart:

Surefire is the plugin that runs unit tests in the phase test. Failsafe is the plugin that runs integration tests in the phases integration-test and verify. Failsafe's default patterns are IT*, *IT and *ITCase. For the phases, see the section The lifecycle.

The parent configures both plugins in pluginManagement:

<pluginManagement>
    <plugins>
        <!-- ... -->
        <!-- mvn verify runs the fast tests only: *Test.java. The *IT.java tests need Docker. -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <configuration>
                <argLine>@{argLine} -javaagent:${org.mockito:mockito-core:jar}</argLine>
                <excludes>
                    <exclude>**/*IT.java</exclude>
                </excludes>
            </configuration>
        </plugin>

The parent's <plugins> section adds the plugin that sets the property. Its comment gives the reason for the agent:

<!--
  Sets the property org.mockito:mockito-core:jar to the jar's path, so the test JVMs
  below can load Mockito as an agent at startup. Loading it later, on first use, prints
  a warning on current JDKs, which will block it in a future release.
-->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>properties</goal>
            </goals>
        </execution>
    </executions>
</plugin>

The goal properties of maven-dependency-plugin sets one property for each dependency, named by its coordinates, with the path of its jar. This plugin is in <plugins>, not in pluginManagement, so it runs in every child.

A run for this book removed the agent from the test JVM and ran OrderServiceTest on Java Development Kit (JDK) 26.0.1. The tests passed, and the output warned twice:

Mockito is currently self-attaching to enable the inline-mock-maker. This will no longer work in future releases of the JDK.
WARNING: A Java agent has been loaded dynamically (/Users/kodebot/.m2/repository/net/bytebuddy/byte-buddy-agent/1.18.15/byte-buddy-agent-1.18.15.jar)
WARNING: Dynamic loading of agents will be disallowed by default in a future release

So without -javaagent, Mockito loads its agent itself while the tests run, and the JDK warns that a future release will block that. With the agent named at startup, no warning appears.

Failsafe runs only in the profile it:

<profiles>
    <!-- mvn verify -Pit also runs the integration tests (*IT.java) with Testcontainers. -->
    <profile>
        <id>it</id>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-failsafe-plugin</artifactId>
                    <executions>
                        <execution>
                            <goals>
                                <goal>integration-test</goal>
                                <goal>verify</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </profile>

A Maven profile is a named block of the build that -P switches on. This one names failsafe in <plugins> and binds its two goals. The goal integration-test runs the *IT classes. The goal verify fails the build if one of them failed.

The parent has a second profile, contract-first. It runs openapi-generator-maven-plugin 7.26.0, which generates Java interfaces and models from a service's contracts/openapi.yaml before the code compiles. The profile is switched on by a property, not by -P. It needs two conditions. The build must set -Dcontract-first, and the module must have the file contracts/openapi.yaml. Maven 3.9 switches a profile on only when all its conditions hold. So the platform's modules, which have no contract, skip it. A run of mvn verify -Dcontract-first on the companion generated the code, compiled it with the service, and passed. For what the profile is for, and when to choose it, see the section Contract first: openapi-generator.

Boot's parent has failsafe in its own pluginManagement, with the same two goals. That alone runs nothing. The run for this book confirmed it. A plain mvn verify on Boot's parent did not run OrderIT. It ran only in a profile that names the plugin.

The choice of a profile has a reason. A developer without Docker still gets a full, green mvn verify. The build server runs mvn verify -Pit, where Docker is always there. For what each kind of test covers, see the chapter Testing in depth.

What the library brings to every servicenew#

A service adds one dependency, shop-platform. Through it, the service gets every library that the platform uses. The library's POM groups them by concern:

<dependencies>
    <!-- Web, validation and health -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    // ...
    <!-- Security: each service checks JWTs (resource server) and gets tokens for its own calls (client) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security-oauth2-resource-server</artifactId>
    </dependency>

The first starter, spring-boot-starter-webmvc, brings Spring model-view-controller (MVC) and the embedded server. Each dependency is a compile dependency with no version. Its version comes from the parent. Every project that uses the library also gets the library's compile dependencies. So each of these reaches the service's classpath, and its auto-configuration runs there:

So the order service's POM names none of these. It needs only one extra starter, for its cache. For what each concern adds at run time, see the chapter Writing the platform library.

One library for everything has a cost. A service that sends no events still has the messaging libraries on its classpath. The platform answers with a switch that turns messaging off. For the switch, and for why the shop chose one library over one per concern, see the section One library, not one per concern.

The Boot 4 starter namestwist#

A tutorial for Boot 3 adds spring-boot-starter-web. The shop's library adds spring-boot-starter-webmvc. Spring Boot 4 named its modules after their technology, in the form spring-boot-<technology>. These are the starters that the shop uses:

The library adds the two security starters under their Boot 4 names:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security-oauth2-resource-server</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security-oauth2-client</artifactId>
</dependency>

The second <artifactId> is the Boot 4 name of the OAuth2 client starter. With the old name spring-boot-starter-oauth2-client, the build would still work in 4.1.2, but the starter is deprecated. For the general renames, see the section Starters. For a whole upgrade from Boot 3, see the chapter Migrating Spring Boot 3 to 4.

Optional dependencies: test support without test librariestwist#

The platform ships test support, such as the annotation @PlatformWebMvcTest and ArchitectureRules. That code is in the library's main source, so it must compile against JUnit, Spring's test support and ArchUnit. But a service's production jar must never contain those libraries:

<ItemGroup>
  <PackageReference Include="xunit.assert" Version="2.9.3" PrivateAssets="all" />
</ItemGroup>

<!--
  Needed only by com.acme.platform.test. They are optional, so they never reach a
  service's production classpath. Services get them, test-scoped, from the parent POM.
-->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <optional>true</optional>
</dependency>
// ...
<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit</artifactId>
    <optional>true</optional>
</dependency>

<optional>true</optional> marks a dependency that this project needs, but a project that uses it does not. The library compiles against ArchUnit. A service that depends on the library does not get ArchUnit from it. The run for this book showed both sides. In the library, ArchUnit is compile (optional). In the service, ArchUnit is test, because it comes from the parent's test dependencies.

PrivateAssets="all" has the same purpose in .NET. A run for this book packed a library with that attribute on xunit.assert. The dependency list of the packed file held its other reference, and not xunit.assert.

So the two parts work together. The library compiles its test code with optional dependencies. The parent gives each service the same libraries with the test scope. A service's test code can then use @PlatformWebMvcTest, and its production jar holds none of it.

The configuration processor, and the file it did not writetrap#

A developer types platform. in application.yml and expects the IDE to complete the platform's settings. An IDE does that from a file named META-INF/spring-configuration-metadata.json in the library's jar. The annotation processor spring-boot-configuration-processor writes the file while the library compiles. It reads every @ConfigurationProperties class.

The usual advice is to add the processor to the library as an optional dependency. The companion's library did that first, and the file was missing.

So the parent names the processor in the compiler's configuration, in its pluginManagement:

<!--
  Runs Spring Boot's configuration processor while the code compiles. It writes
  META-INF/spring-configuration-metadata.json from each @ConfigurationProperties
  class, so an IDE completes the keys. The processor must be named here: on JDK 26,
  a processor that is only a dependency did not run, and the file was missing.
  Boot manages the processor's version.
-->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-configuration-processor</artifactId>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

The setting is in pluginManagement, so it applies to every child of the parent. After the change, the build wrote the file into the library's jar. It held 16 keys in 9 groups, from platform.logging to platform.security. The order service's jar got a file too, with the four keys of clients.stock. Without the file, a service still starts and binds every setting. Only the completion in the IDE is missing. Check the library's jar for the file after a change to the build.

The service POM: almost nothingtwist#

With the parent and the library in place, a service's POM is short. Here it is in full, without its header:

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <PackageReference Include="Shop.Platform" />
  </ItemGroup>
</Project>

<!--
  The platform parent sets Java, the plugins and every dependency version.
  In this service's own repository, remove <relativePath>: the parent then comes from the
  company's artifact repository.
-->
<parent>
    <groupId>com.acme.platform</groupId>
    <artifactId>shop-platform-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <relativePath>../shop-platform/shop-platform-parent/pom.xml</relativePath>
</parent>

<groupId>com.acme</groupId>
<artifactId>order-service</artifactId>
<version>1.0.0-SNAPSHOT</version>

<dependencies>
    <!-- Everything cross-cutting. No version: the parent manages it. -->
    <dependency>
        <groupId>com.acme.platform</groupId>
        <artifactId>shop-platform</artifactId>
    </dependency>

    <!-- Only what this service needs on top. Test libraries come from the parent. -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-cache</artifactId>
    </dependency>
</dependencies>

<build>
    <plugins>
        <!-- Builds the executable jar, with layers for the Docker image -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

The C# pane is the project file from the run for this book. Its target framework came from a Directory.Build.props above it, and its version of Shop.Platform from a Directory.Packages.props. The Java pane needs more lines, because Maven names a parent by its coordinates, and the service must declare its own coordinates too.

The executable jar has layers. Libraries change rarely, so they are in their own layers, and Docker reuses them from its cache. The Dockerfile extracts the layers with java -Djarmode=tools -jar app.jar extract --layers --launcher. For the image, see the chapter Running locally and shipping. For executable jars in general, see the section The fat JAR.

The commandstwist#

The companion builds with Maven 3.9.16, and all its tests pass, the unit tests and the integration tests. These are the commands that it uses:

The Dockerfile states the build command in its first line:

# Build the jar first:  mvn package   (from the companion root: mvn -pl order-service -am package)

-pl order-service selects one module, and -am also builds the modules it needs. For both flags, see the section Command mapping.

The first build downloads every library and plugin. So it needs Maven Central, or a company repository that mirrors it. After that, the libraries are in ~/.m2/repository, and mvn -o builds offline. For a company repository, see the section Where artifacts come from.

Upgrading Spring Boot for every servicenew#

A new patch release of Spring Boot comes out. The shop has ten services. Without a shared parent, ten teams would each change a version, and some would forget. With the parent, the upgrade has one place to start. The parent's comment says so:

It sets the Java release, the build plugins and the version of every dependency.
A service never writes a version number itself. To upgrade Spring Boot for every service,
change the parent below and release a new platform version.

The words change the parent below mean the element that names spring-boot-starter-parent, version 4.1.2. The steps are these:

1. The platform team changes the version of spring-boot-starter-parent in shop-platform-parent. It checks the versions of the libraries that Boot does not manage, such as Spring Modulith and springdoc, against the new Boot release.
2. It builds the platform with mvn verify -Pit. The platform's own tests, and the wiring test of at least one service, show whether an auto-configuration changed.
3. It releases a new platform version, such as 1.4.0, with upgrade notes.
4. Each service changes the version in its <parent> element to 1.4.0. The library's version follows, because the parent manages it.
5. Each service builds and runs its own tests, then ships.

The parent's version and the library's version are always the same. So a service changes one number, and it gets a matching parent and library. The rule of the shop is that a service stays at most one minor version behind. For the versioning rules, see the section Versions, and the rules for upgrading.

For a patch release of Boot, the change is usually the one version line. A minor release can rename a property or deprecate a class. A major release, such as Boot 3 to Boot 4, renames starters and packages. For that kind of upgrade, see the chapter Migrating Spring Boot 3 to 4.

Compared with Directory.Build.props and NuGettwist#

Five .NET mechanisms each have a counterpart in the parent or the library. The match is close, but not exact:

The largest difference is the parent. A shared Directory.Build.props is found by its folder. A Maven parent is found by its version. A NuGet package can also add build settings to the projects that use it. Its files build/<package_id>.props and build/<package_id>.targets are imported into each such project. But NuGet's documentation says that such files must not set the properties and items that affect restore, such as TargetFramework and PackageVersion. A Maven parent may set the Java release and every managed version. So each service chooses the version of its build settings, as it chooses the version of a library. That is why an upgrade of Spring Boot is one release of the platform, and a change of one number in each service.

<ItemGroup>
  <PackageVersion Include="Shop.Platform" Version="1.0.0" />
</ItemGroup>

<!-- The platform library itself -->
<dependency>
    <groupId>com.acme.platform</groupId>
    <artifactId>shop-platform</artifactId>
    <version>${shop-platform.version}</version>
</dependency>

Maven in depth: resolution and the lifecycle#

Scene 1: the command becomes goalstwist#

For the basics of a POM against a .csproj, see the chapter Maven vs csproj. That chapter also gives the first look at two versions of one library. The shop's services share a platform library. For the parent POM of the shop, see the chapter The build: a parent POM and a platform library. This chapter starts where those two stop, and it follows a real build. The numbers and the output lines come from one run on 26 October 2026, with Maven 3.9.16, on the author's laptop. Maven ran on Java Development Kit (JDK) 26.0.1. The run script is companion/runs/maven/run.sh.

The service is built with one command. In .NET, three commands do the same work:

dotnet restore
dotnet build --configuration Release
dotnet test --no-build

mvn verify

mvn verify names a phase, not a task. Maven has a list of phases called the default lifecycle, and the command runs every phase from the first one up to the named one. The phases that matter for the service are these, in order:

A phase does nothing by itself. Each phase runs the plugin goals bound to it, and a phase with no goals does not execute. The packaging decides the first set of bindings. For the packaging jar, Maven 3.9 binds the resources, compiler, surefire, jar, install and deploy plugins to their phases. The POM adds more. The run ran mvn package and printed one line for each goal, and this is the list for the order service, in order:

dependency:3.10.0:properties (default)
resources:3.5.0:resources (default-resources)
compiler:3.15.0:compile (default-compile)
resources:3.5.0:testResources (default-testResources)
compiler:3.15.0:testCompile (default-testCompile)
surefire:3.5.6:test (default-test)
jar:3.5.1:jar (default-jar)
spring-boot:4.1.2:repackage (repackage)

Each line names the plugin, its version, the goal, and the execution id in brackets. An id of the form default-compile means the packaging bound the goal. The first line, dependency:3.10.0:properties, is a goal that the parent POM bound. The last line is the Spring Boot plugin's repackage goal, which the starter parent binds with the execution id repackage. The failsafe plugin does not appear. It runs the integration tests, and the parent binds it only inside a profile:

<!-- mvn verify runs the fast tests only: *Test.java. The *IT.java tests need Docker. -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <argLine>@{argLine} -javaagent:${org.mockito:mockito-core:jar}</argLine>
        <excludes>
            <exclude>**/*IT.java</exclude>
        </excludes>
    </configuration>
</plugin>

In .NET, the sequence is also fixed, and it is MSBuild's. A target in the project file, or in Directory.Build.targets, adds work to it. In Maven, the matching idea is a plugin execution bound to a phase. The parent binds one this way:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>properties</goal>
            </goals>
        </execution>
    </executions>
</plugin>

The execution names a goal, properties, and no phase. When the phase is left out, the goal's own default phase is used. The goals of the packaging run first in a phase, and the goals of the POM run after them, in the order of the POM.

What you can see here#

The --- plugin:goal (id) @ module --- lines of any build, which say what ran and in which order. mvn help:describe -Dcmd=verify says which goals a phase would run. And mvn -X, the debug output, prints the configuration of each goal as Maven saw it. It is long. Pipe it to a file.

What you can hook here#

A plugin execution, with a goal and optionally a phase, in the parent POM for every service or in one service's POM. Give every execution an id, because a child POM overrides a parent's execution with the same id and merges one with a different id. And give every plugin a version, in pluginManagement of the parent, so that two machines run the same plugin code. The Spring Boot starter parent already does this for the plugins it knows.

Scene 2: the POM that Maven really usestwist#

Before any goal runs, Maven builds one model of the project. It is called the effective POM. It starts from the Super POM, which Maven ships, and layers each parent on top, then the project's own POM, then the active profiles. Properties are replaced with their values. For the order service the chain has five layers:

The effective POM is what help:effective-pom prints. The run wrote it to a file and searched it for commons. The property and the managed version both came from the bill of materials (BOM) of Spring Boot, three layers up:

<commons-lang3.version>3.20.0</commons-lang3.version>
...
  <dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.20.0</version>
  </dependency>

The first line is the property commons-lang3.version, and the dependency block uses it. The second block is inside dependencyManagement. A managed version is not a dependency. It is the version to use if that library appears, from any direction. The next scene shows how far that reaches.

In .NET, the SDK and Directory.Build.props play the same role as the Super POM and the parent. MSBuild can write its evaluated model to one file, with dotnet msbuild -preprocess:out.xml. Maven writes the whole model on request too. The chapter on the parent POM reads one in the section Compared with Directory.Build.props and NuGet.

What you can see here#

mvn help:effective-pom -Doutput=effective.xml writes the model to a file, and -Dverbose=true adds a comment to each element that says which file it came from. mvn help:active-profiles lists the profiles that are active and where each was defined.

What you can hook here#

A property, which any layer can set and a lower layer can override. The Spring Boot parent exposes most of its versions as properties. So <commons-lang3.version> in the service's POM would change the managed version for the whole tree. And a profile, which adds plugins, dependencies or properties when it is active. The parent's it profile is the model.

Scene 3: the version that got intrap#

Now the story. A developer adds Apache Commons Text to the order service, to escape a string for a log line. The library is not managed by Spring Boot, so the version is written in the POM. They also add Commons Lang, because a colleague once said that Commons Text needs it, and they take the version that another project uses. Two dependencies, both with versions:

<!-- the conflict: commons-text needs a newer commons-lang3 than the one declared below -->
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-text</artifactId>
    <version>1.12.0</version>
</dependency>
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.9</version>
</dependency>

The first dependency block asks for Commons Text 1.12.0, and the second asks for Commons Lang 3.9. The run added these two blocks to the service's POM on a branch made for the run, and the comment already states the ending. Commons Text 1.12.0 was built against Commons Lang 3.14.0. The service now declares Commons Lang 3.9. Maven must choose one version, because one jar of a library goes on the classpath. Its rule is called dependency mediation, and the guide states it in one sentence. Maven picks the nearest definition, the version closest to the project in the tree of dependencies, and at equal depth the first declaration wins.

The dependency tree shows the choice. The run printed it with -Dverbose=true, which keeps the versions that lost:

[INFO] +- org.apache.commons:commons-text:jar:1.12.0:compile
[INFO] |  \- (org.apache.commons:commons-lang3:jar:3.20.0:compile - version managed from 3.14.0; omitted for conflict with 3.9)
[INFO] +- org.apache.commons:commons-lang3:jar:3.9:compile (scope not updated to compile)

The first line is the commons-text node. Read the middle line slowly, because three rules act in it. Commons Text asked for 3.14.0. The BOM of Spring Boot manages Commons Lang at 3.20.0, and a managed version beats mediation, so the request became 3.20.0. Then the service's own declaration of 3.9 beat the managed version. A direct declaration is nearer than anything, and a direct version beats the managed one. The line is in brackets because the node lost. The last line is the version on the classpath, 3.9.

Here are the three rules, in the order Maven applies them:

NuGet solves the same problem with other rules, and a C# developer's instinct comes from them. NuGet takes the lowest applicable version, the lowest that satisfies every reference. A direct reference wins over a transitive one too, and NuGet calls that rule direct-dependency-wins. But when that rule lowers a version that a library asked for, NuGet logs the warning NU1605 and says that a version was downgraded. Maven printed no warning about the version, and the compile step was green. One test failed later, in scene 5.

Nothing in the build knew that Commons Text would ask Commons Lang for a method that 3.9 does not have. The compiler checked the service's own code against 3.9, and the service's own code calls nothing that is missing. Commons Text was compiled long ago, against 3.14.0, and Maven does not compile a dependency again. The mismatch is inside a jar that nobody compiled today.

What you can see here#

mvn dependency:tree -Dverbose=true, and the words in brackets. The phrase "omitted for conflict with" names a loser, and the version after it is the winner. The phrase "version managed from" names a request that the BOM changed. A second goal, mvn dependency:analyze, reports the libraries the code uses without declaring them and the ones it declares without using them. On the service it listed 45 used but undeclared libraries, such as spring-web and spring-data-mongodb, because the platform brings them in. That is the design, not a fault, so the goal is for reading and not for failing the build.

What you can hook here#

Three hooks, in order of preference. A version in dependencyManagement of the parent, which is how Spring Boot's own BOM works. The service then declares no version at all, and every service of the shop gets the same one. An <exclusions> block on a dependency, which removes one transitive dependency from under it, when a library drags in a jar you have replaced. And the enforcer plugin, which turns the silent choice into a failed build. Its rule requireUpperBoundDeps fails when the chosen version is lower than another version in the tree, which is exactly this scene. Its rule dependencyConvergence fails when two paths reach different versions at all. The parent POM of the shop has no enforcer rule yet. Add one, and the branch of this chapter fails in the phase validate, before a class is compiled.

Scene 4: where the jars come fromtwist#

When Commons Lang 3.9 is not on the machine yet, Maven downloads it once and keeps it. Every download is saved in the local repository, ~/.m2/repository, in a folder per group, artifact and version. The run listed the laptop's folder for Commons Lang, and it held twelve versions:

~/.m2/repository/org/apache/commons/commons-lang3/
3.7  3.8.1  3.9  3.10  3.11  3.12.0  3.14.0  3.16.0  3.17.0  3.18.0  3.20.0  3.21.0

The path is the group org.apache.commons and the artifact commons-lang3, then one folder for each version. The local repository is a cache of downloads, and it also holds what mvn install built on this machine. Maven downloads an artifact when the local copy is missing. For a release version, that happens once. A release version never changes, so a second download is never needed. For a SNAPSHOT version, Maven also checks the remote repository for a newer copy, by default once a day. The shop's own modules are 1.0.0-SNAPSHOT, which means the moving development version.

Where does a download come from? The Super POM declares one repository, Maven Central, at https://repo.maven.apache.org/maven2. A POM can add repositories, and so can settings.xml. Maven queries them in a fixed order. The settings files come first, then the POM and its parents, then the POMs of the dependencies on the path to the artifact. A team with a repository manager sends every request to it with one mirror in ~/.m2/settings.xml:

<settings>
  <mirrors>
    <mirror>
      <id>shop-repository-manager</id>
      <mirrorOf>*</mirrorOf>
      <url>https://repo.shop.example/maven2</url>
    </mirror>
  </mirrors>
</settings>

The mirrorOf value * matches every repository id, so the manager sees every request and forwards each one to Maven Central. The Maven documentation calls a repository manager an essential best practice for any significant use of Maven. The <servers> block of the same file holds the credentials, keyed by the mirror's id.

Beside each cached file, Maven's resolver keeps a small file named _remote.repositories. It says which repository the file came from. If a later build does not know that repository, the resolver treats the cached file as absent and downloads it again. This can cause a download that seems not to be needed.

NuGet has the same shape with other names. The global-packages folder, ~/.nuget/packages, is the cache, with one folder per library and version. NuGet.Config holds the sources, and the files are layered from the machine to the solution folder. A difference is in the project file. A NuGet source list is in the config files only. A Maven repository can be declared in a POM, and then every project that depends on that POM queries that repository too.

What you can see here#

The folder ~/.m2/repository, and the versions in it. mvn -o builds offline and fails if something is missing, which is the quickest test of whether the cache is complete. mvn help:effective-settings prints the merged settings, with the mirrors and the servers.

What you can hook here#

A mirror, as above. A repository policy on a repository, which sets the update policy for snapshots to always, daily, never or an interval in minutes. And the flags -U, which forces a check for updated snapshots, and -nsu, which forbids one.

Scene 5: the method that is not therenew#

The branch compiles. Then the tests run, and one test fails. It is not a test of the log line, and not a test of anything that names Commons Text. It is the contract test of the OpenAPI document, which starts the web layer and fetches /v3/api-docs:

[ERROR] com.acme.orderservice.contracts.OpenApiContractTest.theCommittedContractMatchesTheCode -- Time elapsed: 0.584 s <<< FAILURE!
[ERROR] Tests run: 112, Failures: 1, Errors: 0, Skipped: 0
[INFO] BUILD FAILURE

The console names the failed test, theCommittedContractMatchesTheCode. The surefire report of the test has the line that matters, java.lang.AssertionError: Status expected:<200> but was:<500>. The test asked for the document and got a 500. Nothing in the test names the two new libraries. The run built the jar without the tests, started the service, and requested the document with curl. The service's error handler logged the cause:

ERROR [nio-8080-exec-2] c.a.p.core.error.GlobalExceptionHandler  : Unexpected error
jakarta.servlet.ServletException: Handler dispatch failed: java.lang.NoClassDefFoundError: org/apache/commons/lang3/Strings
Caused by: java.lang.NoClassDefFoundError: org/apache/commons/lang3/Strings
	at org.springdoc.api.AbstractOpenApiResource.calculatePath(AbstractOpenApiResource.java:697) ~[springdoc-openapi-starter-common-3.2.0.jar:3.2.0]

The frame below the Caused by line is inside springdoc, the library that writes the OpenAPI document. Springdoc uses a class called Strings from Commons Lang. The jar of Commons Lang 3.9 has no such class. Springdoc asked for 3.20.0, as the tree shows. The Javadoc of NoClassDefFoundError says that the JVM tried to load the definition of a class and no definition could be found. The developer added a dependency for a log line, and broke a library they never touched. Then the run placed one order. The order was accepted:

POST /orders -> 201

The 201 says that the order was created. The request succeeded because the new line of code is not on the request's path. It is in OrderMetrics, the listener that counts placed orders, and that listener runs after the transaction commits, on another thread. Less than a second later the log held this:

ERROR [task-1] .a.i.SimpleAsyncUncaughtExceptionHandler : Unexpected exception occurred invoking async method: void com.acme.orderservice.order.application.OrderMetrics.on(com.acme.orderservice.order.domain.event.OrderPlaced)

java.lang.NoSuchMethodError: 'org.apache.commons.lang3.Range org.apache.commons.lang3.Range.of(java.lang.Comparable, java.lang.Comparable)'
	at org.apache.commons.text.translate.NumericEntityEscaper.<init>(NumericEntityEscaper.java:97) ~[commons-text-1.12.0.jar:1.12.0]
	at org.apache.commons.text.translate.NumericEntityEscaper.between(NumericEntityEscaper.java:59) ~[commons-text-1.12.0.jar:1.12.0]
	at org.apache.commons.text.StringEscapeUtils.<clinit>(StringEscapeUtils.java:270) ~[commons-text-1.12.0.jar:1.12.0]
	at com.acme.orderservice.order.application.OrderMetrics.on(OrderMetrics.java:45) ~[classes/:na]

Read the stack from the bottom. The listener called StringEscapeUtils of Commons Text for the first time. The JVM initialised that class, which is the <clinit> frame, and the class built its escapers. One escaper called Range.of in Commons Lang. The JVM looked for that method in the Commons Lang on the classpath, version 3.9. It found no method with that name and those parameters. So it threw NoSuchMethodError. The Javadoc of that error says it plainly. The error is normally caught by the compiler, and it occurs at run time only if the definition of a class has incompatibly changed. Here the definition changed backwards, from 3.14.0 to 3.9.

javap proves it. The run disassembled the Range class from both jars, with -p so that every member shows, and kept the static factory methods:

== commons-lang3 3.9
  public static <T extends java.lang.Comparable<T>> org.apache.commons.lang3.Range<T> between(T, T);
  public static <T> org.apache.commons.lang3.Range<T> between(T, T, java.util.Comparator<T>);
== commons-lang3 3.20.0
  public static <T extends java.lang.Comparable<? super T>> org.apache.commons.lang3.Range<T> between(T, T);
  public static <T> org.apache.commons.lang3.Range<T> between(T, T, java.util.Comparator<T>);
  public static <T extends java.lang.Comparable<? super T>> org.apache.commons.lang3.Range<T> of(T, T);
  public static <T> org.apache.commons.lang3.Range<T> of(T, T, java.util.Comparator<T>);

Version 3.9 has between. Version 3.20.0 has between and of. Commons Text 1.12.0 calls of, so it needs a Commons Lang from the release that added it. Commons Text 1.12.0 asks for 3.14.0, so 3.14.0 or a newer version should have the method.

Two things make this failure worse than a crash. The order was placed, so nobody saw an error. And the listener that failed was a Spring Modulith listener, part of the outbox that the chapter Publishing events: the outbox explains. Spring Modulith writes down each delivery, and a delivery that fails stays incomplete in the registry. It is retried only if something resubmits it. The run read the registry in MongoDB afterwards, and the publication was still there, with completionAttempts: 1. The counter is never incremented, the registry grows, and the log of a background thread is the only place where the cause is written.

The same conflict, with one class and a main method of about twenty lines, is in the lab project of this chapter's run. Its POM declares the same two dependencies, and its one class calls five methods of Commons Text in turn:

substitute: ok -> the order service
wrap: ok -> a sentence that is\nlong enough to be\nwrapped
json: java.lang.NoSuchMethodError: 'org.apache.commons.lang3.Range org.apache.commons.lang3.Range.of(java.lang.Comparable, java.lang.Comparable)'
camel: ok -> orderPlaced
levenshtein: ok -> 2

The line that starts with json is the call to StringEscapeUtils. Four of the five calls work. Only the one that touches StringEscapeUtils fails. A test suite that happens to use the other four is green. That is why the rule is not "run the tests". The rule is "read the tree".

What you can see here#

A jar, or JAR, is one file that holds many classes. The first NoSuchMethodError or NoClassDefFoundError in a log is the place to start. Spring Boot adds the jar names in square brackets at the end of each stack frame. The two jars that disagree are usually both in the first ten frames. Then javap -p on the class, from each jar, and jar tf to list what a jar holds. The chapter Two JARs, one class covers the case where two jars hold the same class.

What you can hook here#

Nothing at run time. The fix is in the build, in scene 3. Remove the direct declaration of Commons Lang, so that the managed version 3.20.0 wins, and let the enforcer refuse the next one.

Scene 6: the jartwist#

The last goal of the build was spring-boot:repackage. It takes the jar that jar:jar made, which holds only the service's classes, and builds the jar that java -jar runs. The original is kept beside it with the suffix .original. The run listed the Commons jars inside the result:

BOOT-INF/lib/commons-text-1.12.0.jar
BOOT-INF/lib/commons-lang3-3.9.jar

Every dependency jar is inside the jar, under BOOT-INF/lib. The entries are stored and not compressed, so that the launcher can read a class without unpacking the file. The service's own classes are under BOOT-INF/classes. The manifest names Spring Boot's JarLauncher as the main class, and the service's application class as the start class. Two index files are beside them. classpath.idx gives the order of the jars on the classpath. layers.idx groups the content into layers, so that a container image can keep the dependency layer from one build to the next. The chapter The Dockerfile: a layered jar uses the layers. The chapter Running with -cp or -jar explains the plain classpath that the launcher replaces.

In .NET, dotnet publish writes the assembly and every dependency as separate files in one folder. The Java jar holds the same set in one file, and the version that scene 3 chose is the file in it. There is no second copy of Commons Lang that could serve instead.

What you can see here#

jar tf order-service-1.0.0-SNAPSHOT.jar lists every entry, and java -Djarmode=tools -jar order-service-1.0.0-SNAPSHOT.jar list-layers lists the layers. The jar on the classpath at run time is the one in BOOT-INF/lib. When the tree and the jar disagree, the jar is what ran.

What you can hook here#

The layers configuration of the plugin, which can split the application's own modules into a layer of their own. And the mainClass parameter, when a jar holds two classes with a main method and the plugin's guess is wrong.

Scene 7: the same bytes twicetwist#

A build is reproducible when the same source, the same build environment and the same instructions give the same bytes, every time, for everyone. Maven 3.9 can do this, but it must be asked. One property in the parent POM switches the plugins into reproducible mode:

<properties>
    <project.build.outputTimestamp>2026-10-26T00:00:00Z</project.build.outputTimestamp>
</properties>

The property is project.build.outputTimestamp, and its value is a date and time in UTC. With the property set, the jar plugin and the Spring Boot plugin write that timestamp into every entry instead of the clock. The Spring Boot plugin also sorts the classpath index. Maven 3.10.0 turns this mode on by default, with no property. The guide adds a second condition that belongs to this chapter. A reproducible build uses no version ranges, because a range resolves to whatever is newest on the day.

The test is two builds. mvn clean install, then mvn clean verify artifact:compare, which compares the second build with the first and writes a .buildcompare file. The guide warns that this local test does not yet prove that a third party gets the same bytes. The environment can leak into the build. It proves that the build does not depend on the clock.

NuGet's answer to the version half of this question is packages.lock.json. With the lock file committed and restore --locked-mode, a restore either gets the exact versions in the file or fails. Maven has no lock file. Its exact versions, its managed versions and its ban on ranges do the same work.

What you can see here#

The .buildcompare file after artifact:compare, which lists each artifact as ok or different. And mvn artifact:check-buildplan, which names any plugin in the build that is too old to be reproducible.

What you can hook here#

The property above, in the parent, bumped by the release process. The enforcer rules of scene 3, for the versions. And pluginManagement with a version for every plugin, so that the build plan itself does not drift.

<!-- Directory.Packages.props -->
<PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
<!-- the project file -->
<PackageReference Include="Newtonsoft.Json" />

<!-- the parent POM -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.21</version>
        </dependency>
    </dependencies>
</dependencyManagement>
<!-- the service's POM -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>

The domain model in plain Java#

The domain package: plain Java, and the base classesnew#

A rule such as "an order ships only when it is paid" should be easy to test. It should also stay the same when the service changes its database or its framework version. So the order feature keeps its rules in classes that depend on no framework at all. This is the full style of Domain-Driven Design (DDD) in the order service. This chapter starts from the code. For why the order is an aggregate, see the chapter Finding the aggregates. For why only the order feature uses this full style, see the chapter How much DDD: three levels in one service.

The domain of the order feature is one package with five sub-packages:

order/domain/
  model/        Order, OrderLine, the typed IDs, the value objects, the two status enums
  event/        OrderPlaced, LinePicked, OrderShipped, OrderCancelled, PaymentRecorded
  exception/    one exception class for each broken rule
  repository/   OrderRepository, the port for storing orders
  service/      ShippingPolicy, the one rule that needs two aggregates

The model package holds the aggregate and its values. Every class in these packages uses only the Java standard library and the platform's own domain package. The platform library describes that package in its package-info.java file. A file of this name holds the documentation of a whole package:

/**
 * The building blocks of a domain model, in plain Java.
 *
 * <p>Nothing in this package imports Spring, MongoDB or Jackson. A service's {@code domain}
 * packages may use these classes and still stay plain Java. The classes hold no business
 * concepts: they remove code that every aggregate would otherwise repeat, such as equality by
 * identity, the version for optimistic locking, the list of raised events and simple checks.
 */
package com.acme.platform.domain;

The comment of com.acme.platform.domain names the contract. The base classes remove code that every aggregate would otherwise repeat. They hold no business concept, such as an order or a payment. An architecture rule of the platform makes the build fail when a domain class imports a framework:

/** A {@code domain} package uses no framework, no adapter and no other layer. */
public static ArchRule domainIsPlainJava() {
    return noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage(
                    "org.springframework..", "com.mongodb..", "org.bson..", "jakarta..",
                    "tools.jackson..", "com.fasterxml..", "io.awspring..",
                    "..application..", "..api..", "..persistence..", "..client..", "..messaging..",
                    "com.acme.platform.core..", "com.acme.platform.mongo..")
            .as("A domain package is plain Java");
}

The test ArchitectureTest.domainIsPlainJava calls this rule. For the other rules and how a service runs them, see the chapter Testing in depth.

The platform's domain package holds these building blocks. The sections below show each one where the order uses it:

An interface that the domain declares and an outer layer implements is called a port. The class that implements a port is called an adapter. A design built from ports and adapters is called hexagonal architecture. For ports and adapters, see the chapter How much DDD: three levels in one service.

Entity: identity, written oncetwist#

public abstract class Entity<TId> where TId : Identifier
{
    protected Entity(TId id)
    {
        ArgumentNullException.ThrowIfNull(id);
        Id = id;
    }

    public TId Id { get; }
}

public abstract class Entity<ID extends Identifier> {

    private final ID id;

    protected Entity(ID id) {
        this.id = Objects.requireNonNull(id, "id");
    }

    public ID id() {
        return id;
    }

The class also defines equals and hashCode by class and ID. Each one is a final method, so no subclass can override it. In C#, a method can be overridden only when it is virtual. In Java, every method can be overridden unless it is final. For this rule, see the section Overriding needs no keyword. For the code of equals, see the section Inside the aggregate: entities and value objects.

AggregateRoot: the version and the eventsnew#

Every aggregate needs two things that have nothing to do with its rules. Storage needs the version for optimistic locking. The use case needs the domain events that a change raised. If each aggregate kept these itself, each one could get them slightly wrong. So the platform keeps them in one base class:

/**
 * The base class of an aggregate root: the only object of an aggregate that outside code may
 * hold. Every change to the aggregate goes through the root, which checks the rules.
 *
 * <p>The root carries two things for the layers around it. The first is the version, which
 * optimistic locking needs: the version comes from storage and goes back to storage unchanged,
 * and no rule ever reads it. The second is the list of domain events the root raised. The
 * application service pulls the events after saving and publishes them in the same transaction.
 *
 * @param <ID> the typed identifier of the aggregate
 */
public abstract class AggregateRoot<ID extends Identifier> extends Entity<ID> {

    private final Long version;
    private final List<DomainEvent> events = new ArrayList<>();

    /**
     * Creates the root.
     *
     * @param id      the identity
     * @param version the stored version, or {@code null} for an aggregate that was never saved
     */
    protected AggregateRoot(ID id, Long version) {
        super(id);
        this.version = version;
    }

    /** Records an event. A subclass calls this in the method that changed its state. */
    protected final void raise(DomainEvent event) {
        events.add(event);
    }

    /** Returns the raised events and clears the list, so a second call returns an empty list. */
    public final List<DomainEvent> pullEvents() {
        List<DomainEvent> raised = List.copyOf(events);
        events.clear();
        return raised;
    }

    /**
     * Returns the stored version. Only persistence uses it.
     *
     * <p>The version is final. Saving creates a new instance with the new version (see
     * {@link Repository#save}), so the instance you saved keeps the old one.
     */
    public final Long version() {
        return version;
    }
}

The test of the base class shows both parts:

@Test
void pullEventsReturnsTheRaisedEventsAndClearsThem() {
    Thing thing = new Thing();
    thing.doSomething();

    assertThat(thing.pullEvents()).containsExactly(new ThingHappened(Instant.EPOCH));
    assertThat(thing.pullEvents()).isEmpty();
}

@Test
void aNewAggregateHasNoVersion() {
    assertThat(new Thing().version()).isNull();
}

The first test raises one event. The first call of pullEvents returns it. The second call returns an empty list. The second test shows that a new aggregate has no version.

Optimistic locking needs the version that was loaded. The adapter sends that version back with the save, and storage refuses the save if the stored version has moved on. So the version goes from storage, through the aggregate, back to storage, and nothing in between reads it. For how storage checks it, see the chapter Storing aggregates in DocumentDB. For what the use case does with the events, see the section Domain events: collected by the aggregate.

Typed IDs: Identifier and its subclassesnew#

An order ID and a line ID are both universally unique identifiers (UUIDs). A method that takes two strings accepts them in the wrong order, and nothing warns you. A typed ID makes that mistake a compiler error. For the two compiler errors, in C# and in Java, see the section Typed IDs inside the aggregate. This section shows the base class that every typed ID extends:

public abstract class Identifier implements ValueObject {

    private static final Pattern UUID_FORMAT =
            Pattern.compile("^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$");

    private final String value;

    /**
     * Checks and stores the value.
     *
     * @param value     the UUID as text
     * @param fieldName the name a client sees in the error, for example {@code orderId}
     */
    protected Identifier(String value, String fieldName) {
        String normalised = value == null ? null : value.toLowerCase(Locale.ROOT);
        if (normalised == null || !UUID_FORMAT.matcher(normalised).matches()) {
            throw new InvalidValueException(fieldName, "must be a valid identifier");
        }
        this.value = normalised;
    }

    /** Returns a new random value, for the {@code newId()} factory of a subclass. */
    protected static String newValue() {
        return UUID.randomUUID().toString();
    }

    /** Returns the UUID as lower-case text. */
    public String value() {
        return value;
    }

    @Override
    public final boolean equals(Object other) {
        if (this == other) {
            return true;
        }
        if (other == null || getClass() != other.getClass()) {
            return false;
        }
        return value.equals(((Identifier) other).value);
    }

    @Override
    public final int hashCode() {
        return Objects.hash(getClass(), value);
    }

    @Override
    public String toString() {
        return value;
    }
}

The test IdentifierTest records the rule about case:

@Test
void acceptsUpperCaseAndStoresLowerCase() {
    String value = ParcelId.newId().value();

    ParcelId upper = new ParcelId(value.toUpperCase());

    assertThat(upper.value()).isEqualTo(value);
    assertThat(upper).isEqualTo(new ParcelId(value)).hasToString(value);
}

The test class ParcelId is a typed ID made only for the test. The test makes a new ID, and builds a second ID from its upper-case text. The second ID holds the lower-case text, and it is equal to the first one. In C#, Guid.TryParse accepts both cases too. A run for this book printed a Guid parsed from upper-case text in lower case.

Each typed ID of the order feature is a small class. Here is the ID of a line:

/** The identity of a line within an order. */
public final class LineId extends Identifier {

    private LineId(String value) {
        super(value, "lineId");
    }

    public static LineId of(String value) {
        return new LineId(value);
    }

    public static LineId newId() {
        return new LineId(newValue());
    }
}

A typed ID is a class and not a record, because a record cannot extend a class. The compiler refuses record RecId(String value) extends Identifier with error: '{' expected. For what a record can and cannot do, see the section Where records fit.

Typed IDs stay inside the feature. Between features, an ID travels as plain text. The note feature stores the order ID as a String, and the order feature checks it with OrderId.of. So the features share no type, and the owner of the ID checks it. For this choice and its callout, see the section A type for a foreign ID, or plain text.

The ID holds the UUID as text, not as a java.util.UUID. The JSON body, the path and the stored document all carry the ID as text. So text needs no conversion at any of those borders, and the pattern still checks the format.

Value objects as recordstwist#

public record CustomerContact
{
    public CustomerContact(string name, string email)
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new ArgumentException("must not be blank", nameof(name));
        (Name, Email) = (name, email);
    }

    public string Name { get; }
    public string Email { get; }

    public override string ToString() => "CustomerContact[masked]";
}

public record CustomerContact(String name, String email) implements ValueObject {

    public CustomerContact {
        Guard.notBlank(name, "customer.name");
        Guard.maxLength(name, 200, "customer.name");
        Guard.maxLength(email, 254, "customer.email");
        Guard.matches(email, "[^@\\s]+@[^@\\s]+\\.[^@\\s]+", "customer.email");
    }

    @Override
    public String toString() {
        return "CustomerContact[masked]";
    }
}

Both panes check the value when it is created, and both hide it in the text form. The Java record needs no assignments and no properties. The overridden toString matters because a log line or an exception message often prints an object. In runs for this book, the default text forms printed every value:

So a value object that holds personal data overrides toString. The test ValueObjectTest.customerContactHidesItsPersonalDataInToString checks the masked text.

The other value objects of the order are smaller. A delivery method is a lookup code:

/**
 * How the order reaches the customer, as a lookup code such as {@code STANDARD}.
 *
 * <p>Only the format is checked here. Whether the code is an active lookup value is checked by
 * the reference feature, which owns the list.
 */
public record DeliveryMethod(String code) implements ValueObject {

    public DeliveryMethod {
        Guard.matches(code, "[A-Z_]{1,50}", "deliveryMethod");
    }
}

The record checks only the format, such as STANDARD. It cannot know whether the code is an active lookup value, because that list is stored data of the reference feature. The use case asks the reference feature. For why that check is in the application service, see the section The lookup rule in an application service.

The stock service's answer is a value object too. It holds a list, so its compact constructor copies the list:

public record StockAvailability(boolean available, List<ProductCode> unavailableProducts) implements ValueObject {

    public StockAvailability {
        unavailableProducts = List.copyOf(unavailableProducts);
    }

    public static StockAvailability allAvailable() {
        return new StockAvailability(true, List.of());
    }

    public static StockAvailability unavailable(List<ProductCode> products) {
        return new StockAvailability(false, products);
    }
}

The other value objects of the order feature follow the same pattern:

For why a payment is a value object and a line is an entity, see the section Inside the aggregate: entities and value objects. For why an enum is stored by its name, see the section Storing an enum as a number.

Money: a currency, and no silent roundingtwist#

public record Money(decimal Amount, string Currency)
{
    public decimal Amount { get; } = Math.Round(Amount, 2);
}

/**
 * An amount of money in one currency, such as 12.50 GBP.
 *
 * <p>The amount may have at most two decimal places. A value such as 12.345 is refused, not
 * rounded: money from another service that has more precision is a mistake to report, and
 * rounding it would silently change the amount. The amount is stored with exactly two places, so
 * {@code 10} and {@code 10.00} are equal.
 *
 * @param amount   zero or more, with at most two decimal places
 * @param currency an ISO 4217 code, such as {@code GBP}
 */
public record Money(BigDecimal amount, String currency) implements ValueObject {

    public static final int DECIMAL_PLACES = 2;

    public Money {
        Guard.notNegative(amount, "amount");
        if (amount.stripTrailingZeros().scale() > DECIMAL_PLACES) {
            throw new InvalidValueException("amount", "must have at most " + DECIMAL_PLACES + " decimal places");
        }
        amount = amount.setScale(DECIMAL_PLACES);
        Guard.matches(currency, "[A-Z]{3}", "currency");
        if (Currency.getAvailableCurrencies().stream().noneMatch(known -> known.getCurrencyCode().equals(currency))) {
            throw new InvalidValueException("currency", "is not a known currency");
        }
    }

    public static Money of(String amount, String currency) {
        return new Money(new BigDecimal(amount), currency);
    }
}

The C# record rounds the amount. A run for this book showed that Math.Round(12.345m, 2) gives 12.34, with no error. The Java value object refuses 12.345 with amount must have at most 2 decimal places. The test ValueObjectTest.moneyRefusesMoreThanTwoDecimalPlacesInsteadOfRounding checks it.

Rounding has a careful version. RoundingMode.HALF_EVEN rounds a half to the even neighbour, so many roundings do not drift upwards. C# Math.Round on a decimal does the same by default. That is the right tool when the service computes an amount itself, such as a share of a total. Then the rounding is a business step, and the code names its mode. But a payment comes from another service. An amount with three decimal places means that the other side made a mistake or uses another unit. Rounding it would change the amount and hide the mistake. So the value object refuses it, and the mistake becomes visible instead of hidden.

The two places also decide equality. A record compares its components with equals, and BigDecimal.equals compares the scale. In a run for this book, new BigDecimal("10").equals(new BigDecimal("10.00")) returned false. In C#, 10m == 10.00m is true. Because Money stores exactly two places, Money.of("10", "GBP") equals Money.of("10.00", "GBP"). The test ValueObjectTest.moneyIsEqualWhateverTheNumberOfTrailingZeros checks it. For the trap in full, see the section BigDecimal inside equals.

The amount always travels with its currency. Money.of("1", "GBP") is not equal to Money.of("1", "EUR"), and the test ValueObjectTest.moneyNeedsAKnownCurrencyAndNoNegativeAmount checks that too. Without a currency, every reader of an amount would have to know its unit from somewhere else.

Guard: checks that name the fieldnew#

Every value object checks its values. Without a helper, each one writes its own if and throw, each with its own wording. A client then gets "name is empty" from one field and "missing value" from another. So the platform has one class of checks, each with one fixed message:

public final class Guard {

    private Guard() {
    }

    public static <T> T notNull(T value, String field) {
        if (value == null) {
            throw new InvalidValueException(field, "is required");
        }
        return value;
    }

    public static String notBlank(String value, String field) {
        if (value == null || value.isBlank()) {
            throw new InvalidValueException(field, "must not be blank");
        }
        return value;
    }

    public static String maxLength(String value, int max, String field) {
        if (value != null && value.length() > max) {
            throw new InvalidValueException(field, "must be at most " + max + " characters");
        }
        return value;
    }

    public static String matches(String value, String regex, String field) {
        if (value == null || !value.matches(regex)) {
            throw new InvalidValueException(field, "has an invalid format");
        }
        return value;
    }
    // ...
    public static <C extends Collection<?>> C notEmpty(C values, String field) {
        if (values == null || values.isEmpty()) {
            throw new InvalidValueException(field, "must have at least 1 item");
        }
        return values;
    }

    public static <C extends Collection<?>> C maxSize(C values, int max, String field) {
        if (values != null && values.size() > max) {
            throw new InvalidValueException(field, "must have at most " + max + " items");
        }
        return values;
    }

Each check builds its message from the field name and a fixed text:

The messages reach the client. The platform's exception handler puts the field and the message into the errors list of a 400 response:

@ExceptionHandler(InvalidValueException.class)
ResponseEntity<ProblemDetail> invalidValue(InvalidValueException ex) {
    ProblemDetail problem = domainProblem(HttpStatus.BAD_REQUEST, INVALID_REQUEST, ex);
    problem.setProperty("errors", List.of(fieldError(ex.field(), ex.getMessage())));
    return respond(problem);
}

fieldError builds a small map with the keys field and message. The tests GuardTest.namesTheFieldInTheError and ValueObjectTest.codesAndQuantitiesAreChecked check the texts. For the whole problem response, see the chapter The web layer in depth.

The request of the API checks most of these values too, with Bean Validation:

/**
 * The JSON body that places an order. The validation annotations give a client a 400 that lists
 * every bad field at once, and springdoc copies them into the OpenAPI document. The domain's
 * value objects check the same values again, and the domain's check is the one that counts.
 */
@Schema(description = "An order to place, with its first notes")
public record PlaceOrderRequest(
        @NotNull @Valid CustomerRequest customer,
        @Schema(description = "A DELIVERY_METHOD code", example = "STANDARD") @NotBlank String deliveryMethod,
        @NotEmpty @Size(max = 50) List<@Valid LineRequest> lines,
        @Schema(description = "Notes saved with the order, in the same transaction")
        @Size(max = 20) List<@Valid NoteRequest> notes) {

    public record CustomerRequest(
            @Schema(example = "Jo Bloggs") @NotBlank @Size(max = 200) String name,
            @Schema(example = "jo@example.com") @NotBlank @Email String email) {
    }

The annotations @NotBlank, @Size and @Email check the JSON body before the controller method runs. When several fields are wrong, the 400 lists them all at once. CustomerContact checks the same values again when the controller builds it. When the two checks disagree, the value object decides, because it is the only check on every path in.

The Order aggregate: its fields and its constructornew#

In an anaemic model, a service sets order.Status directly, and any class can do the same. Such a service often adds an outbox for its events. For that design and a fair comparison, see the section An anaemic model with an outbox, compared fairly. The order aggregate allows no such change. Its class comment lists its rules, and its fields can be changed only from inside the class:

/**
 * An order: the aggregate root of the order feature.
 *
 * <p>The aggregate holds what its rules need at every change: the status, the lines and the last
 * payment. Notes are a separate aggregate, because no order rule needs every note, and they can
 * grow without limit.
 *
 * <p>The rules on the order's own data:
 * <ul>
 *   <li>An order is placed only if every product is available, with 1 to {@value #MAX_LINES} lines.</li>
 *   <li>A shipped or cancelled order cannot change, except that payments are still recorded.</li>
 *   <li>A line is picked once.</li>
 *   <li>An order ships only when it is paid and every line is picked.</li>
 *   <li>A payment is recorded only if it is later than the last one, so repeated and late
 *       messages change nothing. The first payment makes a new order paid.</li>
 * </ul>
 *
 * <p>The rule that no note may need action is across two aggregates, so it lives in
 * {@code ShippingPolicy}.
 *
 * <p>State changes only through these methods. There are no setters, and the time always comes
 * from the {@link Clock} the caller passes.
 */
public class Order extends AggregateRoot<OrderId> {

    public static final int MAX_LINES = 50;

    private final CustomerContact customer;
    private final DeliveryMethod deliveryMethod;
    private final Instant placedAt;
    private final List<OrderLine> lines;
    private OrderStatus status;
    private Payment lastPayment;
    private Instant shippedAt;
    private Instant cancelledAt;

    private Order(OrderId id, Long version, CustomerContact customer, DeliveryMethod deliveryMethod, Instant placedAt,
                  List<OrderLine> lines, OrderStatus status, Payment lastPayment, Instant shippedAt, Instant cancelledAt) {
        super(id, version);
        this.customer = Guard.notNull(customer, "customer");
        this.deliveryMethod = Guard.notNull(deliveryMethod, "deliveryMethod");
        this.placedAt = placedAt;
        this.lines = new ArrayList<>(lines);
        this.status = status;
        this.lastPayment = lastPayment;
        this.shippedAt = shippedAt;
        this.cancelledAt = cancelledAt;
    }

The class has no setters. The accessors have no get prefix, as in a record, for example status() and lastPayment(). An architecture rule makes sure that no entity gets a public setter later:

public static ArchRule entitiesHaveNoPublicSetters() {
    DescribedPredicate<JavaClass> entities = assignableTo(Entity.class)
            .or(DescribedPredicate.describe("light-style entities",
                    (JavaClass type) -> type.isAnnotatedWith(Document.class)
                            && !type.getPackageName().contains(".persistence")));
    return methods().that().areDeclaredInClassesThat(entities)
            .and().haveNameMatching("set[A-Z].*")
            .should().notBePublic()
            .allowEmptyShould(true)
            .as("Entities have no public setter");
}

The test ArchitectureTest.entitiesHaveNoPublicSetters runs the rule. So a change to the state always goes through a method that applies the rule, and nobody can skip it.

Placing versus rehydratingnew#

An order comes into memory in two ways. An agent places a new order, or the adapter loads a stored one. These are different actions. Placing checks the rules and tells other services that something happened. Loading only rebuilds what was already true. So the order has two static factories:

/**
 * Places a new order. This is a business action: it applies the rules and raises
 * {@link OrderPlaced}.
 *
 * <p>The caller chooses the ID first, because it already sent the ID to the stock service as
 * the idempotency key of the reservation.
 *
 * @param stock the stock service's answer for these items
 */
public static Order place(OrderId id, CustomerContact customer, DeliveryMethod deliveryMethod,
                          List<OrderItem> items, StockAvailability stock, Clock clock) {
    Guard.notEmpty(items, "lines");
    Guard.maxSize(items, MAX_LINES, "lines");
    if (!stock.available()) {
        throw new ProductsUnavailableException(stock.unavailableProducts());
    }
    List<OrderLine> lines = items.stream().map(OrderLine::add).toList();
    Order order = new Order(id, null, customer, deliveryMethod, clock.instant(), lines, OrderStatus.NEW,
            null, null, null);
    order.raise(new OrderPlaced(id, deliveryMethod, List.copyOf(items), order.placedAt));
    return order;
}

/** Rebuilds a stored order. Loading is not a business action, so it applies no rules and raises no events. */
public static Order rehydrate(OrderId id, Long version, CustomerContact customer, DeliveryMethod deliveryMethod,
                              Instant placedAt, List<OrderLine> lines, OrderStatus status, Payment lastPayment,
                              Instant shippedAt, Instant cancelledAt) {
    return new Order(id, version, customer, deliveryMethod, placedAt, lines, status, lastPayment,
            shippedAt, cancelledAt);
}

Loading must not apply the rules of placing. Suppose that rehydrate asked the stock service again. A stored order whose mug is now sold out could then not be loaded, and it could not be shipped or cancelled either. Suppose that it raised OrderPlaced. Every load would then tell other services that a new order exists. The constructor still checks what holds for every order, such as a customer, so a broken document fails on load.

The caller chooses the ID before placing, because the use case has already sent it to the stock service. The stock service uses it as the idempotency key of the reservation. For that call, see the chapter Calling other services.

Only the persistence mapper calls rehydrate. For the mapper, see the chapter Storing aggregates in DocumentDB. The line has the same pair of factories, and its add is package-private. See The root is the only way in. The light-style note loads through a constructor instead. See Creating and loading.

The time comes from an injected Clocktwist#

builder.Services.AddSingleton(TimeProvider.System);

/** The clock that the domain reads the time from. Code never calls {@code Instant.now()}. */
@Bean
@ConditionalOnMissingBean
Clock clock() {
    return Clock.systemUTC();
}

Both panes register one object that tells the time, so tests can replace it. In Java, the application service receives the Clock in its constructor. It passes the clock to each domain method that needs the time, such as order.ship(clock). An aggregate is not a bean, so nothing could inject the clock into it. The aggregate reads the time with clock.instant(), which returns an Instant. No domain code calls Instant.now().

The tests pass a clock that always returns the same time:

public static final Instant NOW = Instant.parse("2026-01-15T09:00:00Z");
public static final Clock CLOCK = Clock.fixed(NOW, ZoneOffset.UTC);

Instant.parse reads an ISO 8601 text. Clock.fixed returns a clock that always gives that instant, and ZoneOffset.UTC is its time zone. So a test can expect shippedAt to be exactly NOW. In C#, a test passes its own subclass of TimeProvider that overrides GetUtcNow. For the classes of java.time, see the section java.time.

Changing an order: pick, ship and cancelnew#

Each change of an order is one method. Each method follows the same three steps. It checks the rule, it changes the state, and it raises the event. Here are shipping and cancelling, and the check that both use first:

public void ship(Clock clock) {
    requireNotFinished();
    if (status != OrderStatus.PAID) {
        throw new OrderNotPaidException(id());
    }
    if (lines.stream().anyMatch(line -> !line.isPicked())) {
        throw new UnpickedLinesException(id());
    }
    status = OrderStatus.SHIPPED;
    shippedAt = clock.instant();
    raise(new OrderShipped(id(), shippedAt));
}

public void cancel(Clock clock) {
    requireNotFinished();
    status = OrderStatus.CANCELLED;
    cancelledAt = clock.instant();
    raise(new OrderCancelled(id(), cancelledAt));
}
// ...
private void requireNotFinished() {
    if (status == OrderStatus.SHIPPED || status == OrderStatus.CANCELLED) {
        throw new OrderFinishedException(id(), status);
    }
}

So one method holds the rule, the change and the event. A reader who asks "when can an order ship?" reads ship and its tests. The test OrderTest.Shipping checks the paid order, the unpaid one and the one with a line that is not picked. One shipping rule is missing here. An order with a note that needs action cannot ship either. That rule needs two aggregates, so it is in a domain service. For the reason, see the section Worked example: no shipping while a note needs action.

pickLine follows the same steps. It finds the line by its ID, or throws LineNotFoundException, which the platform answers with 404. Then it asks the line to pick itself. For its code, see the section The root is the only way in.

Recording a payment, once and in ordernew#

The payment service reports each payment with a message. A queue can deliver a message twice, and two messages can arrive in the wrong order. The order must stay correct in both cases. So the method that records a payment keeps the newest payment, and ignores any other:

/**
 * Records a payment, unless it is not later than the last one.
 *
 * <p>SQS can deliver a message twice, and messages can arrive out of order. Both cases leave
 * the order unchanged. A payment for a shipped or cancelled order is still recorded, on
 * purpose: the money was received, and the payment service handles any refund.
 *
 * @return whether the order changed, so the caller knows whether to save it
 */
public boolean recordPayment(Payment payment) {
    if (lastPayment != null && !payment.paidAt().isAfter(lastPayment.paidAt())) {
        return false;
    }
    lastPayment = payment;
    if (status == OrderStatus.NEW) {
        status = OrderStatus.PAID;
    }
    raise(new PaymentRecorded(id(), payment.reference(), payment.amount(), payment.paidAt()));
    return true;
}

The method does not call requireNotFinished. That is on purpose. The money was received, even for a cancelled order, and the payment service handles any refund. The comment of the method says so, the README of the service says so, and a test records it:

@Test
void aPaymentForACancelledOrderIsStillRecorded() {
    Order order = newOrder();
    order.cancel(CLOCK);

    assertThatCode(() -> order.recordPayment(payment(NOW))).doesNotThrowAnyException();

    assertThat(order.status()).isEqualTo(OrderStatus.CANCELLED);
    assertThat(order.lastPayment()).isNotNull();
}

The test cancels an order, then records a payment for it. The call throws nothing, the status stays CANCELLED, and the payment is stored. An exception to a rule such as "a cancelled order cannot change" must be written down in the code, and tested. Otherwise the next developer adds the missing check, and payments start to fail.

The use case saves only when the method returns true:

@Transactional
public void recordPayment(OrderId orderId, Payment payment) {
    Order order = orders.get(orderId);
    if (order.recordPayment(payment)) {
        saveAndPublish(order, AuditActions.PAYMENT_RECORDED);
    }
}

The if here is not a business rule. The domain already decided to ignore the payment. The use case only skips the save. For how the message reaches this method, see the chapter Consuming events: SQS and the inbox.

OrderLine: a status that is computedtwist#

public DateTimeOffset? PickedAt { get; private set; }

public bool IsPicked => PickedAt is not null;

public LineStatus Status => IsPicked ? LineStatus.Picked : LineStatus.Waiting;

public boolean isPicked() {
    return pickedAt != null;
}

public LineStatus status() {
    return isPicked() ? LineStatus.PICKED : LineStatus.WAITING;
}

Both panes compute the status from the pick time. The line stores only pickedAt. So the status and the time can never disagree. A line with a pick time is picked, and a line without one is waiting. The C# pane uses properties. The Java pane uses two methods, because Java has no properties. For more, see the section The property gap.

The line is an entity with its own LineId, because a picker names the line that was picked. Its methods that change it are package-private, so only the order can call them. See The root is the only way in.

Collections leave as copiestrap#

The order holds its lines in a list that it can change. Outside code must not change that list. In C#, a class returns such a list as IReadOnlyList<T>. Java has no read-only list interface, so the order returns a copy:

/** Returns a read-only copy, so outside code cannot add or remove lines. */
public List<OrderLine> lines() {
    return List.copyOf(lines);
}

The test OrderTest records the rule:

@Test
void linesCannotBeChangedFromOutsideTheAggregate() {
    Order order = newOrder();

    assertThatThrownBy(() -> order.lines().clear()).isInstanceOf(UnsupportedOperationException.class);
}

assertThatThrownBy runs the lambda and expects it to throw. So the test fails if someone changes lines() to return the field.

Java has several ways to return a collection. They differ in what a caller can do:

The order uses List.copyOf. The copy also refuses null elements. In a run for this book, List.copyOf of a list that held a null threw NullPointerException. For the other ways to create a list, see the section Creating collections.

The copy holds the same line objects as the order. A run for this book kept the list from order.lines(), then picked the first line through the order. The kept line then reported isPicked() as true. So the copy protects the list, and package-private access protects each line. A caller outside the package that calls pick on a line gets a compiler error:

The use cases go one step further. They never return the aggregate at all. They return a view, a record of plain values:

public record OrderView(String orderId, String status, String deliveryMethod, Instant placedAt, Instant shippedAt,
                        Instant cancelledAt, List<Line> lines, LastPayment lastPayment) {

    public record Line(String lineId, String productCode, int quantity, String status, Instant pickedAt) {

        static Line from(OrderLine line) {
            return new Line(line.id().value(), line.product().value(), line.quantity(), line.status().name(),
                    line.pickedAt());
        }
    }

Line is a record declared inside the record OrderView. A record inside another type is always static, so it needs no instance of the outer record. Its full name is OrderView.Line. A caller who holds a view cannot call ship and skip the steps of the use case. For views, see the chapter Use cases: the application service.

Domain events: collected by the aggregatenew#

When an order ships, the shop must tell the warehouse and the customer. The order does not send anything itself. It records what happened, and the use case publishes the records after it saves. A record of something that happened in the domain is called a domain event. Every domain event implements one small interface:

/**
 * Something that happened inside the service, named in the past tense, such as
 * {@code OrderShipped}.
 *
 * <p>A domain event is internal. It may change whenever the model changes. Only the events that
 * an integration-event mapper translates leave the service, as versioned integration events.
 * Write domain events as records.
 */
public interface DomainEvent {

    /** Returns when the event happened, taken from the injected clock. */
    Instant occurredAt();
}

The interface has one method, occurredAt(). An event is named in the past tense, because it already happened. Its time comes from the clock that the method received. The order's events are records:

/** An order was shipped. It leaves the service as {@code OrderShippedV1}. */
public record OrderShipped(OrderId orderId, Instant occurredAt) implements DomainEvent {
}

A record implements occurredAt() through its component of the same name. So OrderShipped needs no body. The order feature has five events:

A domain event belongs to the service, and it may change whenever the model changes. Only a mapper turns some of them into versioned integration events for other services. For that step, see the chapter Publishing events: the outbox.

The use case publishes the events through a port:

/**
 * The port that application services use to publish the events an aggregate raised.
 *
 * <p>Call it inside the use case's transaction, after saving. The platform's implementation
 * writes the events to the outbox in that transaction, so an event is stored only with its
 * change.
 */
public interface DomainEventPublisher {

    void publish(List<DomainEvent> events);
}

publish takes the whole list of events of one change. The use case calls it after the save, inside the same transaction.

Every use case of the order feature ends with the same private method:

private Order saveAndPublish(Order order, String auditAction) {
    List<DomainEvent> raised = order.pullEvents();
    Order saved = orders.save(order);
    events.publish(raised);
    audit.record(auditAction, AuditActions.ORDER, saved.id().value());
    return saved;
}

So no use case can save a change and forget its event. The order raised the event in the method that changed it, and this one method publishes whatever was raised. For the steps of a use case, see the chapter Use cases: the application service.

The repository porttwist#

public interface IOrderRepository
{
    Task<Order?> FindByIdAsync(OrderId id);

    async Task<Order> GetAsync(OrderId id) =>
        await FindByIdAsync(id) ?? throw new OrderNotFoundException(id);
}

/**
 * The port for storing orders, in the domain's own types. The persistence package implements it.
 * Lists are sorted newest first.
 */
public interface OrderRepository extends Repository<Order, OrderId> {

    /** Loads the order, or throws the 404 exception, so a use case loads in one line. */
    default Order get(OrderId id) {
        return findById(id).orElseThrow(() -> new OrderNotFoundException(id));
    }

    PageResult<Order> findAll(PageQuery page);

    PageResult<Order> findByStatus(OrderStatus status, PageQuery page);
}

Both ports load or fail in one line. The Java port returns Optional<Order>. The C# port returns Order?. For when to use Optional, see the section Optional is for return values. The base port is short:

public interface Repository<A extends AggregateRoot<ID>, ID extends Identifier> {

    Optional<A> findById(ID id);

    /**
     * Saves the aggregate and returns the stored copy, which holds the new version.
     *
     * <p>Continue with the returned instance. The instance you passed in keeps the old version,
     * so saving it a second time fails. For a new aggregate it fails as a duplicate insert, with
     * {@code DuplicateKeyException}; for a loaded one, as a concurrent update. Saving also fails
     * with Spring's {@code OptimisticLockingFailureException} when someone else saved the
     * aggregate after you loaded it; that exception is unchecked, so this plain-Java interface
     * can only name it here.
     * Inside a transaction, MongoDB usually reports the same conflict as a write conflict, which
     * Spring translates to {@code DataIntegrityViolationException}. The platform answers both with 409.
     *
     * <p>Never retry a failed save with the same instance. Load the aggregate again, apply the
     * change again, and save that.
     */
    A save(A aggregate);

    boolean exists(ID id);

The interface has two type parameters. A extends AggregateRoot<ID> says that only an aggregate root can be stored. ID extends Identifier says that its ID is a typed ID. The bound on A uses ID, so the aggregate and its ID type must fit together. A repository of Order with a LineId does not compile.

The comment of save names Spring's OptimisticLockingFailureException. The interface cannot import it, because the domain is plain Java. It does not need to declare it either, because the exception is unchecked. So the comment is the only place where a reader learns about it. For what the comment says about the returned instance, see the section The version, and the save that returns a new instance.

The base port is for aggregates only. The reference feature has no aggregate, so its repository extends Spring Data directly:

public interface ReferenceItemRepository extends MongoRepository<ReferenceItemDocument, String> {

    @Cacheable("reference-data")
    List<ReferenceItemDocument> findByTypeOrderByCodeAsc(String type);
}

MongoRepository is the Spring Data interface for MongoDB, and @Cacheable keeps each list in a cache. A lookup value has no version and no events, so the base port would give it nothing.

The note feature, in the light style, also injects a Spring Data repository directly. For both styles, see the chapter How much DDD: three levels in one service.

The version, and the save that returns a new instancenew#

The version of an order is final, and no rule reads it. So the save cannot write the new version into the order that the use case passes in. The repository returns a new instance instead, and the use case continues with that one. Placing an order saves it, and then uses the saved order's ID for its notes:

return transaction.execute(status -> {
    Order order = Order.place(orderId, customer, deliveryMethod, items, availability, clock);
    Order saved = saveAndPublish(order, AuditActions.ORDER_PLACED);        // aggregate 1
    List<String> noteIds = notes.addNotes(saved.id().value(), firstNotes); // aggregate 2, same transaction
    return new PlacedOrder(saved.id().value(), noteIds);
});

saveAndPublish returns the saved instance. The lambda keeps it as saved, and passes saved.id() to the note feature. The instance order is not used after the save. What goes wrong when a use case saves the old instance again is a trap of its own. For the run that shows it, see the section The order that was passed to save.

A unit test of the use case must behave like the real repository. A mock that returns the instance it received would hide a use case that keeps the old one. So the test's mock builds a new instance with the next version. The mock comes from Mockito:

/** Makes the mocked repository behave like the real one: save returns a stored copy with the next version. */
private void saveReturnsTheStoredCopy() {
    when(orders.save(any())).thenAnswer(call -> {
        Order order = call.getArgument(0);
        long next = order.version() == null ? 0 : order.version() + 1;
        return Order.rehydrate(order.id(), next, order.customer(), order.deliveryMethod(), order.placedAt(),
                order.lines(), order.status(), order.lastPayment(), order.shippedAt(), order.cancelledAt());
    });
}

thenAnswer runs the lambda for each call, and getArgument(0) is the order that the use case passed. The lambda rebuilds it with Order.rehydrate and the next version, as the real adapter does. A first save gives version 0, because a new order has no version. For more about mocks, see the chapter Testing in depth.

A failed save is never retried with the same instance. The comment of Repository.save says so. The use case loads the order again, applies the change again, and saves that. The light-style note works differently, because Spring Data writes the new version into the same object. See Versions after a save. For the stored version and the conflicts, see the chapter Storing aggregates in DocumentDB.

Paging without Spring: PageQuery and PageResulttwist#

/**
 * Which page of a list to return, without any Spring type. Pages count from zero.
 *
 * @param page the page number, from 0
 * @param size the number of items on a page, from 1 to {@value #MAX_SIZE}
 */
public record PageQuery(int page, int size) implements ValueObject {

    public static final int MAX_SIZE = 100;
    public static final int DEFAULT_SIZE = 20;

    public PageQuery {
        if (page < 0) {
            throw new InvalidValueException("page", "must not be negative");
        }
        if (size < 1 || size > MAX_SIZE) {
            throw new InvalidValueException("size", "must be between 1 and " + MAX_SIZE);
        }
    }

    /** Returns the first page with the default size. */
    public static PageQuery first() {
        return new PageQuery(0, DEFAULT_SIZE);
    }
}

A list query takes a PageQuery instead of Spring Data's Pageable, so the port stays plain Java. The compact constructor refuses a negative page and a size outside 1 to 100. {@value #MAX_SIZE} puts the value of the constant into the documentation. first() is a static factory for the first page with 20 items. Pages count from zero, as in Spring Data.

The answer is a PageResult, with the numbers that a client needs to ask for the next page:

public record PageResult<T>(List<T> items, int page, int size, long totalItems) {

    public PageResult {
        items = List.copyOf(items);
    }

    public int totalPages() {
        return size == 0 ? 0 : (int) Math.ceil((double) totalItems / size);
    }

    /** Converts each item and keeps the paging numbers, for example from aggregates to views. */
    public <R> PageResult<R> map(Function<? super T, ? extends R> mapper) {
        return new PageResult<>(items.stream().<R>map(mapper).toList(), page, size, totalItems);
    }
}

The use case turns a page of orders into a page of views in one call, result.map(OrderView::from). The controller turns the result into the JSON of a page. For that step, see the chapter The web layer in depth.

Exceptions by kind, with stable codesnew#

A use case throws "this order is not paid". The client must get the same status for it in every service, and a code that its program can test. If each feature wrote its own exception handler, the statuses would drift. So the platform defines exactly three kinds of domain exception. The kind decides the status, and a feature only chooses the kind:

public abstract class DomainException : Exception
{
    private protected DomainException(string code, string message) : base(message) => Code = code;

    public string Code { get; }
}

public abstract class NotFoundException : DomainException
{
    protected NotFoundException(string code, string message) : base(code, message) { }
}

/**
 * The base of every exception the domain throws. It has exactly three kinds, and the kind
 * decides the HTTP status, so a feature never writes an exception handler.
 *
 * <ul>
 *   <li>{@link NotFoundException}: the thing does not exist (404).</li>
 *   <li>{@link InvalidValueException}: a value has the wrong format (400).</li>
 *   <li>{@link BusinessRuleViolationException}: the request breaks a business rule (422).</li>
 * </ul>
 *
 * <p>The class is sealed, so no other direct subclass can exist. Extend one of the three kinds.
 * The message is returned to the caller, so it must never hold personal data. IDs are fine.
 */
public abstract sealed class DomainException extends RuntimeException
        permits NotFoundException, InvalidValueException, BusinessRuleViolationException {

    private final String code;

    protected DomainException(String code, String message) {
        super(message);
        this.code = code;
    }

    /** Returns a stable, machine-readable code, such as {@code ORDER_NOT_PAID}. */
    public String code() {
        return code;
    }
}

The compiler's message names the rule:

The C# pane has no list of permitted classes. The closest match in C# is a private protected constructor. Only a derived class in the same assembly can call it. In a run for this book, a class in another assembly that derived from the C# DomainException failed with error CS1729. A class that derived from NotFoundException compiled. The Java rule works by name, across packages and libraries.

Each kind is non-sealed, so features may extend it. Here is one of them:

/**
 * The thing a request names does not exist. The platform answers 404.
 *
 * <p>Write one subclass per kind of thing, such as {@code OrderNotFoundException}. The class is
 * non-sealed and its constructor is protected, so features can extend it but not throw it bare.
 */
public non-sealed class NotFoundException extends DomainException {

    protected NotFoundException(String code, String message) {
        super(code, message);
    }
}

non-sealed opens this branch again. Any class may extend NotFoundException. The constructor is protected, so a feature cannot throw a bare NotFoundException. In a run for this book, new NotFoundException("X", "y") in another package failed with NotFoundException(String,String) has protected access in NotFoundException. For sealed and non-sealed in general, see the section Sealed types: Java's discriminated unions.

The three kinds differ in their status and in how a feature uses them:

One broken rule of the order looks like this:

public class OrderNotPaidException extends BusinessRuleViolationException {

    public OrderNotPaidException(OrderId id) {
        super("ORDER_NOT_PAID", "Order " + id + " cannot ship before it is paid");
    }
}

The class name says which rule broke. The code ORDER_NOT_PAID is the same name in capitals, and the message explains it for a person. The order feature has one exception class for each rule:

Clients may rely on a code, so a code never changes. A client program tests code == "ORDER_NOT_PAID", and it never parses the message. The message is returned to the caller too, so it must never hold personal data. IDs and product codes are fine. A customer's name is not.

The platform's exception handler maps each kind to its status:

@ExceptionHandler(NotFoundException.class)
ResponseEntity<ProblemDetail> notFound(NotFoundException ex) {
    return respond(domainProblem(HttpStatus.NOT_FOUND, "Not found", ex));
}
// ...
@ExceptionHandler(BusinessRuleViolationException.class)
ResponseEntity<ProblemDetail> businessRule(BusinessRuleViolationException ex) {
    return respond(domainProblem(HttpStatus.UNPROCESSABLE_CONTENT, "Business rule violated", ex));
}

@ExceptionHandler names the exception class that the method handles. The method also handles every subclass of that class. So OrderNotPaidException reaches businessRule and becomes a 422. The test OrderControllerTest.aBrokenBusinessRuleIsA422WithItsCode checks the status and the code in the body. HttpStatus.UNPROCESSABLE_CONTENT is the name of 422 in Spring Framework 7. No feature writes a handler of its own. For the problem response and its code property, see the chapter The web layer in depth.

The light-style Note, for comparisontwist#

/**
 * Writes a new note on an order. The caller has checked that the order exists and that the
 * category is an active lookup value. {@code createdBy} is the ID of the agent who writes it.
 */
public static Note create(String orderId, String text, String category, boolean actionRequired,
                          String createdBy, Clock clock) {
    Guard.notBlank(orderId, "orderId");
    Guard.notBlank(text, "text");
    Guard.maxLength(text, MAX_TEXT_LENGTH, "text");
    Guard.matches(category, "[A-Z_]{1,50}", "category");
    Guard.notBlank(createdBy, "createdBy");
    Note note = new Note(UUID.randomUUID().toString(), null, orderId, text, category, actionRequired,
            clock.instant(), createdBy, null);
    note.events.add(new NoteAdded(note.id, orderId, note.createdAt));
    return note;
}

The note keeps the same ideas as the order, with fewer types. create is a business action that checks the values with Guard and records NoteAdded. It also records the ID of the agent who writes the note, for the rule that another agent resolves it. Its IDs are plain String values. It has no base class, so it keeps its own event list and its own equals. The table compares the two styles where this chapter used them:

The note has four rules of its own. Only a note that needs action can be resolved. It is resolved once. The agent who wrote it may not resolve it. Its text never changes. resolveAction checks the first three rules. It throws NoteHasNoActionException, NoteActionAlreadyResolvedException or NoteResolvedByItsAuthorException, which are all business rule violations. When it succeeds, it raises NoteActionResolved. requireBelongsTo answers a note under another order with NoteNotFoundException, a 404. A 403 would tell the caller that the note exists. For that choice, see the section Rules about one record: in the domain, with the actor passed in.

A note's text may hold personal data, so its toString leaves the text out:

/** Leaves the text out: an agent may have written personal data in it. */
@Override
public String toString() {
    return "Note[id=" + id + ", orderId=" + orderId + ", " + text.length() + " chars]";
}

The text form prints text.length(), the number of characters, and never the text itself. The test NoteTest.checksItsValuesAndHidesItsTextInToString writes a phone number into a note. It checks that the text form does not contain it, and contains 36 chars.

The reference feature, at the simple level, has no value object at all. A lookup value is a document record, ReferenceItemDocument, with a type, a code, a label and an active flag. An inactive value stays stored, because old orders still use it. For the three levels side by side, see the chapter How much DDD: three levels in one service.

Testing the modelnew#

A rule of the domain is plain Java, so its test is plain Java too. The test of the order creates orders, calls their methods and checks the result. It starts no Spring and needs no mocks:

/**
 * The order's rules, in plain JUnit: no Spring, no mocks, a few milliseconds. If a test here
 * needed Spring, the code under test would be in the wrong place.
 */
class OrderTest {

    @Nested
    class Placing {

        @Test
        void placesANewOrderAndRaisesOrderPlaced() {
            OrderId id = OrderId.newId();

            Order order = Order.place(id, CUSTOMER, STANDARD, TWO_MUGS, StockAvailability.allAvailable(), CLOCK);

            assertThat(order.status()).isEqualTo(OrderStatus.NEW);
            assertThat(order.version()).isNull();
            assertThat(order.lines()).singleElement().satisfies(line -> {
                assertThat(line.product()).isEqualTo(new ProductCode("MUG-001"));
                assertThat(line.status()).isEqualTo(LineStatus.WAITING);
            });
            assertThat(order.pullEvents()).containsExactly(new OrderPlaced(id, STANDARD, TWO_MUGS, NOW));
        }

The comment of the class states a rule for the codebase. If a test here needed Spring, the code under test would be in the wrong place. Other tests start from a ready state with a helper:

/** A new order with no raised events, so each test starts clean. */
public static Order newOrder() {
    Order order = Order.place(OrderId.newId(), CUSTOMER, STANDARD, TWO_MUGS, StockAvailability.allAvailable(), CLOCK);
    order.pullEvents();
    return order;
}

/** A paid order whose lines are all picked, with no raised events: ready to ship. */
public static Order readyToShip() {
    Order order = newOrder();
    order.recordPayment(payment(NOW));
    order.lines().forEach(line -> order.pickLine(line.id(), CLOCK));
    order.pullEvents();
    return order;
}

newOrder and readyToShip pull the events at the end. So each test sees only the events of the method it tests. In the tests, order.lines().getFirst() returns the first element of the list. getFirst was added in Java 21. See Sequenced collections. For the test kinds of the whole service, see the chapter Testing in depth.

public record OrderItem(ProductCode Product, int Quantity)
{
    public const int MaxQuantity = 999;

    public ProductCode Product { get; } =
        Product ?? throw new ArgumentNullException(nameof(Product));

    public int Quantity { get; } = Quantity is >= 1 and <= MaxQuantity
        ? Quantity
        : throw new ArgumentOutOfRangeException(nameof(Quantity));
}

public record OrderItem(ProductCode product, int quantity) implements ValueObject {

    public static final int MAX_QUANTITY = 999;

    public OrderItem {
        Guard.notNull(product, "productCode");
        Guard.between(quantity, 1, MAX_QUANTITY, "quantity");
    }
}

Where each rule goes#

Three places for a rulenew#

An agent asks the service to ship an order. Three different kinds of logic decide what happens. The order checks that it is paid and picked. A rule across the order and its notes checks that no note needs action. And the use case loads, saves and publishes. The method that ships an order shows all three, one line each:

/** Ships the order. The rule across the order and its notes is checked by the domain service. */
@Transactional
public void ship(OrderId orderId) {
    Order order = orders.get(orderId);                                         // load
    long notesNeedingAction = notes.countNeedingAction(orderId.value());       // ask the note feature
    shippingPolicy.assertCanShip(order, notesNeedingAction);                   // rule across aggregates
    order.ship(clock);                                                         // rule and change
    saveAndPublish(order, AuditActions.ORDER_SHIPPED);                         // save, publish, audit
}

So the use case contains no rule of its own. It decides the order of the steps, and the domain decides what is allowed. For that structure in full, see the chapter Use cases: the application service. For the code of order.ship, see the section Changing an order: pick, ship and cancel.

Each place holds one kind of logic. The table also lists a fourth place, the value object, which checks the form of a single value:

A domain service receives what it needs, and it never loads anything. Because of that, its test needs no mock. The application service is the only place that touches storage, other services and transactions. Because of that, it is the only place whose test needs mocks.

The decision order: five questionsnew#

A new rule arrives. An order may hold at most 50 lines. A developer could check it in the controller, in the use case or in the order. Each choice compiles, and each passes a first test. But only one place covers every way into the service. The order service checks it here, in the factory that places an order:

public static Order place(OrderId id, CustomerContact customer, DeliveryMethod deliveryMethod,
                          List<OrderItem> items, StockAvailability stock, Clock clock) {
    Guard.notEmpty(items, "lines");
    Guard.maxSize(items, MAX_LINES, "lines");

Guard.maxSize throws a 400 that names the field lines. Lines are added only when an order is placed, so every order passes this check. To find such a place for any rule, ask these questions in order, and stop at the first yes:

Each question, with an answer from the order service:

1. The form of one value. A quantity from 1 to 999 needs nothing but the quantity. So OrderItem, a record, checks it in its compact constructor. Every path that builds an item meets the check.
2. One aggregate's data. "At most 50 lines" needs only the order's lines. So Order.place checks it. The rules on one aggregate are the most common kind, so most rules stop here.
3. Two or more aggregates. "No note needs action" needs the order and its notes. So a domain service checks it, and the use case gives it the data. The section Worked example: no shipping while a note needs action shows why.
4. Another feature owns the data. "The delivery method is an active lookup value" needs the lookup list of the reference feature. So the order feature calls ReferenceDataService.requireActive, and it never reads the list itself.
5. Input, output, a transaction or a permission. "Call the stock service before the transaction starts" is about how the work runs, not about what is allowed. So it is a step of OrderService.place. A permission is checked where users enter. See Choosing the place by the shape of the service.

The order of the questions matters. The first questions choose the most local places. A check in a value object runs on every path, and a check in the aggregate runs on every change. A check in a use case runs only in that use case. So a rule that could stop at question 1 or 2, but is written at question 5, is skipped by every other use case.

Prefer the aggregate over a domain service whenever the aggregate's own data is enough. Each rule that moves out of the aggregate leaves the aggregate with less to do. When most rules have moved out, the aggregate only holds data. Such a model is called an anaemic domain model. Every caller must then know the rules again. For that outcome, see the section What an anaemic model looks like, and what goes wrong.

The five questions follow from one principle. The root of an aggregate guards the rules on its own data. For that principle and the others, see the chapter The principles.

The business-expert testnew#

The five questions need some thought. A quicker test works on a single line of a use case. Picture a person who knows the business but no code, such as the head of customer service. Read the line to them in plain words. If they say "yes, that is one of our rules", the line does not belong in the application service. The class comment of the order's use cases states the test:

* <p>Every change follows the same steps: load, let the domain apply its rules and change
* itself, save, publish the events, record the audit. The steps that call other services run
* before the transaction. This class decides the order of the steps and never contains a
* business rule: a line that a business expert would recognise as a rule belongs in the domain.

The comment of OrderService lists the steps of a change. Its last sentence names the test, with the words a business expert would recognise as a rule. Here are lines of the order service, read to a business expert:

The fourth line is the one if in the use cases of the order. Its comment explains why it is not a rule:

/**
 * Records a payment from the payment service. A message starts this use case, so no user
 * acts, and the audit log records the system actor.
 *
 * <p>It joins the transaction of the inbox that called it. The one {@code if} here is not a
 * business rule: the domain decided to ignore the payment, so there is nothing to save.
 */
@Transactional
public void recordPayment(OrderId orderId, Payment payment) {
    Order order = orders.get(orderId);
    if (order.recordPayment(payment)) {
        saveAndPublish(order, AuditActions.PAYMENT_RECORDED);
    }
}

order.recordPayment(payment) applies the rule and returns whether anything changed. The if only skips a save when there is nothing to save. An expert would not recognise it. So the test also tells you which if statements may stay in a use case.

Worked example: no shipping while a note needs actionnew#

A customer-service agent writes a note on an order, "call the customer before shipping". The note needs action. Until an agent resolves it, the order must not ship. The rule needs the order, which knows whether it can ship, and the notes, which know whether any needs action. Order and note are two aggregates. For why they are separate, see the section Why order and note are separate aggregates.

The service checks the rule in a domain service:

public class ShippingPolicy {

    public void assertCanShip(Order order, long notesNeedingAction) {
        if (notesNeedingAction > 0) {
            throw new OrderHasOpenActionsException(order.id(), notesNeedingAction);
        }
    }
}

assertCanShip receives the order and a number. It throws OrderHasOpenActionsException when the number is above zero, and the platform answers 422 with the code ORDER_HAS_OPEN_ACTIONS. The class has no field, no repository and no Spring annotation.

Four other designs look possible. Each one is tempting, so each one deserves a fair look.

Why not inside Order, with the notes loaded. The order could hold its notes, and ship could check them. But notes have no limit, and no other rule of the order needs them. Every load of an order would then load every note, and every new note would change the order's document. For the full reasons, see the section Why order and note are separate aggregates.

Why not inside Order, with a repository. The order could ask a note repository in ship. Then the aggregate would do input and output. The domain would no longer be plain Java, and every test of ship would need a mock. The architecture rule domainIsPlainJava forbids it anyway.

Why not inside Order, with the number passed in. This is the strongest alternative. order.ship(clock, notesNeedingAction) keeps every shipping rule in one method, and its test needs no mock either. It is a good design, and a small service may choose it. The service still prefers the policy for three reasons. The number is a fact of the note feature, not of the order. A class of its own shows a reader that this rule spans two aggregates. And a rule across two aggregates holds only at the moment it is checked, so it helps to see such a rule apart. Choose the parameter instead when the cross-aggregate rule is the only one, and the team prefers fewer classes.

Why not in the application service. The use case could write if (notesNeedingAction > 0) throw ... itself. A business expert would recognise that line as a rule. And a rule in one use case is missing from the next one. Suppose that the warehouse later ships orders from a message. Its listener would call another method, and that method must copy the check or forget it. A test of the rule would also need the mocks of the whole use case.

The guarantee holds only at the moment of shipping. An agent may add a note that needs action a second after the order shipped. The business owner accepted that, and the README writes the decision down. For the gap between two aggregates and the ways to close it, see the section What holds between two aggregates, and what does not.

The policy receives a number, not a list of notes. The note feature counts the notes, and gives the order feature only the count:

/** For the order feature's shipping rule: a plain number, so no note crosses the boundary. */
public long countNeedingAction(String orderId) {
    return notes.countByOrderIdAndActionRequiredTrueAndActionResolvedAtIsNull(orderId);
}

countNeedingAction returns a long. So no note object crosses from the note feature into the order feature. The order feature may not even hold one. An architecture rule makes the build fail when an application service takes another feature's entity or repository:

/**
 * A service never takes another feature's repository or entity. It asks that feature's
 * service, which checks that feature's rules. This is a narrower, clearer form of the rule
 * above for the most common mistake.
 */
public static ArchRule servicesDoNotUseOtherFeaturesRepositoriesOrEntities(String basePackage) {

ArchitectureTest runs servicesDoNotUseOtherFeaturesRepositoriesOrEntities for the order service. A note is a stored document, so it counts as an entity here. For the rules between features, see the chapter Features, layers and the rules.

Because the policy receives plain values, its test is plain JUnit:

class ShippingPolicyTest {

    private final ShippingPolicy policy = new ShippingPolicy();
    private final Order order = readyToShip();

    @Test
    void allowsShippingWhenNoNoteNeedsAction() {
        assertThatCode(() -> policy.assertCanShip(order, 0)).doesNotThrowAnyException();
    }

    @Test
    void refusesShippingWhileANoteNeedsAction() {
        assertThatThrownBy(() -> policy.assertCanShip(order, 2))
                .isInstanceOf(OrderHasOpenActionsException.class)
                .hasMessageContaining("2 note(s) need action");
    }
}

The test creates the policy with new, and passes 0 and then 2. No note, no repository and no Spring are involved. The test of the use case only checks that the steps run in order, and that nothing is saved when the rule fails:

@Test
void isRefusedWhileANoteNeedsAction() {
    Order order = readyToShip();
    when(orders.get(order.id())).thenReturn(order);
    when(notes.countNeedingAction(order.id().value())).thenReturn(1L);

    assertThatThrownBy(() -> service.ship(order.id())).isInstanceOf(OrderHasOpenActionsException.class);
    verify(orders, never()).save(any());
    verify(audit, never()).record(anyString(), anyString(), anyString());
}

The mocked note feature returns 1L, the number of notes that need action. The test expects the exception, and verify(orders, never()).save(any()) checks that nothing was saved. The policy's own test covers the values of the rule. The use case's test covers only its place in the steps.

The policy has no Spring annotation, because it is in the domain. The order feature creates it in a configuration class:

@Configuration(proxyBeanMethods = false)
class OrderConfig {

    @Bean
    ShippingPolicy shippingPolicy() {
        return new ShippingPolicy();
    }
}

@Bean tells Spring to call the method and keep the result as a bean. Spring then injects it into OrderService. For @Bean and proxyBeanMethods, see the chapter Wiring the service: the container in depth.

A decision from another service, a rule in the domainnew#

An order is placed only if the stock service can hold every product. The answer comes over HTTP, from another service. The rule "no stock, no order" belongs to this service. So the work is split in two. The use case asks, and the domain decides. The question goes through a port in the application layer:

/**
 * The port to the stock service, in this service's types. The use case does not know that the
 * answer comes over HTTP, and a unit test replaces it with a mock.
 *
 * <p>It lives in {@code application/port}, not in the domain: calling another service is a step
 * of the use case, and the domain only judges the answer.
 */
public interface StockChecker {

    /**
     * Asks the stock service to confirm that the items are available, and to hold them for the
     * order. The stock service keeps the hold until it sees {@code OrderPlacedV1}, or releases it
     * after a timeout if the order is never placed.
     *
     * <p>Calling it twice for the same order holds nothing twice, because the order ID is the
     * idempotency key.
     */
    StockAvailability reserve(OrderId order, List<OrderItem> items);
}

The comment of StockChecker says why the port is in application/port and not in the domain. Calling another service is a step of the use case. The domain only judges the answer. The answer is StockAvailability, a value object in this service's own words. For that value object, see the section Value objects as records.

The use case asks first, and then hands the answer to the order:

public PlacedOrder place(CustomerContact customer, DeliveryMethod deliveryMethod, List<OrderItem> items,
                         List<NewNote> firstNotes) {
    referenceData.requireActive(ReferenceTypes.DELIVERY_METHOD, deliveryMethod.code(), "deliveryMethod");
    OrderId orderId = OrderId.newId();
    StockAvailability availability = stock.reserve(orderId, items);           // outside the transaction

    return transaction.execute(status -> {
        Order order = Order.place(orderId, customer, deliveryMethod, items, availability, clock);

stock.reserve(orderId, items) runs before the transaction starts, because a slow HTTP call would hold the transaction open. Order.place then receives availability, and throws ProductsUnavailableException when a product is missing. For the code of place, see the section Placing versus rehydrating.

Each half has its own test. OrderTest.refusesProductsTheStockServiceCannotHold checks the rule with a value, and no stock service. The test of the use case checks the steps:

@Test
void savesNothingWhenTheStockIsNotAvailable() {
    when(stock.reserve(any(), any())).thenReturn(StockAvailability.unavailable(List.of(new ProductCode("MUG-001"))));

    assertThatThrownBy(() -> service.place(CUSTOMER, STANDARD, TWO_MUGS, firstNotes))
            .isInstanceOf(ProductsUnavailableException.class);
    verify(orders, never()).save(any());
    verifyNoInteractions(notes, events, audit);
}

The mocked port answers that the mug is not available. The test expects the domain's exception, and verifyNoInteractions(notes, events, audit) checks that no note, no event and no audit record was written. For the client behind the port, see the chapter Calling other services.

The same split works for any decision from outside. Another service, a rules engine or a person gives an answer. The use case fetches it and turns it into a value object. The domain says what the answer means for the aggregate.

The rules of the order service, and where each one isnew#

A new developer asks "where is the rule that an order cannot ship unpaid?". The answer should take one look, not a search. This table lists the rules of the service, with the place of each one:

Most rules are in the aggregate or in a value object. One is in a domain service. Two are in application services, and each of those has a reason in the last column. The check that an order exists is one of them. The order feature owns its IDs, so it checks them for the note feature:

/**
 * For other features: checks that an order exists. IDs cross between features as text, and
 * the owner of the ID checks it, so a bad ID gives the order feature's own 400 or 404.
 */
public void requireExists(String orderId) {
    OrderId id = OrderId.of(orderId);
    if (!orders.exists(id)) {
        throw new OrderNotFoundException(id);
    }
}

OrderId.of(orderId) checks the format and answers 400 for a bad ID. orders.exists(id) asks storage, which is why the check is in the application service. So the note feature gets the order feature's own 400 or 404. The README of the service lists the same rules in plain words, so the business can check them.

The lookup rule in an application servicenew#

A client sends an order with the delivery method DRONE. The format is valid, but the shop has no such method. The list of delivery methods is stored data. A seed migration can add a method, or switch one off. So the domain value object cannot know the list. The check is in the reference feature's service:

/**
 * Lists lookup values, and checks codes against them for the other features.
 *
 * <p>The rule "a code must be an active lookup value" is written once, here. Every feature asks
 * this service instead of reading the collection. An unknown or inactive code is a 400 that names
 * the field, because the client sent a value that is not allowed; it breaks no business rule
 * about the order itself.
 */
@Service
public class ReferenceDataService {
    // ...
    /**
     * Throws a 400 for the field unless the code is an active value of the list.
     *
     * @param field the request field the client must correct, such as {@code deliveryMethod}
     */
    public void requireActive(String type, String code, String field) {
        boolean known = items.findByTypeOrderByCodeAsc(type).stream()
                .anyMatch(item -> item.code().equals(code) && item.active());
        if (!known) {
            throw new InvalidValueException(field, "is not a known value");
        }
    }

The order feature calls the check as the first step of placing an order. A test checks that the stock service is never called for an unknown delivery method:

@Test
void checksTheDeliveryMethodBeforeCallingTheStockService() {
    doThrow(new InvalidValueException("deliveryMethod", "is not a known value"))
            .when(referenceData).requireActive("DELIVERY_METHOD", "STANDARD", "deliveryMethod");

    assertThatThrownBy(() -> service.place(CUSTOMER, STANDARD, TWO_MUGS, firstNotes))
            .isInstanceOf(InvalidValueException.class);
    verifyNoInteractions(stock);
}

doThrow makes the mocked reference feature refuse STANDARD. verifyNoInteractions(stock) then checks that no reservation was made for an order that can never be placed.

The exception kind is allowed here, because the platform's exception kinds are plain Java. An application service may throw them, and the platform answers each kind with its status. For the three kinds, see the section Exceptions by kind, with stable codes. For the simple level of the reference feature, see the section The simple level: the reference feature.

What an anaemic model looks like, and what goes wrongnew#

A model whose entities hold data, with the rules in service classes, is called an anaemic model. For a fair comparison of that design with an outbox, see the section An anaemic model with an outbox, compared fairly. This section shows what the design does to the place of each rule:

public class OrderService(ShopDb db)
{
    public async Task ShipAsync(Guid orderId)
    {
        var order = await db.Orders.FindAsync(orderId) ?? throw new OrderNotFound(orderId);
        if (order.Status != OrderStatus.Paid)
            throw new OrderNotPaid(orderId);

        order.Status = OrderStatus.Shipped;
        order.ShippedAt = DateTime.UtcNow;
        await db.SaveChangesAsync();
    }
}

public void ship(Clock clock) {
    requireNotFinished();
    if (status != OrderStatus.PAID) {
        throw new OrderNotPaidException(id());
    }
    if (lines.stream().anyMatch(line -> !line.isPicked())) {
        throw new UnpickedLinesException(id());
    }
    status = OrderStatus.SHIPPED;
    shippedAt = clock.instant();
    raise(new OrderShipped(id(), shippedAt));
}

Both panes refuse an unpaid order. In the C# pane, the check is in a service, and the entity has public setters. In the Java pane, the check, the change and the event are one method of the order. Three things go wrong with the anaemic form, and each one grows with the number of callers:

• Anyone can skip the rule. A batch job, an import or a second endpoint can write order.Status = OrderStatus.Shipped. The compiler allows it, because the setter is public. In the order service, no setter exists, and ArchitectureTest.entitiesHaveNoPublicSetters keeps it that way.
• The event is forgotten. Each service method that ships must also add the event. A new method can forget it, and no test fails. In the order service, ship raises OrderShipped itself.
• The time is hidden. DateTime.UtcNow inside the service reads the system clock. A test cannot fix the time, so it cannot check ShippedAt exactly. In the order service, ship receives a Clock.

These signs in a pull request show that a model is turning anaemic:

• A new public setter appears, or a setter becomes public so that a service can set a value.
• An application service tests an entity's fields with an if, and then changes that entity.
• Code calls Instant.now() or LocalDate.now() instead of a Clock.
• A test of a rule needs mocks of repositories.
• The same check appears in two use cases.

Each sign has the same fix. Move the check and the change into a method of the aggregate, and let the use case call that method.

Name a domain service after its rulenew#

A class called OrderDomainService sounds like the right place for any logic about orders. So it collects all the logic that has no obvious home. After a year, it holds a discount calculation, a date helper and three rules that belong in the aggregate. The order service names its domain service after the one rule that it checks:

/**
 * The rule that needs two aggregates: an order cannot ship while a note on it needs action.
 *
 * <p>It is a domain service because neither aggregate holds the data alone. It is named after
 * the rule, not {@code OrderDomainService}, so unrelated code does not collect in it. It takes a
 * number, not the notes, so the order feature never sees note objects. It has no state, no
 * repository and no Spring annotation, and the order feature's configuration creates it.
 *
 * <p>The guarantee holds only at the moment of shipping. An agent may add a note that needs
 * action a second after the order shipped. The service accepts that, and the README records the
 * decision.
 */

The comment of ShippingPolicy gives each choice and its reason. It names OrderDomainService as the name to avoid. The name of the class states the rule, so unrelated code has no reason to go there. It takes a number, so the order feature never sees note objects. It has no state, no repository and no Spring annotation, so it stays plain Java.

A name says what the class decides or computes. These forms keep the class small:

When a second rule across aggregates appears, write a second class with its own name. Two small policies are easier to find and to test than one service with two unrelated methods.

public class OrderHasOpenActionsException(OrderId id, long notesNeedingAction)
    : BusinessRuleViolationException("ORDER_HAS_OPEN_ACTIONS",
        $"Order {id} cannot ship while {notesNeedingAction} note(s) need action");

public class OrderHasOpenActionsException extends BusinessRuleViolationException {

    public OrderHasOpenActionsException(OrderId id, long notesNeedingAction) {
        super("ORDER_HAS_OPEN_ACTIONS", "Order " + id + " cannot ship while " + notesNeedingAction
                + " note(s) need action");
    }
}

Wiring the service: the container in depth#