Hexagonal Architecture for Beginners

DZone 's Guide to

Hexagonal Architecture for Beginners

Want to learn more about the hexagonal architecture?

· Java Zone ·
Free Resource

The hexagonal architecture is one more approach to create maintainable software solutions (and it can be one more way to shoot yourself in the foot). The main idea is to separate core logic (business logic and domain) from frameworks. Usually, the first part is called inside and the last one is called outside. Inside provides a port to communicate with it, and at the same time, outside provides the implementation of this port called the adapter. This is why this particular development style has another name — the ports and adapters architecture.


  • Ability to support multiple channels
  • Flexibility in choice of channels
  • Easy testing of core logic by the mock outside part


Speaking of this implementation style in Java, it is easy to imagine that the classic interface plays a role in the port. Therefore, the adapter (the outside part) is the implementation of the current interface. This concept will be shown in the following simple Spring Boot application that will simulate the work of some stock (add/get some orders). The core of our app consists of business logic (OrderService) and the domain part (Order):

public class OrderService {

    private static int MAJOR_UNIT_CUTOFF = 1000;

    private OrderDao dao;

    public void create(int unitCount) {

    public boolean isMajor(int id) {
        Order order = getById(orderId);
        return order.getUnitCount() > MAJOR_UNIT_CUTOFF;

    public Order getById(int id) {
        return dao.get(id);
@Table(name = "order_table")
public class Order {

    private int id;

    private int unitCount;

Of course, it is a far-fetched example, but I suppose it helps to understand the concept in a simple way. As I previously said, our inside part should offer a port to integrate with it. In this specific case, our port is  OrderDao:

public interface OrderDao {
    void save(int unitCount);
    Order get(int id);

In this way, all repositories (the outside part) implement this interface and can be integrated with our inside part. Let us consider a simple one (OrderDaoImpl):

public class OrderDaoImpl implements OrderDao {

    private EntityManager em;

    public void save(int unitCount) {
        Order order = new Order();

    public Order get(int id) {
        return em.find(Order.class, id);

Thus, we have a typical example of a pair (port, adapter) = (OrderDao , OrderDaoImpl), which is a major concept of the hexagonal architecture.


As was mentioned previously, a pleasing benefit of considering this architecture style is that it is easy to test the business logic of our software with mock integration points. You can see that "complex" business logic lays in the isMajor(int id) method of our OrderService. Let us mock OrderDao and test this logic.

public class OrderServiceTest {

    private OrderService service;

    private OrderDao dao;

    public void whenUnitCountGreaterThenHundred_thenOrderIsMajor() {
        Order majorOrder = new Order();

        assertEquals(true, service.isMajor(1));

    public void whenUnitCountLessThenHundred_thenOrderIsNotMajor() {
        Order notMajorOrder = new Order();

        assertEquals(false, service.isMajor(1));


The hexagonal architecture offers efficient tools (ports/adapters) to isolate the business logic of our application from outside elements. Additionally, it leads to flexibility in the testing of our app and enhances the number of possible integration points.

Example code from this post can be found over on GitHub.

adapter, example, hexagonal architecture, integration, integration points, java, port, spring boot, spring boot app, tutorial

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}