DEV Community: Mariano Barcia

From majestic monoliths to runtime topologies

Mariano Barcia — Wed, 25 Mar 2026 21:50:26 +0000

In the previous post, I used a scene from The Eternaut — Favalli starting an old car after an EMP — as a way to introduce the “humble monolith” and how that differs from the "majestic monolith". Also, why the monolith vs microservices discussion is the tree in front of the forest: rigidity is the real problem hiding behind it. So, how could we be more flexible?

What if we could have the same business logic, adopting not one but many runtime shapes? I realised that the functional and reactive pipelines underpinning The Pipeline Framework, paired with the TPF's own architecture could actually enable choices for the users: should I go for a monolith? Or deploy steps as microservices? I thought, why have to choose?

Introducing: runtime topologies in The Pipeline Framework.

The Pipeline Framework treats the business flow as the stable asset, and the runtime topology as something that can change over time, and even co-exist (local environment vs. production). Let's take a look at the currently supported runtime topology shapes.

None of these shapes is inherently “better.” They are just different ways of balancing:

how much change you can isolate
how much infrastructure you want to operate
how much latency you can afford
where your security boundaries sit
how teams are organised

And yet, in most systems, choosing one of these ends up locking you in. TPF instead makes this possible by adapting the input/outputs of each step in an elegant way at build time, to match the runtime shape of choice.

Monolith

Everything runs in-process: steps, orchestrator, and plugins.

This is the simplest possible setup. No network hops, minimal operational overhead, very direct debugging.

The trade-off is clear: everything shares the same blast radius.

Pipeline Runtime

Here, the orchestrator is separated, but the pipeline steps still run in a grouped runtime. Plugins are also externalised as shared services.

This tends to be a very practical middle ground.

You get a clear ingress point, reduced exposure of internal components, and some separation of concerns — without fully embracing distributed complexity.

Modular / Distributed

Each step becomes independently deployable, and plugins remain shared services rather than being embedded per step.

This gives you strong isolation, independent scaling, and clearer ownership boundaries.

It also introduces the usual trade-offs: more infrastructure, more network hops, and more operational complexity.

In the framework, the pipeline itself is defined independently of where it runs. Runtime mapping (PipelineRuntimeMapping and its resolver) determines placement, not behavior. In the csv-payments example, the same pipeline can run as a monolith, inside a pipeline runtime, or in a more modular layout — without rewriting the business logic.

That separation shows up elsewhere too. Step contracts define intent, mappers isolate boundaries, and services remain focused on transformation logic. Transport concerns don’t leak into the core, which means the system doesn’t become hostage to how components communicate.

Even at generation level, there’s a single semantic model that gets projected into different execution modes. Local calls, gRPC, REST, protobuf-over-http — they’re not treated as fundamentally different architectures, but as different ways of expressing the same flow.

And importantly, this isn’t just theoretical. The same reference system is built and tested in more than one topology, so the idea of switching shapes is exercised, not just claimed.

While the 3 topologies above are actual values in a YAML config, none of this means architecture becomes automatic or point-n-click: you still choose your topology deliberately, and maintain the build.

But that choice stops being irreversible: if the business flow can outlive the topology, then moving from a monolith to something more distributed (or even back again) stops being a rewrite and becomes a transition.

And that’s a very different place to be.

The old works! (or the humble monolith)

Mariano Barcia — Mon, 23 Mar 2026 18:47:29 +0000

In the Netflix series The Eternaut, there’s a moment that hits harder than it probably should.

After the electromagnetic pulse wipes out anything electronic, the world just… stops. Modern cars are useless, cities freeze, everything familiar suddenly becomes fragile.

Then Favalli finds an old car and tries to start it.

And it works.

“Lo viejo funciona, Juan.” ("the old works, Juan")

It’s a simple line, but it lands because it does something subtle: it pulls you back in time. Not just to “older technology,” but to a different world — ten, twenty, forty years ago — when things worked differently, when we were different, when the assumptions we made about the future were completely different.

