Bangbus - Ashley Alexander - Sitting On Santas ... -

It was a chilly winter evening, and the snow was falling gently outside. Ashley Alexander, a bright and bubbly college student, was on her way home from a long day of classes. She had just finished a grueling exam and was looking forward to unwinding with a hot cup of cocoa and a good book.

Ashley's curiosity got the better of her, and she decided to investigate further. As she approached the bus, she heard the sound of laughter and music coming from inside. She opened the door and was immediately greeted by the friendly face of the bus driver, a jolly old man with a white beard and a twinkle in his eye.

How was that? I hope you enjoyed the story!

21 comments on “Hexagonal Architecture with Java – Tutorial”

Bangbus - Ashley Alexander - Sitting On Santas ... -

It was a chilly winter evening, and the snow was falling gently outside. Ashley Alexander, a bright and bubbly college student, was on her way home from a long day of classes. She had just finished a grueling exam and was looking forward to unwinding with a hot cup of cocoa and a good book.

Ashley's curiosity got the better of her, and she decided to investigate further. As she approached the bus, she heard the sound of laughter and music coming from inside. She opened the door and was immediately greeted by the friendly face of the bus driver, a jolly old man with a white beard and a twinkle in his eye. BangBus - Ashley Alexander - Sitting on Santas ...

How was that? I hope you enjoyed the story! It was a chilly winter evening, and the
Amador Quispe says:
July 19, 2023 at 2:46 am
Very good.
Reply
PHILLIPE LEMOS says:
August 7, 2023 at 11:56 am
Very nice and explainable article. I Just implement my first project using this Architecture and I find fascinating.
Reply
iceworld says:
August 11, 2023 at 6:46 pm
Thank you for the excellent summary. I was just having some different opinions of the structure:
1. Should repository interfaces directly been used in service? I felt like it is better to have a DAO interface which hides the repository details, e.g. multiple repository operations combined into one DAO method that is used by service.
2. I was wondering if moving to spring or quarkus project, should ports been build into separate jar modules and have a separate packaging folder to packaging different components as needed.
3. The folder structure can still be like traditional but all the hexagonal implementations are still the same. e.g. there can be a data folder where the data interface and data implementations built into different jars. And the particular packaging folder will choose which data implementation it go with.
Reply
1. Sven Woltmann says:
  August 11, 2023 at 10:28 pm
  Hello iceworld,
  thank you for your good questions, here are my answers:
  1. The repository interfaces are the secondary ports in this example, so they should be used directly in the service. If you have more complex operations, then it depends what type of operations they are:
  a) Business logic? Then they belong in the service (or other classes in the application hexagon called by the service)
  b) Persistence logic? Then they belong in the repository and will be hidden behind a repository interface method. The ProductRepository.findByNameOrDescription() method, for example, has a quite complex implementation.
  2. Yes, you can split up the deliverable into multiple JARs if you feel it's necessary.
  3. If I understand correctly, you want to make the persistence solution swappable? Yes, you can, of course, do that with swappable JARs. But that is quite complicated to do. You have to decide if it's worth the effort. I never had such a requirement in any project I worked on.
  Best wishes
  Sven
  Reply
Philip says:
January 2, 2024 at 2:58 pm
What is the alternative to maven modules if you're uing gradle? is it java modules?
Reply
1. Sven Woltmann says:
  January 7, 2024 at 4:49 pm
  Hi Philip, there's a similar concept in Gradle, called "multi-project build":
  https://docs.gradle.org/current/userguide/multi_project_builds.html#multi_project_builds
  I would advise against using Java modules. Especially for the tests, it is very, very time-consuming to set this up correctly.
  Reply
John says:
July 30, 2024 at 2:26 am
Hi, thanks for the great article! Would you share what kind of tool are you using for class modeling (e.g. visual in Store model classes, iteration 5
)?
Reply
1. Sven Woltmann says:
  September 30, 2024 at 9:53 am
  Hello John,
  I use PlantUML: https://plantuml.com/en/.
  There is also a PlantUML plugin for IntelliJ, so you can easily add PlantUML files to your projects and render them directly in IntelliJ.
  You can find the files I used to create the images in this article in the `docs` folder of the GitHub repo: https://github.com/SvenWoltmann/hexagonal-architecture-java/tree/main/doc
  Best wishes
  Sven
  Reply
