Designing Hexagonal Architecture with Java

By Davi Vieira

Early Access

This is an Early Access product. Early Access chapters haven’t received a final polish from our editors yet. Every effort has been made in the preparation of these chapters to ensure the accuracy of the information presented. However, the content in this book will evolve and be updated during the development process.

Learn more
    Advance your knowledge in tech with a Packt subscription

  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. 1 Why Hexagonal Architecture?

About this book

Hexagonal architecture enhances developers' productivity by decoupling business code from technology code, making the software more change-tolerant, allowing it to evolve and incorporate new technologies without the need for significant refactoring. By adhering to hexagonal principles, you can structure your software in a way that reduces the effort required to understand and maintain the code.

This book starts with an in-depth analysis of hexagonal architecture's building blocks, such as entities, use cases, ports, and adapters. You'll learn how to assemble business code in the domain hexagon, create features by using ports and use cases in the application hexagon, and make your software compatible with different technologies by employing adapters in the framework hexagon. Moving on, you'll get your hands dirty with developing a system based on a real-world scenario applying all the hexagonal architecture's building blocks. By creating a hexagonal system, you'll also understand how you can use Java modules to reinforce dependency inversion and assure the isolation of each hexagon in the architecture. Finally, you'll get to grips with using Quarkus to turn the hexagonal application into a cloud-native system.

By the end of this hexagonal architecture book, you'll be able to bring order and sanity to the development of complex and long-lasting applications.

Publication date:
January 2022
Publisher
Packt
Pages
460
ISBN
9781801816489

 

1 Why Hexagonal Architecture?

A software that's not well organized and lacks sound software architecture principles may work just fine but develop technical debt over time. As new features are added, the software may become more complex to maintain because there is no common ground to guide code changes. Based on that problem, this chapter explains how the hexagonal architecture helps tackle technical debt by establishing an approach where business logic is decoupled from technology code, allowing the former to evolve without dependency on the latter.

In this chapter, we will cover the following topics:

  • Reviewing software architecture
  • Understanding Hexagonal architecture

By the end of this chapter, you will learn about the hexagonal architecture main concepts: entities, use cases, ports, and adapters. Also, you'll know the basic techniques to start applying hexagonal principles in your projects.

 

Technical requirements

To compile and run the code examples presented in this chapter, you need the latest Java SE Development Kit and Maven 3.6 installed on your computer. They are all available for Linux, Mac, and Windows operating systems.

You can find the code files for this chapter on GitHub at https://github.com/PacktPublishing/Designing-Hexagonal-Architecture-with-Java-and-Quarkus/tree/main/chapter1.

 

Reviewing software architecture

The word architecture is old. Its origin in history remounts to times when man used to build things with rudimentary tools, often with his own hands. Yet, each generation repeatedly overcame the limitations of its era and constructed magnificent buildings that stood to this day: take a look at the Florence Cathedral and its dome designed by Filippo Brunelleschi, what an excellent architecture example!

Architects are more than just ordinary builders who build things without much thinking. Quite the opposite, they are the ones who care the most about the aesthetics, underlying structures, and design principles. Sometimes they play a fundamental role by pushing the limits to what is possible to do with the resources at hand. The Florence Cathedral, as has already been said, proves that point.

I'll not take this analogy too far because a software is not like a physical building. And, although there should be some similarities between building and software architects the latter differs considerably because of the living and evolving nature of their software craft. But we can agree that both share the same ideal: to build things right.

This ideal helps us understand what software architecture is. If we're aiming to build not just working software, but an easily maintainable and well-structured one, software can even be considered at a certain degree as a piece of art because of the care and attention to details we employed to build it, so then we can take that as a noble definition for software architecture.

It's also important to state that a software architect's role should not only be constrained to decide how things should be made. As in the Florence Cathedral example, where Filippo Brunelleschi himself helped to assent bricks in the building to prove his ideas were sound, a software architect in the same vein should soil his hands to prove his architecture is good.

A software architecture should not be the fruit of one person's mind. Although, there are a few who urge others to purse a path of technical excellence by providing guidance and establishing the foundations, for an architecture to evolve and mature it's necessary to have the collaboration and experience of everyone involved in the effort to improve software quality.

