sequenceDiagram
    actor C as Caller
    participant P as Presentation
    participant A as Application
    participant D as Data
    A -->> P: BusinessException
    P ->> C: 400 
    D -->> P: TechnicalException  
    P ->> C: 500

When needed, some projects added an Error code as an enum in order to perform more complex handling. For most applications, it’s more than enough.

I’m currently working on an application with a richer business and decided to formalise it into an additional domain layer.

This ended up being a DDD inspired application with an hexagonal architecture:

The typical runtime exceptions handled by the presentation layer still worked well for interrupting the flow in the application and infrastructure layers, but they felt less appropriate at the boundary with the new domain layer. That made me wonder whether expected business failures should really follow the same pattern.

Requirements

Going back to the drawing board for something as fundamental as failure handling is an interesting exercise. It’s not something I’d ever really questioned before.

I had already worked on modelling exceptions so they could carry additional information useful to the front-end, but the underlying pattern was still the same: something fails, an exception interrupts the flow, and the presentation layer eventually turns it into a response.

This time felt different. A responsibility that traditionally belongs to a single layer in a three-tier application was now split across two. And neither had the full picture: the domain knew what failed, while its caller knew in which context that failure occurred.

The domain should report what failed, but not decide what that failure means

The domain cannot know if a failure is a critical exception or a simple business rejection. those are the consequences of the failure, they are not the failure itself. As an example, failing to build a Category in an application service is most likely due to an invalid input that needs to be reported back to the user while the same failure from the infrastructure layer means data corruption. the domain doesn’t know.

Since the service handling the domain should be able to handle failures appropriately, it needs to be clearly apparent in the contract

The caller must be aware that the operation it performed might result in failure

And more generally, failures as much as success should be part of the normal domain behaviour.

Any operation impacting the domain should result either in a success or a failure.

Expected business failures are part of the normal behaviour of the domain, not exceptional situations.

An additional property that I wanted to have is to allow for multiple business failures to be reported for a single operation.

The model must be able to represent all meaningful business failures produced by an operation.

Some domain operations may fail for more than one reason. The model should not force you to pick only one violation if several are meaningful.

Representation

So what should we use as the carrier for those failures?

The obvious first contender was using exceptions. It’s familiar and it works. I’m not for reinventing the wheel just for the sake of it.

Runtime exceptions were not an option as they are not visible in the contract. Checked exceptions on the other hand checked (pun intended) nearly all the boxes. Representing multiple failures feels a bit awkward but aside from that, it does the job.

It is worth asking though: are business failures really exceptional and if not, should they be treated as exceptions?

Another contender, one that I like a lot, is to explicitly model domain operations as returning a Result.

It aligns well with the idea that Any operation impacting the domain should result either in a success or a failure. and it explicitly tells the caller that the operation may fail by making failure part of the return contract. It also supports all of my requirements.

The only downside I found is that we don’t have control over the return type of a constructor. It’s not a major drawback though, it’s easy to turn the constructors private and hide them behind a factory method.

Both can do the job, but each comes with trade-offs.

One advantage checked exceptions have is that the compiler forces the caller to acknowledge them. A Result can simply be ignored. In practice I found that discipline, reviews and static analysis were enough, but it’s a trade-off worth acknowledging.

On the other side, catching an exception only to convert it into another one is heavy. It sure works, but it made me wonder: am I modelling the failure, or merely re-purposing exceptions to represent ordinary business outcomes?

If a business operation can normally end in either success or rejection, Result represents that reality better than an exception.

Overall, I went with the Result approach because I felt it aligned better with the spirit of my requirements but checked exceptions would have been a perfectly valid solution as well.

All things considered, the right responsibility split is much more important than the mechanism used to implement it.

Interpretation

Similarly to the domain not being able to select the right presentation-facing exception by itself, the application cannot infer it from the context alone.

Consider a productCreator.create operation :

productCreator.create(name, barcode, actor)

it could fail because the product barcode is invalid, because the actor isn’t authorised to create a product, or because the barcode is already in use. Although they are all business failures, they lead to different outcomes: BadRequest, Forbidden or Conflict.

The application service must be able to determine the appropriate action based on both the context and the failure it received.

One option is to base the application’s decision on individual business failures. This provides the maximum amount of semantic information, but it also tightly couples the application to the domain’s business rules.

