DEV Community: Kamen

Testing the Service Layer - Part 2: Where the Shared Ancestor Ends (Chapter 10)

Kamen — Mon, 21 Sep 2026 08:48:39 +0000

Part 1 of this chapter was about everything AbstractCrudServiceTestCase gets to say once, for every CRUD service that will ever extend it - ownership stamping, idempotent delete, the authorization path shared by update(), loadById(), and delete() alike. That suite works precisely because the behavior it covers really is shared: the same rule, expressed once, correctly inherited by anything that extends the base class. But not everything on ProductsServiceImpl and CategoriesServiceImpl fits that description, and the clearest example is a method the abstract suite never touches at all.

Twins that aren't ancestors

changeStatus() exists independently on both concrete services, and today, the two implementations are nearly identical:

@Transactional
@Override
public void changeStatus(UUID id, ProductStatus newStatus, UUID requesterId) {
    if (requesterId == null) {
        throw new AuthorizationException(UNAUTHORIZED);
    }

    final var product = loadOrThrowNotFound(() -> getDao().loadById(id));
    authorize(product, requesterId);

    if (product.getStatus() == newStatus) {
        return;
    }

    product.transitionTo(newStatus);
    product.setUpdatedById(requesterId);

    getDao().update(product);
}

A same-status request deserved its own explicit decision rather than being left to chance. ProductStatus.ACTIVE.canTransitionTo(ACTIVE) returns false, so without the guard above, requesting a transition to the status a product already holds would throw IllegalStateException. A client retrying a timed-out request would see a failure for a change that had already succeeded. The check mirrors delete()'s idempotency rather than inventing a new definition of it. If nothing would actually change, nothing gets written, not even the audit fields. A retry that touched updatedById on a no-op would leave the audit trail implying movement that never happened. The authorization check still runs before the status comparison. A non-owner requesting the current status doesn't get a silent pass just because nothing would change.

It would be tempting to read that duplication as an oversight. Surely this belongs on AbstractCrudService, right next to create() and update(). It doesn't, for two separate reasons, and both of them are more instructive than the duplication itself.

The first is structural: not every domain in this system has a status at all. AbstractCrudService is generic over any Domain extends AbstractAuditable<UUID>, and forcing a status concept onto that hierarchy would mean either a generic hook that adds ceremony to every future service that never needs status, for example an Order that has no status field to speak of, or a leaky assumption baked into a base class that should know nothing about what any particular domain represents. AbstractAuditable knows about identity and ownership, because every domain object in this system has those. It doesn't know about status, because most won't.

The second reason is the one that actually matters going forward, and it's about where these two methods are headed, not where they are today. Product and Category don't share transition rules: ProductStatus allows a product to move from ACTIVE to OUT_OF_STOCK and back, but CategoryStatus has no equivalent at all. And the side effects each changeStatus() will eventually need to trigger are going to diverge in a way that has nothing to do with today's identical-looking code. When this system integrates with Kafka for event broadcasting, publishing a product to ACTIVE will very likely need to fire an event - a storefront needs to know a product became purchasable. Archiving a category may need to fire an event too, but only on that specific transition, not on every status change a category goes through. Those are two different rules about two different triggers, and they belong on two different methods, sitting inside two different classes, exactly where they already are.

If that behavior had been forced into a shared base method ahead of time - a generic onStatusChanged() hook, parameterized somehow to cover both cases, the divergence would have had nowhere clean to go. You'd end up either parameterizing the hook into meaninglessness, threading flags and conditionals through a method that was supposed to be simple, or growing base-class conditionals that only apply to some subclasses, which is the exact kind of rot this whole series argues against. Two classes having identical code today is evidence of nothing on its own. The real question is whether they're identical because they're expressing the same concept, or identical because they haven't yet diverged. authorize() is the same rule in both classes and will very likely stay the same rule, because ownership-based authorization isn't domain-specific - it's genuinely shared ancestry. changeStatus() is the same code in both classes today for the far less interesting reason that neither one has grown its side effects yet. Promoting the first into the base class was correct. Promoting the second would have been premature abstraction wearing the same clothes as legitimate reuse and premature abstraction is arguably the worse failure of the two, because duplication is at least honest about not knowing yet, while a wrong abstraction actively resists the divergence when it finally shows up.

The test suite reflects that boundary. Each concrete class carries its own full set of changeStatus() tests - null requester, missing entity, wrong owner, valid transition, illegal transition and none of that coverage comes from the abstract suite, because none of it can:

@Test
void changeStatus_WhenTransitionIsIllegal_ShouldThrowAndNeverPersist() {
    final Product existing = persistedProduct(UUID.randomUUID(), requesterId, ProductStatus.ARCHIVED);
    when(productDao.loadById(existing.getId())).thenReturn(existing);
    assertThrows(IllegalStateException.class, () -> productsService.changeStatus(existing.getId(), ProductStatus.ACTIVE, requesterId));
    verify(productDao, never()).update(any());
}

That's not a gap in the abstraction. It's the cost of the abstraction being drawn in the right place. "Extend, don't rewrite" only works as a principle if you're also willing to say, clearly, which things were never meant to be extended from a shared ancestor in the first place. Worth naming directly, while we're on changeStatus(): nothing in this suite would have caught it missing @Transactional. Both implementations follow the same read-modify-write shape as update() - load, mutate, persist and update() carries that annotation for exactly the reason discussed in Chapter 9: it's declarative metadata, not a framework leak, and it matters more once a side effect like Kafka event publishing eventually sits inside the same method. A mocked-DAO test verifies what a method does which calls happen, in what order, under what conditions, but the transactional boundary around those calls is applied by a Spring AOP proxy that never exists in this test setup at all. Catching a missing or misplaced @Transactional requires an integration test with a real Spring context, which is precisely the layer this chapter chose not to test. That's not a flaw in the mocked-DAO approach - it's a reminder that "100% service-layer coverage" from unit tests alone was never actually 100% of what could go wrong.

A specification hiding in a branch

Coverage tooling can tell you that a line or branch executed. It cannot tell you whether the test data and assertions proved the behavior that branch exists to protect.

if (product.getSpecification() == null) {
    product.setSpecification(new ProductSpecification(dto.getDimensions(), dto.getWeight()));
} else {
    product.getSpecification().setDimensions(dto.getDimensions());
    product.getSpecification().setWeight(dto.getWeight());
}

Before this test was added, every update test built an existing product without a specification. The update path therefore always took the if branch and created a new ProductSpecification. The else branch - the normal path for a product that already has a specification was never exercised with a fixture that could prove its intended behavior: mutating the existing object in place rather than replacing it with an equal-looking new one.

The gap was easy to miss because the suite still had broad coverage around updates, and the transformer appeared to work for the creation case. But a flipped condition, a replacement where mutation was intended, or a broken in-place update could all survive until production. The missing test was not merely about increasing a coverage percentage, It had to make the identity of the existing ProductSpecification part of the contract. The fix needed the domain to carry meaningful dimensions and weight, plus a test that could distinguish “the transformer mutated the existing object” from “the transformer built an equal-looking new one.” assertEquals cannot make that distinction on its own:

@Test
void update_WhenSpecificationAlreadyExists_ShouldMutateInPlaceRatherThanReplace() {
    final Product existing = persistedProduct(UUID.randomUUID(), requesterId, ProductStatus.DRAFT);
    existing.setSpecification(new ProductSpecification("10x10x10cm", 450));
    final ProductSpecification originalSpecification = existing.getSpecification();

    final UpdateProduct updateDto = createUpdateDomain();

    when(productDao.loadById(existing.getId())).thenReturn(existing);
    when(productDao.update(existing)).thenReturn(existing);

    final Product result = productsService.update(existing.getId(), updateDto, requesterId);

    // The transformer's else-branch mutates the existing specification rather than
    // allocating a new one - this asserts that behavior directly, not just its effect.
    assertSame(originalSpecification, result.getSpecification());
    assertEquals(updateDto.getDimensions(), result.getSpecification().getDimensions());
    assertEquals(updateDto.getWeight(), result.getSpecification().getWeight());
}

assertSame is doing real work in that test, not just being pedantic. It's the only way to actually prove the else branch ran and mutated the existing object, rather than the if branch running and happening to produce a new object that merely looks equal. Those are two different code paths, guarding against two different bugs, and a weaker assertion would have let either one hide behind the other.

When a fixture stops earning its keep

The suite went through one more revision worth describing, not because the bug it fixed was dramatic, but because it happened inside the test code itself, and the same discipline that applies to production code turned out to apply there too. The original fixture for building an already-persisted entity - needed by every update, delete, and loadById test that requires an existing owner routed through the service's own create() method:

private Domain createPersistedEntity(UUID ownerId) {
    final UUID entityId = UUID.randomUUID();

    when(getMockDao().create(any())).thenAnswer(invocation -> withId(invocation.getArgument(0), entityId));

    final Domain persisted = getService().create(createValidNewDomain(), ownerId);

    assertNotNull(persisted);
    assertEquals(entityId, persisted.getId());
    assertEquals(ownerId, persisted.getCreatedById());

    clearInvocations(getMockDao());

    return persisted;
}

It worked, but it created a dependency that had no business existing: every update, delete, and loadById test in the suite now implicitly depended on create() behaving correctly, purely to get a fixture into existence. If create() ever broke - a transformer throwing, an authorization check misfiring, every ownership test across every concrete service would fail alongside it, for a reason that had nothing to do with what those tests were actually named after. That's a diagnostic cost paid every time someone opens a build with ten failing tests and has to work backward to discover that only one of them represents a real bug. Worse, it needed clearInvocations() afterward, purely to erase the trace that fixture setup had left on the mock, a workaround whose only purpose was to hide the coupling it had just introduced. The replacement drops the indirection entirely, each concrete class already had, separately, a direct helper that builds a persisted entity through its own constructor - no mock, no service call, no cleanup required:

protected abstract Domain buildPersistedEntity(UUID id, UUID ownerId);

private Domain persistedEntity(UUID ownerId) {
    return buildPersistedEntity(UUID.randomUUID(), ownerId);
}

@Override
protected Product buildPersistedEntity(UUID id, UUID ownerId) {
    return persistedProduct(id, ownerId, ProductStatus.DRAFT);
}

private Product persistedProduct(UUID id, UUID ownerId, ProductStatus status) {
    final var product = new Product(id, Instant.now(), Instant.now(), status);
    product.setName("Existing Product");
    product.setSku("EXISTING-SKU");
    product.setPrice(BigDecimal.TEN);
    product.setCreatedById(ownerId);
    product.setUpdatedById(ownerId);
    return product;
}

Now withId() has exactly one caller left - the create-ownership test, the one place that genuinely needs to simulate what a real DAO does on persistence and buildPersistedEntity() has exactly one job, building a fixture, with zero coupling to whether create() happens to work on a given day. Two mechanisms had grown up to solve what was really one problem, and the fix wasn't clever, just a refusal to let that stand. It's worth naming directly: the same principle this whole chapter argues for in production code - extend or override, don't quietly duplicate a slightly different version of the same mechanism applies just as much to the tests themselves. A test suite that hasn't had this kind of pass run over it tends to accumulate exactly this shape of redundancy, because nobody sets out to write two fixture mechanisms, they arrive one at a time, each locally reasonable, and only look wrong once they're standing next to each other.

What this buys, concretely

Put the whole suite next to the two concrete classes and the claim this chapter opened with is checkable rather than rhetorical. AbstractCrudServiceTestCase carries every test for create(), update(), loadById(), and delete() - authorization guards, not-found guards, ownership stamping, idempotent delete - written once, against the shape every future CRUD service will share. ProductsServiceTestCase and CategoriesServiceTestCase add only what's actually theirs: field mapping through their own transformer, the specification branch in Product's case, and a full changeStatus() suite each, because that behavior was never ancestral to begin with. A future OrdersServiceImpl extending AbstractCrudService inherits the first category for free, the same way ProductsServiceImpl and CategoriesServiceImpl did, and only has to write tests for whatever is genuinely its own.

That's the return on the investment this chapter spent both of its halves on: not a percentage on a coverage report, but a shrinking marginal cost for every service this codebase adds from here forward, a boundary drawn deliberately between what gets inherited and what gets grown independently, and a test suite that fails for the reason its name says it will fail, and nothing else.

What's Next?

The service layer this chapter tested stays deliberately ignorant of anything outside it - no Spring context, no HTTP, no idea that a REST controller exists. That ignorance has a cost that hasn't been paid yet: when AuthorizationException or NotFoundException crosses out of the business logic module, something still has to decide it becomes a 401 or a 404. Chapter 11 is about where that decision lives, and why the domain layer should never be the one making it.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 10, use the following link:

GitHub Repository (Tag: chapter-10-bl-testing): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 10, Part 1: What the Generic Suite Owes Every Service
▶️ Read Chapter 11: Error Handling and Domain Exceptions Across Module Boundaries (Coming soon)

Join the Masterclass Journey

This article is part of an ongoing weekly series. If you want to receive every upcoming chapter directly in your inbox, alongside deep-dives, infrastructure architecture diagrams, and premium insights before anyone else, subscribe to my Substack Newsletter here!

Recommended Resources for Java & Spring Boot Engineers

Disclosure: I earn a commission if you purchase through the links below, at no additional cost to you.

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

Testing the Service Layer - Part 1: What the Generic Suite Owes Every Service (Chapter 10)

Kamen — Tue, 15 Sep 2026 12:00:50 +0000

In the preceding chapters, I built a clean architecture with a distinct demarcation line between the domain model, infrastructure, and web layers. The services orchestrate business logic without any awareness of Hibernate, SQL, or HTTP protocols. I apply Spring’s @Transactional declaratively solely at the service level as the transaction boundary of the Use Case, while keeping the services themselves completely clean.

Now I collect the biggest dividend of that discipline: the ability to test the entire business logic in milliseconds, with zero dependencies on the Spring context and zero real databases.

Here is a fixture I'd left half-finished.

when(getMockDao().create(any())).thenAnswer(invocation -> {
    final Domain domain = invocation.getArgument(0);
//  domain.setId(entityId);
    domain.setCreatedById(requesterId);
    savedEntity.set(domain);
    return domain;
});

That commented-out line had been sitting there since the first draft of this fixture, a placeholder from when I was sketching out what a persisted entity should look like, meant to be finished once I got back to it. I didn't get back to it. The test above it kept passing anyway, for reasons I hadn't stopped to check, and a commented-out line that nobody's chasing has a way of looking like it isn't hiding anything. It was, once I went to actually uncomment it. Product extends a base class where id is declared final, assigned once in the constructor, never touched again for the life of the object. There is no setter to call - the line wasn't just unfinished, it was never going to compile. Which meant the fixture had never actually simulated what it claimed to: a DAO assigning an identity on persistence. It had been silently omitting that step since the day I wrote it, and the test suite built on top of it - every update, delete, and loadById test that depends on this same fixture for a "persisted" entity had never noticed, because none of those tests were checking whether the id it produced meant anything. They were checking whether a value came back, and a value always did.

