DEV Community: Charles Hornick

Ports & Adapters: Beyond the Theory - Isolating the Application with JPMS

Charles Hornick — Wed, 25 Mar 2026 10:58:21 +0000

This is the third article in the "Ports & Adapters: Beyond the Theory" series.
Article 2 showed how to organize the inside of the application by combining P&A with Simon Brown's package-by-component.
This article tackles the hole left by the previous article: the public keyword exposing more than necessary.
Every line of code in the companion repository was written by hand. No AI-generated code.

GitHub Repository: GitHub - branch article/3-jpms-isolation

Series - Ports & Adapters: Beyond the Theory

Runtime Adapter Hot-Swapping
Organizing the Application with Package-by-Component
Isolating with JPMS ← you are here
No Exceptions: Result<T> with Pragmatica (coming soon)
Testing in P&A (coming soon)
Architecture-Driven AI Development (coming soon)
Adapter Switching Strategies (coming soon)
Spring Modulith + P&A (coming soon)

"JPMS will keep the local classes in line" - Grand Moff Tarkin, former Software Engineer.

Recap: where article 2 left us

Article 2 showed how to combine Ports & Adapters with Simon Brown's package-by-component to organize the inside of the application. Java's package-private became the default visibility level, hiding the internal logic of each use case.

But we ended on an honest assessment: primary port constructors are public, and so is SnapshotBuilder. package-private covers a good portion of the isolation, but the rest is exposed, and Java offers nothing between public and package-private.

This is where JPMS comes in.

JPMS refresher

The Java Platform Module System (JPMS), introduced in Java 9, adds a level of isolation above packages: the module. A module explicitly declares what it exports and what it needs through a module-info.java file.

The key point is that a module is closed by default. If a package is not explicitly exported, it is invisible from outside the module, even if the classes it contains are public.

That's exactly the mechanism we were missing.

Reorganizing the `snapshot` package

Before setting up modules, there's a problem to fix in the application's organization. The snapshot/ package contains both types that need to be visible to adapters (Snapshot, Action) and purely internal types (CreationPoint, InvestedPoint, CreationPointConsumer, Recorder, SnapshotBuilder).

But JPMS exports packages, not classes. There's no way to say "export Snapshot but hide CreationPoint" if they're in the same package.

The solution is to separate the two categories:

state/
├── CreationPoint.java          # internal - not exported
├── CreationPointConsumer.java  # internal - not exported
├── InvestedPoint.java          # internal - not exported
├── Recorder.java               # internal - not exported
├── SnapshotBuilder.java        # internal - not exported
└── snapshot/
    ├── Snapshot.java           # exposed - adapters need it
    └── Action.java             # exposed - part of the contract

state describes the internal state management mechanics, while state.snapshot contains what comes out of it. The state package is not exported, unlike the state.snapshot package, meaning internal classes disappear for the outside world.

The application module

Here is the application's module-info.java:

module be.charleshornick.supra {
    requires core; // Pragmatica-core

    exports be.charleshornick.supra; // ErrorCause, ForStoringSnapshot
    exports be.charleshornick.supra.create; // Primary port
    exports be.charleshornick.supra.define; // ForLoadingSnapshot, ToCharacter
    exports be.charleshornick.supra.define.race; // Primary port
    exports be.charleshornick.supra.define.profession; // Primary port
    exports be.charleshornick.supra.define.characteristic; // Primary port
    exports be.charleshornick.supra.retrieve.race; // Primary port
    exports be.charleshornick.supra.retrieve.profession; // Primary port
    exports be.charleshornick.supra.retrieve.snapshot; // Primary port
    exports be.charleshornick.supra.race; // Vocabulary
    exports be.charleshornick.supra.profession; // Vocabulary
    exports be.charleshornick.supra.characteristic; // Vocabulary
    exports be.charleshornick.supra.state.snapshot; // Exposed state
}

What stands out is that everything not listed is invisible: CreationPoint, InvestedPoint, CreationPointConsumer, Recorder, SnapshotBuilder are public in their package but no other module can access them. The compiler refuses the import.

The public from article 2 is no longer a master key. It means "public within the module".

Why exports are not qualified

You'll notice that no export uses the to clause:

// We do NOT do this:
exports be.charleshornick.supra.create to be.charleshornick.supra.bootstrap;

The reason is directly tied to Cockburn. The application is "blissfully ignorant of the nature of the input device". If the application declares which modules it exports to, it knows its consumers. That's a form of coupling, even if it's at the module level and not at the code level.

A JDBC adapter today, a MongoDB adapter tomorrow, an in-memory adapter for tests. The application doesn't know and shouldn't know who implements its secondary ports, so exports remain open.

Adapters enter the scene

Until now in the series, the application lived alone. With JPMS and modules, it's time to introduce what lives on the outside.

The primary adapter

A primary adapter translates signals from an external actor to the application's ports. In a complete system, this would be a REST controller, a web interface, a CLI. But for this article, and following the approach Cockburn uses in Hexagonal Architecture Explained, a test console adapter is sufficient:

public class CreateFullCharacter {

    private final CreateCharacter createCharacter;
    private final DefineRace defineRace;
    private final DefineProfession defineProfession;
    private final DefineCharacteristic defineCharacteristic;
    private final GetLastestSnapshot getLastestSnapshot;
    private final GetAllSnapshots getAllSnapshots;

    final String characterName = "Borgrim";