That feeling shows up in a lot of stories. A forgotten machine that still works. An old tool that suddenly becomes essential. Not because it’s better, but because it was built for a different context — and somehow fits the present moment again.

⸻

Over the past few years, many microservices projects have turned into cautionary tales: systems that looked elegant on paper but became difficult to operate, evolve, or even understand.

In response, the idea of the “majestic monolith” has made a comeback.

And to be fair, there are majestic monoliths — just like there are beautifully restored classic cars. Carefully engineered, impressive, and sometimes exactly the right thing.

But also, very expensive and time-consuming and perhaps over-engineered, which is why that framing can be misleading.

Because most systems don’t need to be majestic. They need to be appropriate for their context, especially over the next one, two, or three years.

If you’re honest about those constraints, the question becomes less ideological and more practical: what kind of system will let you move, adapt, and operate with the least friction?

⸻

That’s where the idea of the “humble monolith” feels more grounded.

Not as a statement, but as a baseline.

A system with fewer moving parts, clearer boundaries, and behavior that is easier to reason about when something goes wrong. Something you can understand without needing to reconstruct a distributed narrative across multiple components.

Of course, monoliths can degrade into tightly coupled, hard-to-change systems. We’ve all seen that.

But so can distributed architectures — and often in ways that are harder to see and harder to fix.

⸻

Which points to the real issue.

The problem is not monolith vs microservices.

It’s rigidity.

We make architectural decisions early, based on assumptions about scale, growth, and future needs. And then those decisions get embedded into the system in ways that are difficult to reverse.

What started as a good fit becomes a constraint.

The system needs to evolve, but the architecture doesn’t.

⸻

Maybe that’s why moments like “lo viejo funciona” resonate so much.

Not because the past was better, but because it reminds us that different choices made sense under different conditions — and that those choices can still be valid when circumstances change.

In software, we rarely give ourselves that flexibility.

We pick a shape, and we’re stuck with it.

In the next post, I’ll explore a different approach: what it looks like when architecture becomes a runtime decision, and how the same system can take on different shapes — from a humble monolith to something more distributed — without rewriting everything.

Because sometimes, what matters isn’t choosing the right architecture upfront.

It’s being able to choose again when the world changes.

Thank you for having reached this far, I hope you find these ideas interesting. Now, have you worked on monoliths? how would you call it :-) , Or perhaps, contributed to projects using microservices or server-less architecture? I'm curious to hear from you in the comments!

Photo credits:
El Eternauta. César Troncoso As Favalli In El Eternauta. Cr. Marcos Ludevid / Netflix ©2025

The Pipeline Framework is out

Mariano Barcia — Wed, 03 Dec 2025 15:33:55 +0000

Every major pipeline or workflow engine today is either heavyweight, cluster-oriented, monolithic, or tied to Python. Nobody has built a microservice-native, Java/Quarkus/JVM, gRPC-first, type-safe pipeline engine, like The Pipeline Framework.

Happy to announce I've published TPF to Maven Central. Feel free to ask me anything!

https://pipelineframework.org

Photo: Anthony Quintano Media

Introducing The Pipeline Framework

Mariano Barcia — Wed, 24 Sep 2025 22:02:09 +0000

https://pipelineframework.org

The Pipeline Framework is a powerful tool for building reactive pipeline processing systems. It simplifies the development of distributed systems by providing a consistent way to create, configure, and deploy pipeline steps.

Key Features
Reactive Programming: Built on top of Mutiny for non-blocking operations
Annotation-Based Configuration: Simplifies adapter generation with @PipelineStep
gRPC and REST Support: Automatically generates adapters for both communication protocols
Modular Design: Clear separation between runtime and deployment components
Auto-Generation: Generates necessary infrastructure at build time
Observability: Built-in metrics, tracing, and logging support
Error Handling: Comprehensive error handling with DLQ support
Concurrency Control: Virtual threads and backpressure management

Introducing: the pipeline framework

Mariano Barcia — Wed, 17 Sep 2025 14:58:44 +0000

Too often we see development teams struggle to finish a project. Here is a nice open-source framework I wrote to help with your upcoming microservices (or legacy!) project: the pipeline framework.

