DEV Community: Petter Holmström

Thoughts on AI and Software Design Patterns

Petter Holmström — Fri, 31 Oct 2025 09:47:08 +0000

Before I start, I should mention that I have not yet tried out vibe coding myself. I use AI every day for programming related tasks, but I still write the code myself, for myself. This blog post was inspired by a dream I had last night, after having spent a stressful week thinking about these sort of things. I had to write it down to get it out of my head and make some sense of it.

I started programming "real" applications with Borland Delphi in the late 1990s, when I was a teenager. My first database applications were two-tiered Delphi user interfaces on top of Paradox databases. I did not know SQL and relied only on Delphi's ready-made database components. The user interface was therefore 100% driven by the database schema. It worked, it got the job done, and you could tell that it was a Delphi application only by looking at it.

Then the three-tiered paradigm showed up. You were now supposed to have an application server between the UI and the database. Business logic. Business objects. Web services. Thin clients. Web clients. APIs. I learned PHP and MySQL. Then Java, Spring, and Hibernate. I built UIs with Swing and Eclipse RCP because the old web 1.0 user interfaces felt too restricting.

I heard about Vaadin the first time when I was interviewing for a position at the company (then called IT Mill). I got hired and started my professional journey into web application development with Java.

Back then, our motto was "thinking of U and I". When we gave trainings to other companies, we started by saying that "to the end user, the user interface is the product". Proper UX design was key in all customer projects we delivered. This was a long step away from the data-driven CRUD user interfaces that I used to build with Delphi a decade earlier.

As I worked on customer projects, the biggest challenges were not actually in the user interface, but in the backend. I made lots of mistakes while also cleaning up other peoples' mistakes. Many problems could have been avoided with better architectural design decisions. I learned domain-driven design, first the tactical part, later the strategic part. I read about architectural styles and object oriented design patterns. Decoupling. Separation of concerns. Abstractions. All these helped me build better systems, although it took a while to find the right balance between them.

I started to see system design and coding as a craft, and finished code as an art. There is beauty in well designed and well written software. I bet that's what tailors, carpenters, blacksmiths and other craftspeople thought right before the industrial revolution.

Now look around us. Everything, from clothes to furniture to household items to houses, is streamlined and functional and boring. Mass-produced. Non-customized. Cheap. And gets the job done.

Is this what is happening with the software through the AI revolution? If the code is generated by an AI, the most important artefacts become the specifications and the database. If these are designed well enough, the rest can be generated. And if it can be generated, it can be thrown away and re-generated in the future when a better model comes along.

Is this going to lead us back to the data-driven programming model of the 1990s, where user interfaces where just a thin layer on top of the database? They were ugly, but they worked. If you can get them generated by an AI for a fraction of the cost it would have taken to build them manually, is poorer UX an acceptable trade off? To many people and companies I think it might be.

This in turn makes me question the need for many of the design patterns that I have learned to use and even take for granted. The design patterns we use today were built by humans, for humans. Their intention was to make code bases easy to read, understand, maintain and extend, over long periods of time. If the code base can now be auto-generated, does it matter how it is structured?

Should our focus as developers shift to writing good specs and creating good database schemas, and just accept whatever the AI spits out as long as it makes the tests pass and gets the job done? Do we need to worry about separation of concerns? Decoupling? Layers? Extendability? Should we still think about database normalization or try to design database schemas that are more humane, as they could be used as a basis for UI generation? Should we still be teaching and writing about coding patterns these days? Or should we focus on architectural patterns and start treating the code itself as human-readable byte code?

I know I will continue to make hand-crafted applications on my free time, because I enjoy it - just as there are still carpenters, tailors, and blacksmiths making things by hand (with some help of modern power tools). But professionally, I'm writing documentation and examples for other developers - and AIs - to learn from. And now I'm not sure what level of detail I should focus on. What I have built my career on, and gained all my experience from, appears to become more and more outdated as time passes.

How I think about Vaadin application architecture today

Petter Holmström — Thu, 27 Mar 2025 14:27:48 +0000

During the past year, my main task at work has been to come up with and publish a recommendation for how business applications should be built with Vaadin. This is an ongoing task that won't end as long as Vaadin remains in business. It's also a task that involves sifting through lots of patterns, practices, and opinions. Everybody has their own preferred way of building business applications with Vaadin - including myself.

You may already have read my articles about domain-driven design. It's still an approach I keep close to my heart, but I also realize there are many cases in which other approaches are more appropriate. I could say the same about the ports-and-adapters/hexagonal architectural style.

Well, It Depends

When I was still working as a consultant, helping customers with various Vaadin (and sometimes non-Vaadin) related problems, my first answer to many of their question was "well, it depends". Then, as we gathered more information about the problem, we could narrow down the options until we were confident to make a decision.

When making an architecture recommendation, there's no size that fits all. The best you can do is to come up with a recommendation that hopefully scales. You start out with something simple that you can expand later, if needed. You have to future proof just enough, avoiding painting yourself into a corner while also not over-engineering anything.

My approach to this problem was to go back to the various designs and architectures I've used in my career, and my favorite books on the subject. However, instead of just selecting one at face value, I wanted to pick them apart to find the fundamental ideas behind each, and build something from that.

I wanted to find something that would resonate with most developers (including myself), use terms that were familiar to most developers, and that could be converted into the most common architectural styles without too much effort.

Backend or Frontend?

I soon ran into my first terminology problem. A traditional web-app consists of a frontend and a backend. The frontend contains the UI and runs in the browser; the backend contains the business logic and runs on the server. However, this is problematic in a Vaadin application.

For a Hilla UI, the frontend-backend distinction still applies. For a Flow UI, a big chunk of the user interface actually lives and runs on the server. I decided to introduce the terms presentation layer and application layer.

The presentation layer contains everything related to the user interface, regardless of whether it's running in the browser or on the server.

The application layer contains "the rest of the application", that is, business logic, persistence, integrations to other systems, and so on.

Thus, instead of talking about frontend and backend, I try to talk about presentation layer and application layer. I'm still doubting whether I should have called the presentation layer the UI layer instead...

Starting in the Presentation Layer

Since Vaadin has always been about the user interface, I decided to start there. If I stand in the presentation layer and look at the application layer, what do I see? A big, black box with API:s that I can use. Some API:s may be more generic in nature, others may have been especially crafted for me alone.

Now what to call these API:s? Ports? Endpoints? Facades? Boundaries? Services? Controllers? I decided to settle for application services, inspired by the book Implementing Domain-Driven Design by Vaughn Vernon. I figured most developers would be OK with the idea of having a user interface call services to do what it needs to do.

Looking at the Application Services

So what does the implementation of the application services themselves look like? Well, that depends... For instance:

They could send SQL queries to a database directly. I would not recommend this for anything but really simple, throw-away applications, but it is possible.
They could implement business logic and delegate to DAO:s or repositories to interact with the database.
They could orchestrate workflows with a deep domain model.

Regardless of how the application services are implemented, I think they should always handle two main responsibilities: manage transactions and enforce security.

Transactions

If an application service method touches a database, I believe that method should run inside its own transaction. The application service itself should be responsible for starting the transaction, and either committing it or rolling it back before returning.

Security

I've always considered security in the user interface as improvements of the user experience rather than real security. Even when writing Flow UI:s, I've always protected my application services with method-level security. This means that even if I forget to hide or disable a button in the UI, a user can't perform an unauthorized operation.

This is also the main reason why I never recommend people call DAO:s or repositories directly from their user interfaces. Although you can protect a repository with method-level security, it makes other things more difficult. One good example is writing background jobs, where the a background thread needs to access the database without a valid security context.

Layers vs. Components

I wanted to get away from the traditional layered way of thinking (UI layer, business layer, domain layer, entity layer, infrastructure layer, whatever-you-want-to-call-it-layer). I believe this is too limited, especially if you're only allowing dependencies from an upper layer to a lower one. This makes some things more difficult than they need be.

Instead, inspired by the C4 model of visualizing software, I've explored a component based approach, where an application consists of multiple components that interact with each other. These components aren't classified into any particular layer (except, maybe the presentation layer and application layer).

In my mind, a component has the following qualities:

It can have an API that can be called by other components.
It can have an SPI that can be implemented by other components.
It can be instantiated.

The problem here is that component is a saturated term in our industry. There are components everywhere and they all mean slightly different things. For instance, in Vaadin Flow, you compose your user interfaces by combining UI components.

In Spring, you can make a bean by annotating it with @Component.

Java as a language has no concept of a component at all.

So what is a component then? Is every application service a component, or do they form a component together? Is the domain model a component, or does it consist of components? What about integrations to other systems? Background jobs? Event listeners? Utility classes?

Enter analysis paralysis.

Naming is Difficult

My first attempt was to distinguish between system components and UI components, but I'm about to abandon that. I don't like terms that require a prefix for people to understand what they mean. Having application service and domain service as separate concepts is bad enough.

I've talked with colleagues and various LLMs about alternative naming, but nothing has really stuck. I'm now looking at identifying the typical building blocks of a business application and calling them what they are: entities, services, background jobs, repositories, and so on. I no longer try to force them into being components; however I do think many of them have the component qualities I listed earlier.

I've also started to look closer at Spring Modulith to see if I can get some inspiration from there, though at first sight, I think its application modules are more coarse-grained than what I'm looking for here. Or maybe not.

Next Steps

I plan to explore what a modern, data-driven Vaadin application could look like, and what a modern, domain-driven Vaadin application could look like. I'm hoping to get new insights and ideas that will make developing business applications in Vaadin even easier in the future.

If you have any comments, thoughts, suggestions, or counter-arguments I would very much like to hear from you!

A Potentially Expensive Mistake

Petter Holmström — Mon, 27 Feb 2023 14:45:06 +0000

Once upon a time, there was a project. We upgraded its JVM from Java 11 to Java 17 and did some smoke testing. Everything looked fine, except our financial values, which were not formatted correctly anymore.

We had been using the standard NumberFormat class with the correct locale in order to ensure the correct formatting. Java 11 did this right and formatted numbers with spaces as thousand separators, like this: 1 000 000. Java 17, for some strange reason, decided to change this and used commas instead, like this: 1,000,000, even though the locale was exactly the same.

