Hexagonal Architecture

This article is a guide showing my point of view of the Hexagonal Architecture to implement in Java with the Spring Framework. This Architecture can be useful to create microservices, indeed from it came a lot of other DDD Architectures like Onion or Clean Architecture they took the basic layout and adds their flavours.

Presentation

The Hexagonal Architecture also known as “Ports and Adapters Pattern” has a very tricky name, that’s because it does not refer to a particular layout or scaffolding that we have to follow for our code. Its name came from a visual reminder for what a port is indeed, since the first computers came with several ports to connect with other devices. These ports had a shape like a Hexagon, if you use a little imagination and be accomplice with the author.

Here is a Serial Port and a VGA Port

When Alistair Cockburn wrote the first paper about the pattern, he attempts to: “Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases.”

But how do we implement this in Java and don’t die trying? First we need to understand what is a port and then what is an adapter.

A port is an interface, on the strict meaning of the word, please don’t think about an interface on Java. It’s an endpoint to allow us to consume or expose information to the outside. An adapter is a mechanism to translate the information from a device to the port.

Analogy

For example, a Video Card has many ports, but for now we need to think it has a VGA port, so we bought a new monitor and it came with only an HDMI port. Our Application is the whole Computer and their video cards is one of his domains. The Video Card Domain has ports to communicate with the outside (Infrastructure), but we need an adapter to translate the analog signal on a digital signal for the HDMI. Here comes the adapter to allow us to connect the computer to monitor and enjoy our games. So the video card sends the signal through a port to the adapter, and receives the data to show on the screen. The adapter is part of the infrastructure.

Diagrams

So we can take these concepts and use it to start fitting into Domain Driven Design for our project.

In a first approach of the original conception from the author, the hexagonal architecture may be segregated in three parts, the application, the primary ports/adapters and secondary ports/adapters. The differences between primary and secondary ports/adapters is that in the first one the app is driving or delivering the data to the outside actors and the second ones drives data from outside actors.

So we can take these concepts and use it to start fitting into Domain Driven Design for our project.

Now the Application is what our project exposes to the outside, the API (Application Program Interface), here we can put our rest api endpoints, websockets, exports data endpoints and all stuff that we need to deliver to the front-end or other consumers. The Domain is the core of the project and represents the business rules and main data structures. And finally in the infrastructure layer,The SPI (Server Provider Interface), contains all the mechanisms that we need to consume or persist data, such as repositories or calls to other apis.

Explanation

If we are using Spring in our project, we need to create a folder or package for each aggregate, an aggregate is a domain concept taken like a single unit. So we need into this folder or package, two more, the data and services packages. The data packages contain the class that represents data structure to be manipulated for the services, and the service is the business rules for our domain.

Into the services we declare a port to be instantiated by a factory pattern with adapter that allows it to persist or consume information. With Spring we don’t need to be worried to create the factory for the adapters, we use the dependency injection provided by the framework to instantiate the adapters, the adapter must be defined like a Component to this works fine.

Into the application package we need an Api port, in this case the controllers for our services. Also we may need DTO (Data Transfer Objects) to translate the request parameters to a Data class from the domain layer. Here, may you ask for the adapters? Where is it? The adapter is given by the framework through the request mapping annotation. It handles client requests to the right port method to call the service.

Finally we arrive at the infrastructure package, it contains the entities and their repository for database persistence, the mappers to map our data classes to entities and the adapters to handle the data to connect to outside resources. Also there is a config folder to place all the configuration for our project.