Another option is to expose a broader classification of business failures instead of the individual failures themselves. This can be achieved by introducing failure categories that group together business failures sharing the same broad semantics.

Most of the time, the application doesn’t need to know whether the barcode or the product name is invalid, only that it is dealing with a VALIDATION failure. Broadly speaking, it only needs to know what kind of failure it received in order to make an informed decision, not the specific business rule that was violated.

And what if the application needs to react to a specific business failure? Working with typed failures still allows it to base its decision on more detailed information when, and only when, it needs it.

The two approaches can be summarised as follows:

The application’s decision space is intentionally much smaller than the domain’s failure space: the domain should be free to grow new business rules without forcing the application to grow new decision logic.

Individual failures explain what happened; categories provide just enough information for the application to decide what to do.

But that alone is is not enough to determine the application’s response. The same business failure may have different meanings depending on how the situation arose and who is responsible for it..

During product creation, a VALIDATION failure is interpreted as a BadRequest because the invalid data originates from the caller.

sequenceDiagram
    participant C as Controller
    participant A as Application
    participant D as Domain

    C->>A: createProduct(request)

    A->>D: createProduct.create(request.barcode,...)

    alt Success
        D-->>A: Result.success()
    else Invalid barcode
        D-->>A: Result.failure: VALIDATION
		A-->>A: Wrong caller input
        A-->>C: BadRequestException
    end

By contrast, when validating an identity that was produced internally, the same VALIDATION failure indicates an application invariant has been violated and therefore results in an ApplicationException

sequenceDiagram
    participant P as Presentation
    participant A as Application
    participant D as Domain

    A->>D: Identity.of(actor.identity())

    alt Success
        D-->>A: Result.success()
    else Invalid identity
        D-->>A: Result.failure: VALIDATION
        A-->>A: Internal invariant violated
        A-->>P: ApplicationException
    end

Armed with both the context and the kind of failure it received, the application has all the information it needs to interpret the failure correctly.

Conclusion

I think I ended up in a comfortable place. The responsibility split between the different layers is coherent

• presentation produce caller facing HTTP Responses
• application determine what kind of exception to throw based on the orchestration context and the type of failures it encountered
• domain enforces business rules and inform on failures
• infrastructure throws only technical exceptions

The domain knows why something is invalid. The application knows whether that invalidity is expected but it needed some semantic information to make a decision. Introducing the failure categories neatly solved the tension between the application having to know too much (being aware of every expected failures in the context) or too little ( just getting a failure without knowing how to interpret it).

The value of categories is not only that they reduce coupling. It is that they let the application handle an exhaustive closed set of interpretations without knowing the open-ended set of business failures.

Regarding the failure carrier, once you’ve ruled out the objectively poor fit of run time exceptions, I don’t think the choice has much importance. At this point, the team’s experience and conventions become a perfectly valid tie-breaker. It’s somewhat ironic that I ended up comparing two approaches that are both less common today. Runtime exceptions have become the default in many Java applications, but they were the first option I ruled out because they didn’t satisfy my main requirement: making expected business failures part of the contract.

That’s probably why I’m so reliant on documentation to organise my thoughts: I need the visual support.

But, like most technically inclined people, I’m also (selectively!) extremely lazy. Maintaining documentation by hand is time-consuming, unsatisfactory and, most of the time, a lost battle.

So quite naturally, I developed an interest in living documentation. After all, it’s time spent doing what I like - playing with code - to obtain what I need: an easy-to-consume representation of knowledge that would otherwise remain scattered throughout the project.

I find the emergence of knowledge from raw data extremely satisfying.

In need of visual representations, I’ve looked at different options for diagram generation and eventually settled on Mermaid. It supports most of the diagram types I need, lets me focus on content instead of layout and is widely supported (Confluence, GitHub, GitLab, even this Jekyll site…).

It is also remarkably easy to generate. All you need is a StringBuilder and you are good to go.

That StringBuilder… Having to go back to the Mermaid documentation every time I needed to check the syntax for a diagram was a no-go for me.

I was in Java; I wanted a Java DSL. I prefer working with an abstraction that lets my IDE help me with completion and is less error-prone than handling raw strings everywhere.

Surprisingly, and really frustratingly, I couldn’t find one. Be it because living documentation isn’t widespread or because I’m lazier than most, apparently the DIY approach was the way to go.