We of course needed to fix this, so we changed the DecimalFormatSymbols like this:

var formatter = NumberFormat.getNumberInstance(locale);
var symbols = ((DecimalFormat) formatter)
    .getDecimalFormatSymbols();
symbols.setGroupingSeparator(' ');
symbols.setMonetaryGroupingSeparator(' ');
((DecimalFormat) formatter).setDecimalFormatSymbols(symbols);

This did the trick and the financial values were again formatted correctly and all was well, right?

Unfortunately not. You can also use NumberFormat to parse strings and in a few places of the code, we did just this. When we were using only NumberFormat.getNumberInstance(locale) without any customization, this worked exactly as it was supposed to. Once we started to do customization of the formatting, things took a dangerous turn that was not picked up by any of our unit tests.

If you take a value formatted by the customized formatter and asks a non-customized formatter to parse it, like this, what do you get?

var formatted = formatter.format(1000000); // "1 000 000"
var parsed = NumberFormat.getNumberInstance(locale)
    .parse(formatted); // ??

It turns out, the parsed variable above will not contain the value of 1000000, but 1!

You see, the NumberFormat.parse method only parses the beginning of the string. Once it encounters a character it does not recognize, it stops and returns the result. For example this code:

formatter.parse("1000 pirates on a ship");

will not throw an exception but return 1000 and discard the rest of the string. I was not aware of this, even though it says so in the JavaDocs. This also happened with the parsing of the financial values, since space as a thousand separator was not a valid character from the point of view of the uncustomized formatter.

Needless to say, converting one million into one is quite a serious bug. In our case, it made it all the way into production before we caught it but luckily, it had not managed to cause any damage yet.

I had not expected a change of VM to have this kind of effect, but it is often the unexpected bugs that end up biting you the hardest.

Eventual Consistency Through Scheduled Jobs

Petter Holmström — Thu, 29 Jul 2021 09:57:14 +0000

In my last blog post, I left you with a cliffhanger: how to recover from situations where individual domain event handlers fail or the entire system crashes after a transaction has committed, but before all domain event handlers have processed the event.

Like with most (if not all?) problems in software, there is no silverbullet-one-size-fits-all-solution here. Instead, you have to find the solution that best meets the requirements of your particular system. In this blog post, we are going to look at an easy(ish) approach of guaranteeing eventual consistency even if we miss a domain event now and then. The examples assume we are using Spring and Java, but the principles apply to other frameworks and languages as well.

The General Idea

The idea behind this approach is to use scheduled jobs instead of (or in addition to) domain events to synchronise state between aggregates or even between bounded contexts. The jobs run automatically at different intervals or times of day, but can also be triggered by domain event handlers. This means that if all goes well, the data will become consistent across the system within seconds of the domain event firing. On the other hand, if something goes wrong, the data will become consistent after the next successful scheduled run.

A system like this is not difficult to implement, but also not as trivial as it may seem at first look because of some caveats. However, you can avoid them by following these guidelines:

Make Your Jobs Accept All or Some Inputs

When you run a scheduled job, it is typically some kind of batch operation that works on all applicable inputs. However, in this particular case, you also want to be able to run the job on just one particular input or a small set of inputs. This allows for a lot of flexibility and is quite easy to do if you design the job in this way from the start.

Example

Let's say you have a job that will create an invoice for an order that has been shipped. The class would have the following methods:

@Component
public class InvoiceCreationJob {

    @Transactional(propagation = REQUIRES_NEW)    
    public void createInvoiceForOrders(OrderId... orders) {
        //...
    }

    @Transactional(propagation = REQUIRES_NEW)    
    public void createInvoiceForAllOrders() {
        //...
    }
}

The first method creates invoices for the orders whose IDs have been passed as method parameters (provided, of course, that those orders have been shipped and not invoiced yet; more about that later).
The second method is a batch job that creates invoices for all orders that have been shipped and not invoiced yet.

Decouple the Job and the Triggering of the Job

When you design your jobs, think about when and how they will be triggered:

When the system starts up?
Manually by a user?
In response to a domain event?
As a scheduled job?
Through JMX?
In some other way you are not aware of yet?

I would recommend a design that looks like this:

The job itself is a separate object that does its thing when told to by other objects.
The application service starts the job in response to human user actions.
The domain event handler starts the job in response to a domain event.
The worker handles scheduled job executions (such as once per hour, every ten minutes or every day at midnight).

Example

Let's continue with the invoice generation example. We start with a domain event handler that generates an invoice as soon as an order has been shipped:

@DomainEventHandler
public class InvoiceGenerationOnShipmentTrigger {

    private final InvoiceCreationJob job;

    InvoiceGenerationOnShipmentTrigger(
            InvoiceCreationJob job) {
        this.job = job;
    }

    @TransactionalEventListener
    public void onInvoiceShipped(InvoiceShippedEvent evt) {
        job.createInvoiceForOrders(evt.getOrderId());
    }
}

Next, we want to trigger the job every day at midnight:

@Component
public class InvoiceGenerationWorker {

    private final InvoiceCreationJob job;

    InvoiceGenerationWorker(InvoiceCreationJob job) {
        this.job = job;
    }

    @Scheduled(cron = "0 0 0 1/1 * ? *")
    public void atMidnight() {
        job.createInvoiceForAllOrders();
    }
}

Finally, we want administrators to be able to trigger the job at any time through an application service:

@Service
public class InvoiceGenerationService {

    private final InvoiceCreationJob job;

    InvoiceGenerationService(InvoiceCreationJob job) {
        this.job = job;
    }

    @Secured("ROLE_ADMIN")
    @Async
    public void createInvoiceForAllOrders() {
        job.createInvoiceForAllOrders();
    }
}

Make Your Jobs Idempotent

When you write a job, you know what the intended end state of the system is going to be. However, you should never make any assumptions about this nor should you make assumptions about what the start state is. Your job should always check what the start state is, and then figure out what actions it needs to take in order to get to the desired end state. If the system is already in the desired state, your job should do nothing.

If your job is implemented like this, you can run it as many times as you want with the same inputs and it will not cause any side effects (like generating multiple invoices for the same order). If a job execution fails because of e.g. a network error or power outage, you can just re-run it later.

Example

Let's again continue with the invoice generation example. In the initial design, the states an order will traverse through are the following:

The first step on our road to idempotence is therefore to check the state of the order and only take action if that state is SHIPPED. For each shipped order, the job will then perform the following:

However, there is a problem here: what happens if the second transaction fails for some reason? That would mean that the next time the job runs, there is already an invoice even though the state is SHIPPED.

Thus, the next step on our road to idempotence is to detect whether an invoice has already been create for a particular order. We can do this by adding an OrderId field to the Invoice aggregate and use this to check that no invoices have been created before creating a new one. If an invoice already exists, the job will just proceed to setting the state to INVOICED (you will need some database constraints or pessimistic locking to implement this properly, but that is outside the scope of this article)

In more complex situations, you may have to add some intermediate states (such as INVOICE_GENERATION_IN_PROGRESS) to be able to pick up where you left off in case of failures.

Avoid Simultaneous Executions of the Same Job

Since your job can be started in many different ways, there is a risk that it will be started while it is already running. If the job is idempotent, this should not cause any data consistency problems, but you may end up with transaction deadlocks or other concurrency issues. Also it is a waste of resources and may slow down other parts of the system.

If simultaneous executions of the same job is a rare occurrence, you may choose to just live with it and let the idempotence handle it. However, if it happens frequently, you should deal with it in some way. The action you take depends on the use case, but typically it is one of the following:

Let the current job finish, do not start the new job at all.
Cancel the current job, then start the new job.
Let the current job finish, then start the new job.

Example

I could write an entire blogpost only about this particular problem so for this example, we are going to narrow down the scope quite a bit and continue to use the invoice generation case.

Let's say we are dealing with a small application that is only deployed as a single instance so we do not need to worry about situations where the same job runs at the same time on different machines.

The first thing we want to do is to make sure that only one instance of the batch operation can run at a time. The easiest way of doing this is with an AtomicBoolean (because InvoiceCreationJob is a singleton):

@Component
public class InvoiceCreationJob {

    private final AtomicBoolean working 
        = new AtomicBoolean(false);

    @Transactional(propagation = REQUIRES_NEW)    
    public void createInvoiceForAllOrders() {
        if (working.compareAndSet(false, true)) {
            try {
                // Do the work
            } finally {
                working.set(false);
            }
        }
    }
}

If the working variable is false, if till be set to true and the work is allowed to start. Once finished, the working variable is set back to false.
If the working variable is true, the method will do nothing.

This is good enough since the batch operation is only used as a fallback solution in case we would fail to properly handle some InvoiceShippedEvents.

What about the createInvoiceForOrders method then? This method is likely to run simultaneously for different Orders but that is not a problem so we do not want to prevent that.

The method is unlikely to run simultaneously for the same Order although it still can happen. In this case, we can rely on the idempotence of the operation. The same applies to the case where createInvoiceForOrders and createInvoiceForAllOrders are running simultaneously.

Use Threads Wisely

When you implement a job, you should think about which thread it is going to run in. Will it always run inside of its own thread regardless of how it was started, or inside the thread that started it, or a combination of both?

Let's have a look an some examples to illustrate why this is important:

Let's say a job is scheduled to be continuously executed by a worker with a five minute delay. This means that a new job should start five minutes after the previous one has finished. Now, if the job runs inside its own thread, the worker will think it has finished as soon as the job thread has started. If the job was to take longer than five minutes, the worker would start a new job even though the old one is still running. In this case, it is better to let the job run in the thread that started it.
Another job is started by the user through an application service. This is also a long running job. Now, if the job runs inside the thread that started it, it would block the UI until the job is finished. In this case, it is better to let the job run in its own thread.

Now let's say the jobs mentioned above are actually the same job. In order to keep your options open, you should always implement your jobs to run inside the calling thread and then let the callers worry about which thread to use.

Example