    public CreateFullCharacter(final CreateCharacter createCharacter,
                               final DefineRace defineRace,
                               final DefineProfession defineProfession,
                               final DefineCharacteristic defineCharacteristic,
                               final GetLastestSnapshot getLastestSnapshot,
                               final GetAllSnapshots getAllSnapshots) {
        this.createCharacter = createCharacter;
        this.defineRace = defineRace;
        this.defineProfession = defineProfession;
        this.defineCharacteristic = defineCharacteristic;
        this.getLastestSnapshot = getLastestSnapshot;
        this.getAllSnapshots = getAllSnapshots;
    }

    public void run() {

        System.out.println("=== Character Creation Test ===");

        this.createCharacter
                .named(this.characterName)
                .onSuccess(s -> System.out.println("✓ Created: " + s.name()))
                .onFailure(CreateFullCharacter::logError);

        this.defineRace
                .named(HIGH_ELF)
                .toCharacterNamed(this.characterName)
                .onSuccess(s -> System.out.println("✓ Race: " + s.race().name()))
                .onFailure(CreateFullCharacter::logError);

        this.defineProfession
                .named(ELF_ADVENTURER)
                .toCharacterNamed(this.characterName)
                .onSuccess(s -> System.out.println("✓ Profession: " + s.profession().name()))
                .onFailure(CreateFullCharacter::logError);

        [...]
    }
}

This adapter only knows the primary ports. It cannot instantiate a SnapshotBuilder, nor access a CreationPoint, nor even touch a Recorder, JPMS forbids it at compile time.

An important point about primary adapters: they are shaped by the consumer they serve, not by the application. The idea is the same as BFFs (Backend For Frontend) in microservices: an element dedicated to a front-end, developed by the team that knows that front-end. The application behind doesn't change, only the translation does.

This means the front-end team can develop their adapters in parallel against the ports, using fakes, without being blocked by the application's development. As explained in article 2, the port is an API, a contract, not a synchronization point.

The faked secondary adapter

For this article, the secondary adapter is an in-memory fake located inside the composition root, exactly like the FixedTaxRateRepository Cockburn uses in his book: a trivial implementation that allows testing the wiring without infrastructure.

public class InMemorySnapshotStorage implements ForLoadingSnapshot, ForStoringSnapshot, ForGettingSnapshot {

    private final Map<String, TreeSet<Snapshot>> store = new HashMap<>();

    @Override
    public Option<Snapshot> getLastSnapshot(final String characterName) {
        return Option.option(this.store.get(characterName))
                .filter(set -> !set.isEmpty())
                .map(TreeSet::last);
    }

    @Override
    public Result<Snapshot> store(final Snapshot snapshot) {
        this.store.computeIfAbsent(snapshot.name(), _ -> new TreeSet<>()).add(snapshot);
        return Result.ok(snapshot);
    }

    @Override
    public Option<Snapshot> theLastest(final String name) {
        return this.getLastSnapshot(name);
    }

    @Override
    public List<Snapshot> allOrdered(final String name) {
        return Option.option(this.store.get(name))
                .map(List::copyOf)
                .or(List.of());
    }
}

This implements the secondary port ForStoringSnapshot. It sees the port interface and the Snapshot type because those packages are exported, but it doesn't see SnapshotBuilder, CreationPoint, or anything else. It doesn't need to, and JPMS makes sure it can't.

The Composition Root

The composition root is the only place that sees everything: the application, the primary adapters, the secondary adapters. It's the one that wires implementations together and launches the application.

public class Application {

    void main() {
        final var raceStorage = new InMemoryRaceStorage();
        final var professionStorage = new InMemoryProfessionStorage();
        final var snapshotStorage = new InMemorySnapshotStorage();

        final var createCharacter = new CreateCharacter(_ -> true, snapshotStorage);
        final var defineRace = new DefineRace(snapshotStorage, snapshotStorage, raceStorage);
        final var defineProfession = new DefineProfession(snapshotStorage, snapshotStorage, professionStorage);
        final var defineCharacteristic = new DefineCharacteristic(snapshotStorage, snapshotStorage);
        final var getLastestSnapshot = new GetLastestSnapshot(snapshotStorage);
        final var getAllSnapshots = new GetAllSnapshots(snapshotStorage);

        final var testAdapter = new CreateFullCharacter(
                createCharacter,
                defineRace,
                defineProfession,
                defineCharacteristic,
                getLastestSnapshot,
                getAllSnapshots
        );

        testAdapter.run();
    }
}

No Spring, no automatic injection, no annotations — the wiring is explicit, readable, and verified at compile time. The composition root is the only module with a dependency on all the others, and that's its job.

Composition root `module-info.java`

module be.charleshornick.supra.bootstrap {
    requires be.charleshornick.supra;
    requires be.charleshornick.supra.facade.test;
    requires core;
}

Test adapter `module-info.java`

module be.charleshornick.supra.facade.test {
    requires be.charleshornick.supra;
    requires core;

    exports be.charleshornick.supra.facade.test;
}

Adapters export their package so the composition root can instantiate them. The application doesn't even know these modules exist.

The trap: `opens ... to`

JPMS offers an opens directive that allows reflection on a package. And the temptation is real:

// DON'T DO THIS
module be.charleshornick.supra {
    opens be.charleshornick.supra.race to com.fasterxml.jackson.databind;
}

This would allow Jackson to deserialize Race types through reflection. Convenient. Except the application just declared that it knows about Jackson. It's no longer "blissfully ignorant" of the technology. The boundary is broken, right in the module-info.java itself.

And yes, Jackson is a technology. The choice to use Jackson over Gson belongs to the secondary adapter, not the application.