So that’s what I did. I wrapped it in a thin DSL. Then I copied it, then I copied it, then… you get the idea.

Eventually, when I got fed up with the duplication, I extracted it into a small reusable library. At first, just for myself.

I intentionally kept the DSL close to Mermaid’s terminology. The goal wasn’t to invent another abstraction, only to avoid writing Mermaid by hand.

new FlowchartDiagram()
	.direction(LR)
    .addNode(node("P1").shape(classicNodeShape("Project 1", SQUARE_EDGES)))
    .addNode(node("P2").shape(classicNodeShape("Project 2", SQUARE_EDGES)))
    .addNode(node("P3").shape(classicNodeShape("Project 3", SQUARE_EDGES)))
    .addNode(node("DSL").shape(classicNodeShape("mermaid-java-dsl", SQUARE_EDGES)))
    
    .addLink("P1", "DSL")
    .addLink("P2", "DSL")
    .addLink("P3", "DSL");

flowchart LR
    P1[Project 1]
    P2[Project 2]
    P3[Project 3]
    DSL[mermaid-java-dsl]
    P1 --> DSL
    P2 --> DSL
    P3 --> DSL

But selective laziness struck again, this time in the opposite direction: Reusable code needs to be tested. So I turned the examples from the Mermaid documentation into tests. If the DSL could reproduce the documented diagrams, I could be reasonably confident it generated valid Mermaid. And of course, I had to cover all the examples… because.

That could have been the end of the story. My problem was solved, and the little library had been living its best life on my personal GitLab for quite a while. What a nice Happy Ending.

But I remembered my own frustration when I was looking for something similar and couldn’t find anything. So I figured I might as well open-source it.

It doesn’t implement every Mermaid diagram type, only the ones I actively use (Flowcharts and Class Diagrams for now). That said, those implementations cover all the examples from the Mermaid documentation, so they should be fairly complete.

It solved my problem.

If it happens to solve yours too, even better.

The code is on GitHub: https://github.com/lamzi-com/mermaid-java-dsl and if you’d like to give it a try, it’s available on Maven Central:

<dependency>
    <groupId>com.lamzi.doc</groupId>
    <artifactId>mermaid-java-dsl</artifactId>
</dependency>

It’s still undocumented, but the test cases are full of examples.

• classDiagram

• flowchartDiagram

One of the first principles we learn when studying OOP is: encapsulation is important. Nice one, I can agree with that.

I also learned: Java is an OOP language. Okay!

Then comes the reality of your first job: let’s write a DTO.

public class User{
	private String name; 
	
	public String getName(){
		return this.name; 
	} 
	
	public void setName(String name){
		this.name = name; 
	}
}  

• me: but with the getter and setter, the field is public. why not just make it public?
• senior: No, Encapsulation is important! The field must remain private
• me: but…
• senior: That’s the JavaBeans convention. That’s how it’s done in Java.

My first reaction was incomprehension: Why does the public modifier even exist for fields if it so strongly shouldn’t be used? And aren’t objects supposed to enforce their own state’s validity? How can they do it in this situation?

Why and How: The Convention That Became Law

Objects are supposed to encapsulate state and behaviour; but the reality of DTOs is that they have a different purpose: representing data.

Conceptually, they are a collection of properties; they are closer to a C struct than to a rich domain object.

struct user {
    char *name;
};

The problem is that, historically, Java had no way to express this concept. The language had primitives, enums and objects but nothing that explicitly meant “this type is just data.”

So how do you represent a complex data structure in a language whose primary abstraction is the object? As an object, of course!

As the Java ecosystem grew, frameworks and tools increasingly needed a standard way to discover and manipulate object properties. GUI builders, serializers, and later frameworks all faced the same challenge.

The JavaBeans specification answered that need by introducing a standardised property model based on getters and setters.

At the time, it was a pragmatic solution to a real problem.

The convention worked remarkably well… for the problem it was designed to solve: IDEs started generating getters and setters; frameworks understood them; teams stopped documenting or testing them because they were considered trivial boilerplate.

Over time, the convention escaped its original purpose. Eventually, writing a stateful object without getters and setters started looking wrong. The convention had become the norm.

It no longer felt like a convention, it simply became how Java is written.

The Social Contract