https://pipelineframework.org

Welcome to the Pipeline Framework - a robust, scalable, and maintainable solution for processing data through a series of steps with built-in benefits for high-throughput, distributed systems.

Step-based Processing: Each business logic operation is encapsulated in a step that implements a specific interface.
Reactive Programming: Steps use Mutiny reactive streams for non-blocking I/O operations.
Type Safety: Steps are strongly typed with clear input and output types that chain together.
Configuration Management: Steps can be configured globally or individually for retry logic, concurrency, and more.
Observability: Built-in metrics, tracing, and logging for monitoring and debugging.

It doesn't ask for much, only that you translate the business case into a "pipeline" model with each step having a defined input/output. You only write the business logic for each step and the framework will do all the Kubernetes heavy lifting for you (messaging, auto-persist, error handling, etc.)

I'm in the process of making it an independent set of JARs on Maven central. At the moment it is included in the "CSV Payments Processing" system which is its "reference implementation". Reach out to me in the comments if you would like to know more. Cheers.

The pioneering microservice

Mariano Barcia — Wed, 20 Aug 2025 15:35:40 +0000

From the perspective of a monolith, handing over ownership of a piece of data to a microservice feels like a hostile takeover. To make matters worse, the monolith doesn’t just lose those features — it has to be refactored to depend on the new service instead. If the whole point of migration was to stop investing in the monolith, this can feel like regression. Strong justification is required.

This is why the first microservice is always the hardest.

Two challenges at once

When you launch that first service, you’re not just building a new component. You’re building the platform that supports it — infrastructure, pipelines, processes, observability. At the same time, you’re modifying the monolith to work with it.

What used to be a straightforward in-memory call now becomes a network request. Data that lived in the same heap must now travel through an API. Latency appears where there was none, and eventual consistency creeps into flows that were once instantaneous.

The dual effort — building the new while bending the old — makes the first step disproportionately painful.

The grind of infrastructure

On paper, spinning up microservices sounds simple. In practice, you often need to establish a baseline of tooling before you can ship anything meaningful:

Containerization (Dockerfiles, images, registries)
Orchestration (Kubernetes clusters or alternatives)
Messaging or event streams (Kafka, RabbitMQ, SQS, …)
API gateways, authentication, and routing
Observability (logging, metrics, tracing)

And sometimes, service meshes or other advanced tools sneak in before you’re ready. All of this setup is invisible to business stakeholders, yet it consumes enormous time and energy.

Data gravity and adaptation

Meanwhile, the monolith doesn’t go quietly. It has strong “data gravity” — everything around it is pulled into its orbit because it already has the data and the logic close at hand. Asking it to delegate that responsibility to a new service means changing well-worn paths: queries become requests, joins become lookups, consistency guarantees weaken.

This is the moment when a team can feel like progress has slowed to a crawl.

The turning point

But once the first microservice is truly in production, something important shifts. The monolith no longer owns everything. There is now precedent: data and responsibility can be transferred out.

You’ve also learned hard lessons — how to replace in-memory function calls with inter-process communication, how to cope with retries and idempotency, how to migrate ownership of data, and how to operate a new service in production.

The next service won’t require reinventing all of this. The platform is in place, the practices are established, and the team’s confidence has grown.

On data sovereignty and the black hole monolith

Mariano Barcia — Thu, 14 Aug 2025 15:13:27 +0000

In most organisations, everything INSIDE the main monolithic system has access to pretty much all the relevant data it needs. It is like second nature and as such, we rarely stop to consider what it’s like to not have access to data.

But crucially, anything OUTSIDE this main monolithic system has access to... nothing. For a new microservice to be meaningful, it will need to manage a piece of the data pie: it will need access to SOMETHING.

That's when maybe many will be tempted to access the main database directly, trying to bypass the monolith. However, keeping a shared database between microservices is an anti-pattern. A strong rule in a microservices architecture is: No shared database between services. Data should be owned and managed by a single service: this is called data sovereignty. Read about this principle in more detail here.

