Hexagonal Architecture in Java
A practical example of the pattern principles in Java.
In this short article, we will show with a practical example the usage of the Hexagonal Architecture pattern. The following content is not a comprehensive guide. Rather an illustration of the approach, and implementation of the pattern principles in Java.
The Hexagonal Architecture (or Ports and Adapters) was initially proposed by Alistair Cockburn. The main goal of this architecture is to avoid knows structural pitfalls in software design. Such as the pollution of UI code with business logic or undesired dependencies between layers. Therefore it aims at creating loosely coupled components that can be connected to their software environments using “ports” and “adapters” (see Image 1). As a result, this makes components replaceable at any level and facilitates the testability of the single parts.
Definition
The word “port” is supposed to evoke thoughts of “ports” in electronic gadgets. Where you can plug in any device that fits the mechanical and electrical protocol. For each external device, there is an ‘’adapter’’ that converts the protocol needed by that device and vice versa. Likewise you should think of adapters as the glue between application components and the outside world. Hence there may be multiple adapters for one single port. Most noteworthy is that all external devices are identical from the perspective of the application.
You should not fall into the intuition trap of thinking that there is a meaning in the “hexagonal” word or drawing. The purpose was not to suggests that there needs to be six ports or adapters. Rather the intention is to leave you enough space to depict the different interfaces between the application and the external world. Therefore the term comes from this visual effect.
The natural counterpart of a port in Java is an interface. Likewise the adapter is one implementation of that interface.
Example
As an example we consider an application that stores books. For the sake of simplicity, you can only search for already saved books. The books can be stored in a DB and searchable through an API (HTTP, Browser, …). You can see in the image below a Java implementation of the mentioned example.
First, we define the domain entity of our application:
Consequently, we define the equivalent of an inbound Port:
We now define the outbound port:
Next, we implement the previously defined outbound port. Thus the equivalent of an Adapter:
Similarly, you can see an alternative Adapter for the same interface:
We now define a domain service for our application:
Finally, we provide an adapter for the inbound Port:
Conclusion
First of all, if you follow the pattern principles you will have better “flexibility” at replacing the various dependencies. Finally you will also increase the overall “testability” of the application.
