Code Fountain
Published in

Code Fountain

A quick introduction to Hexagonal Architecture

In this article, we will discuss Hexagonal architecture. It is an architectural style that divides an application into an inside and outside part.

Figure: Hexagonal Architecture

1. Overview

In classic n-tier architecture, an application consists of several conceptual layers. In contrast, Hexagonal architecture intends to shift the focus towards a different direction. It uses the notion of the inside and outside part of an application. The inside part represents the domain layer or the core business logic. Whereas, the outside part consists of possible interaction points of the application.

This architectural style uses a notion of port and adapter. Thus, it is also referred to as Ports and Adapters. Port is an abstract concept, whereas the adapter is the concrete implementation of a port.

2. How it Works

This architecture allows an application to driven by its users and automation scripts. It also provides an ability to develop and test in isolation. Moreover, it removes the dependency of other run-time components and database systems.

The outside world accesses the application through its ports and a technology-specific adapter. An adapter converts the request into a usable procedure call. It then forwards it to the application core for business processing. For outward communication, it uses the same port and adapter pattern.

An application has limited knowledge of the communicating devices. In general, communicating devices stay beyond the application core boundary.

Note that the term hexagonal is being used as a metaphor. A hexagonal architecture need not have six ports or adapters. We can design an application with more or less than six dimensions.

3. Hexagonal Architecture in Java

Ports are abstract in hexagonal architecture and we represent them with an interface. Besides, the port that drives the application core logic is the primary port. And the port that serves the primary port is the secondary port.

3.1. Sample Application

For example, we will use a classic user management application. This application performs basic CRUD operations.

3.2. Primary Port

To continue further, the UserService interface provides the core business services in our application. Thus, this constitutes the core domain of our application. Hence, this is the primary port of the application.

Following business services performed by UserService interface:

public interface UserService {

public User registerUser(User user);
public boolean deactiveUser(int userId);
public User updateUser(User user);
public Collection<User> getAllUsers();
public Optional<User> findUserById(int userId);

Representation of a user in our application:

public class User {    private int userId;
private String userName;

// Getters and Setters

3.3. Secondary Port

The UserRepository interface serves the requests of UserService. Besides, it also provides data storage-related services to UserService. Thus, this interface acts as a secondary port in our application.

Following services offered by User Repository:

public interface UserRepository {

public User save(User user);
public boolean update(int userId) throws UserNotFoundException;
public Collection<User> findAll();
public Optional<User> findById(int userId);

3.4. Adapter

In previous sections, we talked about the ports in Ports and Adapters architecture. We also discussed that adapters are the concrete implementation of ports. For our UserRepository interface, we provide a default in-memory data store implementation. This is an adapter that talks to database services.

An in-memory implementation of UserRepository:

public class InMemoryUserRepositoryImpl implements UserRepository{
// Implementations

4. Conclusion

To sum up, we draw a boundary between the application core and interactions with this pattern. The major advantage is application core logic remains inside the defined application boundary. It does not leak to the outside world.



Blog and mini courses on Java and Spring

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Somnath Musib

Software Developer, Cloud Architect | Author "Spring Boot In Practice" . Find more at