The right approach is for the secondary adapter to handle deserialization. It receives JSON, builds a Race through the public constructor, and passes it to the port. The application doesn't know that JSON exists somewhere. The adapter does its job as an adapter.

`@Transactional` does not belong in the application

Since we're talking about adapters and the composition root, a point that comes up often in discussions: where to place transactions?

Some argue that @Transactional can go in the application (what they call the "domain") because jakarta.transaction.Transactional is a Java standard and therefore "not technology-specific."

This is wrong. jakarta.transaction.Transactional presupposes a transaction manager, which presupposes transactional persistence. Cockburn's application shouldn't even know there's a database. A transaction annotation in the application means the application knows there's transactional persistence behind it.

But beyond theory, there's a practical argument. A single primary port can be wired with different secondary adapters depending on the context. A JDBC adapter needs transactions. An in-memory adapter doesn't. If @Transactional is in the application, it applies in both cases, forcing a dependency on a transaction manager that might not even exist in the in-memory context.

The transactional decision depends on the combination of primary adapter and secondary adapter. Only the composition root knows that combination. @Transactional goes on the handler in the primary adapter, or in a composition root configuration. Not in the application.

The application remains "blissfully ignorant" of everything.

The honest trade-off: the `public` constructor survives

JPMS closes non-exported packages. The public on a CreationPoint or a SnapshotBuilder no longer leaks to adapters, and that's the main gain.

But the public constructor of primary ports survives. CreateCharacter is in an exported package because the primary adapter needs to see it. And as discussed above, JPMS exports packages, not classes, so the public constructor remains accessible to any module that depends on the application.

An adapter doing new CreateCharacter(myFakeChecker, myFakeStorage) still compiles.

One could separate the port and its constructor into two different packages, one exported and one not. But that would break the per-use-case cohesion from Brown, the approach we set up in article 2. The cure would be worse than the disease.

Architecture guides, it doesn't prevent. No technical mechanism will replace the discipline of a team that understands the why behind the structure. JPMS + Brown + package-private cover nearly all of the isolation. The public constructor remains an act of trust in the team.

JPMS trade-offs

`module-info.java` complexity

The larger the application grows, the longer the export list gets. It's verbose but explicit, and a module-info.java of 30 lines remains infinitely more readable than an ArchUnit setup with 50 rules.

Tooling not always module-friendly

Some libraries and tools are not yet ready for JPMS. This is less and less true with recent Java versions and major frameworks, but it's a point to check before adoption.

More constrained tests

Tests must respect the same boundaries as production code. A test cannot access a non-exported package. This is a constraint that forces testing through ports, which is the right level of testing for the application. Internal details shouldn't be tested directly.

Spring Boot and JPMS

Historically, Spring Boot and JPMS didn't get along well. With Spring Boot 4.x and Java 25, the situation has improved considerably. But it's a topic to watch when adding real Spring adapters in the following articles.

Conclusion

Article 2 posed the problem: package-private covers a good portion of the isolation but public is a master key. JPMS fills the gap by adding a level of control above.

Two levels of isolation, two mechanisms, complementary:

JPMS controls what leaves the module. Non-exported packages are invisible, even if classes are public.
package-private controls what leaves the package. Internal classes stay invisible within the module itself.

Brown organizes the inside through package-private which enforces at the package level. JPMS enforces at the module level. Cockburn protects the boundary between the inside and the outside.

The application is now structured, isolated, and verifiable at compile time. But we haven't talked about tests yet. How do we guarantee that primary ports work correctly, that secondary adapters respect their contract, and that everything holds together without test duplication?

That's the subject of article 4: testing in P&A.

The example application evolves from article 2 with the addition of JPMS modules, a test console adapter, an in-memory adapter, and a composition root. The application itself hasn't changed, only the project structure has evolved.

Tech stack: Java 25, Pragmatica (Result<T>, Option<T>), JUnit 6, AssertJ, Maven. No Spring in this article.

Source code: GitHub - article/3-jpms-isolation

This article is part of the "Ports & Adapters: Beyond the Theory" series. The series was initiated after Alistair Cockburn, creator of the Ports & Adapters pattern and co-author of the Agile Manifesto, shared the first article and described the approach as "an amazing use of Hexagonal Architecture."

The architectural decisions in this series are grounded in Cockburn's original 2005 article and in Hexagonal Architecture Explained (Cockburn & Garrido de Paz, updated 1st edition, 2025).

Ports & Adapters: Beyond the Theory - Organizing the Application with Package-by-Component

Charles Hornick — Wed, 18 Mar 2026 23:02:38 +0000

This is the second article in the "Ports & Adapters: Beyond the Theory" series.
Article 1 demonstrated the ability to hot-swap adapters at runtime by leveraging the advantages of the P&A pattern.
This article tackles what Alistair Cockburn deliberately left open: how to organize the inside of the application.
Every line of code in the companion repository was written by hand. No AI-generated code.

GitHub Repository: GitHub — branch article/2-package-by-component

Series — Ports & Adapters: Beyond the Theory

Runtime Adapter Hot-Swapping
Organizing the Application with Package-by-Component ← you are here
Isolating with JPMS
No Exceptions: Result<T> with Pragmatica (coming soon)
Testing in P&A (coming soon)
Architecture-Driven AI Development (coming soon)
Adapter Switching Strategies (coming soon)
Spring Modulith + P&A (coming soon)

"I need to be assured that certain interests are package-private" — Arthur Case, talking about the application.

The application is not protected