And because it became how Java is written, developers started building expectations. Eventually, those expectations formed a social contract, leading developers to infer things that the type system never promises.

Here are a few examples of situations I encountered with my colleagues when I started my Java journey, before I understood how deeply those conventions had shaped developers’ expectations.

In a new application, I prevented a list from being modified via the getter so we had to use a designated method for adding items. My reasoning was that a getter was meant to access the information, not to modify it, so it felt cleaner that way:

public List<Item> getItems() {
    return Collections.unmodifiableList(items);
}

public void addItem(Item item){
    this.items.add(item);
}

My colleague was outraged! Whether the design itself was better or not was almost beside the point. The issue was that I had broken his expectations.

To him, getItems() meant gaining access to the items field.

To me, it meant asking the object for its items.

Those are not necessarily the same thing.

The social contract demands that a getter exposes a backing field. Diverging from that behaviour creates confusion.

Looking back, we might have been able to compromise by skipping the getter naming convention like we did with another colleague where I proposed returning an Optional from a getter-like method as the field was known to sometimes (often) be null:

public class Person{
    private Address address; 
	... 
	Optional<Address> getAddress(){...}
}

The colleague rejected it, really uneasy, because “the return type is not correct”. The expectation is that getAddress should return an Address.

In this case, he agreed for the need and we settled on an alternative name:

Optional<Address> findAddress(){...}

But compromising was only possible because he didn’t feel that the method was a getter anymore.

Trying to write an accessor that doesn’t follow the get/set convention was also often poorly received.
For example, person.name() instead of person.getName() was a no go in my team because, “That’s not how it’s done in java”.

Good conventions reduce cognitive load but they also shape our mental model: at some point, methods stopped being methods.

When people see person.getName(); they don’t see a method to retrieve a person’s name, they see the name property.

Which implies a set of expectations:

For getters, that they return a backing field in O(1) time, that they won’t perform any kind of transformation, validation nor side effects and often, that they are paired with a setter.

For setters, that they would perform simple assignment with no side effect, computation, normalisation nor any validation. Objects.requireNonNull(...) is sometimes tolerated but more often than not, any kind of validation is perceived as a betrayal.

Ironically, most of those expectations were never part of Java or even the JavaBeans specification. They emerged organically over decades of shared practice.

And that wouldn’t have been an issue if it had remained confined to data structure use cases only.

But it didn’t.

When you have a hammer, everything is a nail.

Habits are powerful. Once a solution becomes familiar, we naturally start applying it in places where it wasn’t originally intended.

The hidden costs

Those expectations solved a real problem, but once they became pervasive, they also introduced some subtle costs.

The illusion of encapsulation

First and foremost, what does encapsulation mean to you? While it is one of the fundamental principles of object-oriented programming, I’m not sure it means the same thing to everyone.

My understanding - and the one I’ll be using in this section - is the following:

• allowing an object to keep control of its own state and enforce its invariants
• hiding an object’s internal representation behind its public interface

While using methods to access an object’s state technically preserves the encapsulation, in practice, following the expectations surrounding the JavaBeans conventions can undermine many of its benefits.

Benefit #1: Maintaining invariants

Because the field is private, we think the object is in control. Yet the very expectations encourage us to treat the getter and setter as direct field access.

See the following setter example.

    /**
     * Replace the current age with a new valid one
     *
     * @param age the new age of the person (does it even make sense to externally change the age? hmm... )
     * @throws NullPointerException if age is null
     * @throws BusinessException    if not 0 <= age <= MAXIMUM_AGE
     */
    public void setAge(Integer age) {
        Objects.requireNonNull(age);
        if (age < 0) {
            throw new BusinessException("Age must be strictly positive");
        }
        if (age > MAXIMUM_AGE) {
            throw new BusinessException("Nobody can be that old");
        }
        this.age = age;
    }

Have you seen many setters like this? The reality of this method is that most Java developers - including myself - would call it something like changeAge(...) and not consider it a setter.

As soon as we start using the control that encapsulation gives us, the method stops feeling like a setter. It now has to be documented and tested because callers can no longer infer its behaviour from the naming convention alone.

But uncontrolled mutation jeopardises every other method on the object.

Once the object can no longer assume that age is valid, every method operating on it becomes more defensive… or more fragile

    public boolean canDrinkAlcohol(){
        return this.age >= AGE_LIMIT; 
    }