Scroll back up to the example that demonstrates different ways of triggering the job. Note that the application service uses the @Async annotation whereas the domain event handler and the worker do not. Why? Let's have a look at each case:

The application service is invoked through a UI and is used by administrators to manually trigger the batch job. This job can take some time to complete and we do not want this to block the UI. Therefore, we run it asynchronously inside a background thread.
The domain event handler is invoked when an event arrives and is a bit of an edge case: when you have a small number of event handlers that return quickly you can run them in the calling thread. However, if you have a large number of handlers or some of them take time to complete, you may want to run them in a background thread.
The worker is already invoked by a background thread so we can continue to use that.

Use Upper Limits in Your Queries

Your jobs will perform different queries to determine the state of the system. The amount of data that needs to be processed depends on many factors, such as how heavily the system has been used or when the job was last run.

Because of this, whenever you write a query, you should stick to the good ol' rule of thumb: Any query will return either no records, exactly one record, or a huge load of records

Unless you know for sure that the query falls in the first two categories, you should always add an upper limit to your query. You can either implement the job to run in batches until there is no more data to process, or just process the first N records and then wait for the next run.

Schedule Jobs Wisely

When you schedule a job, you typically have the following alternatives:

Fixed rate: the job is started at a fixed rate, such as once every 60 minutes.
Fixed delay: the job is started with a fixed delay after the previous execution finished.
Cron: the job is started at a particular time of the day, or day of the week, such as five minutes past every hour, or 2 o'clock in the morning on Sundays.

Picking the correct schedule for your job may require some trial and error. If you run too often, you could end up starting new jobs before the old ones have finished, slowing the entire system down and causing transaction deadlocks in other parts of the system. If you run too rarely, the users are unhappy. You may have to try out different schedules to find the best balance.

Finally remember to look at all your jobs as a whole: is there a risk of running into conflicts between different jobs working on the same data? Are different heavy-weight jobs running simultaneously? Do some jobs need to run before others?

Architectural Considerations

Now when we have familiarised ourself with the general idea, we need to look at how it fits into the system architecture (which is assumed to be hexagonal).

Application services and domain event handlers we already know, but where would the workers and the job go? Let's start with the worker, because it is the easiest one.

A worker is a component that triggers actions in response to events generated by a timer. It can control its own transactions and threads if needed. This puts it into the orchestrator category, together with e.g. domain event handlers, and thus it belongs in the application layer.

But what about the job itself? The answer to that is: it depends. Read on.

Single Bounded Context

When the job is about propagating changes inside the same bounded context, the job is most likely implemented as a domain service. The domain event handler, worker and application service live in the application layer and invoke the domain service as needed (and also control the transactions).

Multiple Bounded Contexts

When the job is about propagating changes from one bounded context to another, we are talking about context mapping. The implementation and location of the job depends on the integration pattern you end up choosing. Let's look at three examples (there are more solutions than that but we have to draw the line somewhere).

Customer-Supplier and Conformist

In this case, there is a one-directional relationship between both contexts where the downstream context wants the upstream context to either perform some action (push) or return something (pull). This typically leads to the following architecture:

The upstream context provides an adapter that the downstream context can use to access the system.
- In a customer-supplier relationship, the upstream team is required to design this adapter according to the needs of the downstream team.
- In a conformist relationship, the downstream team will use whatever the upstream team chooses to put into the adapter without having any say.
The job itself is an application service delegate. This means that it lives in the application layer, but it is not a pure application service as it does not perform any security checks at all.
If the contexts are running inside the same monolithic application, the job can be triggered by domain events coming from both contexts.
If the contexts are running inside separate applications, the job can only be triggered by domain events coming from the downstream context because we have no way of distributing the events. Then again, that is one of the reasons why we are using scheduled jobs instead.

Anticorruption Layer

In this case, there is again a one-directional relationship between the contexts, but in this case, the downstream team has decided to completely shield the application from the upstream context:

The downstream context provides an adapter (the anticorruption layer) that adapts the upstream context to an API that has been declared by the downstream team.
The job is still an application service delegate, but it talks to the upstream context through the API.
If the anti-corruption layer includes support for propagating events from the upstream context to the downstream context, then the job can be triggered by events coming from both contexts. Otherwise, it is limited to events coming from the downstream context only.

Middleware

A middleware solution may come in handy in cases where you have no control over any of the involved contexts, or where the relationship is bidirectional even though the contexts themselves are not aware of each others' existence:

The job, the workers, any domain event handlers and other components are moved out from the bounded context and into a separate middleware component.
The middleware is responsible for moving data back and fourth between the contexts, without the contexts even knowing about it.
This works both for monoliths and for distributed systems.

Pros and Cons

Now it is time to wrap things up by looking at the pros and cons of using scheduled jobs to achieve eventual consistency.

The main advantages with this approach are the following:

It works out of the box with @TransactionalEventListener and all the other Spring-based building blocks and tools we have covered in this blog post series so far.
You do not need to introduce any new moving parts (like a message broker) or write any infrastructure code for persisting and distributing domain events.
It is quite easy to implement and its complexity can be tweaked according to the use cases.
When done right it leads to a system that is resilient and robust.

However, it also has several drawbacks:

Your system is not actually event driven. Some events are used to trigger jobs early, but the jobs themselves are data-driven.
Additional state may have to be stored in the aggregates to direct the jobs (for example in order to achieve idempotence).
The coupling increases as the jobs must be fully aware of all the aggregates involved.
Not useful when changes need to be propagated quickly.
For every job you add, the more work your database will have to do. This increases the risk of transaction deadlocks and performance problems.
Scaling out or introducing redundancy need some special attention: you do not want multiple servers to start running the same job on the same data at the same time (even though idempotent jobs should make sure the data does not get corrupted).

Clearly there are systems that are suitable for this approach and I have successfully used it myself in customer projects. However, there are also lots of systems out there for which this approach would not be appropriate. In a future blogpost (or possibly blogposts) we are going to look at other ways of making sure our domain events are not missed and how we can distribute them between systems. Stay tuned!

Handling Domain Events with Spring

Petter Holmström — Fri, 18 Jun 2021 13:05:54 +0000

In my last blog post, with looked at how to publish domain events using Spring Data. However, there is no use in publishing events unless you can also receive and handle them so that is what we are going to look at in this blog post.

We recall that Spring Data publishes domain events using the standard ApplicationEventPublisher. This means that we can also handle events in the standard Spring way using @EventListener so let's have a look at that first.

Handling Events with `@EventListener`

A domain event handler (I sometimes also use the term domain event listener - they mean the same thing) using @EventListener looks something like this:

@Component
class MyDomainEventHandler {

    @EventListener
    public void onMyDomainEvent(MyDomainEvent event) {
        // Handler code here.
    }
}

The domain event handler is a Spring bean, which means you can inject other beans into it.

Once an event is published using the ApplicationEventPublisher, it will by default be handed over to the ApplicationEventMulticaster. The default implementation of this - SimpleApplicationEventMulticaster - will just loop through all applicable listeners and call them one at a time. Unless a task executor and an error handler have been explicitly specified, the listeners will be called inside the same thread that published the event and if any one of the listeners throws an exception, it will halt the process and the remaining listeners will not be notified at all.

This means that if you use the default configuration of the event multicaster and use @EventListener for your domain event handlers, they will participate in the same transaction that published the event. This also means that if you throw an exception from an event handler, you will rollback the entire transaction.

In some use cases, this may be desired behaviour, in which case using @EventListener is the way to go. However, this also violates the third guideline of aggregate design which states that you should only edit one aggregate in one transaction.

There is a reason for this guideline and I've been bitten by it myself when we used @EventListener for our domain event handlers. The thing is, handling domain events in the same transaction that published them works fine as long as you have a small number of domain handlers that are lightweight and that you are aware of. Problems start to show up when other developers attach more heavy-weight domain handlers that themselves may trigger domain events, which are handled in the same transaction, and so on. This leads to two significant problems:

First, this leads to longer running transactions which may timeout or run into different locking issues, such as deadlocks or optimistic locking failures.

Second, if any one of the domain event handlers in the chain fails, that domain event handler will have the power to rollback the entire transaction, essentially undoing all the events. Do you really want to give the power to change the past to a single domain event handler? After all, a domain event is published because something has happened, not because something will or might happen.

So how do we then make sure our domain event handlers run inside their own transactions?

Introducing `@TransactionalEventListener`

Spring has an alternative annotation for event handlers that need to be transaction aware and that is @TransactionalEventListener. The annotation is used exactly the same way as @EventListener:

@Component
class MyTransactionalDomainEventHandler {

    @TransactionalEventListener
    public void onMyDomainEvent(MyDomainEvent event) {
        // Handler code here.
    }
}

These event listeners are not invoked directly when an event is published. Instead, they are tied to the lifecycle of the current active transaction (and because of this, they do not work if you use a reactive transaction manager).

The default behaviour of a @TransactionalEventListener is to execute after the current transaction has been successfully committed. If the transaction is rolled back, or there is no active transaction to begin with, nothing happens.

You can change this behaviour by passing different parameters to the annotation. The annotation can be configured in several ways but we will only look at two parameters:

phase: The transaction phase to bind the event to. Default is AFTER_COMMIT, but other options are BEFORE_COMMIT, AFTER_ROLLBACK and AFTER_COMPLETION (event handler is executed regardless of whether the transaction was committed or rolled back).
fallbackExecution: Whether the event handler should be executed even if there is no active transaction. Default is false.

If you use AFTER_COMMIT or AFTER_COMPLETION, it is very important that any transactional code that you may invoke from within the event handler starts its own transaction (in other words, they should use the REQUIRES_NEW transaction propagation and not REQUIRED). You can read about why in this blog post.

So now all of our problems are solved, right? Not quite. When our events were handled inside the same transaction, either all the changes were committed or none were. The data would always be in a consistent state after the transaction was complete.

With the @TransactionalEventListener this is no longer the case. What if some of the event listeners fail and others succeed? Or what if the entire system goes down after the first transaction has committed, but before any event listener gets executed? This could put our data into an inconsistent state. How do we recover from this?

I'm going to leave you with a cliffhanger now, because that will be the subject of a future blogpost.