Let's be clear, Alistair Cockburn's Ports & Adapters pattern can be summed up with the following points:

The system is split into two parts: the inside (the application) and the outside (the adapters);
The application focuses solely on business needs;
The application communicates with the outside world through ports;
Adapters translate and communicate with the application through these ports.

There you go, as simple as it sounds.

Imagine a laptop that only has USB-C ports. You want to connect your wired mouse but it's USB-A.
To allow communication, you need a USB-A to USB-C adapter.
Now your mouse click, going through the adapter, is understood by the laptop because the connection has been established.

(This analogy is much harder to make with the term "hexagonal architecture")

Unfortunately, while P&A guarantees an effective separation between the inside and the outside, it absolutely does not guarantee that the inside is properly organized.

But what do we see in tutorials and blog posts? That the organization is almost always the same:

domain/
├── model/
├── port/
│   ├── in/
│   └── out/
└── service/

And with such an approach, two things stand out immediately:

domain is used even though it's a DDD (Domain-Driven Design) term, and is never used by Alistair in his writings, where he uses the term Application;

"The application is everything on the inside, everything that isn't technology-specific."

everything ends up public so that each element can access whatever it needs to function.

And this last point is the most problematic. The whole purpose of having an inside and an outside is that what's on the inside, and has no reason to leak out, stays there. Yet with this keyword, everything that should remain internal becomes accessible to any adapter.

Now, if article 1 showed one thing, it's that it is possible to swap an adapter on the fly with zero impact on the application, simply because it doesn't know and doesn't care.

"Remember, in Ports & Adapters you are free to organize the inside of the app in any way you like, and the things outside the app in any way you like. Just put ports in place."

Right, just put ports in place. But what are they exactly?

There are two types of ports that are important to explain in order to properly understand their role.

Primary ports

These ports represent the way the application wants to be talked to, meaning that any adapter talking to a primary port becomes by definition a primary adapter and follows a precise protocol.

As Alistair puts it:

"The protocol for a port is given by the purpose of the conversation between the two devices. The protocol takes the form of an application program interface (API)."

In the case of primary ports, this protocol represents the action that the adapter wants to see executed when it uses the application.

Except that when we look at articles, conference talks, and tutorials, this protocol often boils down to a Java interface. And worse, that interface tends to become a catch-all.

Yet in the updated edition of Hexagonal Architecture Explained (2025), Alistair explains that a port can be either an interface or a class.

"In your life, decide which way you prefer to write."

In this implementation, primary ports are concrete final classes that represent the API, and offer a protocol that makes the conversation between the adapter and the application explicit.

Secondary ports

On their side, secondary ports remain interfaces in the Java sense.

The reason is simple:

"A port identifies a purposeful conversation. There will typically be multiple adapters for any one port, for various technologies that may plug into that port."

The application sets up a conversation with an adapter it knows nothing about. If the application used anything other than an interface, it would mean that it becomes part of the implementation, breaking the boundary.

What about the rest of the application?

While ports are perfectly justified in being public, the same is not true for all the other elements that make up the application.

This brings us back to the point raised earlier: primary and secondary adapters can only use what the application allows them to use, for the sake of the conversations/protocols.

Except that this aspect is only reinforced if adapters rely solely on the defined conversation, not on the hallway rumors that an unfortunate keyword made public.

But how do we protect the inside?

This is where Simon Brown enters the scene

In "The Missing Chapter" of the book "Clean Architecture", Simon Brown offers a different approach, in opposition to the layered approach as well as, indeed, Ports & Adapters.

But what if, instead of opposing them, the application used both in a complementary way, P&A protecting from adapters, Brown protecting from itself?

Where P&A provides the boundaries protecting the application, package-by-component provides the internal organization it lacks.

The idea is simple: instead of organizing code by technical layer (model/, port/, service/), code is organized by use case and component. Java's package-private becomes the default visibility level: what has no reason to be public is not.

In the example code, the application itself is the component, turning package-by-component into package-by-use-case: the same idea applied at the right level of granularity.

Here is the application's organization, with brief explanations of each element:

be.charleshornick.supra
├── ErrorCause.java                         # cross-cutting error constants
├── ForStoringSnapshot.java                 # secondary port, shared across use cases
│
├── create/                               # use case: create a character
│   ├── CreateCharacter.java                # primary port (public final)
│   ├── ForCheckingNameUnicity.java         # secondary port (specific)
│   ├── Character.java                      # package-private
│   └── CharacterNameValidator.java         # package-private
│
├── define/                                 # use cases: modify an existing character
│   ├── ForLoadingSnapshot.java             # secondary port, shared within define/
│   ├── ToCharacter.java                    # step interface, shared within define/
│   ├── race/
│   │   ├── DefineRace.java                 # primary port (public final)
│   │   ├── ForLoadingRace.java             # secondary port (specific)
│   │   ├── DefineRaceStep.java             # package-private
│   │   └── Character.java                  # package-private
│   ├── profession/
│   │   ├── DefineProfession.java           # primary port (public final)
│   │   ├── ForLoadingProfession.java       # secondary port (specific)
│   │   ├── DefineProfessionStep.java       # package-private
│   │   └── Character.java                  # package-private
│   └── characteristic/
│       ├── DefineCharacteristic.java        # primary port (public final)
│       ├── AddOnePoint.java                 # package-private (step builder)
│       ├── RemoveOnePoint.java              # package-private (step builder)
│       └── Character.java                   # package-private
│
├── retrieve/                                # use cases: read data
│   ├── race/
│   │   ├── ForGettingRaces.java             # secondary port (specific)
│   │   ├── GetAllRaces.java                 # primary port (public final)
│   ├── profession/
│   │   ├── ForGettingProfessions.java       # secondary port (specific)
│   │   ├── GetAllProfessions.java           # primary port (public final)
│   └── snapshot/
│       ├── ForGettingSnapshot.java          # secondary port (specific)
│       ├── GetAllSnapshots.java             # primary port (public final)
│       └── GetLatestSnapshot.java           # primary port (public final)
│
├── race/                                    # vocabulary: what a race IS
│   ├── Race.java
│   └── RaceName.java
├── profession/                              # vocabulary: what a profession IS
│   ├── Profession.java
│   ├── ProfessionName.java
│   ├── ProfessionType.java
│   └── Prerequisite.java
├── characteristic/                          # vocabulary: what a characteristic IS
│   ├── PrimaryCharacteristic.java
│   └── PrimaryCharacteristicName.java
└── snapshot/                                # state management internals
  ├── Snapshot.java
  ├── SnapshotBuilder.java
  ├── Action.java
  ├── Recorder.java
  ├── CreationPoint.java
  ├── CreationPointConsumer.java
  └── InvestedPoint.java