Once I saw it, the question stopped being "why is this line wrong" and became "why does this class refuse to let it be right." A mutable id would mean an object could change what it is mid-lifecycle - that a Product persisted under one identity could quietly become a different Product without anyone reassigning the reference. The equality contract further up the hierarchy is built entirely on that id. If it moved, two variables holding what used to be the same entity could silently stop agreeing on whether they still were. Making id final wasn't an oversight that happened to inconvenience a test author. It was a decision that a domain object's identity is not something even its own author gets to revise after the fact and a mock that pretends otherwise isn't a shortcut, it's a small act of denying that decision ever happened. Which means the actual bug wasn't the missing setter. The actual bug was a fixture that had been left to imply persistence without ever actually simulating it. A real DAO doesn't mutate the transient instance you hand it. It takes what you give it - no identity yet, nothing persisted and it hands back something new, same data, an id that didn't exist a moment ago. The mock's job was never to make the assertion pass. It was to tell the same story a real database would tell, minus the SQL.

This is the shape most of the mistakes in this chapter turned out to have. Not a typo, not a missed edge case in the everyday sense, but a test quietly rewriting the contract of the thing it was supposed to be checking, because rewriting the contract was easier than satisfying it. AbstractCrudServiceTestCase - the generic suite that every CRUD service in this codebase is meant to inherit for free, three abstract hooks and nothing else to implement, had this problem baked into its shared fixture, which meant the problem wasn't confined to one test. It was inherited by every service that extended the base class, silently, the way a real trait gets inherited: without anyone deciding to pass it on. That word - inherited, is worth sitting with the rest of this chapter, because it cuts both ways, and the good half of it is the actual point. The same mechanism that let one broken fixture assumption propagate to every concrete service is the mechanism that, once fixed, lets every concrete service pick up the correct behavior without anyone touching them again. ProductsServiceTestCase and CategoriesServiceTestCase didn't need to relearn what ownership-stamping means, or what an idempotent delete looks like, or how authorization should fail. They inherited it - the way an organism inherits a nervous system rather than growing one from scratch each generation. And they only had to express what was actually theirs: how a Product maps its own fields, what it means for a Product specifically to change status, what a Category does differently. Software that evolves rather than gets rewritten looks like this from the inside. Not code that never changes, but code where the right thing changes and nothing else has to.

Why mock the DAO instead of an in-memory database

Before any of that inheritance can happen, there's a decision underneath it that's easy to walk past: why mock the DAO at all, instead of pointing every test at an in-memory database and calling it a day. I'd spent years testing the persistence layer that way - an H2 instance, Flyway migrations running against it, real SQL executing against a real schema and it worked, in the sense that it caught real bugs. But it was testing a different layer than the one I needed to test here, and conflating the two is exactly the kind of unexamined habit that produces slow, ambiguous test suites without anyone deciding that's what they wanted.

An in-memory database test of ProductsServiceImpl.create() verifies two things at once, bundled together whether you like it or not: that the service's own logic is correct, and that Hibernate's mapping, the schema, and the query it generates are all correct. When that test fails, you don't know which of those two failed without opening the stack trace and reading past the assertion into the actual exception. A ConstraintViolationException on a NOT NULL column tells you the schema and the entity disagree about nullability - a real, valuable thing to know but it tells you nothing about whether authorize() correctly rejects a non-owner, which is a business rule with no SQL in it at all. Persistence-layer testing, which I covered back in Chapter 7, exists precisely to isolate that first category of failure. Business-logic testing needs to isolate the second, which means the persistence layer has to be prevented from participating in the test at all. A Dao mock doesn't approximate a database, it refuses to be one. productDao.create(any()) returns exactly what the test tells it to return, nothing more, and if ProductsServiceImpl.create() is wrong, that wrongness has nowhere to hide behind an ORM quirk. The cost of that isolation is that a mocked-DAO test suite can be lying to you in a way an in-memory database test can't. Mockito doesn't know what ProductDao.create() is supposed to do, it only knows what you told it to do when you wrote when(...).thenAnswer(...). If that stub embeds an assumption that doesn't match how the real ProductDaoImpl actually behaves, the test can pass forever while the production code silently diverges from the fixture's model of it. That's not a hypothetical risk, it's the exact failure mode the half-finished create() fixture represented, just at the interface boundary instead of inside a single test. Coverage percentage cannot see this category of bug, because coverage measures whether a line executed, not whether the value flowing through that line at test time was honest. A mocked-DAO suite earns its speed and its isolation by taking on a permanent, structural obligation: every stub has to be checked, by a human, against what the real implementation actually contracts to do - the DAO's Javadoc, its own persistence-layer tests from Chapter 7, its behavior under the constraints the database schema actually enforces. Chapter 7 and this chapter aren't separate concerns that happen to share a domain object, they're two halves of a coverage claim that's only true if both halves hold, and neither replaces the other's job.

What the abstract suite actually asks of a new service

The whole promise of the base class is that a new CRUD service - some future OrdersServiceImpl, some future WarehousesServiceImpl - gets four operations, fully tested, in exchange for implementing three methods: a create transformer, an update transformer, and an authorization rule. Everything else is inherited, unquestioned, from AbstractCrudService and its matching AbstractCrudServiceTestCase. It's worth walking through why each of those four operations is shaped the way it is, because none of the shapes were arbitrary, and a few of them only look obvious in hindsight. create() has exactly one guard - a null requesterId throws before anything else runs, and then it does something that's easy to read past: it stamps createdById and updatedById onto the domain object itself, before the DAO ever sees it. The test that proves this uses an ArgumentCaptor rather than inspecting the method's return value, and the distinction matters more than it looks like it should.

@Test
void create_WhenRequesterIdIsPresent_ShouldStampOwnershipBeforePersisting() {
    final NewDomain newDomain = createValidNewDomain();
    final UUID assignedId = UUID.randomUUID();

    when(getMockDao().create(any())).thenAnswer(invocation -> withId(invocation.getArgument(0), assignedId));

    final Domain result = getService().create(newDomain, requesterId);

    final ArgumentCaptor<Domain> captor = ArgumentCaptor.captor();
    verify(getMockDao(), times(1)).create(captor.capture());
    final Domain domainPassedToDao = captor.getValue();

    // A transient domain has no identity until the DAO assigns one - the service must never invent an id itself.
    assertNull(domainPassedToDao.getId());
    assertEquals(requesterId, domainPassedToDao.getCreatedById());
    assertEquals(requesterId, domainPassedToDao.getUpdatedById());
    assertEquals(assignedId, result.getId());
    assertEquals(requesterId, result.getCreatedById());
}

The test needs to distinguish two moments in time that a single returned object collapses into one: what the service handed the DAO before persistence, and what the DAO handed back after. If I only inspected result - the return value of create(), I'd be looking at the post-persistence object, the one withId() constructed, and I'd have no way of proving that createdById was already set on the object before it reached the DAO rather than after. That distinction sounds pedantic until you imagine the bug it protects against: a future version of create() that persists the domain object first and only stamps ownership afterward, in a follow-up dao.update() call. That version would produce an identical-looking result. It would also mean a brief window during which an unowned entity exists in the database, which is precisely the kind of window a security review should be able to trust the test suite to have already ruled out. ArgumentCaptor.capture() freezes the argument at the moment of the call, not at the moment of the test's assertion, which is the only way to make that distinction visible.

withId() itself exists because of the same immutability the opening story ran into. There is no setId() anywhere in the hierarchy, by design, so a mock that simulates persistence has to construct a genuinely new instance carrying the assigned identity rather than mutate the one it was handed. Each concrete test class implements it once, against its own domain object's actual constructors:

@Override
protected Product withId(Product transientProduct, UUID id) {
    return new Product(
            id,
            transientProduct.getCreatedById(),
            transientProduct.getUpdatedById(),
            transientProduct.getName(),
            transientProduct.getSku(),
            transientProduct.getPrice(),
            transientProduct.getSpecification()
    );
}

update() carries a signature decision worth naming directly: authorize(Domain domain, UUID requesterId) takes the full, already-loaded entity, never just its id. It would have been the more obvious signature to reach for, and it would have quietly forced every implementation to reload the entity a second time inside authorize() itself, since ownership checks need to inspect getCreatedById(), and an id alone tells you nothing about who created anything. Passing the already-loaded domain object means the one dao.loadById() call inside update(), loadById(), and delete() does double duty: it fetches the entity for the operation, and it hands that same instance to the authorization check without a second round trip. In a mocked-DAO test, this shows up as a single verify(getMockDao(), times(1)).loadById(...) and the fact that it's times(1) and not times(2) is itself asserting something about the architecture, not just about the test. If a future refactor accidentally reintroduced a second load inside authorize(), this test would catch it immediately, because the interaction count would change even though every return value would still look correct.

The update test that checks ownership survives correctly is doing a similarly specific job, and it's worth naming exactly what regression it exists to catch, because on the surface it looks like it's testing something that can't fail:

@Test
void update_WhenRequesterIsOwner_ShouldPersistWithUpdatedByChangedAndCreatedByPreserved() {
    final Domain existingDomain = persistedEntity(requesterId);
    final UpdateDomain updateDomain = createUpdateDomain();

    when(getMockDao().loadById(existingDomain.getId())).thenReturn(existingDomain);
    when(getMockDao().update(any())).thenAnswer(invocation -> invocation.getArgument(0));

    final Domain result = getService().update(existingDomain.getId(), updateDomain, requesterId);

    final ArgumentCaptor<Domain> captor = ArgumentCaptor.captor();
    verify(getMockDao(), times(1)).update(captor.capture());
    final Domain persisted = captor.getValue();

    assertEquals(existingDomain.getId(), persisted.getId());
    assertEquals(requesterId, persisted.getCreatedById());
    assertEquals(requesterId, persisted.getUpdatedById());
    assertEquals(existingDomain.getId(), result.getId());
}

getUpdateTransformer().copyToOutput(updateDomain, domain) is supposed to copy only the fields the update DTO actually carries - name, SKU, price, dimensions onto the loaded domain object. Nothing about UpdateProduct or UpdateCategory mentions createdById. But "the DTO doesn't carry the field" and "the transformer definitely won't touch the field" are two different guarantees, and only one of them is enforced by the type system. The shared transformer base class both UpdateProductTransformer and UpdateCategoryTransformer extend is exactly the kind of shared code where a well-intentioned future change could add a line that resets audit fields as a default, on the reasoning that every update should reset something. If that line ever landed, every existing test that only asserts on name, SKU, and price would keep passing, because none of them look at createdById at all. The test doesn't exist because I distrust today's transformer. It exists because the transformer is shared ancestry, and shared ancestry is exactly where a mistake gets inherited by every subclass at once - the same lesson the opening story already taught the hard way.

loadById() and delete() follow the same authorization pattern as update(), with one deliberate asymmetry worth calling out: delete() is idempotent by design, established back in Chapter 9 on RFC 7231 grounds, and the test proving it looks almost suspiciously simple:

@Test
void delete_WhenEntityDoesNotExist_ShouldBeANoOp() {
    final UUID randomId = UUID.randomUUID();
    when(getMockDao().loadById(randomId)).thenReturn(null);

    assertDoesNotThrow(() -> getService().delete(randomId, requesterId));

    verify(getMockDao(), times(1)).loadById(randomId);
    verify(getMockDao(), never()).delete(any());
}

There's no exception to catch, no return value to inspect, the entire assertion is behavioral: the DAO gets asked to look, and is never asked to delete something that was never there. It's a small test, and it's easy to underrate exactly because it's small. A previous version of this same test verified dao.create() was never called instead of dao.update() - the wrong method entirely, copy-pasted down from a sibling test and never corrected. It would have passed forever regardless of what delete() actually did, because nothing it checked had anything to do with deletion. The fix wasn't clever, it was reading the test's own name against its own assertions and noticing they'd stopped agreeing with each other.

BigDecimal, and the failure that only shows up later

One more small decision belongs in this section, not because it's exotic, but because it's the kind of mistake that's genuinely invisible until it produces a wrong invoice in production. BigDecimal.equals() considers scale part of the value being compared - new BigDecimal("239.99").equals(new BigDecimal("239.990")) returns false, despite both representing the identical monetary amount. A field-mapping test asserting assertEquals(newDto.getPrice(), result.getPrice()) would be correct today, while the DTO and the domain object happen to construct their BigDecimal values with matching scale, and would become a source of mysterious, intermittent test failures the moment either side's construction path changed - a different BigDecimal.valueOf(...) overload, a database column that returns a different scale than the one supplied. Every price assertion in this suite uses compareTo() == 0 instead, because that's the only question that actually matters for money: are these the same amount, not are these represented identically.

assertEquals(0, newDto.getPrice().compareTo(result.getPrice()));

Getting this wrong in a chapter about testing discipline would have been its own small failure of the thing the chapter argues for.

What's inherited, and what isn't yet

AbstractCrudServiceTestCase now does exactly what it was supposed to: every guard, every ownership rule, every authorization path for create(), update(), loadById(), and delete() is written once, and any CRUD service that extends AbstractCrudService picks all of it up without writing a line. ProductsServiceTestCase and CategoriesServiceTestCase prove it by how little they have to add on top - field mapping through their own transformer, and nothing else that this generic contract already covers.

But "nothing else that this generic contract covers" is doing some quiet work in that sentence, because there's a whole method - changeStatus() sitting on both concrete services that the abstract suite never touches at all, and it's worth asking why before assuming it's an oversight.

Part 2 picks up exactly there: why changeStatus() was deliberately left out of the shared ancestor, a coverage gap that survived hiding inside a fully-executed branch, and one more pass through the test suite itself to find a redundancy that had no business surviving this long.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 10, use the following link:

GitHub Repository (Tag: chapter-10-bl-testing): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 9: The Core Business Logic Module
▶️ Read Chapter 10 - Part 2: Testing the Service Layer: Where the Shared Ancestor Ends (Coming soon)

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

Our H2 tests passed but postgres in production disagreed

Kamen — Mon, 14 Sep 2026 07:20:09 +0000

The test suite was green, as it had been for months. The migration ran clean on H2, the repository tests passed, the CI pipeline gave its usual thumbs up, and the change went out. A few hours later, a batch job that touched category records started failing in production with an error none of us recognized on sight: invalid input value for enum category_status. We didn't have that enum in our test environment. We had a VARCHAR column.

The status field had gone through a refactor earlier in the year, moving from a loose two-value flag to a proper three-value enum, ACTIVE, INACTIVE, ARCHIVED. On Postgres, that was implemented as a native enum type at the database level, which is the stricter, more correct way to do it, since the database itself now refuses anything outside the three allowed values. On H2, for reasons that made sense at the time and stopped making sense the day this happened, the equivalent migration script defined the column as a plain string. H2 doesn't support native Postgres enum types, so somewhere along the way the two migration scripts had quietly diverged, one for tests, one for production, and nobody had flagged it as a problem because both passed their respective test suites.