Publishing Domain Events with Spring Data

Petter Holmström — Sat, 29 May 2021 07:40:58 +0000

In my last two posts about domain-driven design, we looked at how to build repositories and how to use value objects as aggregate IDs. Now we are going to have a closer look at domain events.

From Spring's point of view, a domain event is just another application event that can be published using the built-in ApplicationEventPublisher. In other words, we do not need to worry about building an event bus or some other infrastructure for publishing domain events: you inject the event publisher into your domain service and publish the event. However, in most cases you want to publish domain events directly from the aggregate without having to go via a domain service just for that purpose. Fortunately, we can do just that.

Spring Data provides a mechanism for publishing domain events directly from within aggregates without having to get a hold of the event publisher. We already touched on this mechanism when we looked at BaseAggregateRoot and now we are going to take a closer look at it.

Under the hood, Spring Boot will register a method interceptor for all repository methods whose names start with save, such as save and saveAndFlush. This interceptor will look for two methods in your aggregate: one annotated with @DomainEvents and another annotated with @AfterDomainEventPublication.

The method annotated with @DomainEvents is expected to return a list of events to publish. The interceptor will publish these events using the Spring application event publisher. Once the events have been published, the method annotated with @AfterDomainEventPublication is invoked. This method is expected to clear the list of events, to prevent them from being published again the next time the aggregate is saved.

There is a caveat to keep in mind when designing and publishing domain events in this way and it has to do with events that include a reference to the aggregate root itself, for example like this:

public class PotentiallyProblematicDomainEvent {
    private final MyAggregate myAggregate;

    public PotentiallyProblematicDomainEvent(@NotNull MyAggregate myAggregate) {
        this.myAggregate = myAggregate;
    }

    public @NotNull MyAggregate getMyAggregate() {
        return myAggregate;
    }
}

Whenever you design events like this, you have to be aware of how Spring Data and JPA work under the hood.

