Hexagonal Architecture in Java

DZone 's Guide to

Hexagonal Architecture in Java

In this article we discuss the benefits of hexagonal architecture and how to implement it with a simple example in Java.

· Java Zone ·
Free Resource


Hexagonal Architecture is a software architecture that allows an application to be equally driven by users, programs, automated tests, or batch scripts and to be developed in isolation from its run-time target system. The intent is to create an application to work without either a User Interface or a database so that we can run an automated regression test against the application, work with an application when a run-time system, such as a database is not available, or integrate applications without user interface.


Many applications have two ends: a user-side and server-side, often designed in two, three, or n-layers architecture. The main problem with n-layered architecture is the layer lines are not taken seriously, causing application logic to leaks across the boundaries. This entanglement between the business logic and the interaction makes it impossible or difficult to extend or maintain the application. 

For instance, adding a new attractive UI to support new devices could be a tough task when the application business logic is not completely isolated in its own boundary. In addition, applications can have more than two sides that make it more difficult to fit well in one-dimensional layer architecture, as shown below.

Three-Layer vs Hexagonal architecture

The hexagonal, or ports and adapters or onion architecture, solves these problems. In this architecture, the application in the inside communications over some number of ports with systems on the outside. Here, the term hexagonal itself is not important, rather it demonstrates the effect to insert ports and adapters as needed in the application in a uniform and symmetric way. The main idea is to isolate the application domain by using ports and adapters.

Organizing Code Around Ports and Adapters

Let's build a small anagram application to show how to organize code around ports and adapters to represents the interaction between inside and outside the application. On the left, we have an application, such as console or REST and inside is the core business logic or domain. The anagram service takes two Strings and returns a Boolean corresponding to whether or not the two String arguments are anagrams of each other. On the right, we have the server-side or infrastructure, for instance, a database for logging metrics about service usage.

Anagram application architecture

The Anagram application source code below shows how the core domain is isolated inside and ports and adapters are provided to interact with it.

Domain Layer

The domain layer represents the inside of the application and provides ports to interact with application use cases.

  • IAnagramServicePort interface defines a single method that takes two String words and returns a boolean.
  • AnagramService implements the IAnagramServicePort interface and provides business logic to determine whether or not the two String arguments are anagram. It also uses the IAnagramMetricPort to output the service usage metric to server-side run-time outside entities such as a database.

Application Layer

The application layer provides different adapters for outside entities to interact with the domain. The interaction dependency goes inside.

  • ConsoleAnagramAdaptor uses the IAnagramServicePort to interact with the domain inside the application.
  • AnagramsController also uses the IAnagramServicePort to interact with the domain. Similarly, we can write many more adaptors to allow various outside entities to interact with the application domain.

Infrastructure Layer

Provide adapters and server-side logic to interact with the application from the right side. Server-side entities, such as a database or other run-time devices, use these adapters to interact with the domain. Note the interaction dependency goes inside.

Outside Entities Interacting With the Application

The following two outside entities use adapters to interact with the application domain. As we can see, the application domain is completely isolated and equally driven by them regardless of external technology.

Here's a simple console application interacting with the application domain using an adapter:


Here's an example of a simple test script mocking the user interaction with the application domain using a REST adapter.



Using ports and adapters, the application domain is isolated at the inner hexagon, and it can be equally driven by a user or automated test scripts regardless of the external system or technology.

adapter ,application layer ,architechture ,domain layer ,hexagonal architecture ,infrastructure layers ,java ,port ,tutorial

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}