The batch job was writing a leftover status value from before the refactor, a string that used to be valid and no longer was. On H2, that string went into a VARCHAR column without complaint. On Postgres, the database did exactly what a native enum type is supposed to do and rejected it outright. The bug wasn't really in the batch job. It was in the fact that our tests had never once run against a schema that could actually catch this class of error, because the schema they ran against wasn't the same schema running in production.

2026-03-14 14:22:07.113 ERROR --- [batch-worker-3] o.h.engine.jdbc.spi.SqlExceptionHelper
org.postgresql.util.PSQLException: ERROR: invalid input value for enum category_status: "LEGACY_HIDDEN"
at CategoryStatusUpdateBatchJob.processRecord(CategoryStatusUpdateBatchJob.java:47)
at o.hibernate.exception.internal.SQLStateConversionDelegate.convert
H2 test run for this batch job: PASSED

We moved that test suite onto Testcontainers, running the real Postgres migration script instead of an H2 substitute, and reran the batch job's test coverage against it. It failed on the first run. Ten minutes of investigation, and it was pointing at the exact same invalid enum value production had hit, except this time in a local test run instead of an incident channel.

The lesson isn't that H2 is bad, it's fast and convenient for a lot of testing. The lesson is that convenience has a boundary, and that boundary is anywhere your production database enforces something your test database doesn't know how to enforce. If your schema does real work at the database level, constraints, enums, exclusion rules, your tests need to run against a database willing to do that same work. Otherwise green tests are only telling you the code runs, not that it's correct.

More like this?
I write short production war stories like this one, plus a deep-dive architecture series. Subscribe here if you want both in your inbox.

Recommended Resources for Java & Spring Boot Engineers

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

One Missing Parameter Doubled Our Connection Pool Wait Time

Kamen — Fri, 11 Sep 2026 08:47:15 +0000

It was a Friday afternoon, the worst possible time for an incident, which is of course when it happened. Traffic was at its weekly peak, and our connection pool metrics started climbing in a way that didn't match the load. Requests weren't failing outright, they were just queuing, waiting longer and longer for a connection to free up. Nothing in the code had changed that week. Nothing in the infrastructure had changed either. The only thing that had changed was traffic volume, and the pool was buckling under it far earlier than our capacity planning said it should. The investigation started where these things usually start, with dashboards and guesses. CPU was fine. Database load was fine. The pool itself was correctly sized for what we thought our read-to-write ratio was. That assumption turned out to be the problem.

A handful of endpoints, all of them read-only by contract, category listings, product lookups, dashboard summaries, were annotated with plain @Transactional, missing the readOnly = true attribute. They worked and they returned the correct data. Nothing about their behavior looked wrong in any functional test. But without that attribute, Hibernate treated every one of those calls as a potential write, It tracked every loaded entity for dirty checking, it ran a flush at the end of the transaction to look for changes to persist, and none of that work is free. On a single request it costs a few milliseconds nobody notices but multiply it across the volume of read traffic we get at peak, and connections were being held measurably longer than they needed to be, which meant fewer of them were cycling back into the pool for the next request in line.

The fix was easy enough - adding readOnly = true to those methods took an afternoon. Hibernate skips the dirty check, skips the flush, and the transaction closes as soon as the data is read. Pool wait times at the next peak dropped by roughly half, which lines up with how much of our traffic was hitting those endpoints in the first place.

What stuck with me afterward wasn't the fix, it was how invisible the cost was until the volume made it visible. readOnly = true reads like a hint, almost decorative, the kind of thing that's easy to skip when you're moving fast and the tests are green but it isn't decorative. It's telling the persistence layer to stop doing work it was never going to need, and at scale that work adds up to real contention on a resource every request in your system is competing for.

If you're auditing your own services for this, the search is quick: grep for @Transactional without readOnly, then check whether the method actually writes anything. The attribute costs a few keystrokes but the absence of it costs connections you'll be short of exactly when you can least afford it.

More like this?
I write short production war stories like this one, plus a deep-dive architecture series. Subscribe here if you want both in your inbox.

Recommended Resources for Java & Spring Boot Engineers

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

The Core Business Logic Module (Chapter 9)

Kamen — Mon, 07 Sep 2026 09:43:43 +0000

A business layer is only as independent as the shape of the objects that cross its boundary. It doesn't matter how carefully a service class avoids importing javax.servlet or a Kafka client if the object it accepts as input is a one-to-one mirror of the database row. At that point the transport has already leaked in, just wearing a plain Java object instead of a @RequestBody annotation. The rule this chapter works from is narrow enough to apply consistently: a service method's input should reflect what a caller is allowed to do, not what the entity happens to look like. Creating a product and updating one are different operations with different rules about what's mutable, who sets what, and what's off-limits entirely - so they get different input types, even when large parts of them overlap. The same goes for who's asking: a requesterId arrives as a bare UUID, and the service has no idea about whether it came from a JWT claim, a session, or a Kafka message header. That indifference is the actual independence being aimed for, not the absence of framework imports.

What makes this rule worth a full chapter, rather than a paragraph, is the case where following it isn't obvious, where a field looks like it belongs on one side of the boundary until you actually reason through what the operation is supposed to guarantee.

What "independent" is supposed to mean

"Business logic should be independent of transport and infrastructure" gets repeated often enough that it stops meaning anything. In practice, for this service layer, it means three concrete things:

The service methods don't know whether the caller is a REST controller, a Kafka listener, or a CLI tool. They take a requesterId as a UUID and a domain-shaped input, and that's the entire contract. Nothing about how that UUID was extracted - JWT claim, session or a message header.

The service methods don't know what database sits behind the DAO. AbstractCrudService depends on CrudDao<UUID, Domain>, an interface. Whether that's MySQL, an in-memory test double, Apache Coherence or something else entirely is invisible from here.

And the service methods don't accept whatever shape of data happens to be convenient for the caller. They accept exactly the shape that matches what the operation is allowed to do. That third point is where status transitions turn out to be a harder case than they first look, so it's worth slowing down on.

Different intent, different object

NewCategory carries just a name - a category is created without a provided status at all, it's INACTIVE by default until someone deliberately changes that. UpdateCategory carries a name too, because renaming a category turned out to be a legitimate, unremarkable operation with no special rule attached to it. What it doesn't carry is status, and that absence is the interesting part:

public class UpdateCategory {
    private String name;
    // no status field
}

That's not the same reasoning as leaving a field off because it's immutable, name isn't immutable here, it's just not entangled with anything else. Status is left off for the opposite reason: changing it is entangled with a rule, the same kind Product enforces through transitionTo. A category can move from INACTIVE to ACTIVE or straight to ARCHIVED, but once ACTIVE it can only be archived, and ARCHIVED is terminal - no path back. None of that belongs in a generic update method next to a name change, so it doesn't live there. It lives in its own operation:

public void changeStatus(UUID id, CategoryStatus newStatus, UUID requesterId) {
    final var category = loadOrThrowNotFound(() -> getDao().loadById(id));
    authorize(category, requesterId);
    category.transitionTo(newStatus);
    category.setUpdatedById(requesterId);
    getDao().update(category);
}

This category originally shipped with a plain active boolean, and for a while that was a perfectly reasonable representation, there were exactly two states, and a flag models two states fine. The same reasoning that shaped ProductStatus into a guarded enum applied here too, once a third state showed up: a boolean has no way to express "archived" without either overloading active = false to mean two different things, or bolting on a second flag and hoping the combination of both flags never goes somewhere nonsensical. The category status shows that lesson getting applied a second time, ahead of the problem this time rather than after it, a CategoryStatus enum with the same canTransitionTo shape as ProductStatus, so a name change and a status change stay two operations that can never be confused for one.

NewProduct and UpdateProduct follow the same instinct for most fields, no caller ever gets to set id, createdAt, or createdById from outside, because those fields don't exist on either input object. They're populated by the service (preProcessNewEntity) or never populated by input at all. A create payload and the domain object it produces are not the same shape, on purpose, and that gap is the whole point: it's not possible to forge a creation timestamp or claim someone else's authorship, because there's no field to put it in. The same discipline shows up in how UpdateProductTransformer handles the embedded specification, and it's a smaller but no less deliberate decision:

if (product.getSpecification() == null) {
    product.setSpecification(new ProductSpecification(dto.getDimensions(), dto.getWeight()));
} else {
    product.getSpecification().setDimensions(dto.getDimensions());
    product.getSpecification().setWeight(dto.getWeight());
}

An update caller sends flat dimensions and weight fields, not a ProductSpecification object. The transformer decides whether that means constructing a new embedded object or mutating an existing one, and the caller never has to know or care which branch ran. That's the input shape matching the operation, not the internal object graph, a product created without dimensions can still be updated to add them later, without the caller needing to understand that ProductSpecification exists as a separate type at all.

Status is where that question gets harder to answer by instinct, and it's worth reasoning through it explicitly. At first glance, status looks like it belongs on UpdateProduct next to name, SKU, and price, it's a field on the entity, the caller wants to change it, so it goes in the update payload with the rest. That reasoning holds right up until you ask what "changing status" is actually supposed to mean, and the domain object itself answers that question before the DTO gets a chance to:

public void transitionTo(ProductStatus nextStatus) {
    if (!this.status.canTransitionTo(nextStatus)) {
        throw new IllegalStateException(
            "Business rule violated: Cannot transition from " + this.status + " to " + nextStatus);
    }
    this.status = nextStatus;
}

Product doesn't expose a setStatus. It exposes a guarded transition. There's no legal way to skip from DRAFT straight to ARCHIVED, or to move backward from PUBLISHED to DRAFT, without the domain itself refusing. That's the correct place for that rule to live - not in a controller, not in a transformer, not scattered across whichever service happens to touch the domain next. Which means a plain field copy in the transformer - product.setStatus(dto.getStatus()) was never going to be the right move, regardless of whether anyone remembered to write it. It would have bypassed canTransitionTo entirely, applying whatever status the caller sent without checking if the move was legal. Once that's clear, the field doesn't belong on UpdateProduct at all, not because leaving it there caused a defect, but because a generic update method has no business deciding whether a status transition is allowed. That's a different kind of operation, with its own rule, and it earns its own method - the same one Category already uses:

public void changeStatus(UUID id, ProductStatus newStatus, UUID requesterId) {
    final var product = loadOrThrowNotFound(() -> getDao().loadById(id));
    authorize(product, requesterId);
    product.transitionTo(newStatus);
    product.setUpdatedById(requesterId);
    getDao().update(product);
}

It's worth noticing that this is the exact same shape as Category.changeStatus - same load, same authorize call, same transition, same save. Neither entity needed a bespoke publish() or activate() method with its own hand-rolled orchestration. The variation between products and categories lives entirely inside canTransitionTo, where it belongs, not in how the operation is wired up around it.

Now there are three independent layers standing between a caller and an invalid state: the DTO doesn't carry the field at all, the service exposes the change as a named, intentional action, and the domain object enforces the transition rule regardless of who calls it. Any one of those layers failing doesn't compromise the other two. That's worth more than a single well-placed validation, because it's the kind of protection that survives someone else touching the code six months from now without having read this chapter.

The same status reasoning extends one layer further, past persistence. CategoryStatus - the domain enum with canTransitionTo and CategoryStatusEntity the JPA-mapped enum stored as a string column are two separate types, converted explicitly at the DAO boundary rather than shared directly. The domain module never imports anything from jakarta.persistence, so it has no idea EnumType.STRING exists, or that the column is even a string rather than an integer code. That's the same independence argument as the transport boundary, aimed at the other side of the service: the business rule for what states a category can move through doesn't change if the storage representation does.

The template, and what it deliberately doesn't decide

AbstractCrudService is the same shape for both ProductsServiceImpl and CategoriesServiceImpl, and that repetition is intentional rather than lazy. create, update, loadById, and delete are implemented once, in the base class, calling out to a small set of abstract hooks:

protected abstract Transformer<CreateDomain, Domain> getCreateTransformer();
protected abstract Transformer<UpdateDomain, Domain> getUpdateTransformer();
protected abstract void authorize(Domain domain, UUID requesterId);

Each concrete service answers three questions - how do I build this domain object from a create payload, how do I apply an update payload, and who's allowed to touch this domain object and the orchestration around those answers (transaction boundaries, null checks, the not-found and unauthorized exceptions) is written exactly once.

It's worth addressing the one place this chapter's independence argument looks like it bends: every write method carries @Transactional, a Spring annotation, sitting directly in what's supposed to be framework-agnostic business logic. That's a smaller compromise than it looks. @Transactional is declarative metadata, read reflectively by a proxy Spring builds around the class - the method itself never touches a TransactionManager, never begins or commits anything, never knows the annotation is even being honored. Strip Spring from the classpath and the method still compiles and runs, just without the transactional wrapping. That's a fundamentally different kind of coupling than a JPA entity or an HttpServletRequest parameter would be, where the method literally cannot execute without the framework type on the classpath.
The alternative - moving transaction demarcation out to the controller, or configuring it externally via XML or AspectJ doesn't remove the framework, it just relocates a decision that belongs here anyway: what counts as one atomic unit of work for a given operation is a business question, not a transport one. A controller has no basis for deciding whether update() should be one transaction or two. That's exactly why this rule is enforced at exactly one layer. @Transactional lives on service methods, in this base class or its concrete implementations, and nowhere else. Not on controllers, not inside DAO implementations. A transaction boundary that can start from either direction is a transaction boundary nobody can reason about.

Notice also what Transformer<CreateDomain, Domain> doesn't do: it only moves data one direction, from the create or update input object into the domain object it produces. There's no copyToInput here for turning that domain object back into a response shape, that's a different interface entirely, used elsewhere in the codebase for DTO serialization. Collapsing the two into one bidirectional transformer would be a natural shortcut, since a lot of the field-copying code would look identical going either direction. It would also mean the same class that decides how a creation payload becomes a product is now also deciding how a product becomes an API response and the moment those two responsibilities share a class, it becomes easy to add a field to one direction and forget the other silently breaks the boundary this chapter is about. Keeping create/update transformers strictly one-way means that possibility doesn't exist structurally, not just by convention.

authorize is worth pausing on, because it takes the fully loaded domain object, not just an id:

protected void authorize(Product domain, UUID requesterId) {
    if (!domain.getCreatedById().equals(requesterId)) {
        throw new AuthorizationException(UNAUTHORIZED);
    }
}

That forces a load before the authorization check can run, which looks like it could be optimized away. It can't, not without losing generality. Ownership by creator works for products, but nothing guarantees the next domain object's access rule is that simple, it could depend on a collaborator list, a tenant boundary, a status field, any combination of the object's own state. The moment authorization can depend on arbitrary domain content, loading the object first stops being a choice and becomes a requirement. The base class doesn't try to special-case this, it just accepts the domain object as a parameter and lets each subclass decide what "authorized" means for that domain.

delete carries a smaller, quieter version of the same idea:

final var domain = dao.loadById(id);
if (domain == null) {
    return;
}

