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 hexagonal architecture helps to build software prepared to accommodate changes from unexpected requirements and, by doing so, allows us to increase software maintainability and keep technical debt under control.

We tackle the technical debt problem that arises when shortcuts are taken to overcome the difficulty of introducing changes caused by an inflexible software architecture. We will see how hexagonal architecture helps us improve maintainability by providing the principles to decouple the business logic (code that should purely represent a business problem) from the technology code (code that integrates the system with different technologies such as databases, messaging queues, and external APIs to support the business logic).

I have seen systems developed with business logic closely related to the technology code. Some of those systems would rarely change, so the coupling between business logic and technology code would never be a problem. However, significant refactorings would be necessary for other systems where the requirements would change often and substantially. That was because the business logic was so tightly coupled with the technology code that rewriting the business logic was the only plausible solution.

Using hexagonal architecture may help you to save time and effort due to the software rewrites caused by such scenarios where requirements change often and significantly.

In this chapter, we will cover the following topics:

• Reviewing software architecture
• Understanding hexagonal architecture

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

To compile and run the code examples presented in this chapter, you need the latest Java SE Development Kit and Maven 3.8 installed on your computer. They are both available for Linux, macOS, 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---Second-Edition/tree/main/Chapter01.

The word architecture is old. Its origin traces back to times when people used to build things with rudimentary tools, often with their own hands. Yet, each generation repeatedly overcame the limitations of its era and constructed magnificent buildings that stand to this day. Take a look at the Florence Cathedral and its dome designed by Filippo Brunelleschi – what an excellent example of architecture!

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 aesthetics, underlying structures, and design principles. Sometimes, they play a fundamental role by pushing the limits of what is possible to do with the resources at hand. The Florence Cathedral, as has already been mentioned, proves that point.

I’ll not take this analogy too far because software is not like a physical building. And although there are 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 goal: to build things right.

This goal helps us understand what software architecture is. If we’re aiming to build not just working but also easily maintainable and well-structured software, it can even be considered to a certain degree as a piece of art because of the care and attention to detail we employ to build it. So, we can take this activity of building easily maintainable and well-structured software as a noble definition of software architecture.

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

Software architecture should not be the fruit of one person’s mind. Although there are a few who urge others to pursue a path of technical excellence by providing guidance and establishing the foundations, for an architecture to evolve and mature, it’s necessary to utilize the collaboration and experience of everyone involved in the effort to improve the 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.

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 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 may have the money to do so but sometimes we may not. Bad decisions at the beginning of a project can cost us a high price in the future.

The decisions we take regarding code structure and software architecture lead us to what is called internal quality. The degree to which software code is well organized and maintainable corresponds to the internal quality. On the other hand, the value perception about how valuable and good 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 code base.

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 by constantly adding changes to the software without increasing the time and money required to add such changes, as the following pseudo-graph depicts:

Figure 1.1 – 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 a decision-making process that will lead to software architecture that best meets the business needs. Sometimes, even the users don’t know completely what they want, leading to new or changed requirements as the project evolves. We tackle such unpredictability by using a software architecture that helps us add changes in a sustainable way to ensure the code base grows without increased complexity and decreased maintainability.

The ability to quickly introduce changes is a major concern in software design, but we should be cautious about how much time we spend thinking about it. If we spend too much time designing, we may end up with an overengineered and possibly overpriced solution. On the other hand, if we ignore or do not reflect enough on design concerns, we may end up with a complex and hard-to-maintain solution. As pointed out by Extreme Programming Explained: Embrace Change, the resources spent on design efforts should match a system’s need to handle changes at an acceptable pace and cost.

In the end, we want the flexibility of adding new stuff while keeping complexity under control. With that in mind, this book is concerned with software architecture ideas that allow us to handle software design decisions to meet changing business needs. The hexagonal architecture helps us to build change-tolerant systems to support those needs.

The invisible things

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

When we talk about profitable software, we’re talking about software that solves real-world problems. Or, in the context of large enterprises, to speak more precisely, we mean software that meets business needs. Anyone who has worked in a large enterprise will know that the client generally doesn’t want to know how the software is built. They are interested in what they can see: working software meeting business expectations. After all, that’s what pays the 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, scalability, reliability and other capabilities. If adequate care is not taken, those things unseen from the client’s perspective can compromise the whole purpose of the software. 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 such as 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 only 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 cohesively defining the underlying structures that will allow us to solve client needs and doing 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 software code. Such unnecessary complexity may also be referred to as cruft – that is, the difference between the current code and how it would ideally be. We’ll see next how technical debt can appear in a software project.