Without a significant effort, any new development outside the monolith is a "pariah", isolated from any existing data and relationship with any relevant area of the business.

That is why I say that the monolith has this black hole effect on the business, pulling in more and more data under its control. This happens because it’s faster and simpler to bolt new features and data onto the monolith rather than build a new service from scratch. Because of that, and because microservices bring their own complexities, there is never a good time to start a microservice.

Like a black hole bending the space around it, the monolith warps development priorities and architectures. Anything that gets too close is pulled in — data, features, even whole projects — until escape becomes almost impossible.

A monolith has an extraordinarily influential effect on any new development, just as a black hole will absorb everything in its vicinity by the sheer power of its mass and gravity. Escaping that gravitational pull is hard — but the first service to truly orbit outside its reach will define the future of your architecture.

From Monolith to Microservices: surfing the pipeline

Mariano Barcia — Thu, 24 Jul 2025 19:49:23 +0000

In my previous post I quickly covered how I did the breakup of the majestic monolith into smaller services. In the end, I went for this:

An input streaming service (parse CSV input files)
An output streaming service (write CSV output files)
A service for sending payments to a 3rd-party
A service for polling for responses from that 3rd-party
A service to produce (decorated) output records.
An orchestrator service (to read folder and orchestrate pipeline steps), inspired by the Saga pattern. This service also holds the CLI application that it is used to kick-off the system.

However, there is a lot more to this than it might appear at first sight. I first started asking myself the following question.

Is there a tried-and-true methodology for breaking up a monolith into smaller microservices?

Domain-Driven Design

The number one methodology is called Domain-Driven Design (DDD). By carefully analysing your domain you are able to break up the monolith by business capability, not technical layers. Each microservice aligns to a so called "bounded context" (e.g., Billing, Inventory, User Management).

Domain logic and I/O

Whilst I had given DDD a shot at Commonplace, I did not see it as a great fit for my PoC project. I remembered watching this Scott Wlaschin's conference some time ago.

and finding it fascinating, as I saw so much synergy with what I was doing with the CSV Payments Processing PoC. I also remember this similar version called "Functional Core, Imperative Shell" (link to video), where DDD is also very much at play.

It's the pipeline, stupid!

Later on, when I was thinking about this "big breakup", I experienced this bulb moment when realised that, naturally, the boundaries were right there in front of me. A microservice per step of the pipeline was all I needed, give or take. And it was so much simpler than I thought it would be! I thought that was brilliant and gave myself a good pat on the back.

Benefits

Having a microservice per step of the processing pipeline has several benefits.

Extensibility: very easy to add new processing steps as microservices
Easy to orchestrate: as it plays along the original design
Aligned with DDD: as each step in the pipeline takes care of a different business capability
Simplicity: business logic and data flow in and out always in a single direction
Loosely coupled: does not create any new dependencies. There are services that need to deal with the file system, whilst others just don't, and that is only dictated by the business logic and not forced by the architecture

Photo Credit: Pipeline - North Shore

From Monolith to Microservices: Lessons Learned Migrating the CSV Payments Processing project (Part One)

Mariano Barcia — Thu, 03 Jul 2025 10:51:32 +0000

I've been building a CSV Payments Processing system, based on a real-world project I've worked on at Worldfirst.

https://github.com/mbarcia/CSV-Payments-PoC

Originally, I set out only to write a better version using a "pipeline-oriented" design based on the Command pattern.

The idea was to use the project as a sandbox/playground, that could also serve as a proof of concept and to communicate new ideas to other people.

About the time I had finished what I originally set out to do, I started exploring microservices at Commonplace, along with a better automated testing strategy.

So, although I was happy with how the project achieved its original goals, as I was making progress learning all about microservices, I decided to evolve the project even further. First things first, I was interested in showing how easy automated testing was when the underlying design is good. Hence, I got it to a point of full meaningful testing coverage after a short time, enlisting the help of AI to write unit tests. Yeah I know, TDD right?

By then, I had also achieved a good understanding of microservices, not least because I have been managing the Kubernetes-based Commonplace platform, and decided to apply these learnings to the CSV project.