Deleting something that doesn't exist isn't an error here - it's a no-op. That's a defensible, idempotent design, and it matches how HTTP itself defines the semantics of DELETE: RFC 7231 specifies DELETE as idempotent, meaning repeated identical requests should leave the system in the same end state as a single one - a resource that's already gone stays gone, without that repetition needing to be an error. It's also easy to violate by accident. When someone adds anything after dao.delete() in this method - an audit entry, a notification, anything - that addition needs to remember this early return exists, or it'll fire for deletes that never happened. Worth a comment at the call site, not because the current code is wrong, but because the next change to it won't have this context unless it's written down.

What this buys, concretely

None of this is abstract payoff. A ProductsServiceImpl constructed with nothing but a ProductDao can be exercised with a mocked DAO and zero Spring context - no database, no HTTP layer, no message broker, because none of those things are reachable from inside the class in the first place. The transformer contract only moves data one direction, so there's no path by which a create or update payload construction accidentally becomes the shape used for API responses later. And status transitions, once reasoned through as their own kind of operation rather than just another field, end up structurally incapable of bypassing the domain object's own rules, not because someone remembered to guard against it, but because the shortcut was never given a path to exist.

The same boundary is what makes future changes cheap instead of invasive. If ProductDao moves from MySQL to something else, or gets a caching layer bolted in front of it, ProductsServiceImpl doesn't change, it was never coupled to the implementation, only the interface. The same will hold when this service eventually needs to notify the rest of the system that a product was created or updated, that's a dependency the service will accept through its constructor, the same way it accepts the DAO now, and the create and update methods above won't need to know whether that notification goes out over Kafka directly or through an outbox table written in the same transaction. That's a later chapter's problem specifically because this chapter's boundary makes it one.

The tests that prove all of this - what a mocked DAO actually looks like, how you assert an unauthorized update throws before it touches persistence, how you write a test that locks in a status transition rule so a future change can't quietly loosen it are their own chapter. This one was about the shape the code has to have before those tests are worth writing.

What's Next?

Chapter 10 walks through testing this exact service layer with the DAO mocked out entirely, no Spring context, no database, no HTTP layer, using ProductsServiceImpl and CategoriesServiceImpl as the running examples. The boundary this chapter drew is what makes those tests possible in the first place - the next one is about actually writing them, including the test that would have caught the status field slipping through if it had shipped that way.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 9, use the following link:

GitHub Repository (Tag: chapter-09-business-logic): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 8: Why almost every ‘Temporary’ Workaround is Permanent
▶️ Read Chapter 10: The Testing of Business Logic Service

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

Why almost every ‘Temporary’ Workaround is Permanent (Chapter 8)

Kamen — Mon, 31 Aug 2026 05:55:42 +0000

Somewhere around month four of any project I've worked on, someone says a version of the same sentence. "Just hardcode it for now, we'll fix it after the release." Nobody arguing against it and they genuinely believe it's temporary. The problem isn't the shortcut itself, sometimes a shortcut is the correct call. The problem is that "temporary" has no owner, no ticket, and no deadline of its own. It just sits there until someone forgets it was ever supposed to be temporary at all, and by then it's load-bearing. Here's how that actually plays out, because the abstract version of this story is boring and everyone nods along without changing anything.

The shortcut

We needed to ingest pricing updates from an upstream provider. Three days, full stop, because a partner integration deadline had already been communicated externally and nobody wanted to be the one calling to push it back. The fastest path was obvious: inject a RestClient call directly into the business-logic service method that needed the data, parse the JSON inline, map a couple of fields by hand, and move on.

We shipped it on time, it worked and everyone moved on to the next fire, which is what always happens after a deadline shortcut lands successfully. Success is exactly what makes it invisible.

Two months later we get an update: "The upstream team is moving to Kafka. They want to push events, not serve a REST endpoint anymore.", and now the HTTP call is gone, but it was never just a call - it was call semantics baked into a domain-facing method signature. The service method that used to return synchronously now needs to react to a stream. Unit tests that mocked an HttpClient are gone and now they need to mock a Kafka consumer instead. Every call site that invoked the pricing method synchronously has to be reconsidered, because the whole shape of "when do we have this data" changed underneath them.

Three weeks after that migration finished, we got again another update: "Edge devices in the field can't maintain a Kafka connection reliably. We're pushing over MQTT instead." Same story again, except now it's the third rewrite of the same core logic in five months, and each rewrite touches more of the codebase than the last one did, because more things had grown to depend on the leaked transport assumptions in the meantime.

Nobody planned for three transport migrations. Nobody ever does. That's exactly the point - the shortcut wasn't wrong because REST was the wrong choice, it was wrong because it welded a decision that was going to change into logic that was supposed to be stable.

What it should have looked like

This is precisely why business-logic in this project never talks to a transport mechanism directly. It depends on an interface, a port, if you want the textbook word for it, though I'd rather just call it what it is: an interface that answers the domain's question ("give me the latest price for this SKU") without knowing or caring how the answer arrives. Whether that interface is backed by a REST client, a Kafka listener, or an MQTT subscriber is bridge-impl's problem, sealed away from business-logic by the same compiler-enforced module boundary that's been the whole point of this architecture since Chapter 1.

When the transport changes, bridge-impl changes. The interface in bridge-api doesn't move, and neither does a single line in business-logic. Three transport migrations in five months would have been three rewrites of one implementation of the interface instead of three rewrites of everything downstream of a leaked implementation detail.

The uncomfortable part of this story is that we didn't have that boundary in place when the first shortcut happened. We built it because of this exact pain, not before it. That's usually how it goes, the boundary gets built in the shape of whatever already went wrong once, the same way most safety rules only exist because a crash already happened.

The same failure, dressed differently

The transport story is the clean, satisfying version, because it has a name and a fix. The uglier version of the same failure shows up whenever someone decides a mapper is overhead the deadline can't afford. "Why write a DTO and a transformer? Just return the entity from the controller." It takes five minutes to wire up and it works immediately, which is exactly the illusion - the cost isn't paid at the point of the shortcut, it's paid the first time someone needs to rename a column and discovers that half a dozen frontend clients have quietly come to depend on the JPA entity's field names as if they were a public contract.

This is what the Transformer/BiTransformer split from Chapter 4 actually buys you, beyond the argument against MapStruct. It's not really about avoiding a mapping library, It's about there being exactly one place where "how the database shape becomes the domain shape" is decided, so that decision can change without becoming an incident. Skip it under deadline pressure and you haven't saved the mapping work, you've just deferred it to whoever eventually has to reverse-engineer which fields are safe to touch.

The actual cost, after the fact

We went back and counted, roughly, what the three transport rewrites cost against what the port/adapter boundary would have cost to build up front. Building the boundary correctly the first time would have added maybe a half day or a day to the original three-day deadline - one interface, one adapter implementation, tests against the interface instead of the HTTP client. The three subsequent rewrites, combined, cost closer to three weeks, most of it not writing new code but tracing which parts of the business logic had quietly grown to assume synchronous, request-shaped delivery of data that was never going to stay synchronous or request-shaped.

That ratio is the entire chapter. The shortcut doesn't remove the cost, it just moves it downstream, converts it from a schedule risk into a production risk, and hands the bill to whoever's on call when a customer reports that a price didn't update and nobody can immediately say which of three transport layers is currently responsible for getting it there.

The part that doesn't fit in a retro

The hard part isn't spotting this pattern in hindsight, it's obvious once it's a war story. The hard part is that at the moment the shortcut gets proposed, it is correctly, the fastest way to hit the date. Refusing every shortcut on principle is its own failure mode. You'll miss real deadlines defending abstractions nobody needed. The distinction that actually matters is whether the shortcut cuts a corner inside a module boundary you're allowed to redo later in isolation, or whether it cuts through a boundary that other code is going to grow around before anyone circles back to it. A hardcoded value inside bridge-impl is an annoyance, a hardcoded assumption smuggled into business-logic about how data arrives is a liability with compound interest, and the interest rate is set by how many other developers touch that code before someone pays it down.

What's Next

Chapter 9 continues into the business logic module itself - what it means to write core services that depend on nothing but interfaces they own, and what actually breaks when that discipline slips.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 8. There's no code change between Chapter 7 and Chapter 8, I'm tagging each chapter regardless, for consistency:

GitHub Repository (Tag: chapter-08-shortcuts): advanced-spring-multimodule

Maven 3.9.x and Java 25 are required.

◀️ Read Chapter 7: The DAO Testing
▶️ Read Chapter 9: The Core Business Logic Module

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

What Spring Data Tests Can Miss: Testing Beyond Hibernate’s Persistence Context (Chapter 7)

Kamen — Mon, 24 Aug 2026 07:41:04 +0000