What follows is a discussion around the technical and organizational challenges we may encounter in our journey to create and evolve a software architecture to help us tackle the threat of chaos and indomitable complexity.

The invisible things

Software development is not a trivial activity. It demands a considerable effort to become competent in any programming language and even a greater effort to use that skill to build software that generates profit. Surprisingly, sometimes it may not be just enough to make a profitable software.

When we talk about a profitable software, we're talking about a software that solves real-world problems. Or in the context of large enterprises, to speak more precisely, it's a software that meets business needs. Also, everyone who has worked in large enterprises understands that the client generally doesn't want to know how the software is built. They are interested in what they can see: a working software meeting business expectation. After all, that's what pays bills at the end of the day.

But the things that clients cannot see also have some importance. Such things are known as non-functional requirements. They are things related to security, maintainability, operability, and other capabilities. If adequate care is not taken, those things unseen from the clients' perspective can compromise the whole software purpose. That compromise can occur subtly and gradually, giving origin to several problems, including technical debt.

I've mentioned previously that software architecture is about doing things right. So, it means that among its concerns, we should include both unseen and seen things. For things that are seen by the client, it's essential to deeply understand the problem domain. That's where techniques like Domain-Driven Design can help us approach the problem in a way that allows us to structure the software in a form that makes sense not just for programmers but also for everyone involved in the problem domain. Domain-Driven Design also plays a key role in shaping the unseen part by defining cohesively the underlying structures that will allow us to solve client needs and do that in a well-structured and maintainable manner.

Technical debt

Coined by Ward Cunningham, technical debt is a term used to describe how much unnecessary complexity exists in a software code. Such unnecessary complexity may also be referred to as cruft—that's the difference between the current code and how it would ideally be. We'll see next how technical debts can appear in a software project.

To develop a software that just works is one thing. You assemble code in a way you think is adequate to meet business needs, and then package and throw it in to production. In production, your software meets client expectations, so everything is fine, and life goes on. Sometime later, another developer comes in to add new features to that same software you started. Like you, this developer assembles code in a way he thinks is adequate to meet business needs, but there are things in your code this developer doesn't clearly understand. Hence, he adds elements to the software in a slightly different manner than you would. The software makes its way into production, and the customer is satisfied. So, the cycle repeats.

Software working as expected is what we clearly can see from the previous scenario. But what we cannot see so clearly is that the lack of some common grounds defining how features should be added or modified to the software leaves a gap that every developer will try to fill whenever he does not know how to handle such changes. This very gap leaves space for the growth of things like technical debts.

Reality very often pushes us to situations where we just cannot avoid technical debts. Tight schedules, poor planning, unskilled people, and of course, the lack of software architecture are some of the factors that can contribute to the creation of technical debts. Needless to say, we should not believe that the enforcement of a software architecture will magically solve all our technical debt problems. Far from that, here we're just tackling one facet of the problem. All other technical debt factors will remain and can actually undermine our efforts to establish a sound software architecture.

Vicious cycle

Financial debts tend to continue to grow regardless of if you don't pay them. Also, the bank and authorities can come after you and your assets if you don't pay those debts in time. Contrary to its financial counterpart, technical debts don't necessarily grow if you don't pay them. What determines their growth, though, is the rate and nature of software changes. Based on that we can assume that frequent and complex changes have a higher potential to increase technical debts.

You always have the prerogative not to pay technical debts—sometimes that's the best choice depending on the circumstance—but you diminish your capacity to change the software as you do so. With higher technical debt rates, the code becomes more and more unmanageable, causing developers to either avoid touching the code at all or finding awkward workarounds to solve the issues.

I believe most of us had at least once the unpleasant experience of maintaining brittle, insanely complex systems. In such scenarios, instead of spending time working with valuable things for the software, we spend more time fighting technical debts to open space to introduce new features. If we don't keep the technical debts controlled, one day, it will not be worth adding new features to the technical debt overloaded system. That's when people decide to abandon applications, start a new one, and repeat the cycle again. So, the effort in tackling technical debts should be motivated to break that cycle.