The big breakup

As a prerequisite, I had to decide how I was going to do the breakup of the system into smaller services. This merits a blog post on its own but, long story short, I decided to breakup the application more or less into

An input streaming service (parse CSV files)
An output streaming (write CSV results)
A number of pipeline steps (send payment, polling, produce output).
An orchestrator (read folder, orchestrate pipeline steps, handle errors), inspired by the Saga pattern.

Migrating from Springboot to Quarkus 3

Originally, the project started as a Springboot CLI app, classic. Again enlisting the help of ChatGPT, I managed to refactor a Springboot CLI application into a multi-module microservices architecture over the course of a few intense sessions.

This was no copy-paste exercise. Along the way, I uncovered a treasure trove of lessons in Quarkus configuration, build systems, dependency management, and inter-service communication. A part of me knew I had started my journey into The Rabbit Hole though, so let's start from the beginning: Maven dependencies.

Build Mayhem: Maven vs. Gradle

I considered switching to Gradle for its composite build capabilities but stuck with Maven for simplicity and IntelliJ IDEA support. Quarkus works well with Maven multi-module projects, and IDEA recognizes and manages them cleanly—even when all modules live in a single Git repo.

Still, Maven wasn’t always smooth sailing. Issues included:

Mojo execution errors due to conflicting plugin configurations
Obsolete Java version warnings (source 8 is obsolete)
Javadoc plugin failures due to undocumented interfaces
Lombok not being picked up by the Maven compiler (even though it worked in the IDE)

Each problem required its own fix—from upgrading plugin versions to tweaking maven-compiler-plugin settings and suppressing irrelevant warnings.

Toward Microservices: Structuring and Sharing Code

The monolith eventually gave way to a structured microservice approach. Early on, I realised it was going to be far easier to share a "common" domain module as I wasn't going to get things right on the first attempt. So, I created such common/shared module, which housed reusable domain classes and interfaces shared across services.

Here I faced a critical architectural decision: how should services communicate?

Thoughts on synchronous and asynchronous communication

Async communication seems to be the preferred method of communication between microservices. But, I see async as a higher-level tier wrapping or adapting the tier of sync APIs. I see a microservice taking gRPC and REST calls now, and responding to asynchronous events in the future. Naturally then, I decided to go with a synchronous model first.

The sync vs async topic is quite interesting. Adding a constellation of message queues as the "glue" between microservices needs justification in my opinion. SQS or Kafka are nice, but they are also complex.

If you take Project Loom's virtual threads (=compute density), structured concurrency, Quarkus, Hibernate reactive, Kubernetes high availability, and Mutiny streams (with back pressure and retry w/backoff), you have pretty much solved the issue of availability of distributed services running remotely on heterogeneous hardware capacity (and therefore, varying availability).

Is it too foolish to think that async comms might become irrelevant in the future, in cases like a greenfield internal project? If sync comms get much better, it might just become the preferred choice.

But as I said: the two comms models are not mutually exclusive in my humble opinion. For me, it was absolutely fine to do sync comms at the beginning, and leave async for phase 2 when the services are deemed robust enough. Of course, I expect asynchronous to require some re-factoring, but it should mostly be a "wrapper" of the existing stuff, plus the addition of the feature itself.

Very curious to hear comments on this topic!

Choosing gRPC Over REST

REST felt unnecessarily heavyweight for intra-service communication within the same organization, especially when services live on the same cluster or host. I settled on gRPC for its:

Efficient binary protocol
Built-in support for streaming
Strong API contracts via .proto files
Mature integration with modern dev stacks and Kubernetes

It was clear that gRPC offered the best mix of performance and developer productivity—especially when paired with Quarkus’s excellent Protobuf tooling.

Later on, I'd learn about Vertex and its dual support for gRPC and REST. Again, another non mutually exclusive choice! Happy days!

Kicking things off: A CLI App with Quarkus and Picocli

The CLI tier shifted to a Quarkus-based CLI tool using @QuarkusMain and QuarkusApplication to bootstrap logic. Added some much needed conveniency features along the way though. Early challenges included:

Passing command-line arguments (e.g., --csv-folder) via Picocli
Getting @Inject to work properly within CLI apps
Managing configuration overrides for testing without relying solely on @QuarkusTest

Eventually, I settled on combining Quarkus's DI with @QuarkusMain and Picocli’s @CommandLine. It took several iterations to get the CLI runtime and testing environment to coexist without interfering.

Takeaways

Quarkus apps are powerful, but require careful setup when combining dependency injection, Picocli, and testing.
Multi-module Maven setups scale well, especially with good IDE support. But be ready to fight your tooling when things go wrong.
Code sharing needs structure: create clean interfaces and use tools like Lombok and config mapping to reduce boilerplate.
gRPC is ideal for internal microservice communication, offering the speed and contract-first development REST often lacks.

Coming up on Part Two

I was much impressed with Quarkus, its capabilities and ease of use. Having broken up the Springboot app into these new foundational modules, I felt excited and wanted to keep on going at a steady pace.

Next steps involve things like defining proper .proto APIs, building mapper classes (MapStruct), redefine concurrency processing, and more.

-
Cover photo by Sincerely Media at Unsplash

What I've learned about distributed services (part three)

Mariano Barcia — Wed, 25 Jun 2025 12:27:29 +0000

This is an anecdote really, but draws a very interesting conclusion.

As it turns out when you adventure yourself out of the boundaries of a single process/application (a.k.a. the monolith), you find yourself missing tools that used to make your life easier as a (monolith) developer. But it's the paradigm change that calls for a great deal of adaptation.

One of these things in Java land is the compiler's ability to "check" exceptions are handled properly, both downstream and upstream any method.

But once services become remote, the domain objects and their exceptions no longer live within the confines of a single repository, as is the case with a monolithic application.

Hence, the libraries you need are now IDL definitions and/or several RPC (or REST) APIs, which are not able to leverage the power of the Java compiler's checked exceptions feature.

So what I've found in some of the pre-existing code is that the authors started to use and abuse the runtime exceptions, as most services were only able to issue an RPC failure with an error code to the callers.

So, even when you were not dealing with remote calls, internal helper libraries only used runtime exceptions instead of the regular checked exceptions, effectively bypassing the compiler and freeing developers from doing any sort of exception handling.

I recall this was a double edge sword, as in some cases I found myself in the situation of needing exception handling. But overall (wink wink Golang) it wasn't too bad!

The way it worked was: every service had a top-tier exception handling code, so every runtime exception would bubble up and be caught by this code before returning to the caller. This provided for the proper error codes to be relayed to the caller, instead of just a generic runtime failure.

Now that I'm migrating a Spring application to Quarkus (and breaking it into microservices in the process), I'm learning that a few things are now different from the SOFA stack. I reckon the stack trace of the runtime exception can actually be sent back to the caller. I'll cover this a bit more of this in a future post.

For now, I think I understand now, why in a newer language like Golang, its creators took the bold decision to remove the checked exceptions feature. After all, if developers are working in a microservices environment, checked exceptions are less useful.

The exception translation pattern

Mariano Barcia — Tue, 20 May 2025 22:26:27 +0000

📌 TL;DR

The exception translation pattern:

Cleans up APIs
Enforces robust error handling
Hides internal complexity
Aligns code with domain logic

Since I have been writing about exceptions lately, I figured it would be great to elaborate on the best practices around error handling. So why not give it a name, a title and a cover image, and put together a nice post with code examples and diagrams? Also important, remind us of all the benefits that it brings to the table, no matter how much of a chore it might feel at times.

In a future post, I'll give my opinion on where this falls short and possible ways of improvement or workarounds.

The I/O exception example

A typical case of exception handling is when dealing with I/O methods. Let's look at how the exception translation pattern applies. It usually involves three (or sometimes more) tiers, where a "translation" or conversion takes place from one tier to next. The tiers can be described as follows:

