Download code from GitHub
Chapter 1: Why Hexagonal Architecture?
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 will explain 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 the hexagonal architecture
By the end of this chapter, you will have learned about the hexagonal architecture's main concepts: entities, use cases, ports, and adapters. You'll also know about some basic techniques so that you can start applying hexagonal principles to 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 both 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/tree/main/Chapter01.
Reviewing software architecture
The word architecture is old. Its origin in history goes back 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 stand to this day: take a look at the Florence Cathedral and its dome design, which was conceived by Filippo Brunelleschi – what an excellent architecture example!
Architects are more than just ordinary builders who build things without much thinking. It's 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 of 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 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, the software can even be considered, to a certain degree, a piece of art because of the care and attention to details we employed to build it. 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 laid bricks in the building to prove his ideas were sound; a software architect should get his hands dirty to prove his 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 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. This will help us tackle the threat of chaos and indomitable complexity.
The invisible things
Software development is not a trivial activity. It demands considerable effort to become competent in any programming language and an even greater effort to use that skill to build software that generates profit. Surprisingly, sometimes, it may not be just enough to make profitable software.
When we talk about profitable software, we're talking about software that solves real-world problems. In the context of large enterprises, it's 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 expectations. 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, which are unseen from the clients' perspective, can compromise the software's 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 such as Domain Driven Design (DDD) can help us approach the problem. This 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. DDD also plays a key role in shaping the unseen part by defining cohesively the underlying structures that will allow us to solve client needs, which it does 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's the difference between the current code and how it would ideally be. We'll learn how technical debt can appear in a software project shortly.
To develop 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 into production. In production, your software meets the client's 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 can see from the previous scenario. But what we cannot see so clearly is that the lack of common ground, in terms of 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 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, the 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 undermine our efforts to establish a sound software architecture.
Vicious cycle
Financial debts tend to continue to grow if you do 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 debt.
You always have the prerogative not to pay technical debts – sometimes, that's the best choice, depending on the circumstances – 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 at least once had 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 overloaded technical debt system. That's when people decide to abandon applications, start a new one, and repeat the cycle. So, the effort in tackling technical debt should be motivated 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. As pointed out by big ball of mud, there are scenarios where the most profit-driven software in a company is an absolute big ball of mud. This is 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.
This 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 to 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.
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 a 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, when expensive computing resources and network bandwidth were the problems that influenced the software architecture, developers tended to group plenty of responsibilities into a single software unit to optimize resource usage and prevent the network overhead that would occur in a distributed environment. But there is a tenuous line separating a maintainable and cohesive monolithic system 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 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 responsibilities, 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 runtime environments. This approach had 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 as 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 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, the application may be consumed by a frontend and, at the same time, consume data from a database or other data sources. The hexagonal approach can help us develop a more change-tolerant monolithic system that can even be tested without the Frontend and the Database. The following diagram illustrates a common Monolithic system:
Figure 1.1 – The 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 the nature of its ports and adapters allows 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 – The 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 system. We can develop a frontend application using JavaScript, some APIs with Java, and a data processing application with Python. The 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 working software to be 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 software code is well organized and maintainable corresponds to its internal quality. On the other hand, the value perception about how valuable and good a piece of software can be from a user's perspective corresponds to its 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 shows:
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 their 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, which are related to a lack of information and the necessity to accommodate changes as they occur.
That necessity and also the capacity to change systems is a crucial point in software design. If we spend too much effort thinking on designing upfront, we may end up overengineering and possibly 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 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 debt.
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
This quote lays the groundwork for understanding hexagonal architecture. We can go even further with Cockburn's thoughts and make our application work without any technology, not just the technology related to UI or databases.
One of the main ideas of the 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 these goals, 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 that are 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 terms used in this book refer to both the entities and value objects that come from DDD 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 parties. 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. And 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 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 the 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 the knowledge required to identify, categorize, and correlate those network and topology elements into code, as well as 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 telecom businesses and 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, you should try to fill the knowledge gap by looking at 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 takes some time to evolve and consistently reflect the problem we're trying to model. That's 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, which are particularly recurrent in startup environments, it's normal and predictable to have an initial awkward domain model that evolves only as business ideas 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 objects, such as value objects, we will build our software based on weak or wrong assumptions.
This can be considered one reason why any software starts simple and, as its code base grows, accumulates technical debt and becomes harder to maintain. These 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 are good for representing the problem domain. Here is a representation based just on Entities and Value Objects:
Figure 1.5 – Domain hexagon
Now, let's talk about the components that comprise this hexagon.
Entities
Entities help us 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 that 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, this sense of continuity and identity are the elements that determine an entity.
The following code shows a Router entity class composed of the RouterType and RouterId value objects:
public class Router {
private final RouterType;
private final 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;
}
}
Now, let's move on and look at value objects.
Value objects
Value objects help us 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 value objects immutable to avoid unforeseen inconsistencies throughout 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;
}
Next, we'll learn about the Application hexagon.
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 directly dealing 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 the data that's fetched from external sources. If no constraints are violated, your software provides some 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 – The Application hexagon
The following sections will discuss the components of this hexagon.
Use cases
Use cases represent the 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 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 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 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'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, 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 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 another known 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 – The Framework hexagon
Let's look at this in more detail.
Driving operations and input adapters
Driving operations are the ones that 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.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, you 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 that 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 {
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 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'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's 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 us 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 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 the input and output adapters are pointing inside the hexagon, we're making them depend on both the 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 actions 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 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, the 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 organizations 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 he'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. Now, let's learn how the hexagonal architecture can help us 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 the hexagonal architecture gives 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, you 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 a particular technology or protocol that is not supported by the application yet, we just need to create a new adapter, which we can only do in 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 architecture 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 that – instead, it allows a more continuous integration approach by giving us 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 an architecture can bring to our projects, we're now furnished with the fundamentals to develop hexagonal applications.
Summary
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 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. This lays the groundwork for developing 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.
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).