It's not for everyone

This zest for quality and correctness that emerge from any serious architectural undertaking is not always present. As pointed out by big ball of mud, there are scenarios where the most profit-driving software in a company is an absolute big ball of mud. It's a software that has grown without any sense of order, complicated to understand and maintain. Developers who dare to tackle the complexity posed by this kind of system are like warriors fighting a hydra. The refactoring effort required to impose any order in such complexity is sometimes not worth it.

The big ball of mud is not the only problem. There are also cultural and organizational factors that can undermine any software architecture effort. Very often, I've stumbled upon teammates who simply didn't care about architecture principles. The least-effort path to deliver code on production is the norm to be followed in their minds. It's not hard to find this kind of person in projects with a high turnaround of developers. Because there is no sense of ownership, there is no incentive to produce high-quality code.

To push the discipline to follow a software architecture is hard. Both the technical team and management should be aligned on the advantages and implications of following such discipline. It's important to understand that spending more time upfront on dealing with technical aspects that don't add much value in terms of customer features may play a crucial role in the long term. All the effort is paid back with more maintainable software, relieving developers who no longer need to fight hydras, and managers who are now better positioned to meet business deadlines.

Before trying to promote, let alone enforce, any software architecture principle, it is advisable to assess the current environment to make sure there are neither cultural nor organizational factors playing against the attitude of a few trying to raise the bar to better-developed systems.

Monolithic or distributed

There is a recurring discussion in the software community about the organization of a system's components and responsibilities. In the past, where expensive computing resources and network bandwidth were the problems that influenced the software architecture, developers tended to group plenty of responsibilities in a single software unit to optimize resource usage and avoid the network overhead that would occur in a distributed environment. But there is a tenuous line separating a maintainable and cohesive monolithic from an entangled and hard-to-maintain one.

The crossing of such a line is a red sign showing the system has accumulated so many responsibilities and has become so complex to maintain that any change poses a severe risk of breaking down the entire software. I'm not saying that every monolithic that grows becomes a mess. I'm trying to convey that the accumulation of responsibilities can cause serious problems to a monolithic system when such responsibility aggregation is not done with care. Apart from this responsibility issue, it's also equally important to make sure the software is easy to develop, test, and deploy. If the software is too large, developers may have difficulty trying to run and test it locally. It can also have a serious impact on Continuous Integration pipelines, impacting the compiling, testing, and deployment stages of such pipelines, ultimately compromising the feedback loop that is so crucial in a DevOps context.

On the other hand, if we know when a system accumulates sufficient responsibility, we can rethink the overall software architecture and break down the large monolithic into smaller and more manageable, sometimes autonomous, software components, that are often isolated in their own runtime environments. This approach got strong adoption with Service-Oriented Architecture (SOA) and then with what can be called its evolution: the microservice architecture.

Both SOA and microservices can be considered different flavors of distributed systems. Microservice architecture, in particular, is made possible mainly because computing and network resources are not so expensive as they used to be, bringing lots of benefits related to strong decoupling and faster software delivery. However, this does not come without costs, because if earlier we had to deal with complexity in just one place, now the challenge is to deal with complexity scattered around the network.

The hexagonal architecture proposed in this book can be applied to both monolithic and distributed systems. With monolithic, you may have the application being consumed by a frontend and, at the same time, consuming data from a database or other data sources. The hexagonal approach can help us develop a more change-tolerant monolithic system, testable even without the Frontend and the Database. The following diagram illustrates a common Monolithic system:

Figure 1.1 - Hexagonal architecture with a monolithic system

For distributed systems, we may be dealing with lots of different technologies. The hexagonal architecture shines in these scenarios because its ports and adapters nature allow the software to deal with constant technology changes. The following diagram shows a typical microservice architecture where we could apply hexagonal principles:

Figure 1.2 - Hexagonal architecture with a microservices system

One of the great advantages of microservice architecture is that you can use different technologies and programming languages to compose the whole system. We can develop a frontend application using JavaScript, some APIs with Java, and a data processing application with Python. Hexagonal architecture can help us in this kind of heterogeneous technological scenario.