Here's the mechanism, before the war story: every EntityManager keeps a first-level cache, an identity map of every entity it's touched in the current persistence context. Call find() (which is what loadById resolves to, directly or through Spring Data's derived findById) for an entity that's already managed, and Hibernate doesn't ask the database anything. It just hands you back the object it already has. That's not a bug. It's the entire point of the first-level cache, and most of the time it's exactly the behavior you want. The problem is that a green @DataJpaTest can’t tell the difference between 'I verified this round-trips through the database' and 'I got the same Java object reference back.' And I’ve watched teams ship code confident in tests that were only ever validating L1 cache state - right up until a missing constraint violation or a column mapping bug blew up in production because the data was never actually flushed and re-hydrated.

In this chapter of the Evolutionary Architecture series, we're tearing down the illusion of the default Spring Data test. We'll look at exactly where the first-level cache hides bugs, and build a testing architecture around explicit EntityManager clearing, generic test fixtures, and in-memory isolation - so a green test means what you think it means.

What Standard Spring Tests Actually Test

When you write a standard Spring Data test using @DataJpaTest and a repository interface, your test looks clean and harmless:

@Test
void testSaveProduct() {
    var product = new Product("A1", "Gaming Laptop", BigDecimal.valueOf(1500));
    productDao.create(product);

    Product loaded = productDao.loadById(product.getId());
    assertNotNull(loaded);
    assertEquals("Gaming Laptop", loaded.getName());
}

It passes, but let's see here what actually happened:

You call create(). Hibernate generates a managed entity inside the persistence context - the row may or may not have hit the database yet, depending on flush mode. Then, even inside the @Transactional wrapper the test runs in, calling loadById() immediately after doesn't issue a SELECT. The entity you just created is still sitting in the L1 cache, still attached to the same persistence context, and find() short-circuits straight to it. You get the exact object reference back. The table itself never answered a query. To be precise about where this bites and where it doesn't: this specifically applies to find() - based lookups. A custom JPQL or native @Query method always issues real SQL, cache or no cache Hibernate will still try to reconcile the result with anything already managed, but the round-trip to the database happens either way. The gap is narrower than "all your reads are fake." It's specifically the find()/findById() path, which is also the one most CRUD test suites lean on hardest, because it's the one that requires the least code to write. So this test hasn't verified persistence. It's verified Hibernate's in-memory bookkeeping and Spring Data's proxy machinery which isn't nothing, but it's not what the test's name claims. A strict column constraint, a broken mapping, a query that only breaks against a real dialect - all of that can hide behind a green checkmark here.

Forcing a Real Write-and-Read Boundary

If a test exists to verify persistence rather than domain behavior, it needs to force Hibernate to flush its write-behind queue to the database, then clear the persistence context before reading anything back. The next read has to hydrate a fresh entity graph from scratch - no shortcuts, no identity map hits.

Doing that by hand in every test method is exactly the kind of boilerplate that gets skipped under deadline pressure, which defeats the point. So we push the discipline down into the test infrastructure itself, using a test-only proxy that wraps every DAO and forces the flush-and-clear automatically after any write.

Architectural Boundary Note: This proxy layer lives exclusively in test scope (TestConfig, under src/test/java). It's physically unreachable from production code and never ships in a production artifact. Production wiring injects the unproxied DAO implementations directly, so Hibernate keeps its normal write-behind batching with zero caching penalty outside of tests.

Here is our test-only CrudDaoProxy:

public abstract class CrudDaoProxy<
    IdType,
    Domain extends AbstractCreatable<IdType>,
    Dao extends CrudDao<IdType, Domain>
> implements CrudDao<IdType, Domain> {

    protected final Dao proxied;
    private final EntityManager entityManager;

    protected CrudDaoProxy(Dao proxied, EntityManager entityManager) {
        this.proxied = proxied;
        this.entityManager = entityManager;
    }

    @Override
    public Domain create(Domain domain) {
        final var saved = proxied.create(domain);
        flushAndClear();
        return saved;
    }

    @Override
    public Domain update(Domain domain) {
        final var updated = proxied.update(domain);
        flushAndClear();
        return updated;
    }

    @Override
    public Domain loadById(IdType id) {
        return proxied.loadById(id);
    }

    @Override
    public void delete(Domain domain) {
        proxied.delete(domain);
        flushAndClear();
    }

    protected void flushAndClear() {
        // Forces SQL out of write-behind cache into DB
        entityManager.flush(); 
        // Wipes L1 cache, forcing a real JDBC round-trip on next read
        entityManager.clear(); 
    }
}

Notice what's deliberately not overridden here: loadById just delegates straight through to proxied.loadById(id), no flush-and-clear wrapper. It doesn't need one, by the time a test calls it, the previous write already forced the clear. Any DAO with search capability gets the same treatment one level up:

public abstract class SearchableCrudDaoProxy<
        IdType,
        Domain extends AbstractCreatable<IdType>,
        Params extends AbstractParams<? extends SortBy>,
        Dao extends CrudDao<IdType, Domain> & SearchableDao<Domain, Params>
    > extends CrudDaoProxy<IdType, Domain, Dao> implements SearchableDao<Domain, Params> {

    protected SearchableCrudDaoProxy(Dao proxied, EntityManager entityManager) {
        super(proxied, entityManager);
    }

    @Override
    public ResultPage<Domain> search(Params criteria) {
        return proxied.search(criteria);
    }
}

search() passes straight through too - it's backed by a Specification, which always compiles to real SQL regardless of cache state, so there's nothing to force. The proxy only intervenes exactly where the shortcut exists: create, update, delete. That asymmetry isn't an oversight, it's the whole design - wrap the three operations that can lie, leave the two that can't.

A concrete feature DAO just extends the generic proxy and adds whatever custom query methods it has:

public class ProductsDaoProxy extends SearchableCrudDaoProxy<
    UUID,
    Product,
    ProductSearchParams,
    ProductDao
> implements ProductDao {

    public ProductsDaoProxy(ProductDao proxied, EntityManager entityManager) {
        super(proxied, entityManager);
    }

    @Override
    public Product loadBySku(String sku) {
        return proxied.loadBySku(sku);
    }
}

loadBySku isn't part of the generic CRUD/search contract, so it gets a one-line override with no wrapping - same reasoning as loadById.

Ground-Zero: The `TablesEraser`

Relying purely on Spring's @Transactional rollback-per-test can still hide second-level cache pollution, batching side effects, or a connection leak that only shows up across tests, not within one.

So every component test starts from an empty schema. TablesEraser deletes every row from every table before each test runs:

public class TablesEraser {

    public static void emptyAllTables(
        EntityManagerFactory emf,
        DbQueryFactory queryFactory
    ) {
        emptyAllTables(emf, queryFactory, s -> true);
    }

    public static void emptyAllTables(
        EntityManagerFactory emf,
        DbQueryFactory queryFactory,
        Predicate<String> filter
    ) {
        final EntityManager em = emf.createEntityManager();
        try {
            em.getTransaction().begin();

            // Disable foreign key checks dynamically
            em
              .createNativeQuery(queryFactory.disableForeignKeys())
              .executeUpdate();

            // Fetch all table names and truncate them
            final List<String> allTableNames = em
              .createNativeQuery(queryFactory.selectAllTableNames())
              .getResultList();
            for (final var tableName : allTableNames) {
                if (filter.test(tableName)) {
                    em
                    .createNativeQuery("DELETE FROM " + tableName)
                    .executeUpdate();
                }
            }

            // Re-enable foreign keys and commit
            em
              .createNativeQuery(queryFactory.enableForeignKeys())
              .executeUpdate();
            em.getTransaction().commit();
        } catch (Throwable th) {
            em.getTransaction().rollback();
            throw new RuntimeException(th);
        } finally {
            em.close();
        }
    }
}

Worth being precise here: this is a DELETE FROM per table, not a TRUNCATE. That's a deliberate trade-off, not an oversight - DELETE respects the same transaction we're already managing manually and rolls back cleanly if anything in the loop throws, where a bare TRUNCATE in most dialects auto-commits and can't be undone mid-loop. It costs a little raw speed against a TRUNCATE, and it's worth it for a test-suite reset that can fail safely.

Reusable Tests: `AbstractCrudTestCase` & `AbstractSearchableTestCase`

Shared assertions cut real repetition, as long as the abstraction stays shallow. The moment a failing test sends you on a five-class inheritance hunt to understand what actually broke, the abstraction has stopped paying rent.

public abstract class AbstractCrudTestCase<
        ID,
        D extends AbstractCreatable<ID>,
        DAO extends CrudDao<ID, D>
    > extends AbstractDaoTest {

    @Test  
    void testCreate() {  
        final D expectedEntity = runSave();  
        final D dbEntity = getDao().loadById(expectedEntity.getId());  
        assertNotNull(dbEntity, "missing entity");  
        assertEquals(expectedEntity.getId(), dbEntity.getId());  
        getAsserter().assertDeepEquals(expectedEntity, dbEntity);  
    }

    @Test
    void testCreateExisting() {
        final D existing = runSave();
        final var ex = Assertions.assertThrows(
            IllegalArgumentException.class,
            () -> getDao().create(existing)
        );
        Assertions.assertEquals("Entity existing!", ex.getMessage());
    }

    ...

    protected abstract DAO getDao();
    public abstract D createDomain();
    protected abstract DeepEqualsAsserter<D> getAsserter();
}

A concrete case like ProductDaoTestCase stays thin, it implements the domain-specific payload generator (createDomain()) and inherits the full CRUD and search suite for free. It's not only that, though. It also adds its own tests for loadBySku, because that's a query method the generic contract has no way to know about. That's the right shape for this kind of abstraction - the base class owns everything that's structurally identical across every DAO, and the concrete case owns exactly the part that makes this DAO different. If a shared base class tried to guess at loadBySku too, you'd be back to fighting a framework instead of using one.

Not every test in this hierarchy exists to confirm the happy path. One of those tests is in the AbstractSearchableTestCase that specifically is checking a boundary condition:

@Test
public void testSearchNullParams() {
    for (int i = 0; i < 5; i++) {  
        runSave(createDomainWithUniqueData());  
    }

    final ResultPage<Domain> result = getDao().search(null);  
    assertEquals(1, result.totalPages());  
    assertEquals(5, result.totalHits());  
    assertEquals(5, result.elements().size());
}

That test earned its place in the suite the hard way. It didn't start out passing.

What the Null-Params Test Actually Caught

The first version of search() in SearchableDaoImpl assumed a Params object would always be there:

private Pageable toPage(Params criteria) {
    return PageRequest.of(
            criteria.getPage(),
            criteria.getSize(),
            getSortOrDefault(criteria.getSortBy(), criteria.getSortDirection())
    );
}

Reasonable assumption, right up until testSearchNullParams called getDao().search(null) and got a NullPointerException on criteria.getPage() instead of a result page. Which is exactly the point of writing that test before the feature felt finished - a caller passing null to mean "no filters, give me the default page" is a completely ordinary thing to do, and the DAO was punishing it with a stack trace instead of handling it.

The fix has two parts, and both matter for the same reason: Params is a generic type parameter here, so there's no single field-by-field way to "default" a null one into existing. Every concrete DAO defines its own Params subtype with its own fields, which means the null case has to be handled once, centrally, before any of that generic machinery gets involved - not pushed down into every feature DAO's createSpecification implementation as a null-check they'd all have to remember to write.

Paging falls back to a fixed default when there is no parameter to base it on:

private Pageable toPage(Params criteria) {
    if (criteria == null) {
        return PageRequest.of(DEFAULT_PAGE, DEFAULT_SIZE, CREATED_AT_DESC_SORT);
    }
    return PageRequest.of(
            criteria.getPage(),
            criteria.getSize(),
            getSortOrDefault(criteria.getSortBy(), criteria.getSortDirection())
    );
}

And filtering falls back to "match everything" rather than calling the abstract createSpecification(params) with nothing for it to read:

@Override
public ResultPage<Domain> search(Params params) {
    final Pageable pageable = toPage(params);
    final Specification<Entity> spec = params == null
            ? Specification.unrestricted()
            : createSpecification(params);
    final Page<Entity> result = repository.findAll(spec, pageable);
    final List<Domain> content = result.getContent()
            .stream()
            .map(transformer::createOutput)
            .toList();

    return new ResultPage<>(result.getTotalPages(), result.getTotalElements(), content);
}

Specification.unrestricted() is doing real work in that ternary, not just avoiding a null check. The first instinct is usually to pass Specification.where(null) - which is the older, more commonly documented way of expressing "no restriction" in Spring Data JPA. But recent Spring Data versions added a second where(...) overload for PredicateSpecification, and a bare null literal is ambiguous between the two. The compiler can't infer which where you meant, so it refuses to guess. unrestricted() exists to sidestep exactly that ambiguity, it says "match everything" without needing a null argument for the compiler to argue about.

These issues stay hidden if we only test scenarios where valid parameters are provided. Handling unexpected edge cases is where a test suite truly adds value, the testSearchNullParams test might seem boring because it just calls the search method with null param, but it proved its worth because it prevented letting a bug to impact other parts of the system.

Choosing an In-Memory Database

Component tests need to be fast enough that nobody's tempted to skip them, which rules out spinning up a containerized database for every run of a basic CRUD suite. That leaves a choice between H2 and HSQLDB, and it's worth being honest about what that choice costs.

We run H2 in strict compatibility mode (MODE=MySQL, matching our production dialect) for this layer, mainly because startup is sub-second and there's no container to wait on which matters more than it sounds like it should, multiplied across a few hundred local test runs a day. HSQLDB is arguably more stable in isolation, but its dialect compliance with modern MySQL and PostgreSQL features - JSON columns, window functions, strict identifier quoting, lags enough that a test can pass against HSQLDB and break the moment it hits real MySQL. Either way, neither in-memory engine replicates the production query planner, locking behavior, or dialect-specific edge cases. That was never the job we're asking them to do here.

So we split the responsibility deliberately: H2 handles fast, local validation of the mapping and constraint logic through the DAO proxies in this chapter. Later in the series, when we get to end-to-end integration testing, a dedicated suite runs against a real MySQL 9 Testcontainer to validate the behavior H2 can't, that's the layer that's actually authoritative for production-identical engine behavior, and it's allowed to be slower because it runs less often.

What's Next?

With the DAO layer's persistence boundaries actually proven against real database round-trips - not just Hibernate's bookkeeping, the natural next question is what happens to boundaries like this one under deadline pressure.

In Chapter 8: Why almost every ‘Temporary’ Workaround is Permanent, we step back from the happy-path development. The biggest threat to a clean multi-module boundary usually isn’t a missing design pattern, it’s the workaround that was supposed to be temporary. We’ll look at how an unisolated external dependency, a quick infrastructure leak, or a skipped domain boundary compounds quietly over time, before moving on to building the business service layer.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 7, use the following link:

GitHub Repository (Tag: chapter-07-dao-testing): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 6: The DAO Implementation Layer
▶️ Read Chapter 8: Why almost every ‘Temporary’ Workaround is Permanent

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

The Dao Implementation Layer (Chapter 6)

Kamen — Mon, 17 Aug 2026 06:52:51 +0000

The last 11 years through my career, I've seen codebases that suffered from a silent architectural decay. Check any corporate monolith or a microservice and you will find Spring Data repositories, JPA entity annotations, database specifics, and pagination parameters leaking straight into business services, controllers, and domain models. Developers call it "rapid development." What they've actually built is a tightly coupled codebase that is nearly impossible to support, maintain, and bugfix - especially if there are no tests. And guess what? There are none. Because the code is so tightly coupled, developers don't have the time, or honestly the patience, to mock all those dependencies or try to disentangle the mess just to make their lives easier. Divide and conquer - it's the rule I live by whenever I'm building a new service, REST endpoint, or Kafka integration.

In Chapter 2 and Chapter 3, we drew a hard boundary. We established a 100% pure Java domain model completely free of database metadata, and we defined clean DAO API contracts. In Chapter 4, we've shown why we use direct, JIT-optimized Java transformers instead of reflection-based mapping like MapStruct, and in Chapter 5, we explained why we don't even allow Lombok as a dependency.

Now, it's time to open up the engine room. We are implementing the dao-impl infrastructure module using Java 25, Spring Data JPA, and Hibernate. We will look at how generic hierarchy extension and custom Specification execution keep our persistence details locked safely away from the rest of the application.

`CrudDaoImpl` and `SearchableDaoImpl`

Writing boilerplate CRUD and search logic for every single database table is a waste of resources and time. At the same time, copy-pasting generic utility code creates maintenance nightmares. We solve this by structuring a clean, type-safe inheritance hierarchy.

At the base sits CrudDaoImpl. It handles standard entity creation, lifecycle validation, and ID lookups while enforcing the boundary between domain objects and database entities:

public abstract class CrudDaoImpl<
        IdType,
        Domain extends AbstractCreatable<IdType>,
        Entity extends AbstractCreatableEntity,
        Repo extends CrudRepository<Entity, IdType>
    > implements CrudDao<IdType, Domain> {

    protected final Validator validator;
    protected final Repo repository;
    protected final BiTransformer<Entity, Domain> transformer;

    protected CrudDaoImpl(
        Repo repository,
        BiTransformer<Entity, Domain> transformer,
        Validator validator
    ) {
        this.repository = repository;
        this.transformer = transformer;
        this.validator = validator;
    }

    @Override
    public Domain create(Domain domain) {
        if (domain == null) {
            throw new IllegalArgumentException("Entity is mandatory");
        }
        if (domain.getId() != null) {
            throw new IllegalArgumentException("Entity existing!");
        }

        var entity = transformer.createInput(domain);
        preCreate(entity);
        validateEntity(entity);
        entity = repository.save(entity);

        return transformer.createOutput(entity);
    }

    protected void preCreate(Entity entity) {
        final var now = Instant.now();
        entity.setCreatedAt(now);

        if (entity instanceof AbstractUpdatableEntity updatableEntity) {
            updatableEntity.setUpdatedAt(now);
        }
    }

    protected void preUpdate(Entity entity) {
        if (entity instanceof AbstractUpdatableEntity updatableEntity) {
            updatableEntity.setUpdatedAt(Instant.now());
        }
    }
    // Additional shared CRUD machinery...
}

Notice preCreate and preUpdate reach for instanceof instead of calling setUpdatedAt() directly on Entity. That's deliberate, not a gap. CrudDaoImpl has to stay generic over every entity in the hierarchy, including append-only ones like CategoryAssignment that never extend AbstractUpdatableEntity at all - so Entity can only ever be statically bounded by AbstractCreatableEntity, and the compiler genuinely has no way to know, from inside this class, whether a given Entity also supports updatedAt.

The alternative would be a parallel UpdatableDaoImpl layer bounded by AbstractUpdatableEntity, sitting next to SearchableDaoImpl. That sounds cleaner until you remember Java only allows single inheritance: ProductDaoImpl already extends SearchableDaoImpl, so it couldn't also extend a second base class for updatability without either duplicating the search machinery into a combinator class or moving the whole hierarchy to interfaces with default methods. One instanceof check that anyone can read top to bottom is a smaller price than that.

It's also worth being precise about why this isn't the reflection-based magic we spent earlier chapters arguing against: instanceof is a single, explicit, statically-checked type test that the compiler verifies at compile time and the JIT can inline - nothing here is scanning annotations, generating bytecode, or hiding behind a target/generated-sources folder. Runtime type inspection and reflection-based mapping look similar on the surface, but they aren't the same tool, and conflating them would undercut the whole argument this series has been making.

preCreate captures a single now and reuses it for both fields rather than calling Instant.now() twice, so createdAt == updatedAt on a fresh insert is guaranteed exactly, not just approximately - which is what actually makes that equality useful as a "never touched since creation" signal.

Why timestamps are set here, not left to the database

The Flyway migration for this table will have a DEFAULT CURRENT_TIMESTAMP on the created_at and updated_at columns, so it's worth asking directly: if the database is already going to fill it in, why does preCreate and preUpdate set it again in application code? Because the database default and the application value are solving two different problems.

The DB default is a safety net. It exists for anything that touches the table outside the application: a manual INSERT during an incident, a backfill script, another service hitting the same schema directly. It guarantees the column is never null, no matter what wrote the row.

The application-level value is the source of truth for anything going through this DAO, and setting it explicitly in preCreate matters for a concrete reason: Hibernate doesn't automatically read back database-computed defaults after save(). Relying on the DB default alone means the in-memory entity still has createdAt == null right after the insert, and create() hands that same object straight to transformer.createOutput(entity) - so the caller gets back a Product with a null creation timestamp for an entity that very much has one in the database. That's a real bug, not a style nitpick.

The same reasoning is why preCreate sets updatedAt too, not just createdAt. updated_at is NOT NULL, same as created_at, so it can't be left unset until the first real update without hitting the exact null-after-save problem above - except this time the DB default that would normally paper over it isn't guaranteed to fire at all, since CURRENT_TIMESTAMP defaults are typically written to apply on insert, not on every column independently. Setting both fields from a single captured now sidesteps that entirely, and gets you createdAt == updatedAt as a free signal that a record has never been touched since creation, with no extra flag to maintain.

Immutable Audit Fields on the Domain Side

The DAO layer owning createdAt/updatedAt only works if the domain side agrees to stay out of the way. Earlier versions of our domain classes had default no-arg constructors and public setters, which left audit fields mutable and gave the business layer a path to overwrite them by accident.

We removed both. Domain classes no longer have no-arg constructors, and createdAt/updatedAt are final - set once, via the reconstitution constructors covered in Chapter 2, and never touched again for the life of that object. Our transformers reflect this split cleanly: writing domain-to-entity, createInput() ignores audit fields entirely, since preCreate/preUpdate above already own them on the entity side; reading entity-to-domain, createOutput() is the only caller that ever passes a real createdAt/updatedAt into a domain constructor, because it's the only place that has the real, already-persisted values to pass. No service layer and no client payload has a path to either field.

When a domain requires complex search capabilities, pagination, and sorting, we extend CrudDaoImpl with SearchableDaoImpl. Instead of letting business services deal with JPA Criteria APIs or Spring Data Specification objects, the searchable DAO encapsulates query execution internally:

public abstract class SearchableDaoImpl<
        IdType,
        Domain extends AbstractCreatable<IdType>,
        Entity extends AbstractCreatableEntity,
        Repo extends CrudRepository<Entity, IdType> & JpaSpecificationExecutor<Entity>,
        Params extends AbstractParams<? extends SortBy>
    > extends CrudDaoImpl<IdType, Domain, Entity, Repo> implements SearchableDao<Domain, Params> {

    protected static final Sort ID_DESC_SORT = Sort.by(Sort.Direction.DESC, "id");
    protected static final Sort CREATED_AT_DESC_SORT = Sort.by("createdAt").descending().and(ID_DESC_SORT);

    protected SearchableDaoImpl(
        Repo repository,
        BiTransformer<Entity, Domain> transformer,
        Validator validator
    ) {
        super(repository, transformer, validator);
    }

    @Override
    public ResultPage<Domain> search(Params params) {
        final Pageable pageable = toPage(params);
        final Specification<Entity> spec = createSpecification(params);
        final Page<Entity> result = repository.findAll(spec, pageable);
        final List<Domain> content = result.getContent()
                .stream()
                .map(transformer::createOutput)
                .toList();

        return new ResultPage<>(
            result.getTotalPages(),
            result.getTotalElements(),
            content
        );
    }

    protected abstract Specification<Entity> createSpecification(Params params);
}

Why `Repo` needs two bounds, not one

Look closely at the type bound on SearchableDaoImpl:

Repo extends CrudRepository<Entity, IdType> & JpaSpecificationExecutor<Entity>

That & is an intersection type, and it's doing more work than it looks like. CrudRepository gives us save(), findById(), delete() - the basic CRUD operations that CrudDaoImpl needs. But CrudRepository has no idea what a Specification is, that interface lives entirely in JpaSpecificationExecutor, which is what actually declares findAll(Specification<T>, Pageable).

If we bounded Repo on CrudRepository alone, the search() method above simply wouldn't compile - repository.findAll(spec, pageable) calls a method that doesn't exist on that interface. If we bounded it on JpaSpecificationExecutor alone, we'd lose save() and the rest of the CRUD surface that CrudDaoImpl depends on. We need both interfaces satisfied by the same concrete repository type, and Java's intersection bounds are the only clean way to express "this generic parameter must implement A and B" without collapsing the two responsibilities into one bloated interface.

The payoff shows up downstream, in ProductRepository and CategoryRepository, they simply extend both interfaces, and every method from both becomes available on repository inside the DAO, fully typed, with no casting. If any entity doesn't need to be paginated, it will simply extend only the CrudRepository.

Notice also how sorting is handled above. By appending id DESC as a deterministic tie-breaker to every sort order, we eliminate unstable pagination results when multiple records share identical timestamps or property values. I've chased that exact bug in production before - page 3 of a listing quietly returns a row you already saw on page 2, because two rows had the same createdAt millisecond and the database made no promises about their relative order.

`ProductDaoImpl` and `CategoryDaoImpl`

With the generic abstraction we just created, implementing concrete data access objects requires minimal code. Look at how clean CategoryDaoImpl is:


public class CategoryDaoImpl extends SearchableDaoImpl<
        UUID,
        Category,
        CategoryEntity,
        CategoryRepository,
        CategorySearchParams
        > implements CategoryDao {

    public CategoryDaoImpl(CategoryRepository repository, Validator validator) {
        super(repository, CategoryTransformer.instance, validator);
    }

    @Override
    protected Specification<CategoryEntity> createSpecification(CategorySearchParams params) {
        return (root, query, cb) -> {
            final List<Predicate> predicates = new ArrayList<>();

            if (params.getName() != null && !params.getName().isBlank()) {
                predicates.add(cb.like(cb.lower(root.get("name")), "%" + params.getName().toLowerCase() + "%"));
            }

            if (params.getActive() != null) {
                predicates.add(cb.equal(root.get("active"), params.getActive()));
            }

            return cb.and(predicates.toArray(new Predicate[0]));
        };
    }
}

For domain-specific queries like SKU lookups, ProductDaoImpl delegates directly to custom repository methods while keeping the transformation logic fully explicit:

public class ProductDaoImpl extends SearchableDaoImpl<
        UUID,
        Product,
        ProductEntity,
        ProductRepository,
        ProductSearchParams
    > implements ProductDao {

    public ProductDaoImpl(ProductRepository repository, Validator validator) {
        super(repository, ProductTransformer.instance, validator);
    }

    @Override
    public Product loadBySku(String sku) {
        final var product = repository.loadBySku(sku);
        return transformer.createOutput(product);
    }

    @Override
    protected Specification<ProductEntity> createSpecification(ProductSearchParams params) {
        return (root, query, cb) -> {
            final List<Predicate> predicates = new ArrayList<>();

            if(params.getName() != null && !params.getName().isBlank()){
                predicates.add(cb.like(cb.lower(root.get("name")), "%" + params.getName().toLowerCase() + "%"));
            }

            return cb.and(predicates.toArray(new Predicate[0]));
        };
    }
}

Why I don't use Spring Data Method Naming

Look at ProductRepository, or any custom repository method in this codebase, and you won't find something like findByProductStatusAndNameContainingIgnoreCaseAndCreatedAtAfterOrderByPriceDesc. Spring Data will happily generate that query for you from the method name alone - no annotation, no SQL, just string parsing at startup. It seems easy and intuitive, but when we get in a production service taking real traffic, I don't want it anywhere near my persistence layer, for a few concrete reasons.

The first is fragility, if we rename a field on the entity, let's say for example sku becomes productSku, and the derived-name query built on the old name either breaks at startup with a PropertyReferenceException, or, depending on how the method's structured, doesn't break at all and just silently stops matching what you think it matches. Either way, the compiler never told you. An explicit query, by contrast, references the actual JPQL or SQL, so a rename is a normal refactor with a normal compile error, not a runtime surprise waiting for the right request to trigger it.

The second is readability, and the method name above is the proof, once a query needs more than two or three conditions, the method name stops being a name and becomes a run-on sentence encoding your entire WHERE clause in camelCase. Nobody reads that and understands the query faster than they'd understand the five lines of JPQL it's standing in for - they read it slower, and they have to mentally decode ContainingIgnoreCase and OrderByPriceDesc back into SQL concepts they already know.

The third is the one that actually matters most at midnight during an incident: derived queries hide the generated SQL from you until it runs. An explicit @Query shows you the exact projection, the exact joins, the exact fetch strategy, right there in the repository interface, during code review, before it had the chance to quietly become an N+1 problem in production.

ProductRepository's loadBySku makes this concrete:

public interface ProductRepository extends CrudRepository<ProductEntity, UUID>, JpaSpecificationExecutor<ProductEntity> {

    @Query("SELECT p FROM ProductEntity p WHERE p.sku = :sku")
    ProductEntity loadBySku(@Param("sku") String sku);
}

Spring Data could derive this one from a method named findBySku without any annotation at all, it's simple enough. I write the @Query anyway, because the moment this method needs a join or a second condition, I want it to already look like every other query in this codebase, not like a special case that started simple and grew a name nobody can parse at a glance.

What's Next?

We've built a flexible persistence infrastructure: clean generic DAO hierarchies, explicit Java transformers, and validation that fails fast in application code instead of at the database.

Spoiler alert: a green Spring integration test does not necessarily prove that an entity can be written and hydrated correctly by the database. In Chapter 7, we expose Hibernate’s write-behind cache and dirty checking. When a test’s purpose is to verify database constraints or fresh hydration, it should intentionally use .flush() and .clear() at the relevant boundary rather than accidentally read managed state from the persistence context.

See you in the next chapter.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 6, use the following link:

GitHub Repository (Tag: chapter-06-dao-impl): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 5: The Lombok Illusion
▶️ Read Chapter 7: The Persistence layer Testing

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

The Lombok Illusion (Chapter 5)

Kamen — Mon, 10 Aug 2026 06:36:32 +0000

You open a new Spring Boot project and you create a DTO, then an entity, and you’re staring at getters, setters, constructors, equals(), hashCode(), toString(). Someone on the team suggests to put lombok’s @Data, or “just slap @Builder on it, it’ll be cleaner.” Forty lines become five and it looks great in the PR.

Then it hits a real codebase, OpenAPI generation doesn't behave the way the build expects. Hibernate meets an auto-generated equals() and gets confused about identity. Something throws through a generated builder hierarchy at 2 AM, and the method you need to inspect doesn't exist in any file you can open.

Eleven years into enterprise Java, my rule is simple: Lombok doesn't touch core application behavior. Not because writing a getter is interesting - it isn't, but because the handful of lines it saves rarely covers the compiler magic, tooling friction, and debugging problems it adds to something that has to survive for years after you've moved on to another project.

"It just removes boilerplate"

Worth asking what's actually being removed, though. A getter is part of your public API. A setter is a mutation point someone decided to expose. A constructor defines what states an object is allowed to enter. equals() and hashCode() define identity. toString() is what shows up in your logs when things go wrong at 3 AM.

Write those by hand and they live in the source - visible, searchable, debuggable, owned by whoever's reading the file. Generate them with Lombok and the behavior is still there, it's just moved somewhere you can't see it without a separate step.

The annotation most people reach for first time is @Data:

@Data
@Entity
public class CustomerEntity {

    @Id
    @GeneratedValue
    private Long id;

    private String email;

    @OneToMany(mappedBy = "customer")
    private List<OrderEntity> orders;
}

One line and you get getters, setters, toString(), equals(), hashCode() across every field. For a JPA entity that's already a problem before you've written any business logic - an entity carries persistence identity, lazy proxies, mutable state, none of which behaves like a plain data bag. Field-based equality ignores identity semantics entirely. A toString() that walks relationships is a logging hazard waiting for the wrong moment. Public setters on every field quietly throw out encapsulation.

I've had this exact line take down a support investigation:

log.warn("Could not process customer: {}", customer);

If toString() walks a lazy relationship, that log statement fires a database call. If both sides of a bidirectional association reference each other, you get recursion in your logs - I've seen this crash a logging pipeline, not just produce ugly output. And if the persistence context is already closed by the time you log, you can get a LazyInitializationException thrown while you're trying to log an unrelated failure. A ten-minute incident turns into two hours because the stack trace points at logging code, not the actual bug.

The usual patch is a pile of exclusions bolted back on:

@ToString(exclude = "orders")
@EqualsAndHashCode(onlyExplicitlyIncluded = true)

At which point we've added a code generator to save typing, then added more annotations to undo part of what it generated, and now every future developer has to understand the interaction between Lombok, Hibernate proxies, equality semantics, and logging before they can touch this class safely. That's not less work. It's the same work, deferred and hidden.

Builders aren't free either

@Builder is probably the most defended Lombok annotation, and I get the appeal - long constructors are ugly, named construction reads well at the call site. But a nice call site doesn't automatically mean good architecture underneath it.

For immutable request models, a record usually does the job better:

public record CreateCustomerRequest(
    String firstName,
    String lastName,
    String email
) {
}

No annotation processor, no generated builder class sitting somewhere you'll never look, nothing ambiguous about what exists at compile time - constructor, accessors, equals(), hashCode(), toString(), all from the language itself. Where a builder genuinely earns its place - lots of optional parameters, a real construction protocol - write it by hand. It's not that much typing.

@SuperBuilder I'd flag as the one to be most careful with. Inheritance already makes domain models harder to follow. Add generated nested builders and field shadowing on top of ORM concerns, and you get bugs that compile fine and fail much later. A field ends up null nobody set on purpose, an update silently drops a value, and the row in the database stays technically valid while the business state underneath it is quietly wrong. I've debugged exactly this on a service and it took longer than it should have to even locate which builder was involved.

The toolchain cost nobody budgets for

Lombok isn't standard Java. It works by rewriting the compiler's view of your source during annotation processing. That matters because your compiler isn't the only thing reading that code. IDE indexing, static analysis, coverage tools, Javadoc, OpenAPI generation, MapStruct, QueryDSL, whatever other annotation processors are in the build, CI running on a different JDK than your laptop.

Most of the time it works fine, and that's the trap. It's not that Lombok breaks on day one, it's that it adds one more thing every tool in the pipeline has to keep agreeing on correctly. Springdoc and MapStruct can need specific processor ordering. Lombok's own extensions, like chained accessors, can quietly break JavaBean conventions that some framework tooling assumes without checking. The build accumulates workarounds to compensate, and eventually someone bumps a JDK or an IDE version, and a developer burns half a day figuring out why the generated code and the compiler disagree about what a class looks like.

Debugging wants source code, not a description of generated behavior

When something breaks in production I want a straight line: stack trace, source line, method body, state change, fix. Generated code adds fog to every step of that. The file in front of you tells you an annotation exists, not what it expands to. Builders become generated nested types you've never opened. Generated equals() and toString() pull behavior into an incident that nobody in the room actually wrote.

You can delombok a class to see what it really compiles to, but needing a second, generated copy of your own source just to understand what the first one does isn't a workaround. It's the actual problem, restated.

Java 25 already solves this

Lombok got popular in an older Java - verbose syntax, no records, weaker IDE support. We're not in that world anymore, the language itself covers most of what people reach for Lombok to fix:

public record CustomerResponse(
    UUID id,
    String fullName,
    String email
) {
}

public class CustomerEntity {

    private UUID id;
    private String email;

    public CustomerEntity(UUID id, String email) {
        this.id = id;
        this.email = email;
    }

    public UUID getId() {
        return id;
    }

    public String getEmail() {
        return email;
    }

    public void changeEmail(String email) {
        this.email = email;
    }
}

changeEmail() tells you more than a generated setEmail() ever would - it names intent, and naming intent is domain modeling, not boilerplate. For the rare getter or constructor that really is trivial, let the IDE generate it once. That costs less time than a Maven exclusion you'll be maintaining six months from now.

Where I've landed

Records for immutable DTOs like requests, responses, query results. Explicit classes for JPA entities and anything with mutable infrastructure state. Constructors written by hand to protect valid state. Explicit equality on entities where identity actually matters, not field-by-field comparison. No blanket @Data, and nothing generated that the next engineer has to reverse-engineer just to trust the class.

A dependency that shrinks your code but makes the build, the debugger, and the IDE more fragile isn't really improving developer experience, it's borrowing against it, and the interest comes due later. Small at first, then the module count grows, tooling gets stricter, JDK versions move on, and someone's maintaining a pile of invisible generated behavior that nobody currently on the team signed up to own.

What's Next

Stripping out the bytecode magic keeps the codebase predictable, debuggable, and aligned with the standard toolchain instead of fighting it.

Next up, Chapter 6: Implementing the DAO Layer - wiring up Spring Data JPA and Hibernate behind clean data access interfaces, with explicit, reflection-free transformation strategies that respect the database boundary and keep the domain layer pristine.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 5, use the following link:

GitHub Repository (Tag: chapter-05-lombok): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 4: Mapping Strategies Without the Magic
▶️ Read Chapter 6: The Dao Implementation Layer

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

Mapping Strategies Without the Magic (Chapter 4)

Kamen — Mon, 03 Aug 2026 06:22:28 +0000

At the end of the previous chapter, I teased that we were about to dive straight into the heavy machinery of DAO implementation - hooking up Spring Data JPA and Hibernate under the hood.

If you look at our original roadmap, concrete implementation was supposed to be right here. But after laying down our domain models, data contracts, and reading some of your feedback, I realized that we need to address an unspoken architectural trap first: data mapping and transformation.

Most teams blindly adopt automated tools - whether runtime reflection wrappers or compile-time generators like MapStruct - until an architectural mismatch or production incident breaks their service. Before we wire up our database infrastructure, let’s see why we chose to completely bypass mapping "magic" in favor of pure, explicit Java transformers.

And yes, some will say that writing explicit transformers is boilerplate - why write it manually when we can just use an annotation? The answer is simple: we’re not building a simple CRUD application that gets thrown to a support team and forgotten. We’re building an enterprise-ready microservice, built for deployment in Kubernetes, integrated with Kafka, Redis, and multi-tenant authorization layers - a product designed to be actively developed and maintained over years, not weeks.

This is where the real value shines: spending a little more time writing explicit transformers - as I call them, rather than standard Mappers. I call them transformers because they actively reshape data. A "mapping" usually implies just copying a field from ClassA to ClassB (whether with the same or a different name). We aren't doing that here because at an enterprise level, field names, types, and structural representations will diverge significantly between your database entities, domain models, and external DTOs.

The Architectural Trap

Across my 11 years in Enterprise Java, I've seen team after team reach for automated mappers to "save time." To understand why we banned them, we must separate them into two distinct categories - because they fail for entirely different technical reasons.

1. The Reflection Black Box (ModelMapper, Dozer, Spring BeanUtils)

Runtime reflection tools attempt to inspect fields dynamically during application execution.

The Production Tax: They rely on deep reflection APIs, bypassing Java's strong compile-time type safety.
The Debugging Wall: When a field type changes or a property is missing, the application crashes under load with a 50-line stack trace originating from the library's internal reflection routines—giving you zero visibility into which object or field caused the failure.
Performance Drag: Continuously resolving fields via reflection adds memory allocation and CPU overhead to every single request.

2. The Compile-Time Generation (MapStruct)

Unlike reflection tools, MapStruct generates standard Java code in target/generated-sources/ during compilation. It is inspectable, debuggable, and fast at runtime.

To be fair: for a simple, flat 1:1 DTO with no structural divergence, MapStruct works fine and gets out of your way. But the pain scales linearly with how much your layers diverge - and in real-world enterprise systems, domain aggregates, database entities, and REST DTOs diverge rapidly.

When structural divergence happens, MapStruct introduces distinct friction points:

IDE Refactoring Friction: MapStruct relies on string-based path configurations: @Mapping(source = "shippingDetails.address.street", target = "streetAddress"). IDE rename refactoring doesn't reach into these annotation strings the way it does for real Java field references. Even with dedicated MapStruct IDE plugins installed, you're relying on static inspection warnings after the fact, rather than a guaranteed, seamless edit-time rewrite across your codebase.
The Fallacy of 1:1 Matching: If your Domain Model (pure POJO/Record protecting business invariants), your JPA Entity (polluted by Hibernate requirements, proxies, and persistence states), and your REST DTO (flat JSON contract) look identical and map 1:1... you have a severe architectural issue. They should never match 1:1. The domain protects business rules. The entity fights the relational database. The DTO adapts to external API clients.
Framework Leakage into Domain Logic: The moment your domain uses composite hierarchies or custom value objects, MapStruct forces you to write custom @Named helper methods or embed raw Java strings inside annotation parameters: expression = "java(new Money(...))". Writing raw Java code inside annotation strings is a clear indicator that the abstraction has broken down.

Composite Hierarchy Reality Check: MapStruct vs. Pure Java

MapStruct tutorials always feature trivial 1:1 flat classes (UserDto to UserEntity). But real enterprise software uses rich composite value objects on the domain side while entities flatten them or restructure audit information. Let’s compare how MapStruct handles composite hierarchies versus how pure Java solves it safely.

The MapStruct Way (Annotation Spaghetti & Untyped String Expressions)

When field names mismatch, unit conversions are required, or composite objects need instantiation, MapStruct forces you into string-based paths and Java string expressions:

@Mapper(componentModel = "spring")
public interface OrderMapper {

    @Mapping(source = "totalMoney.amount", target = "totalAmountCentimes", qualifiedByName = "amountToCentimes")
    @Mapping(source = "totalMoney.currency", target = "currencyCode")
    @Mapping(source = "shippingDetails.recipientName", target = "deliveryContact")
    @Mapping(source = "shippingDetails.address.street", target = "streetAddress")
    @Mapping(source = "shippingDetails.address.zipCode", target = "postalCode")
    OrderEntity toEntity(Order domain);

    @Named("amountToCentimes")
    default long amountToCentimes(BigDecimal amount) {
        if (amount == null) {
            return 0L;
        }
        return amount.multiply(BigDecimal.valueOf(100)).longValue();
    }

    @InheritInverseConfiguration
    @Mapping(
        target = "totalMoney",
        expression = "java(new Money(entity.getTotalAmountCentimes(), entity.getCurrencyCode()))"
    )
    Order toDomain(OrderEntity entity);
}

Notice what happened: to handle a simple composite conversion, we ended up writing untyped Java inside an annotation string parameter (expression = "java(...)") and configuring string property paths that don't refactor cleanly with standard IDE tools.

The Pure Java Transformer Way (Zero Reflection, 100% Control)

In our multi-module architecture, we stripped out both runtime reflection libraries and compile-time code generators. We replaced them with simple, fully deterministic contracts written in vanilla Java. Here are the root interfaces that dictate the contracts for data transformation:

public interface Transformer<Input, Output> {  

    /**
     * Creates a new instance of an Output type, with transformed data from the input object.
     * @param input the input object  
     * @return the newly created Output object  
     */    
    Output createOutput(Input input);  

    /**
     * Copies the data from input to output.     
     * @param input  the input object  
     * @param output the output object  
     */    
    default void copyToOutput(Input input, Output output) {  
    }  
}

And our transformer contract for reverse transformations (used when models require bi-directional mapping across boundaries):

public interface BiTransformer<Input, Output> extends Transformer<Input, Output> {  

    /**
     * Creates a new instance of an Input type, with transformed data from the output object. 
     * @param output the output object  
     * @return the newly created Input object  
     */
    Input createInput(Output output);  

    /**
     * Copies the data from output to input. 
     * @param output the output object 
     * @param input  the input object  
     */
    default void copyToInput(Output output, Input input) {  

    }  
}

Leveraging Hierarchy: Polymorphic Auditing Without Annotation Duplication

To see how this works beyond abstract interfaces, look at our foundational audit layer. Just as we have domain-level base models, our infrastructure layer features shared concepts like creation and auditing (AbstractCreatableEntity in dao-impl and AbstractCreatable<UUID> in domain).

Instead of writing repetitive @Mapping annotations across dozens of child mappers, our transformer hierarchy follows the class hierarchy:

public abstract class AbstractCreatableTransformer<
    S extends AbstractCreatableEntity,
    D extends AbstractCreatable<UUID>
> extends AbstractBiTransformer<S, D> {

    @Override
    public void copyToInput(D output, S input) {  
        input.setId(output.getId());  
        input.setCreatedAt(output.getCreatedAt());
    }

    @Override
    public void copyToOutput(S input, D output) {  
        output.setId(input.getId());  
        output.setCreatedAt(input.getCreatedAt());
    }
}

Every concrete implementation extends AbstractCreatableTransformer and gains out-of-the-box, strongly-typed transformation of parent audit fields without a single line of duplicated configuration or annotation processing.

The Honest Trade-Off: What We Give Up

I don't claim pure Java transformers come at zero cost. There is no free lunch in software architecture:

More Physical Files: You write and maintain explicit .java transformer classes for every boundary mapping rather than single-line interface annotations.
Initial Writing Time: Setting up a direct transformer takes a minute longer than dropping an @Mapper annotation on a brand-new entity.
Onboarding Learning Curve: New hires accustomed to MapStruct or ModelMapper have to learn your module hierarchy (Transformer vs. BiTransformer) before they write their first transformer.

We deliberately pay this price. We trade a few seconds of initial writing time for 100% compile-time predictability, zero annotation processor build friction, seamless IDE refactoring, and instant local debugging under pressure.

What we win for the price we pay

0% Reflection Magic: The compiler knows everything. Every assignment is an explicit, strongly-typed method call (get / set / constructor / builder).
Guaranteed Refactoring Safety: Rename any field or record component in your domain model, and your IDE renames it across all transformer classes natively.
No Java Strings in Annotations: You write real Java code in Java files—not inside expression = "java(...)" annotation parameter strings.
JIT-Optimized Direct Assignments: The JVM easily unrolls and inlines straightforward Java method calls directly into native machine code. There is simply no faster execution path than raw Java.
Full Debugging Clarity: Place a breakpoint anywhere inside your transformer, hit F7, and inspect your real in-memory objects step-by-step.
Zero Annotation Processor Conflicts: No extra build-phase steps, no processor ordering headaches between tools, and zero build plugin friction.

What's Next?

Before we open up the dao-impl module and start building concrete JPA implementations, we have one more compile-time trap to tear down. In Chapter 5: The Lombok Illusion, we will see why we removed Lombok from our builds and how modern Java features make AST bytecode mutation obsolete.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 4, use the following link:

GitHub Repository (Tag: chapter-04-mappers): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 3: Anatomy of the Data Access Contract
▶️ Read Chapter 5: The Lombok Illusion

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

Anatomy of the Data Access Contract: Protect Your Domain from Framework Leaks (Chapter 3)

Kamen — Mon, 27 Jul 2026 07:27:55 +0000

In almost every modern Java textbook, data persistence is introduced with a dangerous shortcut. You are told to create an interface, extend JpaRepository<Product, UUID>, and call it a day.

The result? Without even noticing, you have tightly coupled your entire application to Spring Data and Hibernate.

The moment a junior developer leaks Pageable or Specification from Spring into your clean @Service layer, or worse—directly into your REST controllers (as we discussed in Chapter 1)—your clean architecture is officially dead. Your core module now depends on the database infrastructure framework.

If tomorrow you want to switch a high-throughput read-heavy path to raw JDBC, or migrate a specific sub-domain to MongoDB, you will realize your business logic is trapped in a framework prison.

In Chapter 3 of our Evolutionary Architecture series, we are building the Dao API Module. A zero-dependency, pure Java module that strictly defines the contracts for persistence and querying, without knowing a single thing about SQL, Hibernate, or Spring.

1. Separation of Concerns: Split Creation from Updates

A common mistake in generic DAO design is introducing a single save(Entity) method that acts as both an INSERT and an UPDATE (the typical CRUD/Upsert pattern).

While frameworks love this because it hides complexity, it introduces an architectural and performance issue.

When creating a new domain object, it enters the system without an ID, allowing the infrastructure layer (like Hibernate with its modern, time-ordered UUIDv7 generator) to assign it upon persistence. However, when updating an existing entity, the ID is already present.

If you expose a unified .save() method to the outer layers, the underlying framework is forced to run a hidden, expensive SELECT query just to check whether the ID already exists in the database before deciding to execute an INSERT or an UPDATE. By explicitly splitting these actions in our core contract, we remove this infrastructure ambiguity entirely:

public interface CrudDao<E, ID> {

    void create(E entity);

    void update(E entity);

    // Return the object or null. The business layer will decide how to proceed
    E loadById(ID id);

    void delete(ID id);
}

Unlike standard frameworks that blindly force you to wrap your lookups in Optional, our core interface relies on clean, raw type returns. Optional at the database level is a costly abstraction. It doesn't eliminate missing values; it just masks them behind wrapper objects, eating up your heap allocation and putting unnecessary pressure on the Garbage Collector in high-throughput enterprise systems. If an object is missing, the database layer should return null. It is up to the business context on the invocation side to decide whether that missing record warrants a NotFoundException or signals an entry point for an initialization flow.

2. Type-Safe Pagination and Sorting Without Spring

How do we support enterprise-grade searching, pagination, and sorting without importing org.springframework.data.domain.Pageable?

We define our own lightweight, framework-agnostic parameter objects. To enforce compile-time safety on sorting and prevent malicious SQL injections via arbitrary string sorting parameters, we introduce the SortBy interface:

public interface SortBy {
    String getPropertyName();
}

Every domain can now declare its own concrete sorting capabilities using type-safe Java Enums:

public enum ProductSort implements SortBy {
    PRICE("price"),
    CREATED_AT("createdAt"),
    NAME("name");

    private final String propertyName;

    ProductSort(String propertyName) {
        this.propertyName = propertyName;
    }

    @Override
    public String getPropertyName() {
        return this.propertyName;
    }
}

Using this, our base search query transport object remains incredibly clean, pure, and descriptive:

public abstract class AbstractParams<S extends SortBy> {

    private int page;
    private int size;
    private S sortBy;
    private Direction direction = Direction.DESC;

    protected AbstractParams(int page, int size) {
        this.page = Math.max(page, 0);  
        this.size = size < 1 ? 10 : size;
    }
    ...
}

3. Defining Domain-Specific Contracts

To tie everything together, we compose these capabilities into a distinct SearchableDao contract and extend it for our specific Aggregate Roots.

public interface SearchableDao<Type, P extends AbstractParams<?>> {
    ResultPage<Type> search(P params);
}

Notice how the ProductDao interface lives entirely within the API module, requires zero infrastructure annotations, and can easily be extended with specialized, high-performance business queries that aren't a good fit for standard CRUD, where ProductSearchParams simply extends our AbstractParams<ProductSort>

public interface ProductDao extends
    CrudDao<Product, UUID>,
    SearchableDao<Product, ProductSearchParams> {

    // Explicit business-driven query contract
    Product findBySku(String sku);
}

4. Continuous Architecture: The Contract Test Blueprint

The hidden superpower of this architecture is how trivial it makes testing. Because our DAO interfaces in this module are completely clean contracts, they allow us to implement bulletproof Contract Testing later on.

While the dao-api module itself contains zero code execution and thus carries no tests, it defines the absolute baseline behaviors. In the next chapter—when we build the concrete database implementation module—we won't just write random tests for our repositories. Instead, we will construct an abstract test suite containing 15 to 20 foundational scenarios: covering successful creation, updates, constraint violations, optimistic locking behaviors, and sorting correctness.

If someone breaks the data contract during a database migration or framework upgrade, the contract test will fail immediately before the code ever leaves the infrastructure module.

What's Next?

By decoupling our data contracts, our domain module remains pristine, bulletproof, and completely independent. Frameworks are put back where they belong: as external delivery mechanisms.

In the next chapter, we will finally bring in the heavy machinery. We will implement the concrete Infrastructure Database Module, plug in Hibernate and Spring Data JPA under the hood, and look into how to seamlessly map database entities back to our rich domain models without losing encapsulation.

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the baseline state established in Chapter 3, use the following link:

GitHub Repository (Tag: chapter-03-dao-api): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 2: Anatomy of the Domain Module
▶️ Read Chapter 4: Mapping Strategies Without the Magic

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

Domain Module: Throw Away Anemic Models and Ban `@ManyToMany` (Chapter 2)

Kamen — Thu, 23 Jul 2026 07:37:53 +0000

Years ago, when I was starting my career, I religiously followed the standard textbooks. The ones that teach you that entities should be anemic (just data holders) and that the "service layer" should orchestrate everything.

The result? After just а couple of months in production, the @Service classes bloated into thousands of lines of spaghetti code, filled with endless validation checks, state mutations, and structural mess. The domain entities completely lost their integrity—anyone could mutate their state from anywhere.

And if you throw physical mappings like @ManyToMany into the data access layer later? You are guaranteed to face N+1 query issues, tight coupling, and a schema so tangled that splitting it into microservices feels like performing open-heart surgery.

In this article, we will break down the design of our domain module. It is written in modern Java, remains completely free of Spring dependencies, guarantees encapsulation through a Rich Domain Model, and runs unit tests in milliseconds.

1. Pure OOP (Without Spring Data Magic)

When writing a clean domain model, we must isolate the infrastructure. Instead of relying on Spring Data JPA’s auditing framework at such an early stage, we define the rules for creation, modification, and naming directly within our domain's Java hierarchy.

Here is the blueprint of our base domain classes:

// Every domain object that requires creation audit tracking
public abstract class AbstractCreatable<IdType> {

    private IdType id;
    private Instant createdAt;

    protected AbstractCreatable(IdType id) {
        this.id = Objects.requireNonNull(id);
        this.createdAt = Instant.now();
    }

    ...
}

// Every domain object that also tracks modification timestamps
public abstract class AbstractUpdatable<IdType>
    extends AbstractCreatable<IdType> {

    private Instant updatedAt;

    protected AbstractUpdatable(IdType id) {
        super(id);
        this.updatedAt = Instant.now();
    }

   ...
}

// Every domain object requiring a full audit trail (who created and updated it)
public abstract class AbstractAuditable<IdType>
    extends AbstractUpdatable<IdType> {

    private UUID createdById;
    private UUID updatedById;

    protected AbstractAuditable(IdType id) {  
     super(id);  
    }  

    protected AbstractAuditable(IdType id, UUID createdById) { 
        super(id);  
        this.createdById = Objects.requireNonNull(createdById);
        this.updatedById = createdById; // At creation, updatedBy matches creator
    }

    ...
}

💡 But wait... why initialize timestamps directly in the constructor?

Because your domain models must be self-contained and fully functional from the very millisecond they are instantiated. Since our domain module is a pure Java library with zero infrastructure awareness, we cannot and should not rely on database triggers or external framework lifecycles.

By setting Instant.now() directly in the constructor, we guarantee that the domain object is always complete, valid, and immediately testable in-memory, without waiting for some future persistence layer to "hydrate" its state. It also prevents NullPointerException bugs when sorting or processing newly instantiated domain events in memory before database transactions.

2. Death to `@ManyToMany` – Designing Decoupled Relationships

In real-world, highly scalable systems, physically coupling two independent business contexts (like Product and Category) via Hibernate mappings is an architectural dead-end.

Therefore, in our architecture, @ManyToMany relationships are strictly banned. Instead, we model them as completely decoupled Aggregates that communicate solely through identifiers (UUIDs) using a dedicated Relationship Entity:

// Aggregate Root #1: Category
public class Category extends AbstractAuditable<UUID> {

    private String name;
    private boolean active;

    public Category() {  
        // POJO  
    }

    ...
}

// The decoupled junction: CategoryAssignment (Relationship Entity)
// Since relationship assignments are append-only, inheriting from AbstractCreatable is perfect!
public class CategoryAssignment extends AbstractCreatable<UUID> {

    private UUID productId;     // Pure UUID instead of Product
    private UUID categoryId;    // Pure UUID instead of Category
    private UUID assignedById;  // For auditing purpose, who made the association

    public CategoryAssignment(
        UUID id,
        UUID productId,
        UUID categoryId,
        UUID assignedById
    ) {
        super(id);
        this.productId = Objects.requireNonNull(productId);
        this.categoryId = Objects.requireNonNull(categoryId);
        this.assignedById = Objects.requireNonNull(assignedById);
    }

    ...
}

Why is this "Distributed Ready"?

If tomorrow your business decides to migrate Categories to a separate microservice (e.g., a dedicated Catalog Service), the code of your Product domain won't change by a single line. The Product database will simply store the categoryId as a plain UUID received via Kafka or a REST payload, without caring about the internal database tables or Hibernate proxies of the neighboring context.

3. When Are Direct Relationships Allowed? (Aggregate Root & 1-to-1)

While we decouple large business units via UUIDs, how do we handle tightly bound details?

If an entity (e.g., ProductSpecification) has no independent business meaning and shares 100% of the lifecycle of the main object (Product), they become part of the same Aggregate Root. When the product is deleted, the specification must be deleted cascadingly.

Here is how we model this in our domain, where Product holds a direct reference to ProductSpecification but acts as the strict transactional boundary:

public class ProductSpecification extends AbstractUpdatable<UUID> {

    private String dimensions;
    private double weight;

    public ProductSpecification(UUID id, String dimensions, double weight) {
        super(id);
        this.dimensions = Objects.requireNonNull(dimensions);
        this.weight = weight;
    }

   ...
}

// Aggregate Root: Product controlling the lifecycle of its nested entities
public class Product extends AbstractAuditable<UUID> {

    private String name;
    private String sku;
    private BigDecimal price;
    private ProductStatus status;
    private ProductSpecification specifications; // Strongly bound 1-to-1

    public Product(
        UUID id,
        String name,
        String sku,
        BigDecimal price,
        ProductSpecification specifications
    ) {
        super(id);  
        this.name = Objects.requireNonNull(name);
        this.sku = Objects.requireNonNull(sku);
        this.price = Objects.requireNonNull(price);
        this.specifications = Objects.requireNonNull(specifications);
        this.status = ProductStatus.DRAFT;
    }

    public void transitionTo(ProductStatus nextStatus) {  
        if (!this.status.canTransitionTo(nextStatus)) {  
            throw new IllegalStateException("Business rule violated: Cannot transition from " + this.status + " to " + nextStatus);  
        }  
        this.status = nextStatus;  
    }
}

4. State Machine: Inside the Enum or in an External State Manager?

A common debate among senior engineers is: Where should the state transition logic live—inside the Enum or delegated to an external State Manager?

The architectural answer is clear: State transition rules belong to the Domain (inside the Enum), while an external State Manager/orchestrator should only handle structural side-effects.

If you leak state validation rules outside, you anemicize Product and allow any developer to bypass the state machine, mutating the object into an invalid state.

Here is our encapsulated ProductStatus enum:

public enum ProductStatus {
    DRAFT {
        @Override
        public boolean canTransitionTo(ProductStatus next) {
            return next == ACTIVE || next == ARCHIVED;
        }
    },
    ACTIVE {
        @Override
        public boolean canTransitionTo(ProductStatus next) {
            return next == OUT_OF_STOCK || next == ARCHIVED;
        }
    },
    OUT_OF_STOCK {
        @Override
        public boolean canTransitionTo(ProductStatus next) {
            return next == ACTIVE || next == ARCHIVED;
        }
    },
    ARCHIVED {
        @Override
        public boolean canTransitionTo(ProductStatus next) {
            return false; // Terminal state. No transitions allowed!
        }
    };

    public abstract boolean canTransitionTo(ProductStatus next);
}

What about the external State Machine? It acts purely as an orchestrator. Once the domain layer successfully performs the transition, the orchestrator commits the transactions and triggers the side-effects (e.g., publishing a ProductActivatedEvent to Kafka or clearing a cache).

5. The 5-Millisecond Unit Test

Since our domain module does not import a single @Component, @Service, or @Autowired annotation, we don't need a slow boot context to validate our business rules.

We test pure Java objects, and the execution completes in under 5 milliseconds:

class ProductDomainTestCase {  

    private static final UUID CREATOR_ID = UUID.randomUUID();  
    private static final ProductSpecification spec = new ProductSpecification(...);  

    private Product product;  

    @BeforeEach  
    void setUp() {  
        product = new Product(...);  
    }  

    // --- DRAFT Status Transitions ---  

    @Test  
    void shouldAllowTransitionFromDraftToActive() {  
        product.transitionTo(ProductStatus.ACTIVE);  
        assertEquals(ProductStatus.ACTIVE, product.getStatus());  
    }  
    ...
}

By keeping the business layer pure, you establish a highly testable, robust, and decoupled domain core. Frameworks, databases, and network protocols are just external details plugged in at a later stage.

What's Next?

In the next part, we will dive into the very foundation of Data Access Layer design — the DAO API Module — and discuss how to keep it 100% pure without a single specific implementation (hibernate, mysql, oracle sql, etc.).

Codebase & Architecture Blueprint

The entire evolutionary architecture of this project is tracked using strict Git tags. To clone the repository and switch exactly to the state established in Chapter 2, use the following link:

GitHub Repository (Tag: chapter-02-domain): advanced-spring-multimodule

Note: All core modules are configured with strict compilation-level boundaries. Compile and run mvn clean install to see the structure in action. Maven version 3.9.* and Java 25 are required.

◀️ Read Chapter 1: Stop returning Spring Data Page from your REST endpoints
▶️ Read Chapter 3: The Dao API Module

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

If you are preparing for Senior/Lead Java interviews or looking to solidify your Spring Boot & Architecture skills, check out these highly-rated resources from the Javarevisited publication (Use promo code friends20 for an exclusive 20% discount automatically applied at checkout):

Grokking the Java Interview Prepare for core Java, concurrency, JVM internals, and design pattern questions. Get Full Book (Paid) | Download Free Sample Copy
Grokking the Spring Boot Interview Master Spring Core, Auto-configuration, Spring Data JPA, Security, and Microservices. Get Full Book (Paid) | Download Free Sample Copy
Grokking the SQL Interview Deep-dive into query optimization, indexing, joins, and complex SQL window functions. Get Full Book (Paid) | Download Free Sample Copy
The Complete Java + Spring + SQL Interview Bundle Get all three interview guides in a single heavily discounted package. Get the Ultimate Interview Bundle
Spring Professional Certification Practice Questions (250+ Questions) Validating your skills? Practice with real exam-style questions before taking the Spring Professional certification. Get the Spring Professional Questions | Download Free Sample Copy

DEV Community: Kamen

Testing the Service Layer - Part 2: Where the Shared Ancestor Ends (Chapter 10)

Twins that aren't ancestors

A specification hiding in a branch

When a fixture stops earning its keep

What this buys, concretely

What's Next?

Codebase & Architecture Blueprint

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

Testing the Service Layer - Part 1: What the Generic Suite Owes Every Service (Chapter 10)

Why mock the DAO instead of an in-memory database

What the abstract suite actually asks of a new service

BigDecimal, and the failure that only shows up later

What's inherited, and what isn't yet

Codebase & Architecture Blueprint

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

Our H2 tests passed but postgres in production disagreed

Recommended Resources for Java & Spring Boot Engineers

One Missing Parameter Doubled Our Connection Pool Wait Time

Recommended Resources for Java & Spring Boot Engineers

The Core Business Logic Module (Chapter 9)

What "independent" is supposed to mean

Different intent, different object

The template, and what it deliberately doesn't decide

What this buys, concretely

What's Next?

Codebase & Architecture Blueprint

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

Why almost every ‘Temporary’ Workaround is Permanent (Chapter 8)

The shortcut

What it should have looked like

The same failure, dressed differently

The actual cost, after the fact

The part that doesn't fit in a retro

What's Next

Codebase & Architecture Blueprint

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

What Spring Data Tests Can Miss: Testing Beyond Hibernate’s Persistence Context (Chapter 7)

What Standard Spring Tests Actually Test

Forcing a Real Write-and-Read Boundary

Ground-Zero: The TablesEraser

Reusable Tests: AbstractCrudTestCase & AbstractSearchableTestCase

What the Null-Params Test Actually Caught

Choosing an In-Memory Database

What's Next?

Codebase & Architecture Blueprint

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

The Dao Implementation Layer (Chapter 6)

CrudDaoImpl and SearchableDaoImpl

Why timestamps are set here, not left to the database

Immutable Audit Fields on the Domain Side

Why Repo needs two bounds, not one

ProductDaoImpl and CategoryDaoImpl

Why I don't use Spring Data Method Naming

What's Next?

Codebase & Architecture Blueprint

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

The Lombok Illusion (Chapter 5)

"It just removes boilerplate"

Builders aren't free either

The toolchain cost nobody budgets for

Debugging wants source code, not a description of generated behavior

Java 25 already solves this

Where I've landed

What's Next

Codebase & Architecture Blueprint

Join the Masterclass Journey

Recommended Resources for Java & Spring Boot Engineers

Mapping Strategies Without the Magic (Chapter 4)

The Architectural Trap

1. The Reflection Black Box (ModelMapper, Dozer, Spring BeanUtils)

2. The Compile-Time Generation (MapStruct)

Composite Hierarchy Reality Check: MapStruct vs. Pure Java

The MapStruct Way (Annotation Spaghetti & Untyped String Expressions)

Ground-Zero: The `TablesEraser`

Reusable Tests: `AbstractCrudTestCase` & `AbstractSearchableTestCase`

`CrudDaoImpl` and `SearchableDaoImpl`

Why `Repo` needs two bounds, not one

`ProductDaoImpl` and `CategoryDaoImpl`

2. Death to `@ManyToMany` – Designing Decoupled Relationships