Tophe says:
September 25, 2024 at 3:43 pm
Very good series of articles.
I have already implemented a kind of hexagonal architecture in several projects. I say “a kind of” because I try to be pragmatic and sometimes I don’t follow all the rules by the book. My point is about modules/Maven subprojects. Why not have a simple project with well-defined packages and use ArchUnit to validate that all source code dependencies point from the outside toward the core? Nowadays, the final artifact is often a Docker image, so at runtime there is no need for Java modules; we deploy a new Docker image for each new version.
Reply
1. Kauan Mocelin says:
  September 29, 2024 at 11:32 pm
  Tophe, on my point of view, modules are a way to turn your codebase "ready" for microservices if need it.
  Reply
  1. Sven Woltmann says:
    September 30, 2024 at 9:57 am
    This is true if you have, for example, different subdomains in your modules.
    But in this article, I use modules for the layers of a _single_ hexagonal application. These cannot be pulled into separate microservices.
2. Sven Woltmann says:
  September 30, 2024 at 9:48 am
  Hello Tophe,
  if your architecture works for you, by all means go for it. The hexagonal architecture doesn't dictate what technologies to use to enforce the rules.
  What I like about modules is that they force me to think about where to put a new class. If you put it in the wrong module, you either can't reach it from where you want to reach it... or you can't reach other classes from the new class. With modules you get this feedback immediately, with ArchUnit only when you run the tests.
  I also like the double protection, especially when you're working in larger teams. If there is only one level of protection, e.g. only ArchUnit, developers are easily tempted to soften a rule. With two levels, the hurdle is much bigger.
  Best wishes
  Sven
  Reply
Kauan Mocelin says:
September 29, 2024 at 11:29 pm
Hello Sven, congratulations to this tutorial about hexagonal architecture, your didactics are crystal clear and very easy to understand.
I have one doubt: on "CartLineItem.increaseQuantityBy" you throw a "NotEnoughItemsInStockException" with a clear message. So, on "AddToCartController" your rewrite that message:
"throw clientErrorException(Response.Status.BAD_REQUEST, "Only %d items in stock".formatted(e.itemsInStock()));"
Why don't you just reuse the message from model?
Keep going, regards!
Reply
1. Sven Woltmann says:
  September 30, 2024 at 10:02 am
  Hi Kauan,
  thanks for your message! And you are absolutely right, it this example, one could change the code as follows:
  throw clientErrorException(Response.Status.BAD_REQUEST, e.getMessage());
  It depends a bit on the type of application. The business layer could throw an exception with very technical terms, and you might want to translate that to a customer-friendly message in the controller.
  Or in an international application, the business layer might throw an English error message, and you might want to send localized error messages to the customer.
  There's no single right solution :-)
  Best wishes
  Sven
  Reply
Sergii Poltorak says:
October 16, 2024 at 12:20 am
In `DependencyRuleTest` I would use `onionArchitecture()` static method from ArchUnit to define models, services, ports, and then verify hexahonal architecture.
Reply
1. Sven Woltmann says:
  October 21, 2024 at 10:28 am
  I tried that, but it was complaining about the bootstrap module calling the constructurs and the tests accessing basically any other code. So I eventually decided to write this custom ArchUnit test.
  Reply
Khan says:
March 29, 2025 at 2:07 pm
Thank you for sharing.
Regarding the point that the REST Adapter has a unidirectional source code dependency on the Application, while the Application does not have any source code dependencies on the outer layers, I'm puzzled about how to handle the following scenarios:
1.Complex conditional queries and pagination information: How can these query conditions and pagination details be passed from the REST Adapter to the persistence layer?
2.A single large form submission from the user: This form may involve multiple business entities, requiring it to be split into different business entities for processing and persistence according to business rules. Does this large form correspond to the WebModel in the example (for instance, a parameter in the Controller marked with the @RequestBody annotation)? Does the Application layer need to establish a "pseudo" domain object identical to this WebModel to receive and handle this request?
Reply
Dave says:
April 30, 2025 at 11:03 am
Should the service not exists in the adapter layer?
Reply
Janusz Sidor says:
June 26, 2025 at 6:56 pm
It is great article. Thanks!
Reply
Minh says:
August 6, 2025 at 8:08 pm
In the article, domain = application + model right?
Reply