Developing 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 deploy it to production. In production, your software meets clients’ expectations, so everything is fine and life goes on. Sometime later, another developer comes in to add new features to that software you created. Like you, this developer assembles code in a way they think is adequate to meet business needs, but there are things in your code this developer doesn’t clearly understand. Hence, they add 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 can clearly see in the previous scenario. But what we cannot see so clearly is that the lack of common ground defining how features should be added or modified leaves a gap that every developer will try to fill whenever they do not know how to handle such changes. This very gap leaves space for the growth of things such as technical debt.

Reality very often pushes us to situations where we just cannot avoid technical debt. Tight schedules, poor planning, unskilled people, and, of course, a lack of software architecture are some of the factors that can contribute to the creation of technical debt. Needless to say, we should not believe that the enforcement of 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 build maintainable software.

Vicious cycle

Financial debts tend to continue to grow regardless 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 debt doesn’t necessarily grow if you don’t pay it. What determines its 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 debt.

You always have the prerogative not to pay technical debt – 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 find awkward workarounds to solve the issues.

I believe most of us will have had at least once the unpleasant experience of maintaining brittle, insanely complex systems. In such scenarios, instead of spending time working on things that are valuable to the software, we spend more time fighting technical debt to open space to introduce new features. If we don’t keep the technical debt under control, 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. So, the effort required to tackle technical debt should be considered worth it to break that cycle.

It’s not for everyone

This zest for quality and correctness that emerges from any serious architectural undertaking is not always present, There are scenarios where the most profit-driving software in a company is an absolute big ball of mud. It’s software that has grown without any sense of order and is 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 architectural principles. The least-effort path to deliver code into 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 in terms of quality and high standards, there is no incentive to produce high-quality code.

Pushing 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 pay dividends 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 circumstances to make sure there are neither cultural nor organizational factors playing against the attitude of a few trying to meet or 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 monolith from an entangled and hard-to-maintain one.

The crossing of such a line is a red flag 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 in a monolithic system when such responsibility aggregation is not handled 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 considered 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 as expensive as they used to be, bringing lots of benefits related to strong decoupling and faster software delivery. However, this comes with costs because earlier we had to deal with complexity in just one place, whereas now the challenge is dealing with complexity scattered around multiple services in the network.

This book proposes hexagonal architecture ideas that you can apply to 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.2 – Hexagonal architecture with a monolithic system

In distributed systems, we may be dealing with lots of different technologies. The hexagonal architecture shines in these scenarios because its ports and adapters 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.3 – Hexagonal architecture with a microservices system

One of the great advantages of microservice architecture is that we 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.

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.

“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 understanding hexagonal architecture. We can go even further with Cockburn’s idea and make our application work without any technology, not just the ones related to the UI or database.

One of the main ideas of hexagonal architecture is to separate business code from technology code.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. Having the business logic independent of any technology details gives a system the flexibility to change technologies without disrupting its business logic. In that sense, the business logic represents the foundation through which the application is developed and from which all other system components will derive.

We must be able to change technology code without causing harm to its business counterpart. To achieve this, 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 in the 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 meaning this book uses for entities and value objects comes from domain-driven design principles.

We also need ways to use, process, and orchestrate the business rules coming from the 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 – this is where we define REST or gRPC endpoints, for example. To consume things from external sources, we use the Framework hexagon to specify the mechanisms to fetch data from databases, message brokers, or any other system. In the hexagonal architecture, we materialize technology decisions through adapters. The following diagram provides a high-level view of the architecture:

Figure 1.4 – The 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 working on a project that requires creating 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 an undertaking may not know much about the telecom business, set aside this inventory thing. As recommended by Domain-Driven Design: Tackling Complexity in the Heart of Software, domain experts or other developers who already know the problem domain should be consulted. If none are available, you should try to fill the knowledge gap by searching in books or any other material that teaches about the problem domain.

Inside the 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 may take some time to evolve and reflect consistently on the problem domain. That’s often the case with new software projects where neither developers nor domain experts have a clear vision of the system’s purpose in its early stages. In such scenarios, particularly recurrent in start-up 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 the domain model is unknown even to 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 model elements, such as value objects, we risk building our software based on weak or wrong assumptions.

Weak assumptions can be one of the reasons why software may start simple but, as its code base grows, it accumulates technical debt and becomes harder to maintain. These weak assumptions may lead to 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 are good for representing the problem domain. Here is a representation based just on entities and value objects:

Figure 1.5 – Domain hexagon

Let’s now talk about the components comprising this hexagon.

Entities

Entities help us to build 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 the existence of routers. 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, continuity and identity are the elements that determine an entity.

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