Benefit #2: Information hiding

Here again, one of the benefits of encapsulation is that it allows an object to hide its internal structure.

In theory, this would let us rename - or remove - a field without impacting the public API.

In practice, however, getAge() doesn’t just expose a value. It also creates the expectation that a private field named age exists behind it.

Renaming that field now either changes the public API or creates a discrepancy between the implementation and what future developers expect to find.

Information hiding isn’t only about what the language exposes. It’s also about what developers infer.

So what information are we actually hiding?

Null creep

Once objects are no longer expected to enforce invariants, there is little preventing them from existing in partially populated states. At that point, reusing the same representation across several use cases becomes an attractive way to reduce duplication.

See the Product DTO here:

@Data
public class Product{
    private Long id;
    private String name;
    private String description; 
    private List<Category> categories; 
}

• id is null when used as a request body in createProduct
• description and categories are null in the return of findProducts as they are not needed in the listing.
• All fields are populated in getProduct.

Three use cases, three implicit contracts.

The problem isn’t the null values themselves, the problem is that nothing in the type tells us which fields are expected to be populated. That knowledge now lives outside of the type system.

Once again, explicit contracts are replaced by shared expectations.

Boilerplate explosion

The last cost I would like to emphasise is the amount of ceremony involved.

Beyond the number of lines of code required to write those accessors, every field exposed via methods becomes part of the public API. And some qualities are expected from public API methods which are not necessarily expected nor beneficial for getters and setters.

Testing and documentation have costs attached to them. And when getters and setters are expected to be just dumb accessors, are those costs justified?

In practice we either acknowledge them as a special kind of methods by exempting them from test/documentation or we decide to prioritise consistency and live with the costs.

In any case, the sheer amount of boilerplate is a clue that something is off.

Light at the end of the tunnel?

Unsurprisingly, the ecosystem started looking for ways to remove it.

IDE code generation

The first step was IDE code generation. It reduced the effort required to write those methods, but they were still part of the codebase. The boilerplate remained, along with the maintenance burden.

Then came automated code generation from dedicated libraries.

Lombok’s annotations

Lombok is an initiative aiming at reducing boilerplate (not only in getters and setters) by the use of annotations and code generation.

The idea is that trivial code could be generated on the fly instead of painstakingly being written and maintained by hand.

It’s nice for boilerplate reduction, and it has the added value of increasing the code readability.

The presence of annotations in the code base communicates intent much more clearly than by simply inferring it from a combination of fields and accessor names: rather than merely generating boilerplate, annotations such as @Getter, @Setter or @Data explicitly tell the reader that the class is meant to be a data holder.

But what it does not solve is the problem of differentiating data from behaviour in the Java language; it only codified the convention (which is already a nice improvement in itself).

Records Clarify Intent

The introduction of records into the Java language is the first time the language explicitly recognises data carriers as a distinct construct.

The fact that records use a noun as a name instead of an action is also a nice move in my opinion. It more clearly indicates that those methods are not acting on anything. They provide access to the underlying information.

Records are not an all-purpose solution but I believe it is a move in the right direction.

Conclusion

Over time, we’ve started conflating three different things.

• what Java allows,
• what JavaBeans standardised,
• what Java developers have come to expect.

Those three are related, but they’re not the same.

As the convention became ubiquitous, it also shaped our mental model. More and more knowledge became implicit, relying on developers’ expectations rather than on what the language or the type system explicitly expressed.

When someone says, “That’s not how Java is written,” they’re often not talking about the language at all. They’re talking about the expectations inherited from a convention that solved a very real problem thirty years ago.

Getters and setters were meant to preserve the possibility of encapsulation. But the irony is that decades of convention have often discouraged us from exercising that possibility. In many codebases, getters and setters are no longer treated as methods that form an abstraction boundary; they’re treated as public fields written with extra ceremony and stronger cultural expectations.

Fortunately, both the ecosystem and the language itself have continued to evolve. IDEs, Lombok and, more recently, records all acknowledge that data carriers deserve better support. Whether that evolution will eventually blur the line between data and behaviour less than JavaBeans did remains to be seen, but I think it’s a step in the right direction.

This is the first post, because there has to be a first.

I’m opening this site to share and organize my thoughts on software engineering.

I hope you’ll find them useful. If not, I apologize in advance. :D