Making decisions

All this discussion around software architecture concerns is relevant because we may undermine our capability to maintain and evolve software in the long run if we ignore those concerns. Of course, there are situations where we're not so ambitious about how sophisticated, maintainable, and feature-rich our software will be.

It may not be worth all the time and effort to build things in the right way for such situations because what's needed is a working software delivered as fast as possible. In the end, it's a matter of priorities. But we should be cautious not to fall into the trap that we can fix things later. Sometimes we can have the money to do so but sometimes we may not. Wrong decisions at the beginning of a project can cost us a high price in the long term.

The decisions we take regarding code structure and software architecture lead us to what calls internal quality. The degree to which a software code is well organized and maintainable corresponds to the internal quality. On the other hand, the value perception about how valuable and good a software can be from a user's perspective corresponds to the external quality. Internal and external quality are not directly connected. It's not difficult to find useful software with a messy codebase.

The effort spent on internal quality should be seen as an investment where the return is not immediate and visible to the user. The investment return comes as the software evolves. The value is perceived then by constantly adding changes to the software without increasing the time and money required to add such changes, as the following pseud-graph depicts it:

Figure 1.3 – Pseudo-graph showing the impact of changes

But how can we make the right decisions? That's a trick question because we often don't have enough information to assist in the decision-making process that will lead us to a software architecture that best meets business needs. Most of the time, even the client doesn't know his needs. That information generally comes as the project evolves. Instead of making upfront decisions, a more sensible approach is to wait until enough information is received, allowing us to be more assertive. This approach naturally leads us to a software architecture that reflects these concerns related to lack of information and the necessity to accommodate changes as they occur.

That necessity and also capacity to change systems is a crucial point on software design. Too much thinking in designing upfront, and we may end up with an overengineering and possible overpriced solutions. The other way around is dangerous because we risk increasing the cost of change by being careless about design. As pointed out in Extreme Programming Explained: Embrace Change, the resources spent on design efforts should match a system's need to process changes at an acceptable pace without increasing the cost to process such changes.

This book is concerned with a software architecture that allows us to postpone decisions by making change-tolerant applications able to cope with changes when decisions are finally made. But reality can be harsh sometimes, forcing us to make hurried decisions with scarce information. These precipitated actions can result in unpleasant consequences such as technical debts.

Now that we're aware of some of the problems related to software architecture, we're in a better position to explore possible solutions to mitigate those issues. To help us in that effort, let's start by looking into the fundamentals of hexagonal architecture.

 

Understanding the hexagonal architecture

Create your application to work without either a UI or a database so you can run automated regression-tests against the application, work when the database becomes unavailable, and link applications together without any user involvement. - Alistair Cockburn.

That quote lays the ground for the understanding of hexagonal architecture. We can go even further with Cockburn's thought and make our application work without any technology, not just the ones related to UI or database.

One of the main ideas of hexagonal architecture is to separate business code from technology code. Still, not just that, we must also make sure the technology side depends on the business one, so that the latter can evolve without any concerns regarding which technology is used to fulfill business goals. And we must also be able to change technology code by causing no harm to its business counterpart. To achieve such purposes, we must determine a place where the business code will exist, isolated and protected from any technology concerns. It'll give rise to the creation of our first hexagon: the Domain hexagon.

In the Domain hexagon, we assemble the elements responsible for describing the core problems we want our software to solve. Entities and value objects are the main elements utilized on Domain hexagon. Entities represent things we can assign an identity to, and value objects are immutable components that we can use to compose our entities. The meanings used in this book to refer to both entities and value objects come from Domain-Driven-Design principles.

We also need ways to use, process, and orchestrate the business rules coming from Domain hexagon. That's what the Application hexagon does. It sits between the business and technology sides, serving as a middleman to interact with both parts. The Application hexagon utilizes ports and use cases to perform its functions. We will explore those things in more detail in the next section.

The Framework hexagon provides the outside world interface. That's the place where we have the opportunity to determine how to expose application features, it's on Framework we define REST or gRPC endpoints, for example. And to consume things from external sources, it's also on Framework we specify the mechanisms to fetch data from databases, message broker, or any other system. In hexagonal architecture, we materialize technology decisions through adapters. The following diagram provides a high-level view of the architecture:

Figure 1.3 - Hexagonal architecture

Next, we'll go deeper into the components, roles, and structures of each hexagon.

Domain hexagon

The Domain hexagon represents an effort to understand and model a real-world problem. Suppose you're in a project that needs to create a network and topology inventory for a telecom company. This inventory's main purpose is to provide a comprehensive view of all resources that comprise the network. Among those resources, we have routers, switches, racks, shelves, and other equipment types. Our goal here is to use the Domain hexagon to model into code the knowledge required to identify, categorize, and correlate those network and topology elements and provide a lucid and organized view of the desired inventory. That knowledge should be, as much as possible, represented in a technology-agnostic form.

This quest is not a trivial one. Developers involved in such undertaking may not know telecom business, set aside this inventory thing. As recommended by Domain-Driven Design: Tackling Complexity in the Heart of Software, it's necessary to consult domain experts or other developers who already know the domain problem. If none of them are available, one should try to fill the knowledge gap by searching on books or any other material that teaches about the domain problem.

Inside Domain hexagon, we have entities corresponding to critical business data and rules. They are critical because they represent a model of the real problem. That model takes some time to evolve and reflect consistently the problem we're trying to model. That's the case of new software projects where neither developers nor the domain experts have a clear vision of the system purpose in its early stages. In such scenarios, particularly recurrent in startup environments, it's normal and predictable to have an initial awkward domain model that evolves only as business ideas also evolve and are validated by users and domain experts. It's a curious situation where domain model is unknown even for the so-called domain experts.

On the other hand, in scenarios where the problem domain exists and is clear in the minds of domain experts, if we fail to grasp that problem domain and how it translates into entities and other Domain objects, like value objects, we will build our software based on weak or wrong assumptions.

That can be considered as one reason why any software starts simple and, as its codebase grows, accumulates technical debt, and becomes harder to maintain. The weak assumptions may lead to a fragile and unexpressive code that can initially solve business problems but is not ready to accommodate changes in a cohesive way. Bear in mind that the Domain hexagon is composed of whatever kind of object categories you feel is good for representing the domain problem. Here is a representation based just on Entities and Value Objects:

Figure 1.4 - Domain hexagon

Let's now talk about the components comprising of this hexagon.

Entities

Entities help us to build a more expressive code. What characterizes an Entity is its sense of continuity and identity, as described by Domain-Driven Design: Tackling Complexity in the Heart of Software. That continuity is related to the life cycle and mutable characteristics of the object. For example, in our network and topology inventory scenario, we mentioned routers' existence. For a router, we can define whether its state is enabled or disabled.

Also, we can assign some properties describing the relationship that a router has with different routers and other network equipment. All those properties may change over time, so we can see that the router is not a static thing and its characteristics inside the problem domain can change. Because of that, we can state that the router has a life cycle. Apart from that, every router should be unique in an inventory, so it must have an identity. So, the sense of continuity and identity are the elements that determine an entity.

The following code shows a Router entity class composed of a RouterType and RouterId value objects:

public class Router {
    private final RouterType routerType;
    private final RouterId routerId;
    public Router(RouterType, RouterId routerId){
        this.routerType = routerType;
        this.routerId = routerId;
    }
    public static Predicate<Router> filterRouterByType(RouterType         routerType){
        return routerType.equals(RouterType.CORE)
                ? isCore() :
                isEdge();
    }
    private static Predicate<Router> isCore(){
        return p -> p.getRouterType() == RouterType.CORE;
    }
    private static Predicate<Router> isEdge(){
        return p -> p.getRouterType() == RouterType.EDGE;
    }
    public static List<Router> filterRouter(List<Router> routers,           Predicate<Router> predicate){
            return routers.stream()
                .filter(predicate)
                .collect(Collectors.<Router>toList());
    }
   
    public RouterType getRouterType() {
        return routerType;
    }
}

Let's move on to the value objects.

Value objects

