Hexagonal Architecture for Beginners

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.

Advantages

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

Implementation

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):

@Service
public class OrderService {

    private static int MAJOR_UNIT_CUTOFF = 1000;

    @Autowired
    private OrderDao dao;

    public void create(int unitCount) {
        dao.save(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);
    }
}

@Entity
@Table(name = "order_table")
@Data
public class Order {

    @Id
    @GeneratedValue
    @Column
    private int id;

    @Column
    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):

@Service
public class OrderDaoImpl implements OrderDao {

    @PersistenceContext
    private EntityManager em;

    @Transactional
    @Override
    public void save(int unitCount) {
        Order order = new Order();
        order.setUnitCount(unitCount);
        em.persist(order);
    }

    @Override
    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.

Test

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.

@RunWith(SpringRunner.class)
@SpringBootTest
public class OrderServiceTest {

    @InjectMocks
    private OrderService service;

    @Mock
    private OrderDao dao;

    @Test
    public void whenUnitCountGreaterThenHundred_thenOrderIsMajor() {
        Order majorOrder = new Order();
        majorOrder.setUnitCount(1001);
        doReturn(majorOrder).when(dao).get(1);

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

    @Test
    public void whenUnitCountLessThenHundred_thenOrderIsNotMajor() {
        Order notMajorOrder = new Order();
        notMajorOrder.setUnitCount(1000);
        doReturn(notMajorOrder).when(dao).get(1);

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

Conclusion

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.