Two categories of packages are visible:

actions (create/, define/, retrieve/) describing what can be done;
vocabulary (race/, profession/, characteristic/, snapshot/) describing what things are.

The first contains all the business logic, hidden behind package-private, while the second contains the shared types that define the application's language.

This isolation by use case keeps the risk of side effects as low as possible, since each internal element serves only its own case.
This fits within the principle of code cohesion: what changes together lives together. Modifying a use case touches only a single package.

Let's take a concrete example of what this isolation brings: the Character class is present in all 3 sub-packages of define/ but its role is different each time.

Following the organization model mentioned earlier, a single class would have existed in models/ and would have exposed as many methods as there are use cases.

There is nothing wrong with this, but modifying that class for one use case risks breaking the others. Brown's approach makes that impossible.

Now that the structure is in place, let's look at what's inside, starting with what stands out in the tree: the port names.

Port naming

As mentioned earlier, Alistair explains that ports have precise conversations with adapters.

A secondary port represents the request that the use case makes to the outside world. To reflect this, I followed the naming convention promoted by Cockburn: ForDoingSomething.

Each secondary port starts a conversation with a specific need, an action it wants to see carried out. These ports are however not placed in a fixed package but as close as possible to where they are used.

For instance, ForCheckingNameUnicity is in the character creation package because that's the only place where it's used. Conversely, ForLoadingSnapshot is at the root of the define/ action because it's used by all of its sub-packages.

Secondary ports are functional interfaces to allow finer granularity in conversations. These secondary ports do not, and cannot, have default methods for the reasons discussed earlier.

On their side, primary ports don't request, they are the actions themselves, and expose them through protocols. Their naming reflects this: each step in the protocol is explicit in order to form a clear protocol.

But naming is not the only reason for setting up protocols this way, this writing also guarantees at compile time that the port is correctly called.

The Step Builder reinforces the protocol

Let's take the following example:

defineCharacteristic
    .byAddingOnePoint()
    .toCharacteristicNamed(CharacteristicName.COURAGE)
    .toCharacterNamed("Borgrim");

Each step refines the protocol by making it more precise about the action it will perform. The action reads naturally: define a characteristic by adding one point to the one named courage, on the character named Borgrim.

But most importantly, it is impossible to call it in a different order, the compiler will automatically block anything that is not explicitly allowed by the protocol.

To guarantee this, the Step Builder pattern is used. Looking at DefineCharacteristic, we can see that two methods are exposed: byAddingOnePoint and byRemovingOnePoint, each returning a new instance of a package-private class implementing DefineCharacteristic.ToCharacteristic.

Since the return type of these methods is DefineCharacteristic.ToCharacteristic, the next available method is necessarily toCharacteristicNamed(String).

Furthermore, that same method returns the ToCharacter interface, which the same package-private classes implement, completing the protocol without ever allowing to bypass the protocol's defined behavior.

public final class DefineCharacteristic {

    public interface ToCharacteristic {
        ToCharacter toCharacteristicNamed(PrimaryCharacteristicName characterName);
    }

    private final ForLoadingSnapshot forLoadingSnapshot;
    private final ForStoringSnapshot forStoringSnapshot;

    public DefineCharacteristic(final ForLoadingSnapshot forLoadingSnapshot, final ForStoringSnapshot forStoringSnapshot) {
        this.forLoadingSnapshot = forLoadingSnapshot;
        this.forStoringSnapshot = forStoringSnapshot;
    }

    public ToCharacteristic byAddingOnePoint() {
        return new AddOnePoint(this.forLoadingSnapshot, this.forStoringSnapshot);
    }

    public ToCharacteristic byRemovingOnePoint() {
        return new RemoveOnePoint(this.forLoadingSnapshot, this.forStoringSnapshot);
    }
}

This approach goes further than simply enabling protocol-like writing: the port is singleton and stateless.

Indeed, each call to the exposed methods creates a new ephemeral step instance, making the pattern thread-safe. Since the instance only lives for the duration of the call, it is immediately collected by the garbage collector once the call ends.

Note that the Step Builder Pattern is not systematic.

createCharacter.named("Borgrim");

Here, the method exposed by the port is sufficient for the protocol. The pattern serves the application, not the other way around.

A note on `Result<T>`

While going through the code, you will have noticed that ports systematically return Result<T>, and that tests use .onSuccess() and .onFailure().