When you save an existing entity (and here I'm talking about the JPA entity concept, not the DDD one), Spring Data will end up calling EntityManager.merge. If the entity is detached, JPA will retrieve the managed entity, copy all the attributes from the detached entity to the managed one, save it and return it. The managed entity will get its optimistic locking version incremented while the detached entity remains untouched.

However, since the domain event was registered on the detached entity, the domain event listeners will get a reference to the detached entity. This can lead to optimistic locking errors if a listener tries to perform any operations directly on the entity and then save it.

Here are a few examples of cases where the listeners will end up getting a stale entity with an incorrect optimistic locking version:

public class PotentiallyProblematicApplicationService {

    @Transactional
    public void firstProblematicMethod(@NotNull MyAggregate aggregate) { // <1>
        aggregate.performAnOperationThatRegistersAProblematicDomainEvent();
        myAggregateRepository.saveAndFlush(aggregate);
    }

    public void secondProblematicMethod(@NotNull MyAggregateId aggregateId) { // <2>
        var aggregate = myAggregateRepository.getById(aggregateId);
        aggregate.performAnOperationThatRegistersAProblematicDomainEvent();
        myAggregateRepository.saveAndFlush(aggregate);
    }
}

This method accepts an aggregate as a parameter and performs operations on it directly. This means the aggregate is detached and will become stale once saved.
This method accepts the aggregate ID as a parameter and looks up the aggregate before performing operations on it. However, the method is not @Transactional which means that both calls to the repository will run inside their own transactions, detaching the aggregate in between.

Now how do we address this? The second method is quite easy to fix: just make the entire method @Transactional. That way, the aggregate will still be managed when it is saved and the domain event listeners will get the correct instance.

But what about the first method? An obvious solution would be to use the aggregate ID instead of the aggregate itself in the event. However, this has a problem of its own: if the event is registered before the aggregate has been persisted, the aggregate has no ID. If you never publish any events from unpersisted aggregates, this is not a problem. If you do, however, you can fix it like this:

public class SaferDomainEvent { 
    private final MyAggregate myAggregate;

    public SaferDomainEvent(@NotNull MyAggregate myAggregate) { // <1>
        this.myAggregate = myAggregate;
    }

    public @NotNull MyAggregateId getMyAggregateId() { // <2>
        return myAggregate.getIdentifier();
    }
}

We still store a reference to the aggregate inside the event...
... but we only expose its ID to the outside world, forcing any listeners to fetch a fresh copy of the aggregate from the repository if they want to do anything with it.

This is yet again an example of the underlying technology silently sneaking into your domain model - your choice of persistence technology can even affect the design of your domain events. Fortunately in this case it is not a big deal, but it is still something that may come back and bite you later if you base your early designs on assumptions that later turn out to be incorrect (I've been there and done that, especially when it comes to JPA). The bottomline is that you need to know your tools well - not only how to use them but also how they work.

In a future post, we are going to look at how to catch the domain events we have published and some caveats related to that.

Event Pitfalls (and How to Avoid Them)

Petter Holmström — Tue, 18 May 2021 13:34:29 +0000

During my time as a software engineer, I've dealt with different kinds of event-driven systems. Some were using events in the UI, others were using events in the backend. In both classes of systems, I've managed to shoot myself in the foot. Let's look at what happened and how it could have been avoided.

Using events as commands

An event bus is a nice way of decoupling communication between components, regardless of whether this is happening in the backend or in the UI. This makes it really easy and compelling to use the event bus as a way of telling other components what to do - i.e. using the events as commands.

This is one of those things that may seem like a good idea at the time but may later come back and haunt you. There are multiple reasons for this:

Your commands typically cannot return any results to the caller. You'd have to use exceptions and return events to indicate the outcome of the command.
It leads to logic that is difficult to understand and debug. Depending on how the event bus is implemented, it may not be obvious to see where the event was sent and where it ended up being handled.
If the event bus itself is changed in the future, e.g. from being a synchronous bus to an asynchronous bus where each event handler runs in its own thread, you may run into some strange side effects.

When building event-driven applications, think of an event as something that has already happened (and name it accordingly). If the application is command-driven as well (which can be really useful in certain use cases), it should use a separate, dedicated infrastructure for routing and handling the commands.

Not isolating consumers from producers

In the previous section, we concluded that an event is something that has happened. Event consumers (or handlers, listeners, observers or whatever you want to call them) should typically not be allowed to change this.

With a simple event bus implementation that just loops through all the consumers and calls them synchronously, you may end up doing exactly that. If one of the consumers ends up throwing an exception, you may end up rolling back the entire transaction and also stopping the remaining consumers from even getting the event.

In some cases where you have a small number of consumers and you are in control of all of them, this may be the desired behaviour and so there is not anything inherently bad about this design. However, if the events are intended to be used by consumers outside your direct control (by other developers for instance), you may want to think twice about your design. If you want the event consumers to be able to affect the producer or other consumers in some way, this should happen explicitly through an API designed for that purpose and not by mistake because of incorrect use of an event bus.

There is also another issue that you can run into by not isolating your event consumers and producers properly. If you are using some kind of security context that is bound to the current thread, the simple event bus implementation mentioned above would invoke each consumer using the producer's security context. This can lead to unintended security breaches, e.g. if the consumers have been registered by different users.

Assuming all event consumers will always succeed

In the previous section, we concluded that event producers and consumers should be isolated from each other. However, this may lead to a situation where some consumers succeed in processing an event and others fail.

Depending on the type of event this may or may not be a big deal. If we are talking about events that are short lived, such as a mouse move event or a GPS-position update of a portable device, we can probably live with a missed event or two as new events would render the old events obsolete anyway.

However, if we are talking about one-off events, you may end up with inconsistent data in your database. For example, in an order processing system, you may have received, processed and shipped an order but failed to generate an invoice because the event consumer that was supposed to handle that failed.

Addressing this problem is not really trivial and the solution would vary from system to system, but in principle it consists of three steps:

Realise that your system is vulnerable to this issue. If the system works most of the time, you may not even notice this until it is too late.
Make sure you can easily detect when an event has been missed, either manually or automatically.
Make sure you can either replay the missed event or retrigger the needed actions in some way, either manually or automatically. If you are not familiar with the concept of event sourcing, I would recommend you to have a look at it.

Assuming all events will occur exactly once

In the previous section, we concluded that one of the ways of dealing with failed event consumers is to replay the event at a later time until all consumers have succeeded. But what would then happen with all the consumers that did succeed on the first try? We typically don't want them to process the same event more than once.

One way of doing this is to somehow keep track of which consumers have successfully handled an event and which ones have not. However, this can become complicated really fast.

A better approach is to make sure all your event consumers are idempotent by design.

In software, an idempotent operation is an operation that can be performed multiple times without changing the state of the system.

An idempotent event consumer would be a consumer that only changes the state of the system the first time an event is received. If the same event is received more than once, the system state remains unchanged. If all your consumers are implemented like this, you can replay your events as many times as needed without side effects. It also makes your system more resilient if you are receiving your events from a remote message queue that cannot guarantee that all events will be delivered exactly once 100% of the time.

Assuming all event streams will be calm and even

On paper, your event-driven design may look nice, clean and simple. Your initial testing on your own workstation may confirm that perception. Then you release your software to production, and things start to go wrong.

It turns out some event consumers are a lot slower than others, and some event producers are producing more events than the consumers can keep up with. Also some event consumers are in turn producing events on their own, further increasing the load on the event bus.

Your first attempt at fixing this is to introduce thread pools for the event consumers, but it only helps for a little while. Soon, the thread pools' queues are full and they start to reject jobs (which means you are essentially throwing away events without handling them).

Event-driven systems are dynamic by their nature. However, it is very easy to only look at the static aspects when you design a software system because they are easier to grasp and reason about. Especially in multi-user systems and systems that respond to events coming from outside the system, it is important to think about event dynamics from the start:

How long will it take for a particular event consumer to process a single event?
Will an event consumer emit new events? What will that lead to?
What is the estimated event throughput during normal load and peaks?
What is the highest event throughput your system should be able to handle and what should happen if the system can't keep up?

This is a back pressure problem that you will run into in any system where you have a producer that is producing data faster than a consumer can process it. There is no one-stop solution to it and discussing it in more detail is way of out scope of this post. However, here are a few things to get you started:

If you can use a ready-made, battle tested product for solving the problem, use it.
If events arrive in bursts, you can store them in a queue. Please note that this won't work if there is never time to empty the queue between bursts.
If the events can be aggregated, you can store them in a queue and then have the consumer process them in groups rather than one by one.
If you are in control of emitting the events in the first place, you may want to do that in sequence instead of in parallel.
If your system and environment allows it, you could automatically scale out the number of event consumers as the load increases and then scale back in when it decreases (this typically requires a message broker that is able to dynamically route messages to different queues).
If you can control the event producer in some way (either by asking it to slow down or stop until further notice), do it. And if you are the one implementing the event producer, consider adding this feature.

Knee-deep in Spring Boot, Transactional Event Listeners and CGLIB proxies

Petter Holmström — Fri, 07 May 2021 15:40:42 +0000

A colleague and I spent two hours tracking down a strange bug in our Spring Boot application today. The cause was so interesting that I have to write about it here. Since I obviously can't write about customer projects here, I'm presenting the problem using a sample application instead. So here we go.

Let's say we have a domain-driven application with two aggregates: Order and Invoice. We also have an orchestrator that automatically should create new invoices once an order transitions into the SHIPPED state.

We start with the following application service for creating new orders:

@Service
public class OrderService {

    private final OrderRepository orderRepository;

    public OrderService(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    @Transactional
    public Long createOrder() {
        var order = new Order();
        return orderRepository.saveAndFlush(order).getId();
    }

    @Transactional
    public void shipOrder(Long orderId) {
        orderRepository.findById(orderId).ifPresent(order -> {
            order.ship();
            orderRepository.saveAndFlush(order);
        });
    }
}

The Order.ship() method will change the state of the order to SHIPPED and publish an OrderStateChangedEvent.

Then we need another application service for creating new invoices:

@Service
public class InvoiceService {
    private final InvoiceRepository invoiceRepository;

    InvoiceService(InvoiceRepository invoiceRepository) {
        this.invoiceRepository = invoiceRepository;
    }

    @Transactional
    Long createInvoiceForOrder(Order order) {
        var invoice = new Invoice(order);
        return invoiceRepository.saveAndFlush(invoice).getId();
    }
}

Finally, we need an orchestrator that creates the invoice when the order is shipped:

@Component
class InvoiceCreationOrchestrator {

    private final OrderRepository orderRepository;
    private final InvoiceService invoiceService;

    InvoiceCreationOrchestrator(OrderRepository orderRepository, InvoiceService invoiceService) {
        this.orderRepository = orderRepository;
        this.invoiceService = invoiceService;
    }

    @TransactionalEventListener
    public void onOrderStateChangedEvent(OrderStateChangedEvent event) {
        if (event.getNewOrderState().equals(OrderState.SHIPPED)) {
            orderRepository
                .findById(event.getOrderId())
                .ifPresent(invoiceService::createInvoiceForOrder);
        }
    }
}

There! Now we just run the application, create a new order, ship it and... no invoice gets created. There are no exceptions in the log either. So what went wrong?

It turns out the problem is in the @TransactionalEventListener. It is by default configured to run after the transaction has been committed. This is exactly what we want, but there is a caveat in how Spring actually implements this.

Domain events are published using the ordinary application event publisher. Spring will actually catch them using an ordinary @EventListener as well. However, instead of invoking the transactional event listener directly, Spring will register a TransactionSynchronization with the TransactionSynchronizationManager. This will invoke the transactional event listener after the transaction has successfully committed, but before the transaction synchronization manager has cleaned itself up.

Now, our event listener is invoking the createInvoiceForOrder method, which has the @Transactional annotation. The default propagation for @Transactional is REQUIRED. This means that if there already is an active transaction, the method should participate in it; otherwise it should create its own transaction.

Because this method is being invoked inside a TransactionSynchronization, there actually is an "active" transaction but it has already been committed. Thus, the call to saveAndFlush will result in a TransactionRequiredException. This exception is swallowed by TransactionSynchronizationUtils (another Spring class) and logged using the DEBUG level. Thus, the only way to detect this exception is by having DEBUG logging turned on for the org.springframework.transaction.support package.

The solution to this problem is to make sure that the InvoiceService always runs inside its own transaction. So we change the method like this:

@Service
public class InvoiceService {
    @Transactional(propagation = REQUIRES_NEW)
    Long createInvoiceForOrder(Order order) {
      // Rest of the method omitted
    }
}

It is anyway a good practice to configure all your application services to always use REQUIRES_NEW since they are responsible for controlling the transactions.

Now we run the application again and... it still does not work. The application behaves exactly the same. What's wrong now?

It turns out that createInvoiceForOrder is not actually running inside a transaction at all. The transaction is started and committed by the call to saveAndFlush() in the repository, and that method still uses REQUIRED transaction propagation. How come?

The InvoiceService is not implementing any interfaces, so Spring is using a CGLIB proxy to add the transaction interceptors. However, the method createInvoiceForOrder happens to have package visibility and the transaction interceptor is only applied to public methods. So we need to change the method to be public:

@Service
public class InvoiceService {
    @Transactional(propagation = REQUIRES_NEW)
    public Long createInvoiceForOrder(Order order) {
      // Rest of the method omitted
    }
}

Now we run the application once more and it finally works!

Java Pitfalls (and How to Avoid Them)

Petter Holmström — Thu, 29 Apr 2021 14:16:35 +0000

I've been coding in Java since 2004, professionally since 2009. During these years I've come across several pitfalls that could have easily been avoided upfront - if you had thought of them. In this post, I'm going to list some of them (or more specifically, how to avoid them), in no particular order.

Validate and Sanitise Your Input Data

Input data can be coming from your users, another component within the system or from another system. This means that data validation and sanitation must be done on multiple levels.

The Difference Between Validation and Sanitation

Validation means that you check that your input data is correct. The result of this operation is essentially a boolean: either the input data is correct, or it is not.

Sanitation means that you take the input data and transform it until it becomes valid. The result of this operation is either valid input data or an exception. Let's take a simple example: phone numbers. People write phone numbers in very different ways, using all kinds of separation characters and groupings. However, writing a function that will remove all other characters except the + sign and the numbers 0-9 from a string is very easy. In addition, it lets the users enter phone numbers in their preferred format and guarantees that the numbers are stored in a consistent format in your system.

What to Validate

What you should validate depends on the use case and the specifications but here is a list to get you started (it is by no means exhaustive):

Empty values and nulls
String max lengths (for example: JPA defaults to 255 characters for string fields)
Allowed and forbidden characters and patterns (such as e-mail addresses, phone numbers, postal codes and filenames)
Checksums (such as social security numbers and bank account numbers)
Numerical limits (such as maximum value, minimum value and number of decimals)
The decimal point character (are you using . or , or both?)
Script injection attacks (such as JavaScript and SQL)

When and Where to Validate

Data should be sanitised and validated whenever and wherever it enters the system. Bad data should be stopped at the gates. Doing validation and sanitation in the user interface is great for improving the user experience, but it should not be the only place where this is done. The real validation and sanitation must always be done in the backend.

Dealing With Bad Legacy Data

Unfortunately it is not always possible to stop bad data at the gates. If you are dealing with a legacy system, the data may already be inside. A typical example could be a date column that used to be a varchar (yes, that happens) and now needs to be changed into a date, or an e-mail column that did not use any kind of validation at all and now contains all kinds of garbage.

You can deal with this in several ways:

Fix the bad data while you migrate it from the old database to the new one
Use double columns, one for bad values that could not be automatically migrated and another for correct values
Use a custom value object that can distinguish between bad data and good data (read more about it here)

In any case you should never let bad legacy data be an excuse not to properly validate and sanitise new data!

Design By Contract

I would guess most programmers that have received some kind of formal training are familiar with the design by contract principle. Let's recap:

Preconditions state what must be true in order for the operation to succeed
Postconditions state what will be true once the operation has finished successfully
Invariants state what conditions remain unchanged before and after the operation has been performed

You should clearly define and document contracts for all your public APIs. This does not mean only the methods you write but also the input and output data (such as DTOs) and any exceptions. You can use JavaDocs and ordinary language for this; there is no need to go formal unless you want to.

A fellow developer (or yourself in six months) should never need to make assumptions of how to use your method or how to interpret its result. For example: I don't know how many times I've had to dig into the source code (sometimes quite deep) just to figure out whether certain output values can be null or not. Which brings me to the next pitfall...

NPEs Can Be Avoided, So Avoid Them!

We have all run into those pesky NullPointerExceptions in production and that is embarrassing. We really should not do that. New programming languages such as Kotlin are doing a great job in combatting them, but even in vanilla Java there are a few simple things you can do to greatly reduce the number of NPEs:

Validate never-null parameters using Objects.requireNonNull()
Use Optionals for return values that can be empty or null (and never use them for values that are never empty nor null)
Never assume an Optional will always contain a value (it wouldn't be an Optional if it could not also be empty in some cases)
Document your code carefully and read the documentation that others (or yourself six months ago) wrote
Use @NotNull and @Nullable annotations if your IDE supports them - your IDE may be able to warn you about potential NPEs even before you compile your code

If Possible: Reuse by Composition, Not by Inheritance

We programmers are lazy. If we can write something only once and reuse later, we very much try to do it (otherwise we copy-paste it). Especially in my earlier programming days my go-to method for doing this was through inheritance. Now I know better.

When I was a child, I loved to play with LEGOs. My cousin had a Playmobile castle and I loved to play with it as well. I could build all kinds of castles with it - but only castles. With my LEGOs I could build whatever I wanted to: castles, fire engines, space ships, boats, and so on.

In the software world, Playmobile would be reuse by inheritance and LEGO reuse by composition.

Reusing code by inheritance assumes that all future use cases will fit into a specific mold. In my experience this is rarely the case and if you find yourself making changes to your base class in order to support a requirement in a subclass, you are in trouble. If this happens, you probably did not have the correct level of abstraction in your base class (google the Single Level of Abstraction principle for more details).

If you instead go for reuse by composition, you build reusable building blocks that can be combined and used as needed. This is often a far more extendable and future proof approach than inheritance and still allows you to reuse code and not repeat yourself.

Getting the reuse approach right is especially important if you are building a platform or a framework. And if you are doing that, you should ask yourself if you actually need to do that or if you are accidentally over-engineering (been there, done that).

Using Value Objects as Aggregate Identifiers with Hibernate

Petter Holmström — Wed, 28 Apr 2021 05:33:21 +0000

In Tactical Domain-Driven Design, we learned that that we should refer to other aggregates by ID and use value objects to distinguish between different aggregate types (second aggregate design guideline).

This is perfectly possible to do with JPA and Hibernate, but requires some additional work as it goes against the design principles of JPA where you should not have to care about the IDs at all and just work with your entity objects directly. Let's have a look at how. We will be building on the code and principles laid out in my posts about value objects and aggregates so please read those first if you haven't already.

If you are using another JPA implementation than Hibernate, you have to check that implementation's documentation for how to create custom types.

Attribute Converters Won't Do

The first thought may be to use a simple value object and an attribute converter. Unfortunately this is not possible as JPA does not support using attribute converters for @Id fields. You can make a compromise and use "raw" IDs for your @Id fields and simple value objects to refer to them from other aggregates, but I do not personally like this approach as you have to move back and forth between the value objects and their wrapped raw IDs, making it more difficult to write queries. A better, more consistent approach is to create custom Hibernate types.

Creating a Custom Hibernate Type

When you create custom Hibernate types for your ID value objects, they become available for use inside your entire persistence context without any additional annotations anywhere. This involves the following steps:

Decide what kind of raw ID type you are going to use inside your value object: UUID, String, or Long
Create a type descriptor for your value object. This descriptor knows how to convert another value into an instance of your value object (wrap) and vice versa (unwrap).
Create a custom type that ties together your type descriptor with the JDBC column type you want to use for your ID.
Register your custom type with Hibernate.

Let's have a look at a code example to better illustrate this. We are going to create a value object ID called CustomerId that wraps a UUID. The value object looks like this:

package foo.bar.domain.model;

// Imports omitted

public class CustomerId implements ValueObject, Serializable { // <1>

    private final UUID uuid;

    public CustomerId(@NotNull UUID uuid) {
        this.uuid = Objects.requireNonNull(uuid);
    }

    public @NotNull UUID unwrap() { // <2>
        return uuid;
    }

    // Implementation of equals() and hashCode() omitted.
}

You have to implement the Serializable interface because Persistable assumes the ID type is persistable. I sometimes create a new marker interface called DomainObjectId that extends ValueObject and Serializable.
You need a way of getting the underlying UUID when you implement the type descriptor.

Next, we will create the type descriptor. I typically place this in a subpackage called .hibernate to keep the domain model itself nice and clean.

package foo.bar.domain.model.hibernate;

// Imports omitted

public class CustomerIdTypeDescriptor extends AbstractTypeDescriptor<CustomerId> { // <1>

    public CustomerIdTypeDescriptor() {
        super(CustomerId.class);
    }

    @Override
    public String toString(CustomerId value) { // <2>
        return UUIDTypeDescriptor.ToStringTransformer.INSTANCE.transform(value.unwrap()); 
    }

    @Override
    public ID fromString(String string) { // <3>
        return new CustomerId(UUIDTypeDescriptor.ToStringTransformer.INSTANCE.parse(string)); 
    }

    @Override
    @SuppressWarnings("unchecked")
    public <X> X unwrap(CustomerId value, Class<X> type, WrapperOptions options) { // <4>
        if (value == null) {
            return null;
        }
        if (getJavaType().isAssignableFrom(type)) {
            return (X) value;
        }
        if (UUID.class.isAssignableFrom(type)) {
            return (X) UUIDTypeDescriptor.PassThroughTransformer.INSTANCE.transform(value.unwrap());
        }
        if (String.class.isAssignableFrom(type)) {
            return (X) UUIDTypeDescriptor.ToStringTransformer.INSTANCE.transform(value.unwrap());
        }
        if (byte[].class.isAssignableFrom(type)) {
            return (X) UUIDTypeDescriptor.ToBytesTransformer.INSTANCE.transform(value.unwrap());
        }
        throw unknownUnwrap(type);
    }

    @Override
    public <X> CustomerId wrap(X value, WrapperOptions options) { // <5>
        if (value == null) {
            return null;
        }
        if (getJavaType().isInstance(value)) {
            return getJavaType().cast(value);
        }
        if (value instanceof UUID) {
            return new CustomerId(UUIDTypeDescriptor.PassThroughTransformer.INSTANCE.parse(value));
        }
        if (value instanceof String) {
            return new CustomerId(UUIDTypeDescriptor.ToStringTransformer.INSTANCE.parse(value));
        }
        if (value instanceof byte[]) {
            return new CustomerId(UUIDTypeDescriptor.ToBytesTransformer.INSTANCE.parse(value));
        }
        throw unknownWrap(value.getClass());
    }

    public static final CustomerIdTypeDescriptor INSTANCE = new CustomerIdTypeDescriptor(); // <6>
}

AbstractTypeDescriptor is a Hibernate base class that resides in the org.hibernate.type.descriptor.java package.
This method converts our value object to a string. We use a helper class from Hibernate's built-in UUIDTypeDescriptor (also from the org.hibernate.type.descriptor.java package) to perform the conversion.
This method constructs a value object from a string. Again, we use a helper class from UUIDTypeDescriptor.
This method converts a value object into a UUID, a string or a byte array. Again, we use helper classes from UUIDTypeDescriptor.
This method converts a UUID, a string or a byte array into a value object. The helper classes are used here as well.
We can access this type descriptor as a singleton since it does not contain any changeable state.

So far we have only dealt with Java types. Now it is time to bring SQL and JDBC into the mix and create our custom type:

package foo.bar.domain.model.hibernate;

// Imports omitted

public class CustomerIdType extends AbstractSingleColumnStandardBasicType<CustomerId> // <1>
    implements ResultSetIdentifierConsumer { // <2>

    public CustomerIdType() {
        super(BinaryTypeDescriptor.INSTANCE, CustomerIdTypeDescriptor.INSTANCE); // <3>
    }

    @Override
    public Serializable consumeIdentifier(ResultSet resultSet) {
        try {
            var id = resultSet.getBytes(1); // <4>
            return getJavaTypeDescriptor().wrap(id, null); // <5>
        } catch (SQLException ex) {
            throw new IllegalStateException("Could not extract ID from ResultSet", ex);
        }
    }

    @Override
    public String getName() {
        return getJavaTypeDescriptor().getJavaType().getSimpleName(); // <6>
    }
}

AbstractSingleColumnStandardBasicType is a Hibernate base class that resides in the org.hibernate.type package.
In order for the custom type to work properly in @Id fields, we have to implement this extra interface from the org.hibernate.id package.
Here we pass in the SQL type descriptor (in this case binary as we are going to store the UUID in a 16 byte binary column) and our Java type descriptor.
Here, we retrieve the ID from a JDBC result set as a byte array...
... and convert it to a CustomerId using our Java type descriptor.
A custom type needs a name so we use the name of the Java Type.

Finally, we just have to register our new type with Hibernate. We will do this inside a package-info.java file that resides in the same package as our CustomerId class:

@TypeDef(defaultForType = CustomerId.class, typeClass = CustomerIdType.class) // <1>
package foo.bar.domain.model;

import org.hibernate.annotations.TypeDef; // <2>
import foo.bar.domain.model.hibernate.CustomerIdType;

This Hibernate annotation tells Hibernate to use CustomerIdType whenever it encounters a CustomerId.
Note that the imports are coming after the annotations in a package-info.java file and not before as they do in a class file.

Phew! Now we can use CustomerId both to identify Customer aggregates and to refer to them from other aggregates. Please keep in mind, though, that if you let Hibernate generate your SQL schema for you and you use IDs to refer to aggregates instead of @ManyToOne associations, Hibernate will not create foreign key constraints. You will have to do that yourself, for example using Flyway.

If you have many different ID value object types, you will want to create abstract base classes for your type descriptors and custom types to avoid having to repeat yourself. I'm going to leave this as an exercise to the reader.

But wait, haven't we forgotten something? How are we actually going to generate new CustomerID instances when we persist newly created Customer aggregate roots? Let's find out.

Generating Value Object IDs

Once you have your ID value objects and custom types in place, you need a way of generating new IDs. You can create your IDs and assign them manually before persisting your entities (this is really easy if you use UUIDs) or you can configure Hibernate to automatically generate IDs for you when they are needed. The latter approach is more difficult to set up but easier to work with once it is done so let's have a look at that.

Refactoring Your Base Classes

JPA has support for different ID generators. If you look at the @GeneratedValue annotation, you can specify the name of the generator to use. Here we run into the first caveat. If you declare your ID field inside a mapped superclass (such as AbstractPersistable), there is no way for you to override the @GeneratedValue annotation for that field. In other words, you are stuck using the same ID generator for all of your aggregate roots and entities that extend this base class. If you find yourself in a situation like this, you have to remove your ID field from the base class and have every aggregate root and entity declare its own ID field.

Thus, the BaseEntity class (we originally defined this class here) changes to something like this:

@MappedSuperclass
public abstract class BaseEntity<Id extends Serializable> implements Persistable<Id> { // <1>

    @Version
    private Long version;

    @Override
    @Transient 
    public abstract @Nullable ID getId(); // <2>

    @Override
    @Transient 
    public boolean isNew() { // <3>
        return getId() == null;
    }

    public @NotNull Optional<Long> getVersion() {
        return Optional.ofNullable(version);
    }

    protected void setVersion(@Nullable version) {
        this.version = version;
    }

    @Override
    public String toString() { // <4>
        return String.format("%s{id=%s}", getClass().getSimpleName(), getId());
    }

    @Override
    public boolean equals(Object obj) { // <5>
        if (null == obj) {
            return false;
        }
        if (this == obj) {
            return true;
        }
        if (!getClass().equals(ProxyUtils.getUserClass(obj))) { // <6>
            return false;
        }

        var that = (BaseEntity<?>) obj;
        var id = getId();
        return id != null && id.equals(that.getId());
    }

    @Override
    public int hashCode() { // <7>
        var id = getId();
        return id == null ? super.hashCode() : id.hashCode();
    }
}

We no longer extend AbstractPersistable but we do implement the Persistable interface.
This method comes from the Persistable interface and will have to be implemented by the subclasses.
This method also comes from the Persistable interface.
Since we no longer extend AbstractPersistable we have to override toString ourselves to return something useful. I sometimes also include the object identity hash code to make it clear whether we are dealing with different instances of the same entity.
We also have to override equals. Remember that two entities of the same type with the same ID are considered the same entity.
ProxyUtils is a Spring utility class that is useful for cases where the JPA implementation has made bytecode changes to the entity class, resulting in getClass() not necessarily returning what you think it may return.
Since we have overridden equals, we also have to override hashCode in the same manner.

Now when we have made the necessary changes to BaseEntity, we can add the ID field to our aggregate root:

@Entity
public class Customer extends BaseAggregateRoot<CustomerId> { // <1>

    public static final String ID_GENERATOR_NAME = "customer-id-generator"; // <2>

    @Id
    @GeneratedValue(generator = ID_GENERATOR_NAME) // <3>
    private CustomerId id;

    @Override
    public @Nullable CustomerId getId() { // <4>
        return id;
    }
}

We extend BaseAggregateRoot, which in turn extends our refactored BaseEntity class.
We declare the name of the ID generator in a constant. We will be using this when we register our custom generator with Hibernate.
Now we are no longer stuck with whatever annotation was used in the mapped superclass.
We implement the abstract getId() method from Persistable.

Implementing the ID Generator

Next, we have to implement our custom ID generator. Since we are using UUIDs this is going to be almost trivial. For other ID generation strategies, I suggest you pick an existing Hibernate generator and build on that (start looking here). The ID generator will look something like this:

package foo.bar.domain.model.hibernate;

public class CustomerIdGenerator implements IdentifierGenerator { // <1>

    public static final String STRATEGY = "foo.bar.domain.model.hibernate.CustomerIdGenerator"; // <2>

    @Override
    public Serializable generate(SharedSessionContractImplementor session, Object object) throws HibernateException {
        return new CustomerId(UUID.randomUUID()); // <3>
    }
}

IdentifierGenerator is an interface that resides in the org.hibernate.id package.
Because of how new generators are registered with Hibernate, we need the full name of the class as a string. We store it in a constant to make future refactoring easier - and minimize the risk of bugs caused by typos.
In this example we use UUID.randomUUID() to create new UUIDs. Please note that you have access to the Hibernate session if you need to do something more advanced, like retrieving a numeric value from a database sequence.

Finally, we have to register our new ID generator with Hibernate. Like with the custom type, this happens in package-info.java, which becomes:

@TypeDef(defaultForType = CustomerId.class, typeClass = CustomerIdType.class)
@GenericGenerator(name = Customer.ID_GENERATOR_NAME, strategy = CustomerIdGenerator.STRATEGY) // <1>
package foo.bar.domain.model;

import org.hibernate.annotations.GenericGenerator;
import org.hibernate.annotations.TypeDef;
import foo.bar.domain.model.hibernate.CustomerIdType;
import foo.bar.domain.model.hibernate.CustomerIdGenerator;

This annotation tells Hibernate to use CustomerIdGenerator whenever it encounters a generator named customer-id-generator.

Double-phew! Now our domain model should just work as we expect it to, with auto-generated value objects as IDs.

A Note on Composite Keys

Before we leave the subject of IDs, I just want to mention one thing. By moving the ID field from the mapped superclass (BaseEntity) to the concrete entity class (Customer in the example above), we also opened up the possibility to use composite keys in our entities (either using @EmbeddedId or @IdClass). You may for example have a situation where the composite key consists of the ID of another aggregate root and an enum constant.

Building Repositories with Spring Data

Petter Holmström — Tue, 27 Apr 2021 06:38:00 +0000

Yesterday, we learned how to build aggregates with Spring Data. Now when we have our aggregates in place, we need to build repositories for storing and retrieving them.

Building repositories with Spring Data is very easy. All you need to do is declare your repository interface and have it extend the Spring Data interface JpaRepository. However, this also makes it easy to accidentally create repositories for local entities (which may happen if you have developers unfamiliar with DDD but familiar with JPA). Therefore, I always declare my own base repository interface like this:

@NoRepositoryBean // <1>
public interface BaseRepository<Aggregate extends BaseAggregateRoot<ID>, ID extends Serializable> // <2>
        extends JpaRepository<Aggregate, ID>,  // <3>
                JpaSpecificationExecutor<Aggregate> { // <4>

    default @NotNull Aggregate getById(@NotNull ID id) { // <5>
        return findById(id).orElseThrow(() -> new EmptyResultDataAccessException(1));
    }
}

This annotation tells Spring Data not to try to instantiate this interface directly.
We limit the entities served by the repository to aggregate roots only.
We extend JpaRepository.
I personally prefer specifications to query methods. We'll return to why in a little bit.
The built in findById method returns an Optional. In many cases when you fetch an aggregate by its ID you assume it will exist. Having to deal with the Optional every single time is a waste of time and code so you might as well do that in the repository directly.

With this base interface in place, the repository for a Customer aggregate root could look something like this:

public interface CustomerRepository extends BaseRepository<Customer, CustomerId> {
    // No need for additional methods
}

This is all you need for retrieving and saving aggregates. Now let us have a look at how to implement queries.

Query Methods and Specifications

The most straightforward way to create queries in Spring Data is by defining carefully named findBy-methods (if you are not familiar with this then check the Spring Data reference documentation).

I find these useful for simple queries that look for aggregates based on one or two keys only; for example, in a PersonRepository you could have a method called findBySocialSecurityNumber and in a CustomerRepository you could have a method called findByCustomerNumber. However, for more advanced or complex queries I try to avoid using findBy-methods.

I do this mainly for two reasons: First, the method names tend to become very long and pollute the code wherever they are used.

Second, very specific needs from application services may sneak into the repository and after a while your repositories are full of query methods that do almost the same thing but with small variations. I want to keep my domain model as clean as possible. Instead, I like to construct my queries using specifications.

When you query by specification, you start by building a specification object that describes the result you want from your query. Specification objects can also be combined using the logical operators and and or. For maximum flexibility, I try to keep my specifications as small as possible. If needed, I create composite specifications for commonly used specification combinations.

Spring Data has built in support for specifications. To create a specification, you have to implement the Specification interface. This interface relies on the JPA Criteria API so you need to familiarize yourself with that if you have not used it before (here is Hibernate's documentation about it).

The Specification interface contains a single method that you have to implement. It produces a JPA Criteria predicate and takes as input all the necessary objects you need to create said predicate.

The easiest way of creating specifications is by making a specification factory. This is best illustrated with an example:

public class CustomerSpecifications {

    public @NotNull Specification<Customer> byName(@NotNull String name) {
        return (root, query, criteriaBuilder) -> criteriaBuilder.like( // <1>
            root.get(Customer_.name), // <2>
            name
        );
    }

    public @NotNull Specification<Customer> byLastInvoiceDateAfter(@NotNull LocalDate date) {
        return (root, query, criteriaBuilder) -> criteriaBuilder.greaterThan(root.get(Customer_.lastInvoiceDate), date);
    }

    public @NotNull Specification<Customer> byLastInvoiceDateBefore(@NotNull LocalDate date) {
        return (root, query, criteriaBuilder) -> criteriaBuilder.lessThan(root.get(Customer_.lastInvoiceDate), date);
    }

    public @NotNull Specification<Customer> activeOnly() {
        return (root, query, criteriaBuilder) -> criteriaBuilder.isTrue(root.get(Customer_.active));
    }
}

Here I'm just doing a simple like query, but in a real-world specification you would probably want to be more thorough, paying attention to wildcards, case matching and so on.
Customer_ is a metamodel class generated by the JPA implementation (such as Hibernate).

You would then use the specifications in the following way:

public class CustomerService {

    private final CustomerRepository repository;
    private final CustomerSpecifications specifications;

    public CustomerService(CustomerRepository repository, CustomerSpecifications specifications) {
        this.repository = repository;
        this.specifications = specifications;
    }

    public Page<Customer> findActiveCustomersByName(String name, Pageable pageable) { // <1>
        return repository.findAll(
            specifications.byName(name).and(specifications.activeOnly()), // <2>
            pageable
        );
    }
}

Never ever write methods that return a result set without an upper bound (at least in production code). Either use pagination (like I do here) or use a finite and reasonable limit on how many records the query can return.
Two specifications are here combined together using the and operator.

A Note About Repositories and QueryDSL

Spring Data also supports QueryDSL. In this case you are not working with specifications but with QueryDSL predicates directly. The design principle is pretty much the same so if you feel more comfortable with QueryDSL than with the JPA Criteria API there is no reason for you to change.

Specifications and Testing

There is one noticeable drawback with using specifications in favor of query methods and that has to do with unit testing. Since the specifications are using the JPA Criteria API under the hood, there is no easy way of making assertions on the contents of a given Criteria object without constructing and analysing its JPA predicate - a nontrivial process.

However, there are ways around this. The most obvious way is to just ignore checking the incoming specifications when mocking repositories in your unit tests and use separate integration tests to test your specifications, for example with an in-memory H2 database. In many cases this may be just good enough.

There is also another way that avoids the use of integration tests but requires some extra work upfront. If you take a closer look at the specifications factory, you will see that the factory methods are not static but instance methods and the class itself is not final. This means that you can mock or stub the entire factory. Also, since the factory methods only return objects that implement the Specification interface, you can mock or stub that interface as well. This means that as long as you avoid using the static helper methods on the Specification interface (which use the JPA Criteria API), you can build a mock specification factory that returns mock specifications that can then be analyzed and used as the basis for test assertions. Unfortunately this post is not the right place to dig deeper into this so I'll just leave it as an exercise to the reader.

In the next post, we are going to look at how to use value objects as aggregate IDs. Stay tuned!

Building Aggregates with Spring Data

Petter Holmström — Mon, 26 Apr 2021 11:00:25 +0000

In my last post we learned how to build value objects that an be persisted with JPA. Now it is time to move on to the objects that will actually contain your value objects: entities and aggregates.

JPA has its own @Entity concept, but it is far less restrictive than the entity concept from DDD. This is both an advantage and a disadvantage. The advantage is that it is quite easy to implement entities and aggregates with JPA. The disadvantage is that is is equally easy to do things that is not allowed in DDD. This may be especially problematic if you are working with developers that have used JPA extensively before but who are new to DDD.

Whereas value objects just implemented an empty marker interface, entities and aggregate roots will need more extensive base classes. Getting your base classes right from the start is important as it will be quite difficult to change them later, especially if your domain model has grown big. To help us with this task, we are going to use Spring Data.

Spring Data provides some base classes out of the box that you can use if you like, so let's start by looking at them.

Using `Persistable`, `AbstractPersistable` and `AbstractAggregateRoot`

Spring Data provides an interface out-of-the-box called Persistable. This interface has two methods, one for getting the ID of the entity and another for checking whether the entity is new or persisted. If an entity implements this interface, Spring Data will use it to decide whether to call persist (new entities) or merge (persisted entities) when saving it. You are, however, not required to implement this interface. Spring Data can also use the optimistic locking version to determine whether the entity is new or not: if there is a version, it is persisted; if there is none, it is new. You need to be aware of this when you decide how you are going to generate your entity IDs.

Spring Data also provides an abstract base class that implements the Persistable interface: AbstractPersistable. It is a generic class that takes the type of the ID as its single generic parameter. The ID field is annotated with @GeneratedValue which means that a JPA implementation such as Hibernate will try to auto-generate the ID when the entity is first persisted. The class considers entities with a non-null ID as persisted and entities with null IDs as new. Finally, it overrides equals and hashCode so that only the class and the ID are taken into account when checking for equality. This is in line with DDD - two entities are considered the same if they have the same ID.

If you are fine with using ordinary Java types (such as Long or UUID) for your entity IDs and letting your JPA implementation generate them for you when the entity is first persisted, then this base class is an excellent starting point for your entities and aggregate roots. But wait, there is more.

Spring Data also provides an abstract base class called AbstractAggregateRoot. This is a class that - you guessed it - is designed to be extended by aggregate roots. However, it does not extend AbstractPersistable nor does it implement the Persistable interface. Then why would you want to use this class? Well, it provides methods that allow your aggregate to register domain events that are then published once the entity is saved. This is really useful and we will return to this subject in a later post. Also, there are some benefits to not declaring the ID field in the base class and having your aggregate roots declare their own IDs. We will also return to this subject in a later post.

In practice, you want your aggregate roots to be Persistable and so you end up implementing either the methods of AbstractAggregteRoot or AbstractPersistable in your own base class. Let's have a look at how to do that next.

Building Your Own Base Classes

In virtually all projects that I work on, both at work and in private, I start by creating my own base classes. Most of my domain models are build from aggregate roots and value objects; I rarely use so called local entities (entities that belong to an aggregate but are not roots).

I often start with a base class called BaseEntity and it looks like this:

@MappedSuperclass // <1>
public abstract class BaseEntity<Id extends Serializable> extends AbstractPersistable<Id> { // <2>

    @Version // <3>
    private Long version;

    public @NotNull Optional<Long> getVersion() {
        return Optional.ofNullable(version);
    }

    protected void setVersion(@Nullable Long version) { // <4>
        this.version = version;
    }
}

Even though the class is named BaseEntity, it is not a JPA @Entity but a @MappedSuperclass.
The Serializable bound comes directly from AbstractPersistable.
I use optimistic locking for all my entities. We will return to this later in this post.
There are very few, if any, situations where you want to set the optimistic locking version manually. However, to be on the safe side, I provide a protected method that makes this possible. I think most Java developers with some years under their belts have experienced situations where they would really have needed to set an attribute or call a method in a super class only to find that it was private.

Once I have the BaseEntity class in place, I move on to BaseAggregateRoot. This is essentially a copy of Spring Data's AbstractAggregateRoot, but it extends BaseEntity:

@MappedSuperclass // <1>
public abstract class BaseAggregateRoot<Id extends Serializable> extends BaseEntity<Id> {

    private final @Transient List<Object> domainEvents = new ArrayList<>(); // <2>

    protected void registerEvent(@NotNull Object event) { // <3>
        domainEvents.add(Objects.requireNonNull(event));
    }

    @AfterDomainEventPublication // <4>
    protected void clearDomainEvents() {
        this.domainEvents.clear();
    }

    @DomainEvents // <5>
    protected Collection<Object> domainEvents() {
        return Collections.unmodifiableList(domainEvents);
    }
}

This base class is also a @MappedSuperclass.
This list will contain all domain events we want to publish when the aggregate is saved. It is @Transient because we don't want to store them in the database.
When you want to publish a domain event from within your aggregate, you register it using this protected method. We will have a closer look at this later in this article.
This is a Spring Data annotation. Spring Data will call this method after the domain events have been published.
This is also a Spring Data annotation. Spring Data will call this method to get the domain events to publish.

Like I said, I rarely use local entities. However, when that need arises, I often create a BaseLocalEntity class that extends BaseEntity but does not provide any additional functionality (except, maybe a reference to the aggregate root that owns it). I will leave this as an exercise to the reader.

Optimistic Locking

We already added a @Version field for optimistic locking to BaseEntity but we did not yet discuss why. In Tactical Domain-DrivenDesign, the fourth guideline for aggregate design was to use optimistic locking. But why did we add the @Version field to BaseEntity and not to BaseAggregateRoot? After all, isn't it the aggregate root that is responsible for maintaining the integrity of the aggregate at all times?

The answer to this question is yes, but here, the underlying persistence technology (JPA and its implementtions) is again sneaking into our domain design. Let's assume we are using Hibernate as our JPA implementation.

Hibernate does not know what an aggregate root is - it only deals with entities and embeddables. Hibernate also keeps track of which entities have actually been changed and only flushes those changes to the database. In practice this means that even though you explicitly ask Hibernate to save an entity, no changes may actually be written to the database and the optimistic version number may remain the same.

As long as you only deal with aggregate roots and value objects, this is not a problem. For Hibernate, a change to an embeddable is always a change to its owning entity and so the optimistic version of the entity - in this case the aggregate root - will be incremented as expected. However, things change as soon as you add local entities to the mix. For example:

@Entity
public class Invoice extends BaseAggregateRoot<InvoiceId> { // <1>

    @OneToMany(cascade = CascadeType.ALL, orphanRemoval = true)
    private Set<InvoiceItem> items; // <2>

    // The rest of the methods and fields are omitted
}

Invoice is the aggregate root and so it extends the BaseAggregateRoot class.
InvoiceItem is a local entity and so it either extends the BaseEntity class or a BaseLocalEntity class depending on your base class hierarchy. The implementation of this class is not important so we are leaving it out, but please note the cascading options in the @OneToMany annotation.

A local entity is owned by its aggregate root and so is persisted through cascading. However, if a change has been made only to the local entity and not to the aggregate root, saving the aggregate root will only result in the local entity being flushed to the database. In the example above, if we made a change only to an invoice item and then saved the entire invoice, the invoice version number would remain unchanged. If another user had made changes to the same item just before we saved our invoice, we would silently overwrite the other user's changes with ours.

By adding the optimistic locking version field to BaseEntity, we protect against situations like this. Both the aggregate root and the local entities will be optimistically locked and it will not be possible to accidentally overwrite somebody else's changes.

In the next post, we are going to look at how to build repositories with Spring Data.

DEV Community: Petter Holmström

Thoughts on AI and Software Design Patterns

How I think about Vaadin application architecture today

Well, It Depends

Backend or Frontend?

Starting in the Presentation Layer

Looking at the Application Services

Transactions

Security

Layers vs. Components

Naming is Difficult

Next Steps

A Potentially Expensive Mistake

Eventual Consistency Through Scheduled Jobs

The General Idea

Make Your Jobs Accept All or Some Inputs

Example

Decouple the Job and the Triggering of the Job

Example

Make Your Jobs Idempotent

Example

Avoid Simultaneous Executions of the Same Job

Example

Use Threads Wisely

Example

Use Upper Limits in Your Queries

Schedule Jobs Wisely

Architectural Considerations

Single Bounded Context

Multiple Bounded Contexts

Customer-Supplier and Conformist

Anticorruption Layer

Middleware

Pros and Cons

Handling Domain Events with Spring

Handling Events with @EventListener

Introducing @TransactionalEventListener

Publishing Domain Events with Spring Data

Event Pitfalls (and How to Avoid Them)

Using events as commands

Not isolating consumers from producers

Assuming all event consumers will always succeed

Assuming all events will occur exactly once

Assuming all event streams will be calm and even

Knee-deep in Spring Boot, Transactional Event Listeners and CGLIB proxies

Java Pitfalls (and How to Avoid Them)

Validate and Sanitise Your Input Data

The Difference Between Validation and Sanitation

What to Validate

When and Where to Validate

Dealing With Bad Legacy Data

Design By Contract

NPEs Can Be Avoided, So Avoid Them!

If Possible: Reuse by Composition, Not by Inheritance

Using Value Objects as Aggregate Identifiers with Hibernate

Attribute Converters Won't Do

Creating a Custom Hibernate Type

Generating Value Object IDs

Refactoring Your Base Classes

Implementing the ID Generator

A Note on Composite Keys

Building Repositories with Spring Data

Query Methods and Specifications

A Note About Repositories and QueryDSL

Specifications and Testing

Building Aggregates with Spring Data

Using Persistable, AbstractPersistable and AbstractAggregateRoot

Building Your Own Base Classes

Optimistic Locking

Handling Events with `@EventListener`

Introducing `@TransactionalEventListener`

Using `Persistable`, `AbstractPersistable` and `AbstractAggregateRoot`