//Router entity class
public class Router {
    private final Type type;
    private final RouterId id;
    public Router(Type type, RouterId id) {
        this.type = type;
        this.id = id;
    }
    public static List<Router> checkRouter(
    Type type, List<Router> routers) {
    var routersList = new ArrayList<Router>();
        routers.forEach(router -> {
        if(router.type == type ){
            routersList.add(router);
        }
    });
    return routersList;
    }
}

Value objects

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

public enum Type {
       EDGE,
    CORE;
}

Application hexagon

So far, 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 at 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’s high-level structure based on use cases, input ports, and output ports:

Figure 1.6 – Application hexagon

The following sections will discuss the components of this hexagon.

Use cases

Use cases represent a system’s behavior through application-specific operations that 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 example 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 the role of the input port. By being a component that’s 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 an implementation that fulfills the software intent stated in the use case:

public class RouterViewInputPort implements RouterViewUse
  Case {
    private RouterViewOutputPort routerListOutputPort;
    public RouterViewInput
      Port(RouterViewOutputPort  routerViewOutputPort) {
        this.routerListOutputPort = routerViewOutputPort;
    }
    @Override
    public List<Router> getRouters(Predicate<Router> fil
       ter) {
        var routers = routerListOutput
             Port.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’s implementation, we can also get things from outside the application. We can 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, what 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 whether the data comes from a particular relational database technology or a filesystem, for example. We assign this responsibility to output adapters, which we’ll look at shortly:

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

Now, let’s discuss the last type of hexagon.

Framework hexagon

Things seem well organized with our critical business rules constrained to the Domain hexagon, followed by the Application hexagon dealing with some application-specific operations through the means of use cases, input ports, 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 the other as driven. For the driver side, we use input adapters, and for the driven side, we use output adapters, as shown in the following diagram:

Figure 1.7 – Framework hexagon

Let’s look at this in more detail.

Driving operations and input adapters

Driving operations are the ones that request actions from 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 could just be 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.8 – 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 the hexagonal architecture, you could create an input adapter for both scenarios, with each adapter attached to the same input port, which would, in turn, translate the request downstream to work in terms of the domain. Here is an input adapter using a use case reference to call one of the input port operations:

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

This example illustrates the creation of an input adapter that gets data from STDIN. Note the use of the input port through its use case interface. Here, we passed the command that encapsulates input data that’s used on the Application hexagon to deal with the Domain hexagon’s constraints. If we want to enable other communication forms in our system, such as REST, we just have to create a new REST adapter containing the dependencies to expose a REST communication 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’s needs. A driven operation generally occurs in response to some driving one. As you can guess, 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 the system what kind of data it needs to perform some application-specific task. It’s up to the output adapter to describe how it will get the data. Here is a diagram of output adapters and driven operations:

Figure 1.9 – Driven operations and output adapters

Suppose your application started working with Oracle relational databases and, after a while, 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 the Framework hexagon, leaving the Application and, most importantly, Domain hexagons untouched. Because both input and output adapters are pointing inside the hexagon, we’re making them depend on both Application and Domain hexagons, 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 Router
  ViewOutputPort {
    @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(
                  Objects.requireNonNull(
                  RouterViewFileAdapter.class
                    .getClassLoader().
                  getResourceAsStream
                    ("routers.txt")))).lines()) {
            stream.forEach(line ->{
            String[] routerEntry = line.split(";");
            var id = routerEntry[0];
            var type = routerEntry[1];
            Router 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 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 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 code base, the hexagonal architecture helps the organization establish the foundational principles on which the software is structured. Whenever a developer switched projects, they had a shallow learning curve to understand how the software was structured because they were already acquainted with hexagonal principles they’d learned about in 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 that are 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 on big refactoring because the software architecture is not change-tolerant.

So, the port and adapter features of hexagonal architecture give us a strong advantage by providing the architectural principles to create applications that are ready to incorporate technological changes with less friction.

Maintainability

If it’s necessary to change some business rule, we know 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 this 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 of grasping 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 architectural approach that removes some mental barriers, I think we should at least try it.

Testability

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

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

In this chapter, we learned how important software architecture is in establishing the foundations to develop robust and high-quality applications. We looked at the pernicious nature of technical debt and how we can tackle it with sound software architecture. Finally, we got an overview of 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 will help us establish boundaries between business code and technology code, laying the ground for the development of complete hexagonal systems.

In the next chapter, we’re going to explore how to start developing a hexagonal application by looking at its most important part: the Domain hexagon.

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

• Get Your Hands Dirty on Clean Architecture (Hombergs , 2019)

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 a system’s behavior through application-specific operations.
4. The Framework hexagon.
5. Driving operations are the ones that request actions from the software. Driven operations are started by the hexagonal application itself. These operations go outside the hexagonal application to fetch data from external sources.