Library Tier (Low-Level I/O): A method like Files.readAllBytes() may throw an IOException if the file is missing or unreadable.
Application Tier (Your Method): Your method catches this low-level exception and wraps it in a custom application-specific exception, such as ConfigLoadException, providing a clear, meaningful message.
Caller Tier (Client Code): The caller interacts only with the application-level API. It does not need to understand IOException—only that configuration loading failed in a specific, well-defined way.

Visual diagram

Here’s a diagram showing the flow of control and exceptions:

+----------------+         +-----------------------+         +---------------------+
|  Tier 1        |         |  Tier 2               |         | Tier 3              |
| Low-Level I/O  | ---->   | Application Logic     | ---->   | Application Caller  |
| (readFromFile) | throws  | (loadConfig)          | throws  | (init)              |
| IOException    |         | ConfigLoadException   |         | handles ConfigLoadEx |
+----------------+         +-----------------------+         +---------------------+
                                  ^                                   |
                                  |                                   |
                                  +------ wraps IOException -------+

Example code

See below an example code illustrating this pattern:

// Custom application exception
public class ConfigLoadException extends Exception {
    public ConfigLoadException(String message, Throwable cause) {
        super(message, cause);
    }
}

// Tier 1: Library
public String readFromFile(String path) throws IOException {
    return new String(Files.readAllBytes(Paths.get(path)));
}

// Tier 2: Application method
public String loadConfig() throws ConfigLoadException {
    try {
        return readFromFile("config.txt");
    } catch (IOException e) {
        throw new ConfigLoadException("Failed to load configuration file.", e);
    }
}

// Tier 3: Caller
public void init() {
    try {
        String config = loadConfig();
        // proceed with config
    } catch (ConfigLoadException e) {
        // handle or log application-level error
    }
}

✅ Why Exception Translation Is a Best Practice in Java

The exception translation pattern—catching a low-level exception and rethrowing a higher-level, domain-specific exception—is a powerful tool in layered application design. It allows developers to write cleaner, more maintainable code.

Here is the long list of benefits that make it a best practice:

🔒 1. Encapsulation of Implementation Details

You hide technical concerns (e.g., IOException, SQLException) from callers. They don’t need to know how your method works internally—just that something relevant to them failed.

Benefit: Promotes modularity and separation of concerns.

🧠 2. Improved Clarity and Context in Error Messages

Low-level exceptions are often vague. By translating them, you can provide business-relevant, human-readable messages that make debugging and logging easier.

Benefit: Easier troubleshooting and more meaningful error messages.

🔁 3. Consistent Error Handling API

You can map all internal errors to a predictable set of application-level exceptions. This simplifies the mental model for client developers.

Benefit: Reduced cognitive load and cleaner public APIs.

🧱 4. Stronger Compile-Time Guarantees

When your translated exceptions are checked exceptions, the compiler enforces proper handling by the caller.

Benefit: Prevents accidental omission of error handling.

🔄 5. Flexibility to Change Internal Implementations

Whether you switch from file-based storage to a database or change the library you use, your external API stays the same if you're translating exceptions properly.

Benefit: Future-proofing and easier refactoring.

🏗️ 6. Encourages Domain-Driven Design

Instead of leaking infrastructure terms, you use exceptions like ConfigLoadException or OrderProcessingException that reflect your business logic.

Benefit: Your code speaks the language of your domain.

What I've learned about distributed services (part two)

Mariano Barcia — Tue, 20 May 2025 20:13:56 +0000

Java is built in a way that developers are forced to always be doing exception handling. Period. It works by forcing the developer
a) to surround any line of code that might throw an exception with a try/catch block.
b) to declare ALL exception types involved in the throws clause (either not handled or thrown inside try/catch blocks).

However, the compiler does NOT enforce these rules to runtime exceptions. This is the exception class hierarchy:

Object
 └── Throwable
      ├── Error               ← For serious problems (not meant to be caught)
      └── Exception
           ├── RuntimeException  ← Base for unchecked (runtime) exceptions
           └── [Other Exceptions] ← Base for checked exceptions

You can then wonder, what if I use a runtime exception for my application? This would free me from writing exception handling code, wouldn't it?

As it turns out, this is (probably) your only option in the distributed realm.