Value objects help us complement our code's expressiveness when there is no need to identify something uniquely and when we are more concerned about the object's attributes than on its identity. We can use value objects to compose an entity object, so we must make value objects mutable to avoid unforeseen inconsistencies across the Domain. In the router example presented previously, we can represent the router Type as a value object attribute from the Router entity:

public enum Type {
    EDGE,
    CORE;
}     

Next, we'll learn about the Application hexagon.

Application hexagon

Until now, we've been discussing how the Domain hexagon encapsulates business rules with entities and value objects. But there are situations where the software does not need to operate directly on the Domain level. Clean Architecture: A Craftsman's Guide to Software Structure and Design states that some operations exist solely to allow the automation provided by the software. These operations—although they support business rules—would not exist outside the context of the software. We're talking about application-specific operations.

The Application hexagon is where we abstractly deal with application-specific tasks. I mean abstract because we're not dealing directly with technology concerns yet. This hexagon expresses the software's user intent and features based on the Domain hexagon's business rules.

Based on the same topology and inventory network scenario described previously, suppose you need a way to query routers of the same type. It would require some data handling to produce such results. Your software would need to capture some user input to query for router types. You may want to use a particular business rule to validate user input and another business rule to verify data fetched from external sources. If no constraints are violated, your software then provides the data showing a list of routers of the same type. We can group all those different tasks in a use case. The following diagram depicts the Application hexagon high-level structure based on Use Cases, Input Ports, and Output Ports:

Figure 1.5 - Application hexagon

The following sections will discuss about the components of this hexagon.

Use cases

Use cases represent system's behavior through application-specific operations, which exist within the software realm to support the Domain's constraints. Use cases may interact directly with entities and other use cases, making them quite flexible components. In Java, we represent use cases as abstractions defined by interfaces expressing what the software can do. The following code shows a use case that provides an operation to get a filtered list of routers:

 public interface RouterViewUseCase {
     List<Router> getRouters(Predicate<Router> filter);
} 

Note the Predicate filter. We're going to use it to filter the router list when implementing that use case with an input port.

Input ports

If use cases are just interfaces describing what the software does, we still need to implement the use case interface. That's precisely the input port role. By being a component directly attached to use cases, at the Application level, input ports allow us to implement software intent on domain terms. Here is an input port providing the implementation to fulfill the software intent stated on the use case:

public class RouterViewInputPort implements RouterViewUseCase {

 private RouterViewOutputPort routerListOutputPort;

  public RouterViewInputPort(RouterViewOutputPort     routerViewOutputPort) {
     this.routerListOutputPort = routerViewOutputPort;
   }

   @Override
   public List<Router> getRouters(Predicate<Router> filter) {
      var routers = routerListOutputPort.fetchRouters();
      return Router.retrieveRouter(routers, filter);
  }
}     

This example shows us how we could use a domain constraint to make sure we're filtering the routers we want to retrieve. From the input port implementation, we can also get things from outside the application. We do that using output ports.

Output ports

There are situations in which a use case needs to fetch data from external resources to achieve its goals. That's the role of output ports, which are represented as interfaces describing in a technology-agnostic way, which kind of data a use case or input port would need to get from outside to perform its operations. I say agnostic because output ports don't care if the data comes from a particular relational database technology or a filesystem, for example. We assign this responsibility to output adapters, which we'll see next:

public interface RouterViewOutputPort {
     List<Router> fetchRouters();
}          

Let's now discuss about the last type of hexagon.

Framework hexagon

Things seem well organized with our critical business rules constrained to the Domain hexagon, following by the Application hexagon in charge to deal with some application-specific operations through the means of use cases, input, and output ports. Now comes the moment when we need to decide which technologies should be allowed to communicate with our software. That communication can occur in two forms, one known as driving and another as driven. For the driver side, we use the Input Adapters, and for the driven one, Output Adapters as shown in the following diagram:

Figure 1.6 - Framework hexagon

Let's go into detail.

Driving operations and input adapters

Driving operations are the ones who request actions to the software. It can be a user with a command line client or a frontend application on behalf of the user, for example. There may be some testing suites checking the correctness of things exposed by your software. Or it can be just other applications in a large ecosystem needing to interact with some exposed software features. This communication occurs through an Application Programming Interface (API) built on top of the input adapters.