I use the Pragmatica library (Apache 2.0, Java 25+) to never throw exceptions in the application. This choice considerably simplifies error handling and testing, but it's a rich enough topic to deserve its own article in this series.

Testability

One of the direct benefits of this organization is testability. The application is pure POJO, no framework is needed to test it.

Since secondary ports are functional interfaces, a lambda is all it takes to create a fake:

@Test
@DisplayName("Succeed when the name is available")
void succeedWhenNameIsFreeToUse() {
    new CreateCharacter(_ -> true, Result::ok)
            .named("Borgrim")
            .onSuccess(snapshot ->
                assertThat(snapshot).isEqualTo(SnapshotFixture.getDefaultOne()))
            .onFailure(cause ->
                fail("Cannot create new character: " + cause.message()));
}

_ -> true means the name is available. Result::ok means storage always succeeds. No Mockito, no mock framework, no when().thenReturn().
The behavior is explicit, readable, and verified at compile time: if a port's signature changes, the lambda breaks, whereas a Mockito mock can keep compiling silently.

The Step Builder is tested the same way:

new DefineRace(forLoadingSnapshot, forStoringSnapshot, forLoadingRace)
        .named(RaceName.ELF)
        .toCharacterNamed("Borgrim")
        .onSuccess(snapshot -> assertEqualsAgainst(snapshot, expected))
        .onFailure(cause -> fail("Failed to define new race: " + cause.message()));

No setup, no teardown, no Spring context to load. We instantiate the port with fakes, call the protocol, verify the result. The test reads like a specification.

The complete testing approach, including sharing scenarios between unit tests and integration tests, will be detailed in article 4.

The honest trade-off: `public` betrays us

Everything shown so far works:

package-private hides internal elements;
the Step Builder enforces the protocol;
ports are final;
no framework infiltrates the application.

But there is a hole because primary port constructors are public:

public final class CreateCharacter {

    public CreateCharacter(
        final ForCheckingNameUnicity forCheckingNameUnicity,
        final ForStoringSnapshot forStoringSnapshot) {
        // ...
    }
}

And this is intentional, it has to be. A composition root, which will live in another package and in another module, will need to instantiate this class and inject the secondary port implementations. Without a public constructor, that's not possible.

Except that also means any adapter can bypass the intended wiring and do:

var rogue = new CreateCharacter(myOwnChecker, myOwnStorage);

The same problem exists for SnapshotBuilder. It is public because the Character classes, which are package-private in each sub-package of define/, need to call it from their doSnapshot() methods.
Different packages, so public is mandatory. And yet, no adapter has any legitimate reason to touch SnapshotBuilder.

Java's visibility model gives us two options: public (everyone sees it) and package-private (only the same package sees it), there is nothing in between. No way to say "this constructor is visible only to that module" or "this class is only accessible from within the application."

Brown's approach with package-private covers a good portion of the isolation we need. The rest, such as public constructors and shared utility classes, remain exposed.

This is a limitation of the language, not of the pattern.

Trade-offs

No approach is perfect, and organizing by use case with Ports & Adapters comes with its own set of trade-offs to be aware of.

The number of files increases

Each use case has its own package with its own Character class, its own step builder, its own ports. Navigating the IDE requires familiarity with the structure to find things quickly.

The learning curve exists

Developers used to service/ and repository/ packages need to shift their mental model. The separation between actions and vocabulary is not intuitive for everyone at first.

Risk of application rigidity

Applied indiscriminately, the approach can become rigid. A trivial use case, like a simple read that passes straight through to the secondary port, does not necessarily justify a dedicated package with four classes.

Risk of duplication

Two use cases that would need the same internal type must either extract it into a vocabulary package, or accept code duplication.

These trade-offs are real and should be weighed carefully. But they should be balanced against the alternative: a domain/ package where everything is public, where nothing is enforced, and where the isolation promise of Ports & Adapters relies solely on the team's good will.

Conclusion

Cockburn protects the application from the outside world. Brown protects the application from itself. Together, they offer an application that is structured, isolated, and testable without any framework.

But Java leaves us a hole: the public keyword is a master key that cannot be revoked at the package level. Internal classes that should only be used within the application are accessible to everyone.

We need an enforcement mechanism beyond package-private.

That's the subject of article 3: JPMS.

The example application implements an RPG character creation system with real business rules: creation, race and profession definition with bidirectional constraints, and point investment in primary characteristics with race-dependent limits.

Tech stack: Java 25, Pragmatica (Result<T>, Option<T>), JUnit 6, AssertJ, Maven. No Spring. No framework. No annotations.

Source code: GitHub — article/2-package-by-component

The architectural decisions in this series are grounded in Cockburn's original 2005 article and in Hexagonal Architecture Explained (Cockburn & Garrido de Paz, updated 1st edition, 2025).

Runtime Adapter Hot-Swapping with Ports & Adapters - The Pattern Alistair Cockburn Didn't Document

Charles Hornick — Thu, 12 Feb 2026 21:07:44 +0000

Series — Ports & Adapters: Beyond the Theory

Runtime Adapter Hot-Swapping ← you are here
Organizing the Application with Package-by-Component
Isolating with JPMS
No Exceptions: Result<T> with Pragmatica (coming soon)
Testing in P&A (coming soon)
Architecture-Driven AI Development (coming soon)
Adapter Switching Strategies (coming soon)
Spring Modulith + P&A (coming soon)

When Alistair Cockburn described the Hexagonal Architecture in 2005, he documented adapter interchangeability as a core property of the pattern. In Chapter 5 of his work, he writes:

"For each port, there may be multiple adapters, for various technologies that may plug into that port."

But the original pattern leaves something open: what happens when you need to switch adapters at runtime, across a distributed system, in response to a failure, and before other instances encounter the same problem?

This article presents a concrete implementation of emergency adapter hot-swapping using Spring Boot 4, Spring Cloud Bus, and Resilience4j. When one service instance detects a failing adapter, it broadcasts the failure via a message bus. All other instances switch to a fallback adapter before they encounter the timeout themselves.

Cockburn's reaction when I explained the concept on LinkedIn:

"Fabulous! I got around to documenting live swaps for long-running systems, but didn't dare think about emergency hot-swapping — thank you!"

The problem

Consider a standard Ports & Adapters setup where your domain service talks to an upstream API through an adapter. When that API starts timing out, every instance of your service will independently discover the failure, each burning through its own timeout window.

With 10 instances and a 3-second timeout, you're looking at 30 seconds of cumulative degraded experience across your cluster, at minimum. In practice, retries, thread pool saturation, and cascading failures make this much worse.

The standard circuit breaker pattern (Hystrix, Resilience4j) solves this per instance: each service independently opens its circuit after detecting failures. But there's no coordination. Instance 7 doesn't know that instance 1 already hit the timeout 2 seconds ago.

The solution: broadcast-driven adapter switching

The key insight: the first instance to detect a failure should warn all others.

Instance 1: timeout detected → broadcast "switch to fallback"
Instance 2: receives event → switches adapter (never hits the timeout)
Instance 3: receives event → switches adapter (never hits the timeout)
...
Instance N: receives event → switches adapter (never hits the timeout)

This is eventual consistency applied to infrastructure. The adapter state propagates across the cluster asynchronously, and every instance converges to the same adapter within milliseconds of the first detection.

Implementation

Full source code: github.com/charles-hornick/adapter-hotswap-spring

The Port

Nothing special here, just a standard port interface:

public interface AnimalPort {
    String getAnimal();
    String name();
}

The Adapter Registry

The critical piece. An AtomicReference holds the active adapter, making the swap lock-free and thread-safe:

@Component
public class AdapterConfig {

    private final Map<String, AnimalPort> adapters;
    private final AtomicReference<AnimalPort> activeAdapter;

    public AdapterConfig(
            @Qualifier("primaryAdapter") final AnimalPort primary,
            @Qualifier("fallbackAdapter") final AnimalPort fallback) {
        this.adapters = Map.of("primary", primary, "fallback", fallback);
        this.activeAdapter = new AtomicReference<>(primary);
    }

    public AnimalPort getActiveAdapter() {
        return activeAdapter.get();
    }

    public boolean switchTo(String adapterName) {
        final var target = adapters.get(adapterName);
        final var previous = activeAdapter.getAndSet(target);
        return !previous.name().equals(adapterName);
    }
}

The swap is a single atomic operation. Threads currently executing a request through the old adapter will finish their call; new requests immediately use the new adapter. No locks, no synchronized blocks.

Timeout detection + broadcast

The service layer wraps adapter calls with Resilience4j's TimeLimiter. On timeout, it publishes a custom Spring Cloud Bus event:

@Service
public class AnimalService {

    private final AdapterConfig adapterConfig;
    private final ApplicationEventPublisher publisher;
    private final BusProperties busProperties;
    private final TimeLimiter timeLimiter;
    private final ExecutorService executor;

    public AnimalService(final AdapterConfig adapterConfig,
                         final ApplicationEventPublisher publisher,
                         final BusProperties busProperties) {
        this.adapterConfig = adapterConfig;
        this.publisher = publisher;
        this.busProperties = busProperties;

        this.timeLimiter = TimeLimiter.of(
                TimeLimiterConfig.custom()
                        .timeoutDuration(Duration.ofSeconds(3))
                        .cancelRunningFuture(true)
                        .build()
        );

        this.executor = Executors.newVirtualThreadPerTaskExecutor();
    }

    public String getAnimal() {
        final var adapter = adapterConfig.getActiveAdapter();
        try {
            final var future = executor.submit(adapter::getAnimal);
            return timeLimiter.executeFutureSupplier(() -> future);
        } catch (final Exception e) {
            // First instance to detect failure → broadcast to all
            publisher.publishEvent(new AdapterSwitchEvent(
                this, busProperties.getId(), "**", "fallback"
            ));
            return adapterConfig.getActiveAdapter().getAnimal();
        }
    }
}

Key decisions:

Virtual threads (Executors.newVirtualThreadPerTaskExecutor()) - Java 25's virtual threads keep the timeout wrapper lightweight. No platform thread blocking.
"**" destination - the bus event targets all services, not a specific instance.
Immediate local fallback - after broadcasting, the current request falls back locally without waiting for the bus round-trip.

The Bus Event

A custom RemoteApplicationEvent that carries the target adapter name:

public class AdapterSwitchEvent extends RemoteApplicationEvent {

    private final String targetAdapter;

    public AdapterSwitchEvent(final Object source,
                              final String originService,
                              final String destinationService,
                              final String targetAdapter) {
        super(source != null ? source : new Object(), originService, () -> destinationService != null ? destinationService : "**");
        this.targetAdapter = targetAdapter;
    }

    // getter
}

Spring Cloud Bus serializes this to JSON, pushes it to RabbitMQ, and every connected instance receives it. The listener on each instance performs the swap:

@EventListener
public void onAdapterSwitch(final AdapterSwitchEvent event) {
    adapterConfig.switchTo(event.getTargetAdapter());
}

Recovery detection

A scheduled health checker pings the primary service and broadcasts a switch-back when it recovers:

@Scheduled(fixedDelayString = "${health.check.interval:5000}")
public void checkPrimaryHealth() {
    if ("primary".equals(adapterConfig.getActiveAdapterName())) {
        return; // already on primary, nothing to check
    }
    try {
        String response = restClient.get().uri("/health")
            .retrieve().body(String.class);
        if ("UP".equals(response)) {
            publisher.publishEvent(new AdapterSwitchEvent(
                this, busProperties.getId(), "**", "primary"
            ));
        }
    } catch (Exception e) {
        // still down, do nothing
    }
}

Running the demo

bashgit clone https://github.com/charles-hornick/adapter-hotswap-spring.git
cd adapter-hotswap-spring
docker-compose up --build

The demo runs two instances of the hotswap service, a flaky primary service (cyclic timeouts), and a stable fallback. Watch the logs for:

Response: Chien          ← primary adapter
Response: Chien
EVENT: Primary adapter timeout — broadcasting switch to fallback
EVENT: Switching adapter from 'primary' to 'fallback'
(instance 2) EVENT RECEIVED: Switch to 'fallback'
Response: Chat            ← fallback adapter
HEALTHCHECK: Primary adapter responding again
EVENT: Switching adapter from 'fallback' to 'primary'
Response: Chien          ← back to primary

Instance 2 switches without ever experiencing the timeout.

Limitations and trade-offs

This is a demo, not a production framework. Real-world considerations:

Split-brain risk. If RabbitMQ is partitioned, instances may diverge on which adapter is active.
Mitigation: use a consensus mechanism or accept eventual convergence via the health checker.

Thundering herd on recovery. When the health checker broadcasts "switch back to primary", all instances hit the primary simultaneously.
Mitigation: add jitter to the health check interval, or use a canary approach where only one instance switches back first.

Single point of decision. Whichever instance first detects the failure makes the decision for the entire cluster. If that detection is a false positive (network blip), the whole cluster switches unnecessarily.
Mitigation: require N consecutive failures before broadcasting, or use a quorum-based decision.

Bus latency. There's a window between the broadcast and reception where other instances may still hit the failing adapter. This is inherent to eventual consistency. For most use cases, the RabbitMQ propagation delay (typically <100ms) is negligible compared to a 3-second timeout.

No adapter state persistence. If an instance restarts, it defaults back to the primary adapter regardless of the cluster state.
Mitigation: persist the adapter state in a shared store (Redis, database) or replay the latest bus event on startup.

When to use this

This pattern is most valuable when:

You have multiple instances of the same service
Adapter failures are detectable (timeout, HTTP 5xx, connection refused)
The cost of independent failure detection across instances is significant
You have a viable fallback adapter (degraded service, cache, alternative provider)

It's overkill for single-instance deployments or when failures are so rare that independent circuit breakers suffice.

Relation to Cockburn's original work

The Hexagonal Architecture describes adapters as interchangeable, so you can swap a database adapter for an in-memory adapter, or a REST adapter for a gRPC adapter. But the original pattern is silent on when and how this swap happens at runtime.

This implementation extends the pattern in two directions:

Runtime swapping - adapters switch while the system is running, without restart or redeployment.
Cluster-wide coordination - the swap propagates across all instances, turning a local failure detection into a global infrastructure decision.

The adapter remains a first-class architectural concept. We're just giving it operational capabilities that the original pattern implied but never specified.

Source code: github.com/charles-hornick/adapter-hotswap-spring

Stack: Java 25, Spring Boot 4.0.2, Spring Cloud 2025.1.0, Resilience4j 2.3.0, RabbitMQ

Charles Hornick - Java consultant specializing in smart refactoring and legacy application rescue. charles-hornick.be

DEV Community: Charles Hornick

Ports & Adapters: Beyond the Theory - Isolating the Application with JPMS

Recap: where article 2 left us

JPMS refresher

Reorganizing the snapshot package

The application module

Why exports are not qualified

Adapters enter the scene

The primary adapter

The faked secondary adapter

The Composition Root

Composition root module-info.java

Test adapter module-info.java

The trap: opens ... to

@Transactional does not belong in the application

The honest trade-off: the public constructor survives

JPMS trade-offs

module-info.java complexity

Tooling not always module-friendly

More constrained tests

Spring Boot and JPMS

Conclusion

Ports & Adapters: Beyond the Theory - Organizing the Application with Package-by-Component

The application is not protected

Primary ports

Secondary ports

What about the rest of the application?

This is where Simon Brown enters the scene

Port naming

The Step Builder reinforces the protocol

A note on Result<T>

Testability

The honest trade-off: public betrays us

Trade-offs

The number of files increases

The learning curve exists

Risk of application rigidity

Risk of duplication

Conclusion

Runtime Adapter Hot-Swapping with Ports & Adapters - The Pattern Alistair Cockburn Didn't Document

The problem

Implementation

The Port

The Adapter Registry

Timeout detection + broadcast

The Bus Event

Recovery detection

Running the demo

Limitations and trade-offs

When to use this

Relation to Cockburn's original work

Reorganizing the `snapshot` package

Composition root `module-info.java`

Test adapter `module-info.java`

The trap: `opens ... to`

`@Transactional` does not belong in the application

The honest trade-off: the `public` constructor survives

`module-info.java` complexity

A note on `Result<T>`

The honest trade-off: `public` betrays us