This API defines how external entities will interact with your system and then translate their request to your domain's application. The term driving is used because those external entities are driving the behavior of the system. Input Adapters can define the application's supported communication protocols, as shown here:

Figure 1.7 - Driver operations and input adapters

Suppose you need to expose some software features to legacy applications that work just with SOAP over HTTP/1.1 and, at the same time, need to make those same features available to new clients who could leverage the advantages of using GRPC over HTTP/2. With hexagonal architecture, you could create an input adapter for both scenarios, each adapter attached to the same input port that would, in turn, translate the request downstream to work in terms of Domain. Here is an input adapter using a use case reference to call one of the input port operations:

public class RouterViewCLIAdapter {
    RouterViewUseCase routerViewUseCase;
    public RouterViewCLIAdapter(){
        setAdapters();
    }
    public List<Router> obtainRelatedRouters(String type) {
        return routerViewUseCase.getRouters(
                Router.filterRouterByType(RouterType.valueOf(type)));
    }
    private void setAdapters(){
    this.routerViewUseCase = new            RouterViewInputPort(RouterViewFileAdapter.getInstance());
    }
}                             

This example illustrates the creation of an input adapter that gets data from the STDIN. Note the use of the input port through its use case interface. Here, we pass the command that encapsulates input data used on the Application hexagon to deal with Domain hexagon's constraints. If we want to enable other communication forms in our system, like REST, we just have to create a new REST adapter containing the dependencies to expose a REST communication's endpoint. We will do this in the following chapters as we add more features to our hexagonal application.

Driven operations and output adapters

On the other side of the coin, we have driven operations. These operations are triggered from your application and go into the outside world to get data to fulfill the software needs. A driven operation generally occurs in response to some driving one. As you may imagine, the way we define the driven side is through output adapters. These adapters must conform to our output ports by implementing them.

Remember, an output port tells which kind of data it needs to perform some application-specific tasks. It's up to the output adapter to describe how it will get the data. Here is a diagram for Output Adapters and Driven operations:

Figure 1.8 - Driven operations and output adapters

Suppose your application started working with Oracle relational databases and, after some time, you decided to change technologies and move on to a NoSQL approach, embracing MongoDB instead as your data source. In the beginning, you'd have just one output adapter to allow persistence with Oracle databases. To enable communication with MongoDB, you'd have to create an output adapter on Framework hexagon, leaving the Application and, most importantly, Domain hexagons untouched. Because both input and output adapters are pointing inwards the hexagon, we're making them depend on both Application and Domain, hence inverting the dependency.

The term driven is used because those operations are driven and controlled by the hexagonal application itself, triggering action in other external systems. Note in the following example how the output adapter implements the output port interface to specify how the application is going to obtain external data:

public class RouterViewFileAdapter implements RouterViewOutputPort {

    @Override
    public List<Router> fetchRouters() {
        return readFileAsString();
    }

    private static List<Router> readFileAsString() {
        List<Router> routers = new ArrayList<>();
        try (Stream<String> stream = new BufferedReader(
                new InputStreamReader(                                      RouterViewFileAdapter.class.getClassLoader().
                      getResourceAsStream("routers.txt"))).lines()){
            stream.forEach(line ->{
            String[] routerEntry = line.split(";");
            var id = routerEntry[0];
            var type = routerEntry[1];
            Router = new                                    Router(RouterType.valueOf(type),RouterId.of(id));
                routers.add(router);
            });
        } catch (Exception e){
           e.printStackTrace();
        }
        return routers;
    }     
}

The output port states what data the application needs from outside. The output adapter in the previous example provides a specific way to get that data through a local file.

Having discussed about the various hexagons in this architecture, we will now look at the advantages that this approach brings.

Advantages of the hexagonal approach

If you're looking for a pattern to help you standardize the way a software is developed at your company or even in personal projects, hexagonal architecture can be used as the basis to create such standardization by influencing how classes, packages, and the code structure as a whole are organized.

In my experience of working on large projects with multiple vendors and bringing lots of new developers to contribute to the same codebase, the hexagonal architecture has helped the organization establish the foundational principles on which the software is structured. Whenever a developer switched projects, he had a shallow learning curve to understand how the software was structured because he was already acquainted with hexagonal principles learned on previous projects. This factor, in particular, is directly related to the long-term benefits of software with a minor degree of technical debt.

Applications with a high degree of maintainability, easy to change, and test are always welcomed. Let's see next how hexagonal architecture helps us to obtain such advantages.

Change-tolerant

Technology changes are happening at a swift pace. New programming languages and a myriad of sophisticated tools are emerging every day. To beat the competition, very often, it's not enough to just stick with well-established and time-tested technologies. The use of cutting-edge technology becomes no longer a choice but a necessity, and if the software is not prepared to accommodate such changes, the company risks losing money and time in big refactoring because the software architecture is not change-tolerant.

So, the ports and adapters nature of hexagonal architecture gives us a strong advantage by providing the architectural principles to create applications ready to incorporate technological changes with less friction.

Maintainability

If it's necessary to change some business rule, one knows that the only thing that should be changed is the Domain hexagon. On the other hand, if we need to allow an existing feature to be triggered by a client that uses particular technology or protocol that is not yet supported by the application, we just need to create a new adapter, performing such change only on the Framework hexagon.

This separation of concerns seems simple, but when enforced as an architectural principle, it grants a degree of predictability that's enough to decrease the mental overload to grasp the basic software structures before deep diving into its complexities. Time has always been a scarce resource, and if there's a chance to save it through an architecture approach that removes some mental barriers, I think we should at least try it.

Testability

One of hexagonal architecture's ultimate goals is to allow developers to test the application when its external dependencies are not present, like UI and databases, as Alistair Cockburn stated. It does not mean, however, that this architecture ignores integration tests. Far from that, instead, it allows a more continuous integration approach by giving the required flexibility to test the most critical part of the code even in the absence of technology dependencies.

By assessing each of the elements comprising the hexagonal architecture and being aware of the advantages such architecture can bring to our projects, we're now furnished with the fundamentals to develop hexagonal applications.

 

Summary

We learned in this chapter how important software architecture is in establishing the foundations to develop robust and high-quality applications. We looked at the pernicious nature of technical debts and how we can tackle them with a sound software architecture. Finally, we overviewed the hexagonal architecture's core components and how they enable us to develop more change-tolerant, maintainable, and testable software.

With that knowledge, we're now able to apply these hexagonal principles to build applications based on the proposed Domain, Application, and Framework hexagons, which help us establish the boundaries between business code from technology code laying the ground for the development of complete hexagonal systems.

In the next chapter, we're going to explore how to start the development of a hexagonal application by its most important part: the Domain hexagon.

 

Questions

  1. What are the three hexagons comprising the hexagonal architecture?
  2. What's the role of the Domain hexagon?
  3. When should we utilize use cases?
  4. The input and output adapters are present in which hexagon?
  5. What's the difference between driving and driven operations?
 

Further reading

  • Get Your Hands Dirty on Clean Architecture: A hands-on guide to creating clean web applications with code examples in Java by Tom Hombergs, published by Packt Publishing Ltd. (September 2019).
 

Answers

  1. Domain, Application, and Framework.
  2. It provides the business rules and data in the form of entities, value objects, and any other suitable categories of objects that help model the problem domain. It does not depend on any other hexagon above it.
  3. When we want to represent system's behavior through application-specific operations.
  4. The Framework hexagon.
  5. Driving operations are the ones who request actions to the software. Driven operations are started by the hexagonal application itself. These operations go outside to fetch data from external sources.

About the Author

  • Davi Vieira

    Davi Vieira is a software craftsman with a vested interest in the challenges faced by large enterprises in software design, development, and architecture. He has more than ten years of experience constructing and maintaining complex, long-lasting and mission-critical systems using object-oriented languages. He values the good lessons and the software development tradition left by others from the past. Inspired by such software tradition, he develops and evolves his ideas.

    Browse publications by this author
Designing Hexagonal Architecture with Java
Unlock this book and the full library for $5 a month*
Start now