<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Aymen Jamaaoui</title>
    <description>The latest articles on DEV Community by Aymen Jamaaoui (@aymenjamaaoui).</description>
    <link>https://dev.to/aymenjamaaoui</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4245981%2F01f28eb1-6988-46cb-9ad3-16c810ebcd1a.jpg</url>
      <title>DEV Community: Aymen Jamaaoui</title>
      <link>https://dev.to/aymenjamaaoui</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/aymenjamaaoui"/>
    <language>en</language>
    <item>
      <title>Hexagonal architecture: ports and adapters, step by step</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Sun, 15 Nov 2026 11:00:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/hexagonal-architecture-ports-and-adapters-step-by-step-52h4</link>
      <guid>https://dev.to/aymenjamaaoui/hexagonal-architecture-ports-and-adapters-step-by-step-52h4</guid>
      <description>&lt;p&gt;"Does the controller implement the incoming port?" "Where do I put the&lt;br&gt;
repository interface?" When you start with hexagonal architecture, or&lt;br&gt;
when you come from a layered application, the direction of the arrows&lt;br&gt;
is easy to get wrong.&lt;/p&gt;

&lt;p&gt;This post explains the ideas one at a time, with one example: create&lt;br&gt;
an order with Spring Boot. At each step, one question guides you:&lt;br&gt;
&lt;strong&gt;here, who calls? who implements?&lt;/strong&gt; The full code is in the public&lt;br&gt;
repository&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/hexagonal-architecture-demo/-/tree/v1" rel="noopener noreferrer"&gt;hexagonal-architecture-demo&lt;/a&gt;&lt;br&gt;
(tag &lt;code&gt;v1&lt;/code&gt;). For a more real case, with Kafka and several use cases,&lt;br&gt;
see&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/hexagonal-architecture-spring-boot/" rel="noopener noreferrer"&gt;Hexagonal architecture with Spring Boot: a simple example&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  The problem
&lt;/h2&gt;

&lt;p&gt;In a layered application, each layer calls the layer below it: the&lt;br&gt;
controller calls the service, the service calls the repository, and&lt;br&gt;
the repository talks to the database. The dependencies go down. So the&lt;br&gt;
business service depends on JPA: to test it, you need a database, or a&lt;br&gt;
lot of mocks.&lt;/p&gt;

&lt;p&gt;Hexagonal architecture turns some of these arrows around. In the&lt;br&gt;
center is the core: the domain and the use cases, in plain Java. Around&lt;br&gt;
it are the adapters: REST, JPA, Kafka, and so on. All dependencies&lt;br&gt;
point to the core. The core knows no adapter.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/hexagonal-architecture-ports-adapters/" rel="noopener noreferrer"&gt;See the diagram in the original post.&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The name comes from Alistair Cockburn (2005). He also calls it "Ports&lt;br&gt;
and Adapters". Its goal: "Allow an application to equally be driven by&lt;br&gt;
users, programs, automated test or batch scripts, and to be developed&lt;br&gt;
and tested in isolation from its eventual run-time devices and&lt;br&gt;
databases." The hexagon shape has no special meaning: "The hexagon is&lt;br&gt;
not a hexagon because the number six is important".&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Here:&lt;/strong&gt; in layers, each layer calls the one below and depends on&lt;br&gt;
it. In hexagonal architecture, the adapters depend on the core, never&lt;br&gt;
the other way.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;
  
  
  The big picture
&lt;/h2&gt;

&lt;p&gt;Here is the whole example in one diagram. There are two kinds of&lt;br&gt;
arrows: full line = "calls", dotted line = "implements".&lt;/p&gt;

&lt;p&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/hexagonal-architecture-ports-adapters/" rel="noopener noreferrer"&gt;See the diagram in the original post.&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;It all fits in two rules:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;incoming side&lt;/strong&gt;: an adapter (here the REST controller) &lt;strong&gt;calls&lt;/strong&gt; an
incoming port; the core &lt;strong&gt;implements&lt;/strong&gt; it;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;outgoing side&lt;/strong&gt;: the core &lt;strong&gt;calls&lt;/strong&gt; an outgoing port; an adapter
(here JPA) &lt;strong&gt;implements&lt;/strong&gt; it.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A port is an interface that belongs to the core. Cockburn defines it&lt;br&gt;
like this: "A port identifies a purposeful conversation." An adapter&lt;br&gt;
translates between this port and a technology. Cockburn also talks&lt;br&gt;
about "driving adapters and driven adapters": the adapters that drive&lt;br&gt;
the application (incoming), and the ones the application drives&lt;br&gt;
(outgoing).&lt;/p&gt;

&lt;p&gt;In the repository, each part has its own package:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Package&lt;/th&gt;
&lt;th&gt;Content&lt;/th&gt;
&lt;th&gt;Knows Spring?&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;domain&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;Order&lt;/code&gt;, &lt;code&gt;OrderLine&lt;/code&gt;, &lt;code&gt;InvalidOrderException&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;application.port.in&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;CreateOrderUseCase&lt;/code&gt;, &lt;code&gt;CreateOrderCommand&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;application.port.out&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;OrderRepository&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;application&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;CreateOrderService&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;adapter.in.web&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the REST controller and its DTOs&lt;/td&gt;
&lt;td&gt;yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;adapter.out.persistence&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the JPA entity, the adapter, the mapper&lt;/td&gt;
&lt;td&gt;yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;config&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the Spring wiring&lt;/td&gt;
&lt;td&gt;yes&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Here:&lt;/strong&gt; the incoming adapter calls, the core implements. The core&lt;br&gt;
calls, the outgoing adapter implements.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;
  
  
  The domain
&lt;/h2&gt;

&lt;p&gt;The domain holds the business rules, and nothing else. In the example,&lt;br&gt;
the rule is simple: an order has at least one line, each quantity is&lt;br&gt;
between 1 and 99, and the domain computes the total.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;Order&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="no"&gt;UUID&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;OrderLine&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;Order&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;UUID&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;OrderLine&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;InvalidOrderException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"an order needs an id"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;lines&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="n"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isEmpty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;InvalidOrderException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"an order needs at least one line"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lines&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;copyOf&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="nc"&gt;Order&lt;/span&gt; &lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;OrderLine&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Order&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;UUID&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;randomUUID&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;BigDecimal&lt;/span&gt; &lt;span class="nf"&gt;total&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stream&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;OrderLine&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="n"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reduce&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;BigDecimal&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;ZERO&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;BigDecimal&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="n"&gt;add&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="c1"&gt;// id(), lines()&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;OrderLine&lt;/code&gt; is a &lt;code&gt;record&lt;/code&gt; that checks the quantity in its constructor.&lt;br&gt;
The rules are checked when the object is created, so an &lt;code&gt;Order&lt;/code&gt; is&lt;br&gt;
always valid.&lt;/p&gt;

&lt;p&gt;Why no JPA annotation here? Because the shape of the database is not a&lt;br&gt;
business rule. A renamed column must not change &lt;code&gt;Order&lt;/code&gt;. Why no DTO?&lt;br&gt;
For the same reason: the JSON format of the API belongs to the REST&lt;br&gt;
adapter.&lt;/p&gt;

&lt;p&gt;In this post, &lt;strong&gt;the domain knows nobody&lt;/strong&gt;: not Spring, not the ports,&lt;br&gt;
not the application. This is a common choice, not a rule from&lt;br&gt;
Cockburn: his page talks about "the application" in the center, and&lt;br&gt;
does not split it into a domain and use cases. Other code bases put&lt;br&gt;
interfaces in the domain (see "Common mistakes").&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Here:&lt;/strong&gt; the domain calls no port and implements no port. The use&lt;br&gt;
case calls it.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;
  
  
  The ports and the use case
&lt;/h2&gt;

&lt;p&gt;The &lt;strong&gt;incoming port&lt;/strong&gt; says what the application offers to the outside&lt;br&gt;
world. It is an interface, in &lt;code&gt;application.port.in&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;interface&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderUseCase&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="nc"&gt;Order&lt;/span&gt; &lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;CreateOrderCommand&lt;/span&gt; &lt;span class="n"&gt;command&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderCommand&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;OrderLine&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The command has no JSON and no HTTP in it. Another adapter (a Kafka&lt;br&gt;
listener, a batch job, a test) can use it in the same way.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;outgoing port&lt;/strong&gt; says what the application needs. It is also an&lt;br&gt;
interface, in &lt;code&gt;application.port.out&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;interface&lt;/span&gt; &lt;span class="nc"&gt;OrderRepository&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Order&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The core writes this interface, with its own words: &lt;code&gt;save&lt;/code&gt;, not&lt;br&gt;
&lt;code&gt;persist&lt;/code&gt; or &lt;code&gt;insertInto&lt;/code&gt;. It does not know that JPA is behind it.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;use case&lt;/strong&gt; implements the incoming port and calls the outgoing&lt;br&gt;
port:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderService&lt;/span&gt; &lt;span class="k"&gt;implements&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderUseCase&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;OrderRepository&lt;/span&gt; &lt;span class="n"&gt;orderRepository&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderService&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;OrderRepository&lt;/span&gt; &lt;span class="n"&gt;orderRepository&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;orderRepository&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;orderRepository&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="nd"&gt;@Override&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;Order&lt;/span&gt; &lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;CreateOrderCommand&lt;/span&gt; &lt;span class="n"&gt;command&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nc"&gt;Order&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;command&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;orderRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Why an interface for the incoming port, when it has only one&lt;br&gt;
implementation? It gives the contract a name, and the adapter depends&lt;br&gt;
only on this contract. This is also a choice: a lot of code calls the&lt;br&gt;
use case class directly. For the outgoing port, the interface is&lt;br&gt;
required: it is what lets the core not depend on JPA.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Here:&lt;/strong&gt; &lt;code&gt;CreateOrderService&lt;/code&gt; implements the incoming port and calls&lt;br&gt;
the outgoing port. Both interfaces are in the core.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;
  
  
  The adapters
&lt;/h2&gt;
&lt;h3&gt;
  
  
  The outgoing adapter: JPA
&lt;/h3&gt;

&lt;p&gt;The JPA adapter implements the outgoing port:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Component&lt;/span&gt;
&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;OrderPersistenceAdapter&lt;/span&gt; &lt;span class="k"&gt;implements&lt;/span&gt; &lt;span class="nc"&gt;OrderRepository&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;OrderJpaRepository&lt;/span&gt; &lt;span class="n"&gt;jpaRepository&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="nc"&gt;OrderPersistenceAdapter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;OrderJpaRepository&lt;/span&gt; &lt;span class="n"&gt;jpaRepository&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;jpaRepository&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;jpaRepository&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="nd"&gt;@Override&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Order&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;jpaRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;OrderMapper&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toEntity&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;OrderJpaRepository&lt;/code&gt; is a Spring Data interface&lt;br&gt;
(&lt;code&gt;JpaRepository&amp;lt;OrderJpaEntity, UUID&amp;gt;&lt;/code&gt;). Only the adapter knows it.&lt;/p&gt;

&lt;p&gt;The JPA entity is a &lt;strong&gt;different class&lt;/strong&gt; from &lt;code&gt;Order&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Entity&lt;/span&gt;
&lt;span class="nd"&gt;@Table&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"orders"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;OrderJpaEntity&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="nd"&gt;@Id&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="no"&gt;UUID&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="nd"&gt;@ElementCollection&lt;/span&gt;
    &lt;span class="nd"&gt;@CollectionTable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"order_lines"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;joinColumns&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nd"&gt;@JoinColumn&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"order_id"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;OrderLineEmbeddable&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;lines&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ArrayList&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;protected&lt;/span&gt; &lt;span class="nc"&gt;OrderJpaEntity&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="c1"&gt;// for JPA&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="c1"&gt;// constructor and getters&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It has the JPA constraints (a constructor with no arguments, fields&lt;br&gt;
that are not &lt;code&gt;final&lt;/code&gt;), and the domain does not have them. The mapper&lt;br&gt;
goes from one to the other:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="nc"&gt;OrderJpaEntity&lt;/span&gt; &lt;span class="nf"&gt;toEntity&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Order&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;OrderLineEmbeddable&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;lines&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stream&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;line&lt;/span&gt; &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;OrderLineEmbeddable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;line&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;productCode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;line&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;quantity&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;line&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;unitPrice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toList&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;OrderJpaEntity&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;id&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Here, the mapper goes in one direction only, because the port has only&lt;br&gt;
&lt;code&gt;save&lt;/code&gt;. A read use case would add the other direction (entity →&lt;br&gt;
&lt;code&gt;Order&lt;/code&gt;).&lt;/p&gt;

&lt;p&gt;The database is H2, in memory. The Spring Boot docs say: "Spring Boot&lt;br&gt;
can auto-configure embedded H2, HSQL, and Derby (deprecated)&lt;br&gt;
databases. You need not provide any connection URLs." The tables are&lt;br&gt;
also created at startup for an embedded database. You do not need&lt;br&gt;
Docker to try the example.&lt;/p&gt;
&lt;h3&gt;
  
  
  The incoming adapter: REST
&lt;/h3&gt;

&lt;p&gt;The controller &lt;strong&gt;does not implement&lt;/strong&gt; the incoming port. It &lt;strong&gt;calls&lt;/strong&gt;&lt;br&gt;
it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@RestController&lt;/span&gt;
&lt;span class="nd"&gt;@RequestMapping&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"/api/orders"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;OrderController&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderUseCase&lt;/span&gt; &lt;span class="n"&gt;createOrderUseCase&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="nc"&gt;OrderController&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;CreateOrderUseCase&lt;/span&gt; &lt;span class="n"&gt;createOrderUseCase&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;createOrderUseCase&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;createOrderUseCase&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="nd"&gt;@PostMapping&lt;/span&gt;
    &lt;span class="nd"&gt;@ResponseStatus&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;HttpStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;CREATED&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="nc"&gt;OrderResponse&lt;/span&gt; &lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nd"&gt;@RequestBody&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderRequest&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nc"&gt;Order&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;createOrderUseCase&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toCommand&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;OrderResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="nd"&gt;@ExceptionHandler&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;InvalidOrderException&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;class&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="nc"&gt;ProblemDetail&lt;/span&gt; &lt;span class="nf"&gt;invalidOrder&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;InvalidOrderException&lt;/span&gt; &lt;span class="n"&gt;exception&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;ProblemDetail&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;forStatusAndDetail&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;HttpStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;BAD_REQUEST&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;exception&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getMessage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The DTOs &lt;code&gt;CreateOrderRequest&lt;/code&gt; and &lt;code&gt;OrderResponse&lt;/code&gt; are records, in the&lt;br&gt;
adapter package. The DTO-to-command conversion happens here&lt;br&gt;
(&lt;code&gt;request.toCommand()&lt;/code&gt;), not in the core. A broken rule&lt;br&gt;
(&lt;code&gt;InvalidOrderException&lt;/code&gt;) becomes a 400 response.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The HTTP direction is not the architecture direction.&lt;/strong&gt; In HTTP, the&lt;br&gt;
request comes in and the response goes out. But for the architecture,&lt;br&gt;
the controller does one thing only: it calls the incoming port, and the&lt;br&gt;
response is the return value of this call. It is still an incoming&lt;br&gt;
adapter.&lt;/p&gt;

&lt;p&gt;A test run, with the application started (&lt;code&gt;mvn spring-boot:run&lt;/code&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;$ curl -X POST localhost:8080/api/orders -H 'Content-Type: application/json' \
  -d '{"lines":[{"productCode":"BOOK-1","quantity":2,"unitPrice":12.50},{"productCode":"PEN-7","quantity":3,"unitPrice":1.20}]}'
{"id":"45e27a15-2bce-454b-83a4-3b770cf674b3","lines":[{"productCode":"BOOK-1","quantity":2,"unitPrice":12.50},{"productCode":"PEN-7","quantity":3,"unitPrice":1.20}],"total":28.60}

$ curl -X POST localhost:8080/api/orders -H 'Content-Type: application/json' \
  -d '{"lines":[{"productCode":"BOOK-1","quantity":0,"unitPrice":12.50}]}'
{"detail":"quantity must be between 1 and 99, got 0","instance":"/api/orders","status":400,"title":"Bad Request"}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The domain computes the total (28.60). The error message comes from&lt;br&gt;
the domain, and the REST adapter turns it into a 400.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Here:&lt;/strong&gt; the controller calls the incoming port; the JPA adapter&lt;br&gt;
implements the outgoing port. The DTOs and the JPA entity stay in&lt;br&gt;
their adapters.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;
  
  
  The Spring wiring
&lt;/h2&gt;

&lt;p&gt;The core does not know Spring. So who gives an &lt;code&gt;OrderRepository&lt;/code&gt; to&lt;br&gt;
&lt;code&gt;CreateOrderService&lt;/code&gt;? Spring does, through the constructor. The Spring&lt;br&gt;
Framework docs recommend it: "The Spring team generally advocates&lt;br&gt;
constructor injection, as it lets you implement application components&lt;br&gt;
as immutable objects and ensures that required dependencies are not&lt;br&gt;
&lt;code&gt;null&lt;/code&gt;." And with a single constructor, you do not need &lt;code&gt;@Autowired&lt;/code&gt;:&lt;br&gt;
"An &lt;code&gt;@Autowired&lt;/code&gt; annotation on such a constructor is not necessary if&lt;br&gt;
the target bean defines only one constructor."&lt;/p&gt;

&lt;p&gt;To create the use case with no annotation in the core, a&lt;br&gt;
&lt;code&gt;@Configuration&lt;/code&gt; class declares the bean:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Configuration&lt;/span&gt;
&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;OrderConfiguration&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="nd"&gt;@Bean&lt;/span&gt;
    &lt;span class="nc"&gt;CreateOrderUseCase&lt;/span&gt; &lt;span class="nf"&gt;createOrderUseCase&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;OrderRepository&lt;/span&gt; &lt;span class="n"&gt;orderRepository&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderService&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;orderRepository&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Spring finds the bean that implements &lt;code&gt;OrderRepository&lt;/code&gt; (the JPA&lt;br&gt;
adapter, marked &lt;code&gt;@Component&lt;/code&gt;) and passes it to the method. The&lt;br&gt;
controller gets the use case in the same way, through its constructor.&lt;/p&gt;

&lt;p&gt;The common variant is shorter: &lt;code&gt;@Service&lt;/code&gt; on &lt;code&gt;CreateOrderService&lt;/code&gt;, and&lt;br&gt;
no configuration class. It works too. Its limit: the core then depends&lt;br&gt;
on a Spring annotation. In the repository, an ArchUnit test forbids&lt;br&gt;
this. With &lt;code&gt;@Service&lt;/code&gt; on the use case, the build fails:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Architecture Violation [Priority: MEDIUM] - Rule 'no classes that reside in any package ['..domain..', '..application..'] should depend on classes that reside in any package ['org.springframework..', 'jakarta..', '..adapter..', '..config..']' was violated (1 times):
Class &amp;lt;dev.aymenjamaaoui.hexagonal.application.CreateOrderService&amp;gt; is annotated with &amp;lt;org.springframework.stereotype.Service&amp;gt; in (CreateOrderService.java:0)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Here:&lt;/strong&gt; Spring calls nothing and implements nothing in the core. It&lt;br&gt;
creates the objects and connects them: the JPA adapter into the use&lt;br&gt;
case, the use case into the controller.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Testing without Spring
&lt;/h2&gt;

&lt;p&gt;This is the real gain. The use case depends only on interfaces, so you&lt;br&gt;
can test it with a fake outgoing port, in memory.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;InMemoryOrderRepository&lt;/span&gt; &lt;span class="k"&gt;implements&lt;/span&gt; &lt;span class="nc"&gt;OrderRepository&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Order&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;saved&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ArrayList&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="nd"&gt;@Override&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Order&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;saved&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Order&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;saved&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;saved&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderServiceTest&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;InMemoryOrderRepository&lt;/span&gt; &lt;span class="n"&gt;repository&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;InMemoryOrderRepository&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderService&lt;/span&gt; &lt;span class="n"&gt;service&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderService&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;repository&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="nd"&gt;@Test&lt;/span&gt;
    &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;savesAValidOrder&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nc"&gt;Order&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;service&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderCommand&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
                &lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;of&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;OrderLine&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"BOOK-1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;BigDecimal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"12.50"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

        &lt;span class="nf"&gt;assertThat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;repository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;saved&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;containsExactly&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="nf"&gt;assertThat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;total&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isEqualByComparingTo&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"25.00"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="nd"&gt;@Test&lt;/span&gt;
    &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;savesNothingWhenTheOrderIsInvalid&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nf"&gt;assertThatThrownBy&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;service&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;CreateOrderCommand&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;of&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isInstanceOf&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;InvalidOrderException&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;class&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

        &lt;span class="nf"&gt;assertThat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;repository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;saved&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isEmpty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;No Spring, no database, no mock: just &lt;code&gt;new&lt;/code&gt;. On my machine,&lt;br&gt;
two runs of &lt;code&gt;mvn verify&lt;/code&gt; give:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Test class&lt;/th&gt;
&lt;th&gt;What it tests&lt;/th&gt;
&lt;th&gt;Time&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OrderTest&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the domain alone&lt;/td&gt;
&lt;td&gt;0.002 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;CreateOrderServiceTest&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the use case, with the fake port&lt;/td&gt;
&lt;td&gt;0.032 to 0.034 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OrderApiTest&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;HTTP → controller → use case → JPA → H2 (&lt;code&gt;@SpringBootTest&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;1.94 to 2.08 s&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The end-to-end test is still useful: it checks the wiring. But you can&lt;br&gt;
test the rules without starting Spring.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Here:&lt;/strong&gt; the test calls the incoming port (through the use case),&lt;br&gt;
and the fake repository implements the outgoing port, in place of the&lt;br&gt;
JPA adapter.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Common mistakes
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Wrong&lt;/th&gt;
&lt;th&gt;Right&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;The REST controller implements the incoming port.&lt;/td&gt;
&lt;td&gt;The controller &lt;strong&gt;calls&lt;/strong&gt; the incoming port; the use case &lt;strong&gt;implements&lt;/strong&gt; it.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The domain gets the DTO or the JPA entity.&lt;/td&gt;
&lt;td&gt;The DTO and the JPA entity stay in their adapters; the conversion happens at the border.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The controller is both incoming and outgoing, because the HTTP response "goes out".&lt;/td&gt;
&lt;td&gt;The response is the return value of the call to the incoming port. The controller is an incoming adapter.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;One point depends on the team's choices: &lt;strong&gt;where the repository&lt;br&gt;
interface lives&lt;/strong&gt;. In this post, it is in &lt;code&gt;application.port.out&lt;/code&gt;, and&lt;br&gt;
the domain knows nobody. In many DDD projects, it is in the domain.&lt;br&gt;
Microsoft's .NET guide on DDD says: "it's recommended that you define&lt;br&gt;
and place the repository interfaces in the domain model layer". Both&lt;br&gt;
ways work. What matters: the interface belongs to the core, and the&lt;br&gt;
implementation is outside.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Here:&lt;/strong&gt; in both variants, the core calls the interface and the&lt;br&gt;
adapter implements it. Only the package of the interface changes.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  When not to use it, and a summary sheet
&lt;/h2&gt;

&lt;p&gt;This structure has a cost. For one feature (create an order), the&lt;br&gt;
repository has 17 classes in &lt;code&gt;src/main&lt;/code&gt;, with 3 for the ports, plus a&lt;br&gt;
JPA entity and a mapper next to the domain. For a simple CRUD, with no&lt;br&gt;
real business rule, a layered application is enough: there is nothing&lt;br&gt;
to protect in the center.&lt;/p&gt;

&lt;p&gt;It pays off when the rules grow, when a technology changes (another&lt;br&gt;
database, Kafka messages next to REST), or when you want to test the&lt;br&gt;
rules fast and often.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Summary sheet&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Element&lt;/th&gt;
&lt;th&gt;Package&lt;/th&gt;
&lt;th&gt;Who calls it&lt;/th&gt;
&lt;th&gt;Who implements it&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;Order&lt;/code&gt; (domain)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;domain&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the use case&lt;/td&gt;
&lt;td&gt;— (a class)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;CreateOrderUseCase&lt;/code&gt; (incoming port)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;application.port.in&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;OrderController&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;CreateOrderService&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;CreateOrderService&lt;/code&gt; (use case)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;application&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the controller, through the incoming port&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;OrderRepository&lt;/code&gt; (outgoing port)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;application.port.out&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;CreateOrderService&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;OrderPersistenceAdapter&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;OrderController&lt;/code&gt; (incoming adapter)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;adapter.in.web&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Spring, for each HTTP request&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;OrderPersistenceAdapter&lt;/code&gt; (outgoing adapter)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;adapter.out.persistence&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the use case, through the outgoing port&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Three rules to keep:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;dependencies point to the core;&lt;/li&gt;
&lt;li&gt;on the incoming side, the adapter calls and the core implements; on
the outgoing side, the core calls and the adapter implements;&lt;/li&gt;
&lt;li&gt;DTOs and JPA entities do not cross the border.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;To keep rule 1 true over time, an ArchUnit test checks it at each&lt;br&gt;
build: see the part "The rule, checked by the build" in&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/hexagonal-architecture-spring-boot/" rel="noopener noreferrer"&gt;the example with Kafka&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Tested with
&lt;/h2&gt;

&lt;p&gt;Java 25 (Temurin 25.0.5), Maven 3.10.0, Spring Boot 4.1.2 (Hibernate&lt;br&gt;
7.4.13), H2 2.4.240 and ArchUnit 1.5.1, on macOS. The code is frozen by&lt;br&gt;
the tag&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/hexagonal-architecture-demo/-/tree/v1" rel="noopener noreferrer"&gt;&lt;code&gt;v1&lt;/code&gt;&lt;/a&gt;&lt;br&gt;
of the demo repository.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Alistair Cockburn, &lt;a href="https://alistair.cockburn.us/hexagonal-architecture/" rel="noopener noreferrer"&gt;Hexagonal architecture&lt;/a&gt;
(2005)&lt;/li&gt;
&lt;li&gt;Microsoft Learn, &lt;a href="https://learn.microsoft.com/en-us/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/infrastructure-persistence-layer-design" rel="noopener noreferrer"&gt;Designing the infrastructure persistence layer&lt;/a&gt;
(.NET guide, DDD part)&lt;/li&gt;
&lt;li&gt;Spring Framework, &lt;a href="https://docs.spring.io/spring-framework/reference/core/beans/dependencies/factory-collaborators.html" rel="noopener noreferrer"&gt;Dependency Injection&lt;/a&gt;,
&lt;a href="https://docs.spring.io/spring-framework/reference/core/beans/annotation-config/autowired.html" rel="noopener noreferrer"&gt;Using @Autowired&lt;/a&gt;,
&lt;a href="https://docs.spring.io/spring-framework/reference/core/beans/java/basic-concepts.html" rel="noopener noreferrer"&gt;@Bean and @Configuration&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Spring Boot, &lt;a href="https://docs.spring.io/spring-boot/reference/data/sql.html" rel="noopener noreferrer"&gt;SQL Databases&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.archunit.org/userguide/html/000_Index.html" rel="noopener noreferrer"&gt;ArchUnit User Guide&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/hexagonal-architecture-spring-boot/" rel="noopener noreferrer"&gt;Hexagonal architecture with Spring Boot: a simple example&lt;/a&gt;:
the same ideas on a real service, with Kafka, a &lt;code&gt;sealed&lt;/code&gt; result and
ArchUnit.&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/kafka-spring-boot-locally/" rel="noopener noreferrer"&gt;Kafka and Spring Boot: a complete local project&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>architecture</category>
      <category>java</category>
      <category>springboot</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>Hexagonal architecture with Spring Boot: a simple example</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Sat, 24 Oct 2026 18:45:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/hexagonal-architecture-with-spring-boot-a-simple-example-1p5l</link>
      <guid>https://dev.to/aymenjamaaoui/hexagonal-architecture-with-spring-boot-a-simple-example-1p5l</guid>
      <description>&lt;p&gt;In a Spring Boot service organized by technical layers (&lt;code&gt;controller&lt;/code&gt;,&lt;br&gt;
&lt;code&gt;service&lt;/code&gt;, &lt;code&gt;repository&lt;/code&gt;, &lt;code&gt;entity&lt;/code&gt;…), the business rule ends up next to&lt;br&gt;
JPA, Kafka and Jackson code. To test it, you start Spring, or you mock a&lt;br&gt;
large part of the framework.&lt;/p&gt;

&lt;p&gt;This post shows another way to organize the code, the hexagonal&lt;br&gt;
architecture, on a small and complete example: a service that reads&lt;br&gt;
sensor readings from Kafka, checks them and computes statistics. The&lt;br&gt;
domain and the use cases are plain Java, Spring, Kafka and JPA stay in&lt;br&gt;
adapters, and a test makes the build fail if this rule is broken. The&lt;br&gt;
code is in the tag&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/iot-monitoring-platform/-/tree/phase-1" rel="noopener noreferrer"&gt;&lt;code&gt;phase-1&lt;/code&gt;&lt;/a&gt;&lt;br&gt;
of the public repository iot-monitoring-platform, presented in the post&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/kafka-spring-boot-locally/" rel="noopener noreferrer"&gt;Kafka and Spring Boot: a complete local project&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  The idea in short
&lt;/h2&gt;

&lt;p&gt;The hexagonal architecture comes from an article by Alistair Cockburn&lt;br&gt;
(2005), who also calls it « Ports and Adapters ». The idea fits in three&lt;br&gt;
words:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;the core&lt;/strong&gt; (the domain and the use cases) holds the rules of the
application, in simple code, without a framework;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;the ports&lt;/strong&gt; are interfaces: what the core offers (input ports) and
what it needs (output ports);&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;the adapters&lt;/strong&gt; connect the ports to the real world: a REST
controller, a Kafka listener, a JPA repository.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Dependencies always point to the inside: an adapter knows the core, the&lt;br&gt;
core knows no adapter.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/hexagonal-architecture-spring-boot/" rel="noopener noreferrer"&gt;See the diagram in the original post.&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The service of the example, &lt;code&gt;iot-backend-processing&lt;/code&gt;, is small on&lt;br&gt;
purpose: it receives a line of text from Kafka (for example&lt;br&gt;
&lt;code&gt;sensor-1 TEMPERATURE 21.5&lt;/code&gt;), checks it with a business rule, stores the&lt;br&gt;
message, updates the statistics of the sensor, and gives them through a&lt;br&gt;
REST API. This is enough to see each part of the architecture, with no&lt;br&gt;
noise around it.&lt;/p&gt;
&lt;h2&gt;
  
  
  Before, after
&lt;/h2&gt;

&lt;p&gt;Before this work, the service was organized by technical layers (public&lt;br&gt;
history of the project, commit &lt;code&gt;82b4054&lt;/code&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;processing/
  BkProcessingApplication.java
  config/       CorsConfig, KafkaConsumerConfig
  controller/   StatsController
  dto/          SensorEvent, SensorEventEnvelope, SensorStats
  entity/       SensorReading
  kafka/        SensorEventConsumer
  repository/   SensorReadingRepository
  service/      AggregationService
  util/         PodInfo
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the tag &lt;code&gt;phase-1&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;processing/
  ProcessingApplication.java
  domain/                  SensorReading, ParseResult, SensorStatistics,
                           SensorType, ReceivedMessage, MessageStatus
  application/
    port/in/               StoreMessageUseCase, ListLastMessagesUseCase,
                           ListStatisticsUseCase, InvalidLimitException
    port/out/              MessageRepository, StatisticsRepository
    StoreMessageService, ListLastMessagesService, ListStatisticsService
  adapter/
    in/kafka/              SensorMessageListener
    in/web/                MessageController, StatisticsController + responses
    out/persistence/       JPA entities, Spring Data repositories, adapters
  config/                  ProcessingConfig
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The two versions do not have the same features: the old one passed pod&lt;br&gt;
info and JSON envelopes along, with no business rule; the new one reads&lt;br&gt;
and checks each line. So we do not compare the number of classes, only&lt;br&gt;
the shape. Before, the name of a package said a technology (&lt;code&gt;kafka&lt;/code&gt;,&lt;br&gt;
&lt;code&gt;repository&lt;/code&gt;); now it says a role.&lt;/p&gt;
&lt;h2&gt;
  
  
  The domain: the rule, in plain Java
&lt;/h2&gt;

&lt;p&gt;A valid line has three parts: a sensor, a type and a value inside the&lt;br&gt;
range of its type. The rule is in &lt;code&gt;SensorReading.parse&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt; &lt;span class="nf"&gt;parse&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;String&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isBlank&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Rejected&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"empty line"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="kt"&gt;String&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;strip&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"\\s+"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Rejected&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"a line needs 3 parts: sensor, type and value"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="kt"&gt;String&lt;/span&gt; &lt;span class="n"&gt;sensorId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="no"&gt;SENSOR_ID&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;matcher&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;sensorId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;matches&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Rejected&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"invalid sensor id "&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;sensorId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="nc"&gt;Optional&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;SensorType&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;SensorType&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fromName&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isEmpty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Rejected&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"unknown type "&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="no"&gt;DECIMAL&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;matcher&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;matches&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Rejected&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"invalid value "&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="kt"&gt;double&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;Double&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;parseDouble&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;accepts&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Rejected&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;name&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="s2"&gt;" must be between "&lt;/span&gt;
                &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="s2"&gt;" and "&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Valid&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;SensorReading&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;sensorId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For a service that receives sensor data, a bad line is a normal case,&lt;br&gt;
not a bug of the program. So the method does not throw an exception: it&lt;br&gt;
returns a result, one of the two cases of a &lt;code&gt;sealed&lt;/code&gt; interface&lt;br&gt;
(Java 17):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;interface&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;Valid&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;SensorReading&lt;/span&gt; &lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;implements&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;Rejected&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;String&lt;/span&gt; &lt;span class="n"&gt;reason&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;implements&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The compiler knows all the cases: a &lt;code&gt;switch&lt;/code&gt; on a &lt;code&gt;ParseResult&lt;/code&gt;&lt;br&gt;
(pattern matching for &lt;code&gt;switch&lt;/code&gt;, Java 21) must handle &lt;code&gt;Valid&lt;/code&gt; and&lt;br&gt;
&lt;code&gt;Rejected&lt;/code&gt;, or it does not compile.&lt;/p&gt;

&lt;p&gt;The statistics of a sensor are an immutable record. Each reading gives&lt;br&gt;
new statistics, without reading the past readings again:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;SensorStatistics&lt;/span&gt; &lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;SensorReading&lt;/span&gt; &lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;sensorId&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;equals&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sensorId&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;IllegalArgumentException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"The reading of "&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sensorId&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="s2"&gt;" "&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="s2"&gt;" does not belong to the statistics of "&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;sensorId&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="s2"&gt;" "&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;SensorStatistics&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;sensorId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;count&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="nc"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;min&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;value&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;max&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;value&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;sum&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;value&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Here, the exception makes sense: adding the reading of another sensor&lt;br&gt;
would be a bug of the program, not bad data.&lt;/p&gt;

&lt;p&gt;In the whole &lt;code&gt;domain&lt;/code&gt; package, there is no import of Spring, Kafka, JPA&lt;br&gt;
or Jackson.&lt;/p&gt;
&lt;h2&gt;
  
  
  The ports and the use cases
&lt;/h2&gt;

&lt;p&gt;The input port says what the service offers:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;interface&lt;/span&gt; &lt;span class="nc"&gt;StoreMessageUseCase&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nc"&gt;ReceivedMessage&lt;/span&gt; &lt;span class="nf"&gt;store&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;String&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;partition&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;long&lt;/span&gt; &lt;span class="n"&gt;offset&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The output ports say what it needs, without saying how. For example,&lt;br&gt;
for the statistics:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;interface&lt;/span&gt; &lt;span class="nc"&gt;StatisticsRepository&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nc"&gt;Optional&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;SensorStatistics&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;find&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;String&lt;/span&gt; &lt;span class="n"&gt;sensorId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;SensorType&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;SensorStatistics&lt;/span&gt; &lt;span class="n"&gt;statistics&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;SensorStatistics&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;findAll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The use case connects the rule and the ports:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;StoreMessageService&lt;/span&gt; &lt;span class="k"&gt;implements&lt;/span&gt; &lt;span class="nc"&gt;StoreMessageUseCase&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;MessageRepository&lt;/span&gt; &lt;span class="n"&gt;messageRepository&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;StatisticsRepository&lt;/span&gt; &lt;span class="n"&gt;statisticsRepository&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;Clock&lt;/span&gt; &lt;span class="n"&gt;clock&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="c1"&gt;// constructor: the three fields above&lt;/span&gt;

    &lt;span class="nd"&gt;@Override&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;ReceivedMessage&lt;/span&gt; &lt;span class="nf"&gt;store&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;String&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;partition&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;long&lt;/span&gt; &lt;span class="n"&gt;offset&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nc"&gt;ParseResult&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;SensorReading&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;parse&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="nc"&gt;ReceivedMessage&lt;/span&gt; &lt;span class="n"&gt;stored&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;messageRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
                &lt;span class="nc"&gt;ReceivedMessage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;notStoredYet&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;partition&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;offset&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Instant&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;now&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;clock&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="k"&gt;instanceof&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Valid&lt;/span&gt; &lt;span class="n"&gt;valid&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="nf"&gt;updateStatistics&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;valid&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;stored&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;updateStatistics&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;SensorReading&lt;/span&gt; &lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nc"&gt;SensorStatistics&lt;/span&gt; &lt;span class="n"&gt;statistics&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;statisticsRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sensorId&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;current&lt;/span&gt; &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;current&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;orElseGet&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;SensorStatistics&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;first&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;reading&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;statisticsRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;statistics&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;No &lt;code&gt;@Service&lt;/code&gt;, no &lt;code&gt;@Autowired&lt;/code&gt;: it is a Java class. The time comes from&lt;br&gt;
a &lt;code&gt;Clock&lt;/code&gt; given to the constructor, so a test can fix it. Spring creates&lt;br&gt;
it in the config class, with the adapters that implement the ports:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Bean&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;StoreMessageUseCase&lt;/span&gt; &lt;span class="nf"&gt;storeMessageUseCase&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;MessageRepository&lt;/span&gt; &lt;span class="n"&gt;messageRepository&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                                               &lt;span class="nc"&gt;StatisticsRepository&lt;/span&gt; &lt;span class="n"&gt;statisticsRepository&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Clock&lt;/span&gt; &lt;span class="n"&gt;clock&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;StoreMessageService&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;messageRepository&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;statisticsRepository&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;clock&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;All the Spring wiring is in &lt;code&gt;config/&lt;/code&gt;. The rest of the core does not&lt;br&gt;
know that Spring exists.&lt;/p&gt;
&lt;h2&gt;
  
  
  The adapters
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;The Kafka listener&lt;/strong&gt; is an input adapter: it turns a Kafka message&lt;br&gt;
into a call of the input port.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@KafkaListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;topics&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"${iot.kafka.topic}"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="nd"&gt;@Transactional&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;onMessage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;ConsumerRecord&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;String&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;String&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;consumerRecord&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nc"&gt;ReceivedMessage&lt;/span&gt; &lt;span class="n"&gt;stored&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;storeMessage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;store&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
            &lt;span class="n"&gt;consumerRecord&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;value&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;consumerRecord&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;partition&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;consumerRecord&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;offset&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="c1"&gt;// … log of the result&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The transaction is opened here, in the adapter: the message and the&lt;br&gt;
statistics are saved together or not at all, and the use case stays&lt;br&gt;
plain Java. This works because the Spring Kafka container calls the&lt;br&gt;
listener through the Spring bean: in proxy mode (the default mode),&lt;br&gt;
Spring intercepts only the calls that go through the proxy.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The JPA adapters&lt;/strong&gt; are output adapters. The JPA entity&lt;br&gt;
(&lt;code&gt;StatisticsEntity&lt;/code&gt;, with its &lt;code&gt;@Entity&lt;/code&gt;, &lt;code&gt;@Column&lt;/code&gt;… annotations) is a&lt;br&gt;
different class from the domain record. The adapter translates:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Override&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;SensorStatistics&lt;/span&gt; &lt;span class="n"&gt;statistics&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nc"&gt;StatisticsEntity&lt;/span&gt; &lt;span class="n"&gt;entity&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;springDataRepository&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findBySensorIdAndSensorType&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;statistics&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sensorId&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;statistics&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;orElseGet&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;StatisticsEntity&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;statistics&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sensorId&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;statistics&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;entity&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;statistics&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;count&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;statistics&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;statistics&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;statistics&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sum&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;springDataRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;save&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;entity&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the same way, the REST API returns response records&lt;br&gt;
(&lt;code&gt;StatisticsResponse&lt;/code&gt;, &lt;code&gt;MessageResponse&lt;/code&gt;), not the domain objects: the&lt;br&gt;
shape of the JSON can change without touching the domain.&lt;/p&gt;
&lt;h2&gt;
  
  
  The tests this allows
&lt;/h2&gt;
&lt;h3&gt;
  
  
  The domain, with nothing to start
&lt;/h3&gt;

&lt;p&gt;One test line per kind of bad line (excerpt):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@ParameterizedTest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"[{0}] -&amp;gt; {1}"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="nd"&gt;@CsvSource&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;delimiter&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'|'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="s2"&gt;"sensor-1 WIND 12                    | unknown type WIND"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="s2"&gt;"sensor-1 TEMPERATURE 21,5           | invalid value 21,5"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="s2"&gt;"sensor-1 HUMIDITY -1                | HUMIDITY must be between 0 and 100"&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;parse_badLine_returnsRejectionWithReason&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;String&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;String&lt;/span&gt; &lt;span class="n"&gt;reason&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nf"&gt;assertThat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;SensorReading&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;parse&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isEqualTo&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ParseResult&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Rejected&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;reason&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  The use case, with fake ports
&lt;/h3&gt;

&lt;p&gt;The ports are interfaces: a test gives them an in-memory version, and a&lt;br&gt;
fixed clock:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;FakeMessageRepository&lt;/span&gt; &lt;span class="n"&gt;messageRepository&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;FakeMessageRepository&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;FakeStatisticsRepository&lt;/span&gt; &lt;span class="n"&gt;statisticsRepository&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;FakeStatisticsRepository&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;StoreMessageService&lt;/span&gt; &lt;span class="n"&gt;service&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
        &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;StoreMessageService&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;messageRepository&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;statisticsRepository&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Clock&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;fixed&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;NOW&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;ZoneOffset&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;UTC&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nd"&gt;@Test&lt;/span&gt;
&lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;store_rejectedLine_savesReasonAndKeepsStatistics&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;service&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;store&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"sensor-1 TEMPERATURE 20"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0L&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="nc"&gt;ReceivedMessage&lt;/span&gt; &lt;span class="n"&gt;stored&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;service&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;store&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"sensor-1 WIND 12"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1L&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="nf"&gt;assertThat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;stored&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;status&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isEqualTo&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;MessageStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;REJECTED&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nf"&gt;assertThat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;stored&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;rejectionReason&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isEqualTo&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"unknown type WIND"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="nf"&gt;assertThat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;statisticsRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findAll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;containsExactly&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;SensorStatistics&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"sensor-1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;SensorType&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;TEMPERATURE&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;20&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;No Spring, no Kafka, no database, no Mockito. The tests of the domain&lt;br&gt;
and of the use cases:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mvn -pl iot-backend-processing &lt;span class="nb"&gt;test&lt;/span&gt; -Dtest=&lt;span class="s1"&gt;'SensorReadingTest,SensorStatisticsTest,StoreMessageServiceTest,ListLastMessagesServiceTest'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.053 s -- in dev.aymenjamaaoui.iot.processing.application.StoreMessageServiceTest
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.007 s -- in dev.aymenjamaaoui.iot.processing.application.ListLastMessagesServiceTest
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.006 s -- in dev.aymenjamaaoui.iot.processing.domain.SensorStatisticsTest
[INFO] Tests run: 24, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.058 s -- in dev.aymenjamaaoui.iot.processing.domain.SensorReadingTest
[INFO] Tests run: 35, Failures: 0, Errors: 0, Skipped: 0
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;35 tests, each one in a few milliseconds. The adapters have their own&lt;br&gt;
tests: a &lt;code&gt;@WebMvcTest&lt;/code&gt; for the REST API, and an integration test with a&lt;br&gt;
real Kafka and a real PostgreSQL (Testcontainers).&lt;/p&gt;
&lt;h3&gt;
  
  
  The rule, checked by the build
&lt;/h3&gt;

&lt;p&gt;An architecture rule written only in a README ends up forgotten. The&lt;br&gt;
project checks it with &lt;a href="https://www.archunit.org/" rel="noopener noreferrer"&gt;ArchUnit&lt;/a&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@AnalyzeClasses&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;packages&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"dev.aymenjamaaoui.iot.processing"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;importOptions&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;ImportOption&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;DoNotIncludeTests&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;class&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;ArchitectureTest&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="nd"&gt;@ArchTest&lt;/span&gt;
    &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;ArchRule&lt;/span&gt; &lt;span class="no"&gt;DOMAIN_AND_APPLICATION_HAVE_NO_FRAMEWORK&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;noClasses&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;that&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;resideInAnyPackage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"..domain.."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"..application.."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;should&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;dependOnClassesThat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;resideInAnyPackage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
                    &lt;span class="s2"&gt;"org.springframework.."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"org.apache.kafka.."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"jakarta.."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"org.hibernate.."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                    &lt;span class="s2"&gt;"com.fasterxml.jackson.."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"tools.jackson.."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;To see it fail, I add &lt;code&gt;@Component&lt;/code&gt; (Spring) to the record&lt;br&gt;
&lt;code&gt;SensorStatistics&lt;/code&gt; on purpose, then I run &lt;code&gt;mvn -pl&lt;br&gt;
iot-backend-processing test -Dtest=ArchitectureTest&lt;/code&gt; (short output):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Architecture Violation [Priority: MEDIUM] - Rule 'no classes that reside in any package ['..domain..', '..application..'] should depend on classes that reside in any package ['org.springframework..', 'org.apache.kafka..', 'jakarta..', 'org.hibernate..', 'com.fasterxml.jackson..', 'tools.jackson..']' was violated (1 times):
Class &amp;lt;dev.aymenjamaaoui.iot.processing.domain.SensorStatistics&amp;gt; is annotated with &amp;lt;org.springframework.stereotype.Component&amp;gt; in (SensorStatistics.java:0)
[ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The message gives the rule, the class and the cause. The build fails,&lt;br&gt;
so nobody can break the rule without seeing it.&lt;/p&gt;

&lt;h2&gt;
  
  
  The cost, honestly
&lt;/h2&gt;

&lt;p&gt;This way of organizing the code has a price:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;more classes&lt;/strong&gt;: the service has 28 classes in &lt;code&gt;src/main&lt;/code&gt;, with
6 ports (interfaces and one exception) and 2 JPA entities next to the
domain records;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;translation code&lt;/strong&gt;: JPA entity ↔ domain record ↔ REST response;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;more files to open&lt;/strong&gt; to follow a call, from the listener to the
database.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;On such a small example, the structure can look heavy: here it is on&lt;br&gt;
purpose, so that each part is visible. It pays when the service grows:&lt;br&gt;
when the rules grow, when a technology changes (another database,&lt;br&gt;
another way to receive the messages), or when you want to test the rule&lt;br&gt;
fast and often. For a service that only copies data from one system to&lt;br&gt;
another, with no real rule, a simpler structure is enough.&lt;/p&gt;

&lt;h2&gt;
  
  
  Tested with
&lt;/h2&gt;

&lt;p&gt;Java 25 (Temurin 25.0.4), Spring Boot 4.1.2, ArchUnit 1.5.1, JUnit 5,&lt;br&gt;
AssertJ, Maven 3.10.0. Code: tag&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/iot-monitoring-platform/-/tree/phase-1" rel="noopener noreferrer"&gt;&lt;code&gt;phase-1&lt;/code&gt;&lt;/a&gt;,&lt;br&gt;
service &lt;code&gt;iot-backend-processing&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://alistair.cockburn.us/hexagonal-architecture/" rel="noopener noreferrer"&gt;Alistair Cockburn, « Hexagonal architecture »&lt;/a&gt;
(the 2005 article, « Ports and Adapters »)&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://openjdk.org/jeps/409" rel="noopener noreferrer"&gt;JEP 409: Sealed Classes&lt;/a&gt; (Java 17)&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://openjdk.org/jeps/441" rel="noopener noreferrer"&gt;JEP 441: Pattern Matching for switch&lt;/a&gt; (Java 21)&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://www.archunit.org/userguide/html/000_Index.html" rel="noopener noreferrer"&gt;ArchUnit, user guide&lt;/a&gt;
(package dependency checks)&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/annotations.html" rel="noopener noreferrer"&gt;Spring Framework: Using @Transactional&lt;/a&gt;
(proxy mode)&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;The ideas one at a time, with a simpler example:
&lt;a href="https://aymenjamaaoui.dev/en/blog/hexagonal-architecture-ports-adapters/" rel="noopener noreferrer"&gt;Hexagonal architecture: ports and adapters, step by step&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;The previous post of the series:
&lt;a href="https://aymenjamaaoui.dev/en/blog/kafka-spring-boot-locally/" rel="noopener noreferrer"&gt;Kafka and Spring Boot: a complete local project&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;The &lt;a href="https://gitlab.com/aymenjamaaoui/iot-monitoring-platform/-/blob/phase-1/README.md" rel="noopener noreferrer"&gt;README of the tag &lt;code&gt;phase-1&lt;/code&gt;&lt;/a&gt;:
the business rule, the API and all the tests.&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>java</category>
      <category>springboot</category>
      <category>architecture</category>
      <category>cleancode</category>
    </item>
    <item>
      <title>Kafka and Spring Boot: a complete local project</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Sat, 24 Oct 2026 17:00:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/kafka-and-spring-boot-a-complete-local-project-48j4</link>
      <guid>https://dev.to/aymenjamaaoui/kafka-and-spring-boot-a-complete-local-project-48j4</guid>
      <description>&lt;p&gt;One service receives the readings of sensors; another one must process&lt;br&gt;
and store them. If the first one calls the second one over REST, the two&lt;br&gt;
are tied: when the second one is stopped or slow, the first one cannot&lt;br&gt;
deliver anything. Kafka sits between them: the first one publishes a&lt;br&gt;
message, the second one reads it at its own pace.&lt;/p&gt;

&lt;p&gt;This post builds that link from end to end, locally: Kafka in KRaft&lt;br&gt;
mode in Docker, a Spring Boot service that publishes a plain line of&lt;br&gt;
text, another one that reads it, and a page that shows the partition and&lt;br&gt;
the offset of each message. All the code is in the tag&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/iot-monitoring-platform/-/tree/phase-1" rel="noopener noreferrer"&gt;&lt;code&gt;phase-1&lt;/code&gt;&lt;/a&gt;&lt;br&gt;
of the public repository iot-monitoring-platform.&lt;/p&gt;
&lt;h2&gt;
  
  
  The project in one diagram
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/kafka-spring-boot-locally/" rel="noopener noreferrer"&gt;See the diagram in the original post.&lt;/a&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;iot-backend-ingestion&lt;/strong&gt; (port 8081) receives a line of text, for
example &lt;code&gt;sensor-1 TEMPERATURE 21.5&lt;/code&gt;, and publishes it to the topic
&lt;code&gt;iot-sensor-events&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;iot-backend-processing&lt;/strong&gt; (port 8082) reads the topic, stores each
message in PostgreSQL and gives it through a REST API.&lt;/li&gt;
&lt;li&gt;A simulator sends one line per second, and an Angular page shows the
last messages.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The message is a plain &lt;code&gt;String&lt;/code&gt;, with no key, on a topic with only one&lt;br&gt;
partition. This is on purpose: the goal is to see the full path of a&lt;br&gt;
message, with as few settings as possible. This post is only about the&lt;br&gt;
Kafka part; the business rule and the way the code is organized&lt;br&gt;
(hexagonal architecture) are the topic of another post.&lt;/p&gt;

&lt;p&gt;At the end, you have Kafka and PostgreSQL in Docker, the two services on&lt;br&gt;
your machine, and messages whose partition and offset you can follow,&lt;br&gt;
from the send to the database.&lt;/p&gt;
&lt;h2&gt;
  
  
  Kafka in KRaft mode with the official image
&lt;/h2&gt;

&lt;p&gt;Since Kafka 4.0, Kafka runs fully without ZooKeeper: in KRaft mode,&lt;br&gt;
controller nodes of Kafka manage the metadata of the cluster. On a dev&lt;br&gt;
machine, one node can be both broker and controller, so one container is&lt;br&gt;
enough.&lt;/p&gt;

&lt;p&gt;The project uses the official image of the Apache Kafka project,&lt;br&gt;
&lt;code&gt;apache/kafka&lt;/code&gt;. With its default config, it starts one node, which is&lt;br&gt;
both broker and controller, and listens on port 9092. The &lt;code&gt;compose.yaml&lt;/code&gt;&lt;br&gt;
file of the project (excerpt):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;kafka&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="c1"&gt;# Official Apache Kafka image. With its default config it starts one
&lt;/span&gt;    &lt;span class="c1"&gt;# node in KRaft mode (no ZooKeeper) and listens on localhost:9092.
&lt;/span&gt;    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;apache/kafka:4.4.0&lt;/span&gt;
    &lt;span class="na"&gt;container_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;iot-kafka&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"9092:9092"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;No environment variable: no &lt;code&gt;KAFKA_ZOOKEEPER_CONNECT&lt;/code&gt;, no list of&lt;br&gt;
listeners to write. The same file also starts PostgreSQL.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker compose up -d
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The logs of the container show what the default config does&lt;br&gt;
(&lt;code&gt;docker logs iot-kafka&lt;/code&gt;, excerpt):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;    advertised.listeners = [PLAINTEXT://localhost:9092]
    node.id = 1
    process.roles = [broker, controller]
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;process.roles = [broker, controller]&lt;/code&gt;: one node has both roles.&lt;br&gt;
&lt;code&gt;advertised.listeners&lt;/code&gt; is the address that Kafka gives to the clients:&lt;br&gt;
&lt;code&gt;localhost:9092&lt;/code&gt;. The Spring Boot services run on the machine, so this&lt;br&gt;
address works for them as it is.&lt;/p&gt;
&lt;h2&gt;
  
  
  Publish a &lt;code&gt;String&lt;/code&gt;
&lt;/h2&gt;
&lt;h3&gt;
  
  
  The config
&lt;/h3&gt;

&lt;p&gt;The &lt;code&gt;application.yml&lt;/code&gt; file of the ingestion service:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;spring&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;application&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;iot-backend-ingestion&lt;/span&gt;
  &lt;span class="na"&gt;kafka&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="c1"&gt;# Spring Boot uses String serializers by default: the message is a plain String.
&lt;/span&gt;    &lt;span class="na"&gt;bootstrap-servers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;localhost:9092&lt;/span&gt;

&lt;span class="na"&gt;iot&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;kafka&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;topic&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;iot-sensor-events&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;There is no Kafka config class in the project. Spring Boot creates a&lt;br&gt;
&lt;code&gt;KafkaTemplate&lt;/code&gt;, and its default serializers are &lt;code&gt;StringSerializer&lt;/code&gt;, for&lt;br&gt;
the key and for the value. So there is nothing to set to publish text.&lt;br&gt;
&lt;code&gt;bootstrap-servers&lt;/code&gt; is already &lt;code&gt;localhost:9092&lt;/code&gt; by default; I write it&lt;br&gt;
anyway, so you can see where the service connects.&lt;/p&gt;
&lt;h3&gt;
  
  
  The send
&lt;/h3&gt;

&lt;p&gt;The adapter that publishes (excerpt of &lt;code&gt;KafkaSensorMessagePublisher&lt;/code&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Override&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;publish&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;SensorMessage&lt;/span&gt; &lt;span class="n"&gt;message&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// No key: in phase 1 the topic has one partition, so the order is&lt;/span&gt;
    &lt;span class="c1"&gt;// kept anyway. The key comes in phase 2, with several partitions.&lt;/span&gt;
    &lt;span class="n"&gt;kafkaTemplate&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;send&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;topic&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;message&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;whenComplete&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;exception&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="c1"&gt;// The send is asynchronous: an error only shows in the log.&lt;/span&gt;
                &lt;span class="c1"&gt;// Error handling (retry, DLT) comes in phase 2.&lt;/span&gt;
                &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;exception&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
                    &lt;span class="no"&gt;LOGGER&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Could not publish the message '{}' to {}"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;message&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;topic&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;exception&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
                &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
                    &lt;span class="no"&gt;LOGGER&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;info&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Published '{}' to {} (partition {}, offset {})"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;message&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;topic&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                            &lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getRecordMetadata&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;partition&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getRecordMetadata&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;offset&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
                &lt;span class="p"&gt;}&lt;/span&gt;
            &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;send&lt;/code&gt; does not block: it returns a &lt;code&gt;CompletableFuture&amp;lt;SendResult&amp;gt;&lt;/code&gt;. The&lt;br&gt;
result comes later, with the partition and the offset that Kafka gave to&lt;br&gt;
the message. This is why the REST controller answers &lt;code&gt;202 Accepted&lt;/code&gt; and&lt;br&gt;
not &lt;code&gt;200 OK&lt;/code&gt;: the service handed the message to Kafka, but it does not&lt;br&gt;
wait for the confirmation. The limit is clear: if the send fails, the&lt;br&gt;
error only shows in the log. Error handling comes with phase 2.&lt;/p&gt;
&lt;h3&gt;
  
  
  The topic
&lt;/h3&gt;

&lt;p&gt;The topic is declared by a &lt;code&gt;NewTopic&lt;/code&gt; bean (excerpt of&lt;br&gt;
&lt;code&gt;IngestionConfig&lt;/code&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Bean&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nc"&gt;NewTopic&lt;/span&gt; &lt;span class="nf"&gt;sensorEventsTopic&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;IotKafkaProperties&lt;/span&gt; &lt;span class="n"&gt;properties&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;TopicBuilder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;name&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;properties&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;topic&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;partitions&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;replicas&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;build&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;At start, Spring creates the topic if it does not exist; if it already&lt;br&gt;
exists, the bean is ignored. So the service does not depend on the&lt;br&gt;
automatic creation of topics by the broker. One partition and one&lt;br&gt;
replica: enough for a single local broker.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker &lt;span class="nb"&gt;exec&lt;/span&gt; iot-kafka /opt/kafka/bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic iot-sensor-events
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Topic: iot-sensor-events    TopicId: oiLmbWoqSneUtet0x7hxCw PartitionCount: 1   ReplicationFactor: 1    Configs: min.insync.replicas=1,segment.bytes=1073741824
    Topic: iot-sensor-events    Partition: 0    Leader: 1   Replicas: 1 Isr: 1  Elr:    LastKnownElr: 
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Consume
&lt;/h2&gt;

&lt;h3&gt;
  
  
  The listener
&lt;/h3&gt;

&lt;p&gt;On the processing side, the config adds a consumer group:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;spring&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;kafka&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="c1"&gt;# Spring Boot uses String deserializers by default: the message is a plain String.
&lt;/span&gt;    &lt;span class="na"&gt;bootstrap-servers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;localhost:9092&lt;/span&gt;
    &lt;span class="na"&gt;consumer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;group-id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;iot-backend-processing&lt;/span&gt;
      &lt;span class="c1"&gt;# Read the topic from the start when the group has no offset yet,
&lt;/span&gt;      &lt;span class="c1"&gt;# so messages sent before the first start are not lost.
&lt;/span&gt;      &lt;span class="na"&gt;auto-offset-reset&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;earliest&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And the listener (excerpt of &lt;code&gt;SensorMessageListener&lt;/code&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nd"&gt;@KafkaListener&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;topics&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"${iot.kafka.topic}"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="nd"&gt;@Transactional&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;onMessage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;ConsumerRecord&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;String&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;String&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;consumerRecord&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nc"&gt;ReceivedMessage&lt;/span&gt; &lt;span class="n"&gt;stored&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;storeMessage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;store&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
            &lt;span class="n"&gt;consumerRecord&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;value&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;consumerRecord&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;partition&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;consumerRecord&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;offset&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="c1"&gt;// … log of the result&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;ConsumerRecord&lt;/code&gt; gives the value (our text), and also its place in&lt;br&gt;
the topic: the partition and the offset. The service stores them with&lt;br&gt;
the message, so we can see them on the page.&lt;/p&gt;

&lt;p&gt;The group &lt;code&gt;iot-backend-processing&lt;/code&gt; is the name under which Kafka keeps&lt;br&gt;
where the consumer is: for each partition, a « committed » position,&lt;br&gt;
the offset of the next message to read. When it restarts, the service&lt;br&gt;
goes on from this position.&lt;/p&gt;
&lt;h3&gt;
  
  
  The trap of &lt;code&gt;auto-offset-reset&lt;/code&gt;
&lt;/h3&gt;

&lt;p&gt;What does a consumer do when its group has no saved position yet, for&lt;br&gt;
example at the very first start? This is the job of&lt;br&gt;
&lt;code&gt;auto.offset.reset&lt;/code&gt;. Its main values:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Value&lt;/th&gt;
&lt;th&gt;With no saved position, the consumer…&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;latest&lt;/code&gt; (default)&lt;/td&gt;
&lt;td&gt;starts at the end of the topic: it reads only the messages that come after&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;earliest&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;starts at the beginning of the topic: it also reads the messages already there&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;none&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;stops with an error&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The setting matters only in this case. As soon as the group has a&lt;br&gt;
position, the consumer goes on from where it was.&lt;/p&gt;

&lt;p&gt;To see it, two new groups read the same topic, which already holds two&lt;br&gt;
messages. First with the default value:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker &lt;span class="nb"&gt;exec&lt;/span&gt; iot-kafka /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic iot-sensor-events --group demo-latest --timeout-ms 5000
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;[2026-10-24 16:59:56,249] ERROR Error processing message, terminating consumer process:  (org.apache.kafka.tools.consumer.ConsoleConsumer)
org.apache.kafka.common.errors.TimeoutException
Processed a total of 0 messages
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then with &lt;code&gt;earliest&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker &lt;span class="nb"&gt;exec&lt;/span&gt; iot-kafka /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic iot-sensor-events --group demo-from-start --command-property auto.offset.reset=earliest --timeout-ms 5000
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;sensor-1 TEMPERATURE 21.5
sensor-3 HUMIDITY 47.2
[2026-10-24 17:01:09,610] ERROR Error processing message, terminating consumer process:  (org.apache.kafka.tools.consumer.ConsoleConsumer)
org.apache.kafka.common.errors.TimeoutException
Processed a total of 2 messages
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;TimeoutException&lt;/code&gt; is normal: &lt;code&gt;--timeout-ms 5000&lt;/code&gt; stops the tool&lt;br&gt;
after five seconds with no new message. (I removed from these outputs a&lt;br&gt;
line of information about the KIP-848 protocol.)&lt;/p&gt;

&lt;p&gt;With &lt;code&gt;latest&lt;/code&gt;, the first group read nothing: the two messages were there&lt;br&gt;
before it. This is exactly what would happen to the processing service&lt;br&gt;
if it started after the ingestion with the default value. Hence&lt;br&gt;
&lt;code&gt;auto-offset-reset: earliest&lt;/code&gt; in its &lt;code&gt;application.yml&lt;/code&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  Run the project and watch Kafka work
&lt;/h2&gt;

&lt;p&gt;Kafka and PostgreSQL are already running (&lt;code&gt;docker compose up -d&lt;/code&gt;). In&lt;br&gt;
two terminals, from the root of the project:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; iot-backend-processing
mvn spring-boot:run
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; iot-backend-ingestion
mvn spring-boot:run
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then one message:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -i -X POST -H &lt;span class="s2"&gt;"Content-Type: text/plain"&lt;/span&gt; --data &lt;span class="s2"&gt;"sensor-1 TEMPERATURE 21.5"&lt;/span&gt; http://localhost:8081/api/messages
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;HTTP/1.1 202 
Content-Length: 0
Date: Sat, 24 Oct 2026 16:59:19 GMT
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The two services tell the path of the message in their logs (after a&lt;br&gt;
second message; I keep only the end of the lines, without the date and&lt;br&gt;
the thread name):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Published 'sensor-1 TEMPERATURE 21.5' to iot-sensor-events (partition 0, offset 0)
Published 'sensor-3 HUMIDITY 47.2' to iot-sensor-events (partition 0, offset 1)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Stored 'sensor-1 TEMPERATURE 21.5' (partition 0, offset 0)
Stored 'sensor-3 HUMIDITY 47.2' (partition 0, offset 1)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The producer and the consumer see the same position: partition 0,&lt;br&gt;
offsets 0 then 1. In a partition, the offset is simply the rank of the&lt;br&gt;
message, and it only grows.&lt;/p&gt;

&lt;p&gt;The tool &lt;code&gt;kafka-consumer-groups.sh&lt;/code&gt; shows where the group of the&lt;br&gt;
processing service is (short output: without the columns &lt;code&gt;CONSUMER-ID&lt;/code&gt;,&lt;br&gt;
&lt;code&gt;HOST&lt;/code&gt; and &lt;code&gt;CLIENT-ID&lt;/code&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker &lt;span class="nb"&gt;exec&lt;/span&gt; iot-kafka /opt/kafka/bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group iot-backend-processing
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;GROUP                  TOPIC             PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG
iot-backend-processing iot-sensor-events 0          2               2               0
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;CURRENT-OFFSET&lt;/code&gt; is the committed position of the group (the next&lt;br&gt;
message to read), &lt;code&gt;LOG-END-OFFSET&lt;/code&gt; the end of the partition, and &lt;code&gt;LAG&lt;/code&gt;&lt;br&gt;
the gap between the two: 0, the service is up to date.&lt;/p&gt;

&lt;p&gt;To send a steady flow, the project has a simulator (one line per&lt;br&gt;
second):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; iot-event-simulator
mvn compile exec:java
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The Angular page (&lt;code&gt;npm start&lt;/code&gt; in &lt;code&gt;iot-frontend-angular&lt;/code&gt;, then&lt;br&gt;
&lt;a href="http://localhost:4200" rel="noopener noreferrer"&gt;http://localhost:4200&lt;/a&gt;) then shows the messages with their partition and&lt;br&gt;
their offset, which grows with each line.&lt;/p&gt;
&lt;h3&gt;
  
  
  See the topic with Kafdrop
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;kafka-console-consumer.sh&lt;/code&gt; is the basic tool. To see the topic in a&lt;br&gt;
browser, &lt;a href="https://github.com/obsidiandynamics/kafdrop" rel="noopener noreferrer"&gt;Kafdrop&lt;/a&gt; is a web&lt;br&gt;
UI for Kafka (Apache 2.0 license, Java 17 or newer). It is not part of&lt;br&gt;
the project: I run it next to it, with its official jar (release&lt;br&gt;
4.3.0), without changing the project:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;java --add-opens=java.base/sun.nio.ch=ALL-UNNAMED \
  -jar kafdrop-4.3.0.jar --kafka.brokerConnect=localhost:9092
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then &lt;a href="http://localhost:9000" rel="noopener noreferrer"&gt;http://localhost:9000&lt;/a&gt;, the topic &lt;code&gt;iot-sensor-events&lt;/code&gt;, and its&lt;br&gt;
messages:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F21iw3rsbxwzjjpy63muc.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F21iw3rsbxwzjjpy63muc.webp" alt="Kafdrop shows the messages of the topic iot-sensor-events: partition 0, offsets 0 to 6, an empty key, and the text of each message, for example sensor-1 TEMPERATURE 21.5" width="800" height="698"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;We find everything from above: one partition, offsets that follow each&lt;br&gt;
other, and &lt;code&gt;Key: empty&lt;/code&gt; on each message, because the service publishes&lt;br&gt;
with no key.&lt;/p&gt;

&lt;p&gt;Kafdrop runs on the machine and not in a container, for a reason seen&lt;br&gt;
above: Kafka advertises &lt;code&gt;localhost:9092&lt;/code&gt;. From another container, this&lt;br&gt;
address means the container itself, and the connection fails. It would&lt;br&gt;
need a second listener in &lt;code&gt;compose.yaml&lt;/code&gt;; that is for phase 2.&lt;/p&gt;

&lt;h2&gt;
  
  
  What is missing, on purpose
&lt;/h2&gt;

&lt;p&gt;This project is minimal on purpose. It lacks what a real system would&lt;br&gt;
have:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;a message key&lt;/strong&gt;: with no key and one partition, the order is kept;
with several partitions, a key (the sensor) will be needed to keep the
order of the messages of one sensor;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;several partitions and several consumers&lt;/strong&gt;, to process in parallel;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;error handling&lt;/strong&gt;: today, a failed send leaves only a log line, and a
message that cannot be stored is retried with the default settings of
Spring Kafka, then lost;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;a typed event&lt;/strong&gt; with a contract, instead of a line of text.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This is the plan of phase 2 of the project, with its own posts.&lt;/p&gt;

&lt;h2&gt;
  
  
  Tested with
&lt;/h2&gt;

&lt;p&gt;Java 25 (Temurin 25.0.4), Spring Boot 4.1.2, Apache Kafka 4.4.0 (image&lt;br&gt;
&lt;code&gt;apache/kafka:4.4.0&lt;/code&gt;), PostgreSQL 18.6, Maven 3.10.0, Docker Desktop on&lt;br&gt;
macOS, Kafdrop 4.3.0. Code: tag&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/iot-monitoring-platform/-/tree/phase-1" rel="noopener noreferrer"&gt;&lt;code&gt;phase-1&lt;/code&gt;&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://kafka.apache.org/blog/2025/03/18/apache-kafka-4.0.0-release-announcement/" rel="noopener noreferrer"&gt;Apache Kafka 4.0.0 Release Announcement&lt;/a&gt;
(Kafka without ZooKeeper, KRaft by default)&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://kafka.apache.org/documentation/#docker" rel="noopener noreferrer"&gt;Kafka: Getting Started, Docker&lt;/a&gt;
(the &lt;code&gt;apache/kafka&lt;/code&gt; image and its default config)&lt;/li&gt;
&lt;li&gt;&lt;a href="https://kafka.apache.org/documentation/#consumerconfigs_auto.offset.reset" rel="noopener noreferrer"&gt;Kafka: consumer configs, &lt;code&gt;auto.offset.reset&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://docs.spring.io/spring-boot/reference/messaging/kafka.html" rel="noopener noreferrer"&gt;Spring Boot: Kafka&lt;/a&gt;
(the auto-configured &lt;code&gt;KafkaTemplate&lt;/code&gt;, the &lt;code&gt;NewTopic&lt;/code&gt; beans)&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://docs.spring.io/spring-kafka/reference/kafka/sending-messages.html" rel="noopener noreferrer"&gt;Spring for Apache Kafka: Sending Messages&lt;/a&gt;
(&lt;code&gt;send&lt;/code&gt; returns a &lt;code&gt;CompletableFuture&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;a href="https://docs.spring.io/spring-kafka/reference/kafka/configuring-topics.html" rel="noopener noreferrer"&gt;Spring for Apache Kafka: Configuring Topics&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/obsidiandynamics/kafdrop" rel="noopener noreferrer"&gt;Kafdrop&lt;/a&gt; (README, license)&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;The &lt;a href="https://gitlab.com/aymenjamaaoui/iot-monitoring-platform/-/blob/phase-1/README.md" rel="noopener noreferrer"&gt;README of the tag &lt;code&gt;phase-1&lt;/code&gt;&lt;/a&gt;:
the whole project, the Angular page and its dev proxy.&lt;/li&gt;
&lt;li&gt;The next post of the series:
&lt;a href="https://aymenjamaaoui.dev/en/blog/hexagonal-architecture-spring-boot/" rel="noopener noreferrer"&gt;Hexagonal architecture with Spring Boot: a simple example&lt;/a&gt;,
how the code of the processing service is organized.&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>java</category>
      <category>springboot</category>
      <category>kafka</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>AWS locally with Floci: an emulator, not a mock</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Sat, 24 Oct 2026 03:30:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/aws-locally-with-floci-an-emulator-not-a-mock-13dh</link>
      <guid>https://dev.to/aymenjamaaoui/aws-locally-with-floci-an-emulator-not-a-mock-13dh</guid>
      <description>&lt;p&gt;My Java code stores files in S3 and data in DynamoDB. How do I develop&lt;br&gt;
and try it on my machine, without an AWS account, without a bill, and&lt;br&gt;
without changing the code that talks to AWS?&lt;/p&gt;

&lt;p&gt;This post introduces &lt;a href="https://github.com/floci-io/floci" rel="noopener noreferrer"&gt;Floci&lt;/a&gt;, a&lt;br&gt;
local AWS emulator, with an end-to-end example: the AWS CLI creates the&lt;br&gt;
resources, a small Java application uses them, and the Floci web&lt;br&gt;
console shows them. I contribute to the Floci project.&lt;/p&gt;
&lt;h2&gt;
  
  
  Why a local emulator
&lt;/h2&gt;

&lt;p&gt;To try code that talks to AWS, you can use a real account: you need&lt;br&gt;
credentials, each call can cost money, and a configuration mistake can&lt;br&gt;
touch more than a test environment. A local emulator answers the same&lt;br&gt;
calls, on the machine, with no account and no bill.&lt;/p&gt;

&lt;p&gt;LocalStack is the best-known tool in this field. Since March 2026,&lt;br&gt;
according to its own blog, it ships as a single image that needs an&lt;br&gt;
auth token, with a free account-based plan for individuals and open&lt;br&gt;
source projects. Floci works with no account and no token.&lt;/p&gt;
&lt;h2&gt;
  
  
  Floci in brief
&lt;/h2&gt;

&lt;p&gt;According to its README, Floci is "a free, open-source local AWS&lt;br&gt;
emulator for development, testing, and CI", under the MIT license. It&lt;br&gt;
is part of a family of emulators: &lt;code&gt;floci&lt;/code&gt; for AWS (port 4566), and&lt;br&gt;
others for Azure, GCP and OCI.&lt;/p&gt;

&lt;p&gt;All AWS services answer on &lt;code&gt;http://localhost:4566&lt;/code&gt;. Any published&lt;br&gt;
region works, and the credentials can be any non-empty values.&lt;/p&gt;
&lt;h2&gt;
  
  
  An emulator, not a mock
&lt;/h2&gt;

&lt;p&gt;In a test, a &lt;strong&gt;mock&lt;/strong&gt; replaces the AWS client with a fake object. It&lt;br&gt;
answers what you told it to answer. The code makes no network call, and&lt;br&gt;
the test mostly checks what you believe about AWS.&lt;/p&gt;

&lt;p&gt;Floci is something else: it is &lt;strong&gt;a server&lt;/strong&gt; that speaks the AWS&lt;br&gt;
protocol. The code keeps &lt;strong&gt;the real AWS client&lt;/strong&gt; (the one of the AWS&lt;br&gt;
CLI, the Java SDK, Terraform…), which sends real HTTP requests, signed&lt;br&gt;
like for AWS. Only the address changes: &lt;code&gt;localhost&lt;/code&gt; instead of AWS.&lt;/p&gt;

&lt;p&gt;The README describes its architecture:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;an HTTP router receives the requests in the AWS format;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;stateless&lt;/strong&gt; services (SQS, SNS, IAM, STS, KMS, Secrets Manager…);&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;stateful&lt;/strong&gt; services: S3, DynamoDB and DynamoDB Streams;&lt;/li&gt;
&lt;li&gt;services that start &lt;strong&gt;real Docker containers&lt;/strong&gt;: Lambda, RDS,
ElastiCache, MSK, ECS, EC2, EKS…;&lt;/li&gt;
&lt;li&gt;the storage of your choice: in memory, persistent, hybrid, or with a
write-ahead log.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Floci measures its compatibility with test suites per SDK and per&lt;br&gt;
tool, published in its repository: for example 1,326 tests for the AWS&lt;br&gt;
SDK for Java v2, 205 for the AWS CLI v2, 67 for Terraform.&lt;/p&gt;
&lt;h2&gt;
  
  
  Start Floci
&lt;/h2&gt;

&lt;p&gt;The simplest way is its CLI,&lt;br&gt;
&lt;a href="https://github.com/floci-io/floci-cli" rel="noopener noreferrer"&gt;floci-cli&lt;/a&gt; (Docker must be&lt;br&gt;
running):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;floci start
floci status
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Floci then runs in a container and answers on port 4566.&lt;/p&gt;

&lt;h2&gt;
  
  
  With the AWS CLI
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;floci env&lt;/code&gt; prints the variables that send the AWS CLI to Floci:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;export AWS_ENDPOINT_URL='http://localhost.floci.io:4566'
export AWS_ACCESS_KEY_ID='test'
export AWS_SECRET_ACCESS_KEY='test'
export AWS_DEFAULT_REGION='us-east-1'
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;localhost.floci.io&lt;/code&gt; is a name that points to &lt;code&gt;127.0.0.1&lt;/code&gt;, like its&lt;br&gt;
subdomains: &lt;code&gt;documents.localhost.floci.io&lt;/code&gt; too. This is useful for S3,&lt;br&gt;
which can put the bucket name in the host name.&lt;/p&gt;

&lt;p&gt;I create the resources of the example: a bucket for the texts, a table&lt;br&gt;
for the info.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;eval&lt;/span&gt; &lt;span class="s2"&gt;"$(floci env)"&lt;/span&gt;
aws s3 mb s3://documents
aws dynamodb create-table \
  --table-name document-info \
  --attribute-definitions &lt;span class="nv"&gt;AttributeName&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;id,AttributeType=S \
  --key-schema &lt;span class="nv"&gt;AttributeName&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;To see that the CLI does nothing special, the &lt;code&gt;--debug&lt;/code&gt; option shows&lt;br&gt;
the request:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;aws s3 ls --debug
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Endpoint provider result: http://localhost.floci.io:4566
Sending http request: &amp;lt;AWSPreparedRequest ... method=GET, url=http://localhost.floci.io:4566/,
  headers={... 'Authorization': b'AWS4-HMAC-SHA256 Credential=test/..., SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=...' ...}&amp;gt;
Response headers: {'Content-Type': 'application/xml', ..., 'x-amz-request-id': '9f476e72-...'}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;(I shortened the lines.) The request is signed with SigV4&lt;br&gt;
(&lt;code&gt;AWS4-HMAC-SHA256&lt;/code&gt;), exactly like for AWS, and Floci answers in XML,&lt;br&gt;
like S3. So that you do not export these variables in each terminal, a&lt;br&gt;
named AWS profile does the same; I explain it in&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-dev-machine-mise/" rel="noopener noreferrer"&gt;the post about my dev machine&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  With the Java SDK
&lt;/h2&gt;

&lt;p&gt;The example is a small application, published on GitLab:&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/floci-aws-local-demo" rel="noopener noreferrer"&gt;floci-aws-local-demo&lt;/a&gt;.&lt;br&gt;
It stores « documents »: the text in S3, the info (title, author) in&lt;br&gt;
DynamoDB, and the consultation returns both together. It uses the AWS&lt;br&gt;
SDK for Java v2; Quarkus is only the web layer.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Endpoint&lt;/th&gt;
&lt;th&gt;What it does&lt;/th&gt;
&lt;th&gt;AWS service&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;POST /documents&lt;/code&gt; (text)&lt;/td&gt;
&lt;td&gt;stores the text, returns an &lt;code&gt;id&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;S3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;POST /documents/{id}/info&lt;/code&gt; (JSON)&lt;/td&gt;
&lt;td&gt;stores the title and the author&lt;/td&gt;
&lt;td&gt;DynamoDB&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GET /documents/{id}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;returns the info and the text&lt;/td&gt;
&lt;td&gt;DynamoDB + S3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GET /documents&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;lists the documents&lt;/td&gt;
&lt;td&gt;DynamoDB&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;It is an educational example: each class builds its client with visible&lt;br&gt;
constants. The S3 client (a simplified part of&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/floci-aws-local-demo/-/blob/main/src/main/java/dev/aymenjamaaoui/flocidemo/DocumentTextResource.java" rel="noopener noreferrer"&gt;DocumentTextResource.java&lt;/a&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="no"&gt;URI&lt;/span&gt; &lt;span class="no"&gt;ENDPOINT&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="no"&gt;URI&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"http://localhost:4566"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;Region&lt;/span&gt; &lt;span class="no"&gt;REGION&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Region&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;US_EAST_1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// Floci accepts any non-empty credentials.&lt;/span&gt;
&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="nc"&gt;AwsBasicCredentials&lt;/span&gt; &lt;span class="no"&gt;CREDENTIALS&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;AwsBasicCredentials&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"test"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"test"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;S3Client&lt;/span&gt; &lt;span class="n"&gt;s3&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;S3Client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;endpointOverride&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;ENDPOINT&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;region&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;REGION&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;credentialsProvider&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;StaticCredentialsProvider&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;CREDENTIALS&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;build&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;

    &lt;span class="nc"&gt;PutObjectRequest&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;PutObjectRequest&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;bucket&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"documents"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;key&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="s2"&gt;".txt"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;contentType&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;MediaType&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;TEXT_PLAIN&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;build&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;s3&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;putObject&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;RequestBody&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fromString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is the S3 client you would use with AWS. The only difference is&lt;br&gt;
&lt;code&gt;endpointOverride&lt;/code&gt;: with real AWS, you remove this line and use real&lt;br&gt;
credentials. The DynamoDB client is built the same way, in&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/floci-aws-local-demo/-/blob/main/src/main/java/dev/aymenjamaaoui/flocidemo/DocumentInfoResource.java" rel="noopener noreferrer"&gt;DocumentInfoResource.java&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;The application runs on the machine, with the Java and Maven versions&lt;br&gt;
given by its &lt;code&gt;mise.toml&lt;/code&gt; file:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mise install
mvn quarkus:dev
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then you store a document and its info, and read it back:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -X POST localhost:8080/documents -H &lt;span class="s1"&gt;'Content-Type: text/plain'&lt;/span&gt; \
  --data &lt;span class="s1"&gt;'Floci speaks the AWS protocol on port 4566.'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;{"id":"3fa7b64a-10e9-4e1e-b9d3-258a043f8122"}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -X POST localhost:8080/documents/3fa7b64a-10e9-4e1e-b9d3-258a043f8122/info \
  -H &lt;span class="s1"&gt;'Content-Type: application/json'&lt;/span&gt; -d &lt;span class="s1"&gt;'{"title":"Hello Floci","author":"Foulen Foulani"}'&lt;/span&gt;
curl localhost:8080/documents/3fa7b64a-10e9-4e1e-b9d3-258a043f8122
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;{"id":"3fa7b64a-…","title":"Hello Floci","author":"Foulen Foulani","createdAt":"2026-10-24T03:12:58.387781Z","text":"Floci speaks the AWS protocol on port 4566."}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The title comes from DynamoDB, the text from S3. An unknown id answers&lt;br&gt;
&lt;code&gt;404&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Here, the Floci address is a constant in the code. In a real project,&lt;br&gt;
you can keep it out of the code: according to the AWS guide, the SDK&lt;br&gt;
for Java 2.x reads &lt;code&gt;AWS_ENDPOINT_URL&lt;/code&gt;, or &lt;code&gt;endpoint_url&lt;/code&gt; in an AWS&lt;br&gt;
profile (the SDK 1.x does not).&lt;/p&gt;

&lt;h2&gt;
  
  
  The web console
&lt;/h2&gt;

&lt;p&gt;Floci has a web console: &lt;code&gt;http://localhost:4566/_floci/ui&lt;/code&gt;. It does not&lt;br&gt;
run at startup. On the first visit, Floci starts a container next to&lt;br&gt;
it, with the console, then redirects the browser there (here, to&lt;br&gt;
port 4500). This is why Floci needs the Docker socket (&lt;code&gt;floci start&lt;/code&gt;&lt;br&gt;
takes care of it). The console does more than show: you can also&lt;br&gt;
create a bucket, upload a file, add an item to a table or run a PartiQL&lt;br&gt;
query.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fb1yf559qwj12pya9h2gd.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fb1yf559qwj12pya9h2gd.webp" alt="The home page of the Floci web console: the available AWS services and the number of resources of each one." width="800" height="583"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The &lt;code&gt;documents&lt;/code&gt; bucket holds the text stored by the application:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fjwcsudk38gst8ykruv3z.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fjwcsudk38gst8ykruv3z.webp" alt="In the Floci console, the documents bucket: its details on the right, and at the bottom its file 3fa7b64a-….txt of 43 bytes." width="800" height="583"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;And the &lt;code&gt;document-info&lt;/code&gt; table holds its info. A PartiQL query shows it&lt;br&gt;
as JSON:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fd6y69lw22mpqflblo66z.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fd6y69lw22mpqflblo66z.webp" alt="In the Floci console, the document-info table with the item of Foulen Foulani, and the result of the PartiQL query SELECT * FROM document-info: createdAt, author, id and title." width="800" height="583"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What to know
&lt;/h2&gt;

&lt;p&gt;An emulator is not AWS. Floci reproduces the protocol and the behavior&lt;br&gt;
of the services, and its test suites measure this compatibility; but&lt;br&gt;
for a given service, check its place in the list of services and in&lt;br&gt;
these tests. The services that start real containers (Lambda, RDS…)&lt;br&gt;
need Docker.&lt;/p&gt;

&lt;p&gt;To go further, Floci also has Testcontainers modules (Java, Node.js,&lt;br&gt;
Python, .NET) that start an isolated Floci for each test. Testing your&lt;br&gt;
code with Floci will be the topic of a next post.&lt;/p&gt;

&lt;p&gt;Tested on macOS with Floci 2.3.0 (CLI 0.4.0), the AWS CLI 2.38.5,&lt;br&gt;
Java 21 (Temurin 21.0.13), Quarkus 3.40.1.1 and the AWS SDK for Java&lt;br&gt;
2.46.7.&lt;/p&gt;

&lt;p&gt;Sources: the &lt;a href="https://github.com/floci-io/floci" rel="noopener noreferrer"&gt;Floci README&lt;/a&gt;&lt;br&gt;
(introduction, architecture, web console, compatibility tests,&lt;br&gt;
Testcontainers), &lt;a href="https://github.com/floci-io/floci-cli" rel="noopener noreferrer"&gt;floci-cli&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://blog.localstack.cloud/the-road-ahead-for-localstack/" rel="noopener noreferrer"&gt;LocalStack's post&lt;/a&gt;&lt;br&gt;
about the delivery of its emulators, and the AWS guide on&lt;br&gt;
&lt;a href="https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html" rel="noopener noreferrer"&gt;endpoints&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-dev-machine-mise/" rel="noopener noreferrer"&gt;Java dev machine: 8 and 25 side by side with mise&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-docker-kubernetes-oomkilled/" rel="noopener noreferrer"&gt;Java in Docker and Kubernetes: avoid OOMKilled&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>aws</category>
      <category>java</category>
      <category>testing</category>
      <category>docker</category>
    </item>
    <item>
      <title>Java dev machine: 8 and 25 side by side with mise</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Sat, 24 Oct 2026 01:30:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/java-dev-machine-8-and-25-side-by-side-with-mise-4bn7</link>
      <guid>https://dev.to/aymenjamaaoui/java-dev-machine-8-and-25-side-by-side-with-mise-4bn7</guid>
      <description>&lt;p&gt;A Java developer often works on several stacks at the same time: a&lt;br&gt;
legacy project in Java 8, a new project in 25. Maven&lt;br&gt;
here, Gradle there. Node for docs, Python for MkDocs. And around them,&lt;br&gt;
tools: &lt;code&gt;aws&lt;/code&gt;, &lt;code&gt;gh&lt;/code&gt;, &lt;code&gt;kubectl&lt;/code&gt;, helm.&lt;/p&gt;

&lt;p&gt;Each SDK and each tool comes with its own installer. Little by little,&lt;br&gt;
the machine fills up: global versions that mix, &lt;code&gt;sudo&lt;/code&gt;, a &lt;code&gt;.zshrc&lt;/code&gt;&lt;br&gt;
filled by installers, an AWS variable left global. My question: how to&lt;br&gt;
have the right version of each SDK and each tool in each project,&lt;br&gt;
without installing anything as root, with one tool, and a terminal that&lt;br&gt;
stays fast?&lt;/p&gt;

&lt;p&gt;Here is my dev machine on macOS, built on a clean OS that I want to&lt;br&gt;
keep clean.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fbw2089lznrkxekpz9w61.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fbw2089lznrkxekpz9w61.webp" alt="In the floci folder, java -version gives Java 25; after cd ../quickfixj, it gives Java 8. The mise ls command shows that Java and Maven come from the mise.local.toml file of the project, and Node from the machine configuration." width="800" height="478"&gt;&lt;/a&gt;&lt;/p&gt;
&lt;h2&gt;
  
  
  My criteria for a dev machine
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Nothing as root.&lt;/strong&gt; No &lt;code&gt;sudo&lt;/code&gt; to install or update a dev tool.
Everything lives in my user folder.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;One tool for SDKs and tools.&lt;/strong&gt; One place, one command, one file to
read.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The right version on &lt;code&gt;cd&lt;/code&gt;.&lt;/strong&gt; I enter a project and I get its Java
and Maven versions, without thinking about it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Isolation.&lt;/strong&gt; Each project has its versions. A special environment
(for example a local AWS emulator) stays in one tab.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A terminal that stays fast&lt;/strong&gt;, even with completions for all the
tools.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The rest of the post answers these criteria, in this order.&lt;/p&gt;
&lt;h2&gt;
  
  
  mise in a few words
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://mise.jdx.dev" rel="noopener noreferrer"&gt;mise&lt;/a&gt; describes itself as "dev tools, env vars,&lt;br&gt;
and tasks in one CLI": it installs the tools of a project, sets its&lt;br&gt;
environment variables and runs its tasks. Here, I use it mostly for&lt;br&gt;
the tools. It is one binary, under the MIT license, and it also works&lt;br&gt;
on Linux and Windows.&lt;/p&gt;

&lt;p&gt;The install is one command, with no &lt;code&gt;sudo&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -fsSL https://mise.run &lt;span class="o"&gt;|&lt;/span&gt; sh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The script checks the SHA-256 sum of the binary and puts it in&lt;br&gt;
&lt;code&gt;~/.local/bin/mise&lt;/code&gt;. It does not change &lt;code&gt;~/.zshrc&lt;/code&gt;: it prints the line&lt;br&gt;
to add. I add it myself:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;eval&lt;/span&gt; &lt;span class="s2"&gt;"$("&lt;/span&gt;&lt;span class="nv"&gt;$HOME&lt;/span&gt;/.local/bin/mise&lt;span class="s2"&gt;" activate zsh)"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In a new tab, &lt;code&gt;mise doctor&lt;/code&gt; confirms it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;activated: yes
...
No problems found
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;mise keeps everything in my folder: the tools in&lt;br&gt;
&lt;code&gt;~/.local/share/mise/installs/&amp;lt;tool&amp;gt;/&amp;lt;version&amp;gt;&lt;/code&gt;, the configuration in&lt;br&gt;
&lt;code&gt;~/.config/mise/config.toml&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;One detail for IntelliJ: an app started from the Dock reads the&lt;br&gt;
environment of the login shell, not the one of &lt;code&gt;.zshrc&lt;/code&gt;. The mise docs&lt;br&gt;
recommend adding the "shims" to &lt;code&gt;~/.zprofile&lt;/code&gt;, so that these apps find&lt;br&gt;
the tools too:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;eval&lt;/span&gt; &lt;span class="s2"&gt;"$("&lt;/span&gt;&lt;span class="nv"&gt;$HOME&lt;/span&gt;/.local/bin/mise&lt;span class="s2"&gt;" activate zsh --shims)"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  All SDKs and tools in two commands
&lt;/h2&gt;

&lt;p&gt;First the languages, with their LTS version when there is one:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mise use -g java@temurin-25 node@lts maven@3.10 gradle@9 python@3.15
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then the command-line tools:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mise use -g uv starship gh aws-cli helm github:floci-io/floci-cli
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;-g&lt;/code&gt; means "global": these are the default versions of the machine.&lt;br&gt;
Most of them come from the mise registry (more than 1,000 tools). A&lt;br&gt;
tool that is not in the registry installs from its GitHub releases,&lt;br&gt;
like &lt;code&gt;github:floci-io/floci-cli&lt;/code&gt; here.&lt;/p&gt;

&lt;p&gt;The result is a readable file that describes the machine:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight toml"&gt;&lt;code&gt;&lt;span class="c1"&gt;# ~/.config/mise/config.toml
&lt;/span&gt;&lt;span class="k"&gt;[tools]&lt;/span&gt;
&lt;span class="na"&gt;java&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"temurin-25"&lt;/span&gt;
&lt;span class="na"&gt;node&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"lts"&lt;/span&gt;
&lt;span class="na"&gt;maven&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"3.10"&lt;/span&gt;
&lt;span class="na"&gt;gradle&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"9"&lt;/span&gt;
&lt;span class="na"&gt;python&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"3.15"&lt;/span&gt;
&lt;span class="na"&gt;uv&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"latest"&lt;/span&gt;
&lt;span class="na"&gt;starship&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"latest"&lt;/span&gt;
&lt;span class="na"&gt;gh&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"latest"&lt;/span&gt;
&lt;span class="na"&gt;aws-cli&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;version&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"latest"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;symlink_bins&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"true"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="na"&gt;helm&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"latest"&lt;/span&gt;
&lt;span class="s2"&gt;"github:floci-io/floci-cli"&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"latest"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A version is easy to read: &lt;code&gt;temurin-25&lt;/code&gt; takes the latest Temurin 25,&lt;br&gt;
&lt;code&gt;lts&lt;/code&gt; the latest Node LTS, &lt;code&gt;3.10&lt;/code&gt; the latest patch of Maven 3.10. On a&lt;br&gt;
new machine, you copy this file, then run &lt;code&gt;mise install&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;uv, on top of Python?&lt;/strong&gt; mise installs Python itself. uv is for what&lt;br&gt;
you do with Python: &lt;code&gt;uvx mkdocs serve&lt;/code&gt; runs MkDocs without a global&lt;br&gt;
install, and &lt;code&gt;uv sync&lt;/code&gt; manages the dependencies of a project.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;
  
  
  One version per project
&lt;/h2&gt;

&lt;p&gt;Each project can have its own file. For quickfixj, a project still on&lt;br&gt;
Java 8:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight toml"&gt;&lt;code&gt;&lt;span class="c1"&gt;# ~/devs/GitHub/quickfixj/mise.local.toml
&lt;/span&gt;&lt;span class="k"&gt;[tools]&lt;/span&gt;
&lt;span class="na"&gt;java&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"corretto-8"&lt;/span&gt;
&lt;span class="na"&gt;maven&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"3.10"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;mise.local.toml&lt;/code&gt; is a personal file: the mise docs describe it as&lt;br&gt;
"personal overrides, not committed". I add it to the &lt;code&gt;.git/info/exclude&lt;/code&gt;&lt;br&gt;
file of the project, so that Git does not see it. For a version shared&lt;br&gt;
with the team, you put a &lt;code&gt;mise.toml&lt;/code&gt; in the repository instead. The&lt;br&gt;
file closest to the current folder wins, and what it does not set&lt;br&gt;
comes from the global configuration.&lt;/p&gt;

&lt;p&gt;This is what the first screenshot shows. In floci, &lt;code&gt;java -version&lt;/code&gt;&lt;br&gt;
gives Java 25; in quickfixj, Java 8. And &lt;code&gt;mise ls --current&lt;/code&gt; tells&lt;br&gt;
where each version comes from: Java and Maven from the&lt;br&gt;
&lt;code&gt;mise.local.toml&lt;/code&gt; of the project, Node from&lt;br&gt;
&lt;code&gt;~/.config/mise/config.toml&lt;/code&gt;. mise also updates &lt;code&gt;JAVA_HOME&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;A project already has a version file, like a &lt;code&gt;.nvmrc&lt;/code&gt;? mise can read&lt;br&gt;
it, once the option is on:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mise settings add idiomatic_version_file_enable_tools node
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In a folder whose &lt;code&gt;.nvmrc&lt;/code&gt; says &lt;code&gt;20&lt;/code&gt;, I get Node 20; anywhere else,&lt;br&gt;
Node 24 (the LTS). Nothing to change in the project.&lt;/p&gt;
&lt;h2&gt;
  
  
  A comfortable terminal
&lt;/h2&gt;
&lt;h3&gt;
  
  
  The prompt: Starship
&lt;/h3&gt;

&lt;p&gt;&lt;a href="https://starship.rs" rel="noopener noreferrer"&gt;Starship&lt;/a&gt; shows what matters in the current&lt;br&gt;
folder: the Git branch, the project version, Java, Maven, the AWS&lt;br&gt;
profile. mise already installed it; you only turn it on at the end of&lt;br&gt;
&lt;code&gt;~/.zshrc&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;eval&lt;/span&gt; &lt;span class="s2"&gt;"$(starship init zsh)"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Its docs ask for a Nerd Font, a font with icons. I took JetBrains Mono&lt;br&gt;
Nerd Font, from the&lt;br&gt;
&lt;a href="https://github.com/ryanoasis/nerd-fonts/releases" rel="noopener noreferrer"&gt;official Nerd Fonts releases&lt;/a&gt;&lt;br&gt;
(the SHA-256 sum of each archive is published there). To stay without&lt;br&gt;
root, the font goes to &lt;code&gt;~/Library/Fonts&lt;/code&gt;: it is installed for my user&lt;br&gt;
only. Then I choose it in the terminal settings.&lt;/p&gt;
&lt;h3&gt;
  
  
  Completions without slowing the shell
&lt;/h3&gt;

&lt;p&gt;The &lt;code&gt;Tab&lt;/code&gt; key completes the commands of &lt;code&gt;docker&lt;/code&gt;, &lt;code&gt;kubectl&lt;/code&gt;, &lt;code&gt;gh&lt;/code&gt;…&lt;br&gt;
Many guides load each completion at startup:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;source&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="o"&gt;(&lt;/span&gt;kubectl completion zsh&lt;span class="o"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The program then runs in each new tab. Docker and kubectl document&lt;br&gt;
another way: write the completion once to a file, in a folder that zsh&lt;br&gt;
knows (the &lt;code&gt;fpath&lt;/code&gt;). zsh loads it only on the first &lt;code&gt;Tab&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p ~/.zsh/completions
kubectl completion zsh &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; ~/.zsh/completions/_kubectl
docker completion zsh &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; ~/.zsh/completions/_docker
gh completion -s zsh &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; ~/.zsh/completions/_gh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And in &lt;code&gt;~/.zshrc&lt;/code&gt;, before &lt;code&gt;compinit&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nv"&gt;fpath&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"$HOME/.zsh/completions"&lt;/span&gt; &lt;span class="nv"&gt;$fpath&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt;
autoload -Uz compinit
compinit
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;I measured how long a shell takes to open with the same 10 completions&lt;br&gt;
(docker, kubectl, mise, gh, glab, helm, uv, uvx, Starship, hvm),&lt;br&gt;
10 runs for each case:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Method&lt;/th&gt;
&lt;th&gt;Shell startup&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;No completion&lt;/td&gt;
&lt;td&gt;93 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Files in the &lt;code&gt;fpath&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;92 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;source &amp;lt;(… completion zsh)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;348 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The files cost nothing at startup. Their only limit: they describe the&lt;br&gt;
tool at the time you created them. After an update (&lt;code&gt;mise upgrade&lt;/code&gt;), I&lt;br&gt;
create them again with a small script, &lt;code&gt;~/.zsh/update-completions.zsh&lt;/code&gt;,&lt;br&gt;
with one line per tool.&lt;/p&gt;

&lt;p&gt;Two special cases. The &lt;code&gt;aws&lt;/code&gt; completion is not a file but a program;&lt;br&gt;
the AWS docs give these two lines for zsh:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;autoload -Uz bashcompinit &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; bashcompinit
complete -C aws_completer aws
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And an alias keeps the completion of its command: &lt;code&gt;alias k=kubectl&lt;/code&gt;,&lt;br&gt;
then &lt;code&gt;compdef k=kubectl&lt;/code&gt;.&lt;/p&gt;
&lt;h3&gt;
  
  
  History and a few aliases
&lt;/h3&gt;

&lt;p&gt;macOS keeps 1,000 lines of history (&lt;code&gt;SAVEHIST&lt;/code&gt; in &lt;code&gt;/etc/zshrc&lt;/code&gt;). I keep&lt;br&gt;
more, with no duplicates, shared between tabs:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nv"&gt;HISTSIZE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;50000
&lt;span class="nv"&gt;SAVEHIST&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;50000
setopt HIST_IGNORE_ALL_DUPS SHARE_HISTORY HIST_IGNORE_SPACE
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With &lt;code&gt;HIST_IGNORE_SPACE&lt;/code&gt;, a command that starts with a space is not&lt;br&gt;
saved: useful for a command that contains a secret. And a few aliases:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;alias&lt;/span&gt; &lt;span class="nv"&gt;ls&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'ls -G'&lt;/span&gt;                              &lt;span class="c"&gt;# colors&lt;/span&gt;
&lt;span class="nb"&gt;alias&lt;/span&gt; &lt;span class="nv"&gt;ll&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'ls -lrth'&lt;/span&gt;
&lt;span class="nb"&gt;alias&lt;/span&gt; &lt;span class="nv"&gt;lla&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'ls -lrtha'&lt;/span&gt;
&lt;span class="nb"&gt;alias&lt;/span&gt; &lt;span class="nv"&gt;reload&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'exec zsh'&lt;/span&gt;                       &lt;span class="c"&gt;# reload the shell&lt;/span&gt;
&lt;span class="nb"&gt;alias&lt;/span&gt; &lt;span class="nv"&gt;ports&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'lsof -nP -iTCP -sTCP:LISTEN'&lt;/span&gt;     &lt;span class="c"&gt;# who listens on which port&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Isolate an environment: the Floci example
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://github.com/floci-io/floci" rel="noopener noreferrer"&gt;Floci&lt;/a&gt; is a local AWS emulator (I&lt;br&gt;
introduce it in&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/aws-locally-floci/" rel="noopener noreferrer"&gt;AWS locally with Floci&lt;/a&gt;). To use&lt;br&gt;
it, the AWS client must call &lt;code&gt;http://localhost:4566&lt;/code&gt;. The easy way&lt;br&gt;
is a global variable: &lt;code&gt;export AWS_ENDPOINT_URL=http://localhost:4566&lt;/code&gt;&lt;br&gt;
in &lt;code&gt;.zshrc&lt;/code&gt;. But then every AWS command on the machine goes to the&lt;br&gt;
emulator, and you end up forgetting it.&lt;/p&gt;

&lt;p&gt;The AWS docs let you put the address in a named profile of&lt;br&gt;
&lt;code&gt;~/.aws/config&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ini"&gt;&lt;code&gt;&lt;span class="k"&gt;[profile floci]&lt;/span&gt;
&lt;span class="na"&gt;region&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;us&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;east&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;
&lt;span class="na"&gt;endpoint_url&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//localhost:4566&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The test credentials go to &lt;code&gt;~/.aws/credentials&lt;/code&gt;, under &lt;code&gt;[floci]&lt;/code&gt;. I&lt;br&gt;
have no default profile. The result:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;in a normal tab, &lt;code&gt;aws&lt;/code&gt; finds no credentials ("Unable to locate
credentials"): the command goes neither to Floci nor to a real AWS
account;&lt;/li&gt;
&lt;li&gt;with &lt;code&gt;AWS_PROFILE=floci&lt;/code&gt; (or &lt;code&gt;--profile floci&lt;/code&gt;), it goes to Floci.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So that I do not type &lt;code&gt;AWS_PROFILE&lt;/code&gt; each time, a file&lt;br&gt;
&lt;code&gt;~/.zsh/profiles/floci.zsh&lt;/code&gt; sets it and loads the &lt;code&gt;floci&lt;/code&gt; completion:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;AWS_PROFILE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;floci
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="nb"&gt;command&lt;/span&gt; -v floci &lt;span class="o"&gt;&amp;gt;&lt;/span&gt;/dev/null&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
  &lt;span class="nb"&gt;source&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="o"&gt;(&lt;/span&gt;floci completion zsh&lt;span class="o"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;fi&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;floci&lt;/code&gt; completion is a script that cannot go into the &lt;code&gt;fpath&lt;/code&gt;. So&lt;br&gt;
it stays in this profile, and costs nothing to the other tabs.&lt;/p&gt;

&lt;p&gt;In iTerm2, a "dynamic profile" creates a "Floci" profile from a JSON&lt;br&gt;
file, put in &lt;code&gt;~/Library/Application Support/iTerm2/DynamicProfiles/&lt;/code&gt;.&lt;br&gt;
It inherits from the default profile and shows a badge:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"Profiles"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"Name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Floci"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"Guid"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"647AE153-1576-4C43-A514-1581774C216B"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"Dynamic Profile Parent Name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Default"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"Badge Text"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Floci"&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The iTerm2 docs ask for a unique &lt;code&gt;Guid&lt;/code&gt;: I created it with &lt;code&gt;uuidgen&lt;/code&gt;.&lt;br&gt;
iTerm2 puts the profile name in the &lt;code&gt;$ITERM_PROFILE&lt;/code&gt; variable (I saw&lt;br&gt;
it, but its docs do not mention it). &lt;code&gt;~/.zshrc&lt;/code&gt; then loads the Floci&lt;br&gt;
profile in these tabs. In another terminal, like Ghostty or the one in&lt;br&gt;
IntelliJ, a &lt;code&gt;profile floci&lt;/code&gt; function does the same.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fwlnelvq95i52z0qpvucf.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fwlnelvq95i52z0qpvucf.webp" alt="An iTerm2 tab with the Floci profile: the Floci badge at the top right, the Starship prompt shows floci (us-east-1), aws s3 ls lists the Floci buckets, and the completion of the floci command works." width="800" height="643"&gt;&lt;/a&gt;&lt;/p&gt;
&lt;h2&gt;
  
  
  If you already have tools installed as root
&lt;/h2&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;A tool already installed as root?&lt;/strong&gt; Take &lt;code&gt;aws&lt;/code&gt;, often installed&lt;br&gt;
with the official package in &lt;code&gt;/usr/local&lt;/code&gt;. First install the mise&lt;br&gt;
version (&lt;code&gt;mise use -g aws-cli&lt;/code&gt;), check with &lt;code&gt;which -a aws&lt;/code&gt; that it&lt;br&gt;
comes first, then uninstall the old one with the&lt;br&gt;
&lt;a href="https://docs.aws.amazon.com/cli/latest/userguide/uninstall.html" rel="noopener noreferrer"&gt;Uninstall the AWS CLI&lt;/a&gt;&lt;br&gt;
page from AWS. Same idea for the other tools: the mise version&lt;br&gt;
first, the old one after.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;
  
  
  Summary
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Criterion&lt;/th&gt;
&lt;th&gt;My answer&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Nothing as root&lt;/td&gt;
&lt;td&gt;mise and all the tools in &lt;code&gt;~/.local&lt;/code&gt;, the font in &lt;code&gt;~/Library/Fonts&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;One tool&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;mise use -g&lt;/code&gt; for SDKs and tools; one file, &lt;code&gt;~/.config/mise/config.toml&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The right version on &lt;code&gt;cd&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;a &lt;code&gt;mise.local.toml&lt;/code&gt; or &lt;code&gt;mise.toml&lt;/code&gt; per project, and the existing &lt;code&gt;.nvmrc&lt;/code&gt; files&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Isolation&lt;/td&gt;
&lt;td&gt;one file per project; a named AWS profile with no default profile; a Floci tab&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A fast terminal&lt;/td&gt;
&lt;td&gt;completions in files: 92 ms instead of 348 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The full &lt;code&gt;~/.zshrc&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# PATH: no duplicates, user tools first&lt;/span&gt;
&lt;span class="kd"&gt;typeset&lt;/span&gt; -U path PATH
&lt;span class="nv"&gt;path&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"$HOME/.local/bin"&lt;/span&gt; &lt;span class="nv"&gt;$path&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt;

&lt;span class="c"&gt;# History&lt;/span&gt;
&lt;span class="nv"&gt;HISTSIZE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;50000
&lt;span class="nv"&gt;SAVEHIST&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;50000
setopt HIST_IGNORE_ALL_DUPS SHARE_HISTORY HIST_IGNORE_SPACE

&lt;span class="c"&gt;# Completions: the files in ~/.zsh/completions&lt;/span&gt;
&lt;span class="nv"&gt;fpath&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"$HOME/.zsh/completions"&lt;/span&gt; &lt;span class="nv"&gt;$fpath&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt;
autoload -Uz compinit
compinit
autoload -Uz bashcompinit &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; bashcompinit
complete -C aws_completer aws

&lt;span class="c"&gt;# Aliases&lt;/span&gt;
&lt;span class="nb"&gt;alias&lt;/span&gt; &lt;span class="nv"&gt;ls&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'ls -G'&lt;/span&gt;
&lt;span class="nb"&gt;alias&lt;/span&gt; &lt;span class="nv"&gt;ll&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'ls -lrth'&lt;/span&gt;
&lt;span class="nb"&gt;alias&lt;/span&gt; &lt;span class="nv"&gt;lla&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'ls -lrtha'&lt;/span&gt;
&lt;span class="nb"&gt;alias&lt;/span&gt; &lt;span class="nv"&gt;reload&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'exec zsh'&lt;/span&gt;
&lt;span class="nb"&gt;alias&lt;/span&gt; &lt;span class="nv"&gt;ports&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'lsof -nP -iTCP -sTCP:LISTEN'&lt;/span&gt;
&lt;span class="nb"&gt;alias&lt;/span&gt; &lt;span class="nv"&gt;k&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;kubectl
&lt;span class="nb"&gt;alias&lt;/span&gt; update-completions=&lt;span class="s1"&gt;'~/.zsh/update-completions.zsh'&lt;/span&gt;
compdef &lt;span class="nv"&gt;k&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;kubectl

&lt;span class="c"&gt;# mise: the versions of the current folder&lt;/span&gt;
&lt;span class="nb"&gt;eval&lt;/span&gt; &lt;span class="s2"&gt;"$("&lt;/span&gt;&lt;span class="nv"&gt;$HOME&lt;/span&gt;/.local/bin/mise&lt;span class="s2"&gt;" activate zsh)"&lt;/span&gt;

&lt;span class="c"&gt;# Terminal profiles (~/.zsh/profiles), for example: profile floci&lt;/span&gt;
profile&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;local&lt;/span&gt; &lt;span class="nv"&gt;target&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$HOME/.zsh/profiles/${1:l}.zsh"&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt;&lt;span class="o"&gt;[&lt;/span&gt; -f &lt;span class="s2"&gt;"$target"&lt;/span&gt; &lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
    &lt;span class="nb"&gt;source&lt;/span&gt; &lt;span class="s2"&gt;"$target"&lt;/span&gt;
  &lt;span class="k"&gt;else&lt;/span&gt;
    print -u2 &lt;span class="s2"&gt;"Unknown profile: $1 (see the files in ~/.zsh/profiles)"&lt;/span&gt;
    &lt;span class="nb"&gt;return&lt;/span&gt; 1
  &lt;span class="k"&gt;fi&lt;/span&gt;
&lt;span class="o"&gt;}&lt;/span&gt;
&lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="s2"&gt;"$ITERM_PROFILE"&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt;
  Floci&lt;span class="o"&gt;)&lt;/span&gt; profile floci &lt;span class="o"&gt;;&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;esac&lt;/span&gt;

&lt;span class="c"&gt;# Prompt (keep it at the end)&lt;/span&gt;
&lt;span class="nb"&gt;eval&lt;/span&gt; &lt;span class="s2"&gt;"$(starship init zsh)"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Tested on macOS 27 (Apple Silicon) with zsh 5.9, mise 2026.10,&lt;br&gt;
Starship 1.27, iTerm2 and Ghostty, Floci 2.3.&lt;/p&gt;

&lt;p&gt;Sources: the &lt;a href="https://mise.jdx.dev" rel="noopener noreferrer"&gt;mise&lt;/a&gt; documentation ("Getting&lt;br&gt;
started", "Configuration", "Editors and IDEs", Java, Node), the&lt;br&gt;
&lt;a href="https://zsh.sourceforge.io/Doc/Release/" rel="noopener noreferrer"&gt;zsh manual&lt;/a&gt;, the completion&lt;br&gt;
pages of &lt;a href="https://docs.docker.com/engine/cli/completion/" rel="noopener noreferrer"&gt;Docker&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://kubernetes.io/docs/reference/kubectl/generated/kubectl_completion/" rel="noopener noreferrer"&gt;kubectl&lt;/a&gt;&lt;br&gt;
and the &lt;a href="https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-completion.html" rel="noopener noreferrer"&gt;AWS CLI&lt;/a&gt;,&lt;br&gt;
the AWS guide on&lt;br&gt;
&lt;a href="https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html" rel="noopener noreferrer"&gt;endpoints&lt;/a&gt;,&lt;br&gt;
the &lt;a href="https://starship.rs/guide/" rel="noopener noreferrer"&gt;Starship guide&lt;/a&gt; and the docs of&lt;br&gt;
&lt;a href="https://iterm2.com/documentation-dynamic-profiles.html" rel="noopener noreferrer"&gt;iTerm2 dynamic profiles&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/one-chrome-per-google-account-macos/" rel="noopener noreferrer"&gt;One Chrome per Google account on macOS&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-docker-kubernetes-oomkilled/" rel="noopener noreferrer"&gt;Java in Docker and Kubernetes: avoid OOMKilled&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>java</category>
      <category>productivity</category>
      <category>tooling</category>
      <category>cli</category>
    </item>
    <item>
      <title>Java in Docker and Kubernetes: avoid OOMKilled</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Fri, 23 Oct 2026 19:30:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/java-in-docker-and-kubernetes-avoid-oomkilled-5222</link>
      <guid>https://dev.to/aymenjamaaoui/java-in-docker-and-kubernetes-avoid-oomkilled-5222</guid>
      <description>&lt;p&gt;The pod restarts. &lt;code&gt;kubectl get pod&lt;/code&gt; shows &lt;code&gt;OOMKilled&lt;/code&gt;, and the exit&lt;br&gt;
code is 137. But the logs show no &lt;code&gt;OutOfMemoryError&lt;/code&gt;, and the heap was&lt;br&gt;
far from full. The JVM did not run out of memory: the container did.&lt;br&gt;
The Linux kernel killed the process because it went over its limit.&lt;/p&gt;

&lt;p&gt;This post shows what the JVM sees in a container, what adds to the&lt;br&gt;
heap, how to reproduce the kill, and how to set the memory so that&lt;br&gt;
everything fits. All the examples are in the&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/tree/main/containers" rel="noopener noreferrer"&gt;&lt;code&gt;containers/&lt;/code&gt;&lt;/a&gt;&lt;br&gt;
folder of the public java-gc-lab repository. They use the official&lt;br&gt;
&lt;code&gt;eclipse-temurin&lt;/code&gt; images: no image to build.&lt;/p&gt;
&lt;h2&gt;
  
  
  The Docker commands of this post
&lt;/h2&gt;

&lt;p&gt;If you do not use Docker much, here are the options used below.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Option&lt;/th&gt;
&lt;th&gt;What it does&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker run &amp;lt;image&amp;gt; &amp;lt;command&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Starts a container from the image and runs the command in it.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--rm&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Deletes the container when it stops.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--name over-limit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Gives the container a name, for the next commands.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--memory=512m&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Memory limit of the container. This is the limit the JVM reads.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--memory-swap=512m&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Limit for memory + swap. Same value as &lt;code&gt;--memory&lt;/code&gt;: no swap.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;--cpus=2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;CPU limit: the same as 2 CPUs of time.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-v "$PWD/containers":/app&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Mounts the local folder &lt;code&gt;containers/&lt;/code&gt; as &lt;code&gt;/app&lt;/code&gt; in the container.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-d&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Runs the container in the background.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker inspect &amp;lt;name&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Shows the state of a stopped container: exit code, &lt;code&gt;OOMKilled&lt;/code&gt;.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker exec &amp;lt;name&amp;gt; &amp;lt;command&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Runs a command in a running container.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;docker logs &amp;lt;name&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Shows what the container printed.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Watch out for swap: with &lt;code&gt;--memory&lt;/code&gt; alone, Docker also gives the same&lt;br&gt;
amount of swap. &lt;code&gt;java -XshowSettings:system&lt;/code&gt; shows it: "Memory Limit:&lt;br&gt;
1.00G", "Memory &amp;amp; Swap Limit: 2.00G". The container then uses swap&lt;br&gt;
instead of being killed at the limit. To get what happens in&lt;br&gt;
Kubernetes, I set &lt;code&gt;--memory-swap&lt;/code&gt; to the same value.&lt;/p&gt;
&lt;h2&gt;
  
  
  What the JVM sees in a container
&lt;/h2&gt;

&lt;p&gt;On Linux, the JVM reads the limits of the container (the cgroups): the&lt;br&gt;
memory and the number of CPUs. This is the option&lt;br&gt;
&lt;code&gt;-XX:+UseContainerSupport&lt;/code&gt;, on by default. The JVM uses these limits to&lt;br&gt;
size the heap, choose the GC and set the number of threads.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/blob/main/containers/ShowLimits.java" rel="noopener noreferrer"&gt;ShowLimits.java&lt;/a&gt;&lt;br&gt;
prints what the JVM chose:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;docker run --rm --memory=1g --cpus=2 -v "$PWD/containers":/app eclipse-temurin:25 java /app/ShowLimits.java

CPUs: 2
Max heap: 256 MiB
GC: Copy, MarkSweepCompact
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;"Copy, MarkSweepCompact" is the Serial GC. With other limits, the same&lt;br&gt;
results on Java 17, 21 and 25:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;code&gt;--memory&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;&lt;code&gt;--cpus&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;Max heap&lt;/th&gt;
&lt;th&gt;GC&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;256m&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;126 MiB&lt;/td&gt;
&lt;td&gt;Serial&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;1g&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;256 MiB&lt;/td&gt;
&lt;td&gt;Serial&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;1791m&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;448 MiB&lt;/td&gt;
&lt;td&gt;Serial&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;1792m&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;448 MiB&lt;/td&gt;
&lt;td&gt;G1&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;4g&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;1024 MiB&lt;/td&gt;
&lt;td&gt;G1&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The JVM gives these values itself, with no program:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;docker run --rm --memory=1g --cpus=2 eclipse-temurin:25 java -XX:+PrintFlagsFinal -version | grep -E " MaxHeapSize | UseSerialGC | UseG1GC "
docker run --rm --memory=1g --cpus=2 eclipse-temurin:25 java -XshowSettings:system -version
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The first one prints the computed options (&lt;code&gt;MaxHeapSize = 268435456&lt;/code&gt;,&lt;br&gt;
&lt;code&gt;UseSerialGC = true&lt;/code&gt;). The second one shows the limits read from the&lt;br&gt;
container: "Provider: cgroupv2", "Effective CPU Count: 2", "Memory&lt;br&gt;
Limit: 1.00G".&lt;/p&gt;
&lt;h2&gt;
  
  
  The default heap: 25 %, or 50 % for a small heap
&lt;/h2&gt;

&lt;p&gt;Without &lt;code&gt;-Xmx&lt;/code&gt;, the maximum heap is 25 % of the memory the JVM sees:&lt;br&gt;
this is &lt;code&gt;-XX:MaxRAMPercentage&lt;/code&gt;, 25 by default. In a 1 GB container,&lt;br&gt;
that is 256 MB. The other 75 % are not all free: the rest of the JVM&lt;br&gt;
needs them, as we will see below.&lt;/p&gt;

&lt;p&gt;For a small heap, another option takes over: &lt;code&gt;-XX:MinRAMPercentage&lt;/code&gt;,&lt;br&gt;
50 by default. The documentation talks about a heap of "approximately&lt;br&gt;
125 MB". This is what the table shows: with 256 MB, the heap is 126 MB,&lt;br&gt;
not 64.&lt;/p&gt;

&lt;p&gt;You set both options at startup:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -XX:MaxRAMPercentage=50 -jar app.jar
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A percentage follows the container limit: if the limit goes from 1 to&lt;br&gt;
2 GB, the heap follows. A fixed &lt;code&gt;-Xmx&lt;/code&gt; does not change (see&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/jvm-options-that-matter/" rel="noopener noreferrer"&gt;the JVM options that matter&lt;/a&gt;).&lt;/p&gt;
&lt;h2&gt;
  
  
  Serial or G1: a question of CPUs and memory
&lt;/h2&gt;

&lt;p&gt;The table has a surprise: with 2 CPUs and 1 GB, the JVM picks Serial,&lt;br&gt;
not G1. Oracle's GC guide gives the rule: G1 on a "server-class"&lt;br&gt;
machine, Serial otherwise. A machine is "server-class" if the JVM&lt;br&gt;
detects "two or more processors and physical memory larger than or&lt;br&gt;
equal to 1792 MB". The tests confirm it: Serial at 1791 MB, G1 at&lt;br&gt;
1792 MB.&lt;/p&gt;

&lt;p&gt;Serial stops the application during each GC, with one thread (the&lt;br&gt;
available GCs are described in&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-garbage-collectors-2026/" rel="noopener noreferrer"&gt;the post on garbage collectors&lt;/a&gt;). For a&lt;br&gt;
service with little memory, this is not always a problem. But you must&lt;br&gt;
know it, and choose it. To force G1: &lt;code&gt;-XX:+UseG1GC&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The number of CPUs also changes the number of GC threads. With 2 CPUs,&lt;br&gt;
G1 has 2 parallel threads and 1 concurrent thread. The option&lt;br&gt;
&lt;code&gt;-XX:ActiveProcessorCount=&amp;lt;n&amp;gt;&lt;/code&gt; replaces the number of CPUs that the&lt;br&gt;
JVM uses for these sizes. The documentation says it can be useful "when&lt;br&gt;
running multiple Java processes in docker containers".&lt;/p&gt;

&lt;p&gt;What about the CPU request of Kubernetes? In a pod with&lt;br&gt;
&lt;code&gt;requests.cpu: 1&lt;/code&gt; and no CPU limit, the JVM sees all the CPUs of the&lt;br&gt;
machine: 12 on my machine. The same with the Docker option&lt;br&gt;
&lt;code&gt;--cpu-shares&lt;/code&gt; (the cgroup parameter "cpu.shares"). A limit does reduce&lt;br&gt;
the number of CPUs the JVM sees: with &lt;code&gt;limits.cpu: "2"&lt;/code&gt; (or&lt;br&gt;
&lt;code&gt;--cpus=2&lt;/code&gt;), it sees 2.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Before Java 19:&lt;/strong&gt; the JVM also used "cpu.shares" to count the CPUs,&lt;br&gt;
and could see fewer than available. Java 19 ignores it&lt;br&gt;
(JDK-8281181). In my tests, Temurin 17.0.20 also ignores it.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;
  
  
  What adds to the heap
&lt;/h2&gt;

&lt;p&gt;The container limit covers the whole process, not only the heap:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;the &lt;strong&gt;Metaspace&lt;/strong&gt;: the description of the loaded classes;&lt;/li&gt;
&lt;li&gt;the &lt;strong&gt;thread stacks&lt;/strong&gt;: by default 1024 KB per thread on Linux/x64,
and 2048 KB on Linux/Aarch64 (for example Docker on an Apple Silicon
Mac);&lt;/li&gt;
&lt;li&gt;the &lt;strong&gt;code cache&lt;/strong&gt;: the code compiled by the JIT;&lt;/li&gt;
&lt;li&gt;the &lt;strong&gt;direct memory&lt;/strong&gt;: the &lt;code&gt;ByteBuffer.allocateDirect&lt;/code&gt; buffers.
Without &lt;code&gt;-XX:MaxDirectMemorySize&lt;/code&gt;, the JVM chooses the limit itself;&lt;/li&gt;
&lt;li&gt;the GC data and other internal areas.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A heap at 75 % of the limit leaves 25 % for all of this. If the rest&lt;br&gt;
needs more, the container is killed, even with a half-empty heap.&lt;/p&gt;
&lt;h2&gt;
  
  
  Reproduce the kill
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/blob/main/containers/OverLimit.java" rel="noopener noreferrer"&gt;OverLimit.java&lt;/a&gt;&lt;br&gt;
keeps 250 MB in the heap, then takes direct memory by blocks of 10 MB,&lt;br&gt;
with no end. A 512 MB container with no swap, max heap at 75 %&lt;br&gt;
(384 MB):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;docker run --name over-limit --memory=512m --memory-swap=512m -v "$PWD/containers":/app eclipse-temurin:25 java -XX:MaxRAMPercentage=75 /app/OverLimit.java

Heap: 250 MB used
Direct memory: 10 MB
...
Direct memory: 170 MB
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The output just stops. No &lt;code&gt;OutOfMemoryError&lt;/code&gt;, no stack trace: the&lt;br&gt;
process was killed. &lt;code&gt;docker inspect&lt;/code&gt; confirms it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;docker inspect over-limit --format "exit={{.State.ExitCode}} OOMKilled={{.State.OOMKilled}}"

exit=137 OOMKilled=true
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;137 is 128 + 9: the process got signal 9 (&lt;code&gt;SIGKILL&lt;/code&gt;), which cannot be&lt;br&gt;
caught. The JVM could not write anything, and&lt;br&gt;
&lt;code&gt;-XX:+HeapDumpOnOutOfMemoryError&lt;/code&gt; does not help here: there was no&lt;br&gt;
&lt;code&gt;OutOfMemoryError&lt;/code&gt;. Depending on the version, the kill comes between&lt;br&gt;
170 and 190 MB of direct memory.&lt;/p&gt;
&lt;h2&gt;
  
  
  See where the memory goes with NMT
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-tools-jfr-jcmd-visualvm/" rel="noopener noreferrer"&gt;Native Memory Tracking (NMT)&lt;/a&gt; counts the memory of the JVM by area. I&lt;br&gt;
run it again with NMT, and the argument &lt;code&gt;100&lt;/code&gt; stops the direct memory&lt;br&gt;
at 100 MB; the program then waits 30 seconds:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;docker run -d --name over-limit --memory=512m --memory-swap=512m -v "$PWD/containers":/app eclipse-temurin:25 java -XX:MaxRAMPercentage=75 -XX:NativeMemoryTracking=summary /app/OverLimit.java 100
docker exec over-limit jcmd 1 VM.native_memory summary scale=MB

Total: reserved=1875MB, committed=533MB
-                 Java Heap (reserved=384MB, committed=384MB)
-                     Class (reserved=1024MB, committed=2MB)
-                    Thread (reserved=26MB, committed=1MB)
-                      Code (reserved=245MB, committed=9MB)
-                     Other (reserved=100MB, committed=100MB)
-                 Metaspace (reserved=64MB, committed=9MB)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;(I removed some lines.) &lt;code&gt;1&lt;/code&gt; is the process id of Java in the container.&lt;br&gt;
The heap takes 384 MB, and the 100 MB of direct memory are in "Other".&lt;br&gt;
This small program has few classes and threads; a real application has&lt;br&gt;
more Metaspace, more threads and more compiled code. &lt;code&gt;docker stats&lt;br&gt;
--no-stream over-limit&lt;/code&gt; shows the memory the container really uses:&lt;br&gt;
about 430 MiB in my runs, out of 512. It is not the same measure: NMT&lt;br&gt;
counts the memory "committed" by the JVM, &lt;code&gt;docker stats&lt;/code&gt; the memory the&lt;br&gt;
container uses. (A MiB, like the &lt;code&gt;Mi&lt;/code&gt; of Kubernetes, is 1,048,576 bytes.)&lt;/p&gt;
&lt;h2&gt;
  
  
  Better than a kill: a Java error
&lt;/h2&gt;

&lt;p&gt;With a limit on direct memory, the JVM stops before the container, with&lt;br&gt;
a clear message:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;docker run --rm --memory=512m --memory-swap=512m -v "$PWD/containers":/app eclipse-temurin:25 java -XX:MaxRAMPercentage=75 -XX:MaxDirectMemorySize=100m /app/OverLimit.java

Exception in thread "main" java.lang.OutOfMemoryError: Cannot reserve 10485760 bytes of direct buffer memory (allocated: 104857600, limit: 104857600)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;An error with a stack trace tells what is full. A kill tells nothing.&lt;br&gt;
The other &lt;code&gt;OutOfMemoryError&lt;/code&gt; messages are in&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;the post about OutOfMemoryError&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  Choose &lt;code&gt;MaxRAMPercentage&lt;/code&gt;
&lt;/h2&gt;

&lt;p&gt;There is no good percentage for all applications. The rule is simple:&lt;br&gt;
the maximum heap plus all the rest must fit in the limit. You measure&lt;br&gt;
the rest with NMT, on the application under load.&lt;/p&gt;

&lt;p&gt;In the example, the program needs 250 MB of heap and 200 MB of direct&lt;br&gt;
memory. With 768 MB and 50 %:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;docker run --name over-limit --memory=768m --memory-swap=768m -v "$PWD/containers":/app eclipse-temurin:25 java -XX:MaxRAMPercentage=50 /app/OverLimit.java 200

Done: 250 MB heap, 200 MB direct, waiting 30 s
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;docker inspect&lt;/code&gt; gives &lt;code&gt;exit=0 OOMKilled=false&lt;/code&gt;. The heap can grow to&lt;br&gt;
384 MB (50 % of 768), and 384 MB stay for the direct memory and the&lt;br&gt;
rest of the JVM. The more memory an application uses outside the heap&lt;br&gt;
(threads, direct memory, many classes), the lower the percentage must&lt;br&gt;
be.&lt;/p&gt;
&lt;h2&gt;
  
  
  In Kubernetes
&lt;/h2&gt;

&lt;p&gt;In a pod, each container has &lt;code&gt;requests&lt;/code&gt; and &lt;code&gt;limits&lt;/code&gt;. The Kubernetes&lt;br&gt;
documentation says that the request is used to choose the node for the&lt;br&gt;
pod; the limit is enforced by the kernel. For memory, a container that&lt;br&gt;
goes over its limit can be killed (OOM kill). For CPU, it is slowed&lt;br&gt;
down.&lt;/p&gt;

&lt;p&gt;So the memory limit is the one the JVM reads. Without &lt;code&gt;limits.memory&lt;/code&gt;,&lt;br&gt;
the JVM sees the memory of the node: in a pod with only&lt;br&gt;
&lt;code&gt;requests.memory: 1Gi&lt;/code&gt;, the max heap is 1984 MiB on my machine (25 % of&lt;br&gt;
the 7.7 GB of the Docker VM), much more than the request.&lt;/p&gt;

&lt;p&gt;For the example, the Java file goes into the pod with a ConfigMap: no&lt;br&gt;
image to build. The manifest&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/blob/main/containers/pod-before.yaml" rel="noopener noreferrer"&gt;pod-before.yaml&lt;/a&gt;&lt;br&gt;
is the killed case:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;      &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"java"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-XX:MaxRAMPercentage=75"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"/app/OverLimit.java"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
      &lt;span class="na"&gt;resources&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;requests&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;memory&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"512Mi"&lt;/span&gt;
          &lt;span class="na"&gt;cpu&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1"&lt;/span&gt;
        &lt;span class="na"&gt;limits&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;memory&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"512Mi"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;kubectl&lt;/code&gt; commands used:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Command&lt;/th&gt;
&lt;th&gt;What it does&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;kubectl create configmap over-limit-code --from-file=containers/OverLimit.java&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Stores the Java file in the cluster; the pod mounts it in &lt;code&gt;/app&lt;/code&gt;.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;kubectl apply -f containers/pod-before.yaml&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Creates the pod described in the file.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;kubectl get pod over-limit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Shows the status of the pod.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;kubectl describe pod over-limit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Shows the details: state, reason, exit code, limits.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;kubectl logs over-limit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Shows what the program printed.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;kubectl delete pod over-limit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Deletes the pod.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;kubectl create configmap over-limit-code --from-file=containers/OverLimit.java
kubectl apply -f containers/pod-before.yaml
kubectl get pod over-limit

NAME         READY   STATUS      RESTARTS   AGE
over-limit   0/1     OOMKilled   0          7s

kubectl describe pod over-limit

    State:          Terminated
      Reason:       OOMKilled
      Exit Code:    137
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Here, &lt;code&gt;RESTARTS&lt;/code&gt; is 0: the pod of the example has &lt;code&gt;restartPolicy: Never&lt;/code&gt;,&lt;br&gt;
so that its state stays there to read. With a Deployment, Kubernetes&lt;br&gt;
starts the container again, and &lt;code&gt;RESTARTS&lt;/code&gt; goes up after each kill: this&lt;br&gt;
is the pod that restarts at the start of this post.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/blob/main/containers/pod-after.yaml" rel="noopener noreferrer"&gt;pod-after.yaml&lt;/a&gt;&lt;br&gt;
uses the size that fits: &lt;code&gt;limits.memory: 768Mi&lt;/code&gt;,&lt;br&gt;
&lt;code&gt;-XX:MaxRAMPercentage=50&lt;/code&gt;. After &lt;code&gt;kubectl delete pod over-limit&lt;/code&gt; and&lt;br&gt;
&lt;code&gt;kubectl apply -f containers/pod-after.yaml&lt;/code&gt;, the pod ends as&lt;br&gt;
&lt;code&gt;Completed&lt;/code&gt;, exit code 0.&lt;/p&gt;

&lt;h2&gt;
  
  
  What has changed
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What you still read&lt;/th&gt;
&lt;th&gt;What is true today&lt;/th&gt;
&lt;th&gt;Since&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;-XX:+UseCGroupMemoryLimitForHeap&lt;/code&gt; so that Java sees the limit&lt;/td&gt;
&lt;td&gt;Nothing to add: the JVM reads the limits itself (&lt;code&gt;UseContainerSupport&lt;/code&gt;); the old option is refused&lt;/td&gt;
&lt;td&gt;JDK 10, and Java 8u191; option removed in Java 11&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;-XX:MaxRAMFraction=4&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;-XX:MaxRAMPercentage=25&lt;/code&gt; (and &lt;code&gt;InitialRAMPercentage&lt;/code&gt;, &lt;code&gt;MinRAMPercentage&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;JDK 10&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;"cpu.shares" changes the number of CPUs Java sees&lt;/td&gt;
&lt;td&gt;"cpu.shares" is ignored&lt;/td&gt;
&lt;td&gt;Java 19 (Temurin 17.0.20 too, in my tests)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Tested with Docker Desktop 29.8 (Linux VM, aarch64, cgroup v2), its&lt;br&gt;
Kubernetes (v1.36), and the &lt;code&gt;eclipse-temurin&lt;/code&gt; images 17.0.20, 21.0.12&lt;br&gt;
and 25.0.4.&lt;/p&gt;

&lt;p&gt;Sources: the documentation of the&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/docs/specs/man/java.html" rel="noopener noreferrer"&gt;&lt;code&gt;java&lt;/code&gt;&lt;/a&gt;&lt;br&gt;
command (JDK 25),&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/gctuning/ergonomics.html" rel="noopener noreferrer"&gt;Oracle's GC guide, part "Ergonomics"&lt;/a&gt;,&lt;br&gt;
the release notes of&lt;br&gt;
&lt;a href="https://www.oracle.com/java/technologies/javase/10-relnote-issues.html" rel="noopener noreferrer"&gt;JDK 10&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://www.oracle.com/java/technologies/javase/8u191-relnotes.html" rel="noopener noreferrer"&gt;Java 8u191&lt;/a&gt;&lt;br&gt;
and &lt;a href="https://www.oracle.com/java/technologies/javase/19-relnote-issues.html" rel="noopener noreferrer"&gt;JDK 19&lt;/a&gt;,&lt;br&gt;
and the Kubernetes documentation&lt;br&gt;
(&lt;a href="https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/" rel="noopener noreferrer"&gt;Resource Management for Pods and Containers&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://kubernetes.io/docs/tasks/configure-pod-container/assign-memory-resource/" rel="noopener noreferrer"&gt;Assign Memory Resources to Containers and Pods&lt;/a&gt;).&lt;/p&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/jvm-options-that-matter/" rel="noopener noreferrer"&gt;JVM options that matter, and the ones that no longer work&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;Java OutOfMemoryError: every message, reproduced&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-garbage-collector-guide/" rel="noopener noreferrer"&gt;The Java garbage collector: an up-to-date guide (Java 25)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>java</category>
      <category>docker</category>
      <category>kubernetes</category>
      <category>devops</category>
    </item>
    <item>
      <title>JFR, jcmd, VisualVM: which tool for Java memory problems</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Fri, 23 Oct 2026 07:00:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/jfr-jcmd-visualvm-which-tool-for-java-memory-problems-3g8o</link>
      <guid>https://dev.to/aymenjamaaoui/jfr-jcmd-visualvm-which-tool-for-java-memory-problems-3g8o</guid>
      <description>&lt;p&gt;In this series, we have already used about six tools: GC logs, &lt;code&gt;jstat&lt;/code&gt;,&lt;br&gt;
several &lt;code&gt;jcmd&lt;/code&gt; commands, Eclipse MAT. Each one answers a clear question,&lt;br&gt;
and each one has a cost. This post puts them in order. Then it shows&lt;br&gt;
JFR, the most complete tool of the JDK, on an example: find the method&lt;br&gt;
that creates millions of objects.&lt;/p&gt;
&lt;h2&gt;
  
  
  Which tool for which question
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Question&lt;/th&gt;
&lt;th&gt;Tool&lt;/th&gt;
&lt;th&gt;Command&lt;/th&gt;
&lt;th&gt;Cost&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Does the GC make long pauses? Does the heap after GC go up?&lt;/td&gt;
&lt;td&gt;GC logs&lt;/td&gt;
&lt;td&gt;&lt;code&gt;-Xlog:gc*:file=gc.log&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;keep it on in production&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Which area fills up, live?&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jstat&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jstat -gcutil &amp;lt;pid&amp;gt; 1s&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;not given; its doc says "experimental and unsupported"&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;How much heap is used?&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jcmd&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jcmd &amp;lt;pid&amp;gt; GC.heap_info&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;medium&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Which class grows?&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jcmd&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jcmd &amp;lt;pid&amp;gt; GC.class_histogram&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;high: runs a full GC&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;What keeps the objects alive?&lt;/td&gt;
&lt;td&gt;heap dump + Eclipse MAT&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jcmd &amp;lt;pid&amp;gt; GC.heap_dump&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;high: a big file&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Does the Metaspace grow?&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jcmd&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jcmd &amp;lt;pid&amp;gt; VM.metaspace&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;medium&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;What does native memory do?&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;jcmd&lt;/code&gt; + NMT&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;-XX:NativeMemoryTracking=summary&lt;/code&gt;, then &lt;code&gt;jcmd &amp;lt;pid&amp;gt; VM.native_memory&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;medium&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;What do the threads do?&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jcmd&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jcmd &amp;lt;pid&amp;gt; Thread.print&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;medium&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Which method allocates, where are the pauses, over time?&lt;/td&gt;
&lt;td&gt;JFR&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;-XX:StartFlightRecording&lt;/code&gt;, then &lt;code&gt;jfr view&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;low with the &lt;code&gt;default&lt;/code&gt; configuration&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The "medium" or "high" cost of the &lt;code&gt;jcmd&lt;/code&gt; commands is the one given&lt;br&gt;
in their documentation. Each of these tools was already used in a post:&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/read-java-gc-log/" rel="noopener noreferrer"&gt;GC logs&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;OutOfMemoryError&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-memory-leaks/" rel="noopener noreferrer"&gt;memory leaks&lt;/a&gt; and&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-heap-dump-eclipse-mat/" rel="noopener noreferrer"&gt;the heap dump with Eclipse MAT&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  JFR step by step
&lt;/h2&gt;

&lt;p&gt;Java Flight Recorder (JFR) is part of the JDK. It records events from&lt;br&gt;
the JVM and from the application: GC, allocations, threads, the most&lt;br&gt;
used methods…&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Record.&lt;/strong&gt; At startup:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -XX:StartFlightRecording:filename=hot.jfr,settings=profile -jar app.jar
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Or on an application that already runs: &lt;code&gt;jcmd &amp;lt;pid&amp;gt; JFR.start&lt;/code&gt;, then&lt;br&gt;
&lt;code&gt;jcmd &amp;lt;pid&amp;gt; JFR.dump filename=hot.jfr&lt;/code&gt; to write the recording.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Choose the configuration.&lt;/strong&gt; Oracle's documentation recommends the&lt;br&gt;
&lt;code&gt;default&lt;/code&gt; configuration for continuous recordings, with usually less&lt;br&gt;
than 1% overhead. The &lt;code&gt;profile&lt;/code&gt; configuration records more events, such&lt;br&gt;
as allocation samples: use it to analyze a problem. The doc gives no&lt;br&gt;
number for its overhead.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Read.&lt;/strong&gt; The &lt;code&gt;jfr&lt;/code&gt; command of the JDK shows tables, with no graphical&lt;br&gt;
interface:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;jfr view allocation-by-site hot.jfr
jfr view gc hot.jfr
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Before Java 21:&lt;/strong&gt; &lt;code&gt;jfr view&lt;/code&gt; does not exist. On Java 17, the command&lt;br&gt;
answers &lt;code&gt;jfr: unknown command 'view'&lt;/code&gt;: use &lt;code&gt;jfr print&lt;/code&gt; or JDK Mission&lt;br&gt;
Control.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Example: the method that creates millions of objects
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/blob/level-2/tools/HotAllocation.java" rel="noopener noreferrer"&gt;HotAllocation.java&lt;/a&gt;&lt;br&gt;
builds 10 million labels with &lt;code&gt;String.format&lt;/code&gt;. We record it with JFR,&lt;br&gt;
then:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;jfr view allocation-by-site hot.jfr

Method                                              Allocation Pressure
--------------------------------------------------- -------------------
java.util.Formatter.parse(String)                                24.70%
java.lang.Long.toString(long)                                    18.83%
java.lang.AbstractStringBuilder.&amp;lt;init&amp;gt;(int)                      14.20%
java.util.Arrays.copyOfRange(byte[], int, int)                   10.61%
java.util.ArrayList.grow(int)                                    10.35%
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;Formatter.parse&lt;/code&gt; creates the most objects. These are samples: the&lt;br&gt;
percentages change a little from one run to the next, but the top of&lt;br&gt;
the table stays the same. Now we need the caller in our code: the stack&lt;br&gt;
of one sample gives it.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;jfr print --events jdk.ObjectAllocationSample --stack-depth 6 hot.jfr

  stackTrace = [
    java.util.Formatter.parse(String) line: 2810
    java.util.Formatter.format(Locale, String, Object[]) line: 2744
    java.util.Formatter.format(String, Object[]) line: 2698
    java.lang.String.format(String, Object[]) line: 4455
    HotAllocation.label(int) line: 16
    HotAllocation.main(String[]) line: 24
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The cause: &lt;code&gt;String.format&lt;/code&gt;, called in &lt;code&gt;label()&lt;/code&gt;. Each call parses the&lt;br&gt;
pattern &lt;code&gt;"order-%08d"&lt;/code&gt; and creates several objects. In&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/blob/level-2/tools/FixedAllocation.java" rel="noopener noreferrer"&gt;FixedAllocation.java&lt;/a&gt;,&lt;br&gt;
the same labels are built with a &lt;code&gt;StringBuilder&lt;/code&gt;. Same result, with&lt;br&gt;
&lt;code&gt;-Xmx256m&lt;/code&gt; and JFR on:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;&lt;code&gt;HotAllocation&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;&lt;code&gt;FixedAllocation&lt;/code&gt;&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Java 25&lt;/td&gt;
&lt;td&gt;32 GCs, 2.7 s&lt;/td&gt;
&lt;td&gt;9 GCs, 0.7 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Java 21&lt;/td&gt;
&lt;td&gt;44 GCs&lt;/td&gt;
&lt;td&gt;12 GCs&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Java 17&lt;/td&gt;
&lt;td&gt;94 GCs&lt;/td&gt;
&lt;td&gt;10 GCs&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Fewer objects created, so fewer GCs: this is the "allocation rate" of&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/read-java-gc-log/" rel="noopener noreferrer"&gt;the post about GC logs&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  jcmd, the Swiss Army knife
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;jcmd&lt;/code&gt; sends a command to a running JVM. &lt;code&gt;jcmd &amp;lt;pid&amp;gt; help&lt;/code&gt; lists all&lt;br&gt;
the commands you can use. The ones of this series: &lt;code&gt;GC.heap_info&lt;/code&gt;,&lt;br&gt;
&lt;code&gt;GC.class_histogram&lt;/code&gt;, &lt;code&gt;GC.heap_dump&lt;/code&gt;, &lt;code&gt;GC.run&lt;/code&gt;, &lt;code&gt;VM.metaspace&lt;/code&gt;,&lt;br&gt;
&lt;code&gt;VM.native_memory&lt;/code&gt;, &lt;code&gt;Thread.print&lt;/code&gt;, and &lt;code&gt;JFR.start&lt;/code&gt; / &lt;code&gt;JFR.dump&lt;/code&gt;. Its&lt;br&gt;
documentation gives the impact of each one: read it before you run a&lt;br&gt;
"High" command on a busy production system.&lt;/p&gt;

&lt;h2&gt;
  
  
  VisualVM and JDK Mission Control
&lt;/h2&gt;

&lt;p&gt;If you prefer a window:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://visualvm.github.io/" rel="noopener noreferrer"&gt;VisualVM&lt;/a&gt; follows a JVM live (CPU, GC
activity, heap, Metaspace), shows its threads, takes and opens heap
dumps, and does simple profiling.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://www.oracle.com/java/technologies/jdk-mission-control.html" rel="noopener noreferrer"&gt;JDK Mission Control&lt;/a&gt;
opens &lt;code&gt;.jfr&lt;/code&gt; files and shows the same data as &lt;code&gt;jfr view&lt;/code&gt;, as charts.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The same &lt;code&gt;hot.jfr&lt;/code&gt;, opened in JMC. JMC counts allocations by class,&lt;br&gt;
&lt;code&gt;jfr view allocation-by-site&lt;/code&gt; by method: both views come from the same&lt;br&gt;
recording.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fkd4kf7yo4vssyi57eodx.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fkd4kf7yo4vssyi57eodx.webp" alt="JDK Mission Control, Memory page: at the top, allocations by class (byte[] 50.6%, Object[] 18.9%, java.util.Formatter$FixedString 14.1%); at the bottom, the heap as a saw-tooth line, with one vertical line per GC." width="799" height="550"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Before Java 9:&lt;/strong&gt; VisualVM came with the JDK (&lt;code&gt;jvisualvm&lt;/code&gt;). It was&lt;br&gt;
removed in Java 9, and you now download it on its own.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;You install both separately. The commands of this post are already in&lt;br&gt;
the JDK, and they work on a server with no screen.&lt;/p&gt;

&lt;h2&gt;
  
  
  In production
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Keep on all the time&lt;/strong&gt;: GC logs in a file, and JFR with the
&lt;code&gt;default&lt;/code&gt; configuration.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Now and then, when you know the cost&lt;/strong&gt;: &lt;code&gt;GC.class_histogram&lt;/code&gt; (a
full GC), &lt;code&gt;GC.heap_dump&lt;/code&gt; (a big file, with sensitive data), JFR with
&lt;code&gt;profile&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Before you act&lt;/strong&gt;: read again the "Impact" line of the command in
the &lt;code&gt;jcmd&lt;/code&gt; documentation.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Tested with Java 17, 21 and 25 (Temurin 17.0.20, 21.0.12, 25.0.4), on&lt;br&gt;
macOS; the programs compile with Java 8.&lt;/p&gt;

&lt;p&gt;Sources: the documentation of&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/docs/specs/man/jcmd.html" rel="noopener noreferrer"&gt;&lt;code&gt;jcmd&lt;/code&gt;&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/docs/specs/man/jfr.html" rel="noopener noreferrer"&gt;&lt;code&gt;jfr&lt;/code&gt;&lt;/a&gt;&lt;br&gt;
and &lt;a href="https://docs.oracle.com/en/java/javase/25/docs/specs/man/jstat.html" rel="noopener noreferrer"&gt;&lt;code&gt;jstat&lt;/code&gt;&lt;/a&gt;,&lt;br&gt;
the &lt;a href="https://docs.oracle.com/en/java/javase/25/jfapi/flight-recorder-configurations.html" rel="noopener noreferrer"&gt;Flight Recorder guide on its configurations&lt;/a&gt;&lt;br&gt;
(JDK 25), &lt;a href="https://bugs.openjdk.org/browse/JDK-8306703" rel="noopener noreferrer"&gt;JDK-8306703&lt;/a&gt;&lt;br&gt;
(&lt;code&gt;jfr view&lt;/code&gt;) and &lt;a href="https://bugs.openjdk.org/browse/JDK-8180002" rel="noopener noreferrer"&gt;JDK-8180002&lt;/a&gt;&lt;br&gt;
(VisualVM removed from the JDK).&lt;/p&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-heap-dump-eclipse-mat/" rel="noopener noreferrer"&gt;Java heap dump: find a memory leak with Eclipse MAT&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-memory-leaks/" rel="noopener noreferrer"&gt;Java memory leaks: 6 classic cases, reproduced&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/read-java-gc-log/" rel="noopener noreferrer"&gt;Reading a Java GC log: every number explained&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-garbage-collector-guide/" rel="noopener noreferrer"&gt;The Java garbage collector: an up-to-date guide (Java 25)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>java</category>
      <category>jvm</category>
      <category>monitoring</category>
      <category>tooling</category>
    </item>
    <item>
      <title>Java heap dump: find a memory leak with Eclipse MAT</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Fri, 23 Oct 2026 00:00:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/java-heap-dump-find-a-memory-leak-with-eclipse-mat-55op</link>
      <guid>https://dev.to/aymenjamaaoui/java-heap-dump-find-a-memory-leak-with-eclipse-mat-55op</guid>
      <description>&lt;p&gt;In &lt;a href="https://aymenjamaaoui.dev/en/blog/java-memory-leaks/" rel="noopener noreferrer"&gt;the post about memory leaks&lt;/a&gt;, two&lt;br&gt;
&lt;code&gt;jcmd&lt;/code&gt; histograms showed &lt;strong&gt;which&lt;/strong&gt; class grows. But not &lt;strong&gt;what&lt;/strong&gt; keeps&lt;br&gt;
it alive. For that, you need a heap dump: a picture of the whole heap,&lt;br&gt;
with the objects and the links between them.&lt;/p&gt;

&lt;p&gt;We take the same leak again:&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/blob/level-2/leaks/UnboundedCache.java" rel="noopener noreferrer"&gt;UnboundedCache.java&lt;/a&gt;,&lt;br&gt;
a static &lt;code&gt;HashMap&lt;/code&gt; cache that gets a new key, and a new &lt;code&gt;Report&lt;/code&gt; object,&lt;br&gt;
on each request. We analyze&lt;br&gt;
it with Eclipse Memory Analyzer (MAT), an open source tool that Oracle's&lt;br&gt;
guide names for heap dump analysis. All the commands are in the&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/tree/level-2/heap-dump" rel="noopener noreferrer"&gt;heap-dump&lt;/a&gt;&lt;br&gt;
folder of the &lt;code&gt;java-gc-lab&lt;/code&gt; repository.&lt;/p&gt;
&lt;h2&gt;
  
  
  Step 1: take the heap dump
&lt;/h2&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;javac -d out leaks/UnboundedCache.java
java -Xmx256m -cp out UnboundedCache
jcmd &amp;lt;pid&amp;gt; GC.heap_dump /tmp/cache.hprof
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;After 20 seconds, the file is 22 MB. By default, &lt;code&gt;GC.heap_dump&lt;/code&gt; keeps&lt;br&gt;
only the live objects: it runs a full GC first. The &lt;code&gt;-all&lt;/code&gt; option also&lt;br&gt;
keeps the dead objects. On a real application, it can be&lt;br&gt;
several GB: &lt;code&gt;-gz=1&lt;/code&gt; writes it gzipped. You can also let the JVM write it&lt;br&gt;
at the first &lt;code&gt;OutOfMemoryError&lt;/code&gt;, with &lt;code&gt;-XX:+HeapDumpOnOutOfMemoryError&lt;/code&gt;&lt;br&gt;
(see &lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;the post about OutOfMemoryError&lt;/a&gt;).&lt;/p&gt;

&lt;p&gt;Two warnings:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The dump holds the values of the objects.&lt;/strong&gt; MAT even shows the text
of &lt;code&gt;String&lt;/code&gt; objects. On a real application, it can hold passwords or
personal data: do not share it, and delete it after use.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Compile before you run.&lt;/strong&gt; With &lt;code&gt;java UnboundedCache.java&lt;/code&gt; (no
&lt;code&gt;javac&lt;/code&gt;), the class is loaded in memory by the source launcher, and
MAT points to the &lt;code&gt;main&lt;/code&gt; thread instead of the class that leaks. Run
with &lt;code&gt;-cp&lt;/code&gt;, like a normal application, the class is the one MAT
points to.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;
  
  
  Step 2: Leak Suspects
&lt;/h2&gt;

&lt;p&gt;The "Leak Suspects" report is the first one to open. MAT lists the&lt;br&gt;
objects that keep the most memory alive:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fsdzwtpbactt9n1rrwtm2.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fsdzwtpbactt9n1rrwtm2.webp" alt="The Leak Suspects report of Eclipse MAT: a pie chart where problem suspect 1 takes 17.1 MB of 18.2 MB, and the text &amp;quot;The class UnboundedCache … occupies 17,919,200 (93.87%) bytes&amp;quot;" width="640" height="930"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;What to read: the class &lt;code&gt;UnboundedCache&lt;/code&gt; keeps &lt;strong&gt;93.87%&lt;/strong&gt; of the heap,&lt;br&gt;
and the memory piles up in &lt;strong&gt;one single&lt;/strong&gt; array,&lt;br&gt;
&lt;code&gt;java.util.HashMap$Node[]&lt;/code&gt;: the internal array of a &lt;code&gt;HashMap&lt;/code&gt;. The&lt;br&gt;
culprit is found at the first try.&lt;/p&gt;
&lt;h2&gt;
  
  
  Step 3: shallow heap and retained heap
&lt;/h2&gt;

&lt;p&gt;MAT shows two sizes for each object:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;the &lt;strong&gt;shallow heap&lt;/strong&gt;: the memory of the object itself;&lt;/li&gt;
&lt;li&gt;the &lt;strong&gt;retained heap&lt;/strong&gt;: the memory that the GC would free if this
object were freed, that is everything it keeps alive.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;For a leak, the retained heap is what matters. The class&lt;br&gt;
&lt;code&gt;UnboundedCache&lt;/code&gt; is the best example: its shallow heap is 8 bytes, its&lt;br&gt;
retained heap 17.9 MB.&lt;/p&gt;
&lt;h2&gt;
  
  
  Step 4: the dominator tree
&lt;/h2&gt;

&lt;p&gt;For MAT, an object x &lt;strong&gt;dominates&lt;/strong&gt; an object y if every path from a GC&lt;br&gt;
root to y goes through x. The dominator tree sorts the objects with this&lt;br&gt;
rule, from the biggest retained heap to the smallest:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Class Name                                    Shallow Heap   Retained Heap   Percentage
class UnboundedCache @ 0x124213cd0                       8      17,919,200       93.87%
java.lang.Object[2708] @ 0x133e00000 JNI Global     10,848         105,528        0.55%
java.lang.Object[8187] @ 0x133e71f40 JNI Global     32,768          48,424        0.25%
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The first line crushes all the others: this is where to dig.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 5: the path to GC roots
&lt;/h2&gt;

&lt;p&gt;What is left is &lt;strong&gt;why&lt;/strong&gt; a &lt;code&gt;Report&lt;/code&gt; object stays alive. "Path to GC&lt;br&gt;
Roots" goes up from the object to a GC root, that is an object&lt;br&gt;
reachable from outside the heap, such as a loaded class ("System&lt;br&gt;
Class"). We exclude weak and soft references: they do not stop the GC&lt;br&gt;
from freeing an object.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Flh11dem9scuuaj1hqhd1.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Flh11dem9scuuaj1hqhd1.webp" alt="The path to GC roots in Eclipse MAT: an UnboundedCache$Report object, kept by a HashMap$Node, the HashMap$Node[4096] array, the HashMap, then the static field CACHE of the class UnboundedCache, and at last a root of type System Class" width="640" height="430"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Read the path from the bottom up: the root keeps the class&lt;br&gt;
&lt;code&gt;UnboundedCache&lt;/code&gt;, its static field &lt;code&gt;CACHE&lt;/code&gt; keeps the &lt;code&gt;HashMap&lt;/code&gt;, which&lt;br&gt;
keeps its array, which keeps each &lt;code&gt;Report&lt;/code&gt;. It is exactly the chain of&lt;br&gt;
the diagram in&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-memory-leaks/" rel="noopener noreferrer"&gt;the post about memory leaks&lt;/a&gt;, but&lt;br&gt;
this time found in a real dump.&lt;/p&gt;
&lt;h2&gt;
  
  
  The fix, and the heap curve
&lt;/h2&gt;

&lt;p&gt;The fix: give the cache a maximum size. In&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/blob/level-2/heap-dump/BoundedCache.java" rel="noopener noreferrer"&gt;BoundedCache.java&lt;/a&gt;,&lt;br&gt;
a &lt;code&gt;LinkedHashMap&lt;/code&gt; removes the oldest entry above 500 with&lt;br&gt;
&lt;code&gt;removeEldestEntry&lt;/code&gt;. The heap after each GC goes up while the cache&lt;br&gt;
fills, then does not move anymore (no heap dump here, so running&lt;br&gt;
without &lt;code&gt;javac&lt;/code&gt; is fine):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -Xmx256m -Xlog:gc heap-dump/BoundedCache.java
[0.348s][info][gc] GC(0) Pause Young (Normal) (G1 Evacuation Pause) 48M-&amp;gt;3M(256M) 1.559ms
[16.656s][info][gc] GC(19) Pause Young (Normal) (G1 Evacuation Pause) 156M-&amp;gt;9M(256M) 0.828ms
[35.667s][info][gc] GC(41) Pause Young (Normal) (G1 Evacuation Pause) 156M-&amp;gt;9M(256M) 0.984ms
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;How to read these lines is explained in&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/read-java-gc-log/" rel="noopener noreferrer"&gt;the post about GC logs&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  MAT without a window
&lt;/h2&gt;

&lt;p&gt;MAT also has a batch mode, useful on a server with no screen: it&lt;br&gt;
analyzes the dump and writes the reports as HTML. The screenshots of&lt;br&gt;
this post come from this mode:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;ParseHeapDump.sh /tmp/cache.hprof org.eclipse.mat.api:suspects
ParseHeapDump.sh /tmp/cache.hprof -command=dominator_tree org.eclipse.mat.api:query
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The first one writes &lt;code&gt;cache_Leak_Suspects.zip&lt;/code&gt;, the second one&lt;br&gt;
&lt;code&gt;cache_Query.zip&lt;/code&gt;. The full commands, with the path to GC roots, are in&lt;br&gt;
the README of the &lt;code&gt;heap-dump&lt;/code&gt; folder. Remember to delete the dump and the&lt;br&gt;
index files that MAT writes next to it.&lt;/p&gt;

&lt;p&gt;Tested with Java 25 (Temurin 25.0.4) and Eclipse MAT 1.17, on macOS; the&lt;br&gt;
fix also with Java 11, 17 and 21.&lt;/p&gt;

&lt;p&gt;Sources: the Eclipse MAT help&lt;br&gt;
(&lt;a href="https://help.eclipse.org/latest/topic/org.eclipse.mat.ui.help/concepts/shallowretainedheap.html" rel="noopener noreferrer"&gt;Shallow vs. Retained Heap&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://help.eclipse.org/latest/topic/org.eclipse.mat.ui.help/concepts/dominatortree.html" rel="noopener noreferrer"&gt;Dominator Tree&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://help.eclipse.org/latest/topic/org.eclipse.mat.ui.help/concepts/gcroots.html" rel="noopener noreferrer"&gt;Garbage Collection Roots&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://help.eclipse.org/latest/topic/org.eclipse.mat.ui.help/tasks/batch.html" rel="noopener noreferrer"&gt;Batch mode&lt;/a&gt;),&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/troubleshoot/troubleshooting-memory-leaks.html" rel="noopener noreferrer"&gt;Oracle's troubleshooting guide on memory leaks&lt;/a&gt;&lt;br&gt;
and the &lt;a href="https://docs.oracle.com/en/java/javase/25/docs/specs/man/jcmd.html" rel="noopener noreferrer"&gt;documentation of &lt;code&gt;jcmd&lt;/code&gt;&lt;/a&gt;&lt;br&gt;
(JDK 25).&lt;/p&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-memory-leaks/" rel="noopener noreferrer"&gt;Java memory leaks: 6 classic cases, reproduced&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;Java OutOfMemoryError: every message, reproduced&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/read-java-gc-log/" rel="noopener noreferrer"&gt;Reading a Java GC log: every number explained&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-garbage-collector-guide/" rel="noopener noreferrer"&gt;The Java garbage collector: an up-to-date guide (Java 25)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>java</category>
      <category>jvm</category>
      <category>debugging</category>
      <category>tooling</category>
    </item>
    <item>
      <title>Java memory leaks: 6 classic cases, reproduced</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Thu, 22 Oct 2026 23:05:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/java-memory-leaks-6-classic-cases-reproduced-mb7</link>
      <guid>https://dev.to/aymenjamaaoui/java-memory-leaks-6-classic-cases-reproduced-mb7</guid>
      <description>&lt;p&gt;In Java, the garbage collector frees the objects that nothing&lt;br&gt;
references anymore. So a memory leak is an object that is no longer&lt;br&gt;
useful but still referenced: the GC cannot free it. Oracle's guide puts&lt;br&gt;
it this way: the application keeps references to objects&lt;br&gt;
"unintentionally".&lt;/p&gt;

&lt;p&gt;Here are six classic leaks, each one reproduced by a small program of&lt;br&gt;
the public repository&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/tree/level-2/leaks" rel="noopener noreferrer"&gt;java-gc-lab&lt;/a&gt;,&lt;br&gt;
with what you see and the fix.&lt;/p&gt;
&lt;h2&gt;
  
  
  What keeps an object alive
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-memory-leaks/" rel="noopener noreferrer"&gt;See the diagram in the original post.&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The GC starts from "roots": the static fields of the loaded classes,&lt;br&gt;
the local variables of the running threads… Every object that can be&lt;br&gt;
reached from a root stays alive. A leak is a path that someone forgot&lt;br&gt;
to cut.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Case&lt;/th&gt;
&lt;th&gt;What keeps the object&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Static collection&lt;/td&gt;
&lt;td&gt;a &lt;code&gt;static&lt;/code&gt; field&lt;/td&gt;
&lt;td&gt;remove the elements, or do not keep them there&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cache with no limit&lt;/td&gt;
&lt;td&gt;the map of the cache&lt;/td&gt;
&lt;td&gt;a maximum size or an expiry&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Listeners&lt;/td&gt;
&lt;td&gt;the list of listeners of the event bus&lt;/td&gt;
&lt;td&gt;remove the listener&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;ThreadLocal&lt;/code&gt; in a pool&lt;/td&gt;
&lt;td&gt;the pool thread, which never stops&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;remove()&lt;/code&gt; at the end of the task&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Class loaders&lt;/td&gt;
&lt;td&gt;one object of the old version&lt;/td&gt;
&lt;td&gt;release every reference to the old version&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Resources not closed&lt;/td&gt;
&lt;td&gt;nothing… but the file stays open&lt;/td&gt;
&lt;td&gt;&lt;code&gt;try-with-resources&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;
&lt;h2&gt;
  
  
  How to see a leak
&lt;/h2&gt;

&lt;p&gt;The first sign: the heap after each GC goes up from one GC to the next.&lt;br&gt;
It is explained with real logs in&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;the post about OutOfMemoryError&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;To know &lt;strong&gt;which object&lt;/strong&gt; leaks, take two class histograms, a few&lt;br&gt;
seconds or minutes apart, on the running application:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;jcmd &amp;lt;pid&amp;gt; GC.class_histogram | head
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The class whose number of instances goes up is the leak. Be careful:&lt;br&gt;
this command runs a full GC first, so avoid it under heavy load on a&lt;br&gt;
sensitive production system. Each program of &lt;code&gt;java-gc-lab&lt;/code&gt; leaks&lt;br&gt;
slowly (about 30 seconds) and prints its process id, to give you time&lt;br&gt;
to do it.&lt;/p&gt;

&lt;p&gt;To find out next &lt;strong&gt;what holds&lt;/strong&gt; these objects, you need a heap dump:&lt;br&gt;
see &lt;a href="https://aymenjamaaoui.dev/en/blog/java-heap-dump-eclipse-mat/" rel="noopener noreferrer"&gt;the analysis with Eclipse MAT&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  The six cases
&lt;/h2&gt;
&lt;h3&gt;
  
  
  1. A static collection
&lt;/h3&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="kt"&gt;List&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Order&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="no"&gt;AUDIT&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ArrayList&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// on each request:&lt;/span&gt;
&lt;span class="no"&gt;AUDIT&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Order&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;A &lt;code&gt;static&lt;/code&gt; field lives as long as its class, and so does the whole&lt;br&gt;
list. The histogram, after 5 s and then after 20 s:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;  48:           368           5888  StaticCollection$Order
  19:          1584          25344  StaticCollection$Order
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Fix: remove the elements when they are no longer needed, or do not&lt;br&gt;
keep them in a static collection.&lt;/p&gt;
&lt;h3&gt;
  
  
  2. A cache with no limit
&lt;/h3&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kd"&gt;final&lt;/span&gt; &lt;span class="kt"&gt;Map&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;String&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Report&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="no"&gt;CACHE&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;HashMap&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// a new key on each request: the cache only grows&lt;/span&gt;
&lt;span class="no"&gt;CACHE&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;put&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;requestId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Report&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;  48:           378           6048  UnboundedCache$Report
  19:          1592          25472  UnboundedCache$Report
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;Fix: a maximum size. With the JDK alone, a &lt;code&gt;LinkedHashMap&lt;/code&gt; that&lt;br&gt;
overrides &lt;code&gt;removeEldestEntry&lt;/code&gt; removes the oldest entry when the size&lt;br&gt;
goes over a maximum; its javadoc gives it as an example for a cache.&lt;/p&gt;
&lt;h3&gt;
  
  
  3. Listeners never removed
&lt;/h3&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nc"&gt;Screen&lt;/span&gt; &lt;span class="n"&gt;screen&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Screen&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="no"&gt;BUS&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;register&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;screen&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// the screen is closed, but never removed from the bus&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;  48:           375           6000  Listeners$Screen
  19:          1592          25472  Listeners$Screen
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;The event bus lives for a long time, and it keeps every screen. Fix:&lt;br&gt;
remove the listener when the screen is closed.&lt;/p&gt;
&lt;h3&gt;
  
  
  4. A ThreadLocal in a thread pool
&lt;/h3&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="n"&gt;pool&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;submit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="no"&gt;BUFFER&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Record&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="c1"&gt;// no BUFFER.remove()&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;  48:           376           6016  ThreadLocalInPool$Record
  20:          1585          25360  ThreadLocalInPool$Record
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;According to the javadoc, each thread keeps its copy of a&lt;br&gt;
&lt;code&gt;ThreadLocal&lt;/code&gt; as long as it is alive. The threads of a pool never stop:&lt;br&gt;
their buffers grow without end. Fix: &lt;code&gt;BUFFER.remove()&lt;/code&gt; at the end of&lt;br&gt;
each task, in a &lt;code&gt;finally&lt;/code&gt;.&lt;/p&gt;
&lt;h3&gt;
  
  
  5. Class loaders
&lt;/h3&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nc"&gt;ClassLoader&lt;/span&gt; &lt;span class="n"&gt;loader&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;ClassLoader&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;parent&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="no"&gt;PLUGINS&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Proxy&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;newProxyInstance&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;loader&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;interfaces&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;handler&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;Each "reload" of a plugin creates a class loader and a new class. The&lt;br&gt;
list keeps one object of each version, so no old class loader can be&lt;br&gt;
freed. Here the heap grows little: the Metaspace grows.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;jcmd &amp;lt;pid&amp;gt; VM.metaspace | grep "Total Usage"
Total Usage - 393 loaders, 3538 classes (1261 shared):
Total Usage - 1515 loaders, 4661 classes (1261 shared):
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With a limit, it ends with &lt;code&gt;OutOfMemoryError: Metaspace&lt;/code&gt; (see&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;the post about OutOfMemoryError&lt;/a&gt;).&lt;br&gt;
Fix: release every reference to the old version (objects, classes,&lt;br&gt;
threads, listeners) before a reload.&lt;/p&gt;
&lt;h3&gt;
  
  
  6. Resources not closed
&lt;/h3&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight java"&gt;&lt;code&gt;&lt;span class="nc"&gt;FileInputStream&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;FileInputStream&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;file&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;in&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;read&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// no close()&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;This case is different. The stream is not kept anywhere, so it is not a&lt;br&gt;
heap leak: in my tests, when a GC runs, the JDK closes the files of the&lt;br&gt;
streams it frees (&lt;code&gt;jcmd &amp;lt;pid&amp;gt; GC.run&lt;/code&gt;: from about 830 open files to&lt;br&gt;
about 90). But this program creates almost no garbage: no GC runs, and&lt;br&gt;
the open files pile up (&lt;code&gt;lsof&lt;/code&gt;: about 400 after 5 s, 2,000 after&lt;br&gt;
25 s). With a limit of 512 open files (in Docker):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java.io.FileNotFoundException: /tmp/java-gc-lab8035917117579278064.txt (Too many open files)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The heap is fine, and yet the application fails. Fix:&lt;br&gt;
&lt;code&gt;try-with-resources&lt;/code&gt;. The javadoc of &lt;code&gt;AutoCloseable&lt;/code&gt; says it: it&lt;br&gt;
ensures a prompt release and avoids running out of resources.&lt;/p&gt;

&lt;h2&gt;
  
  
  Avoiding leaks
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;In code reviews&lt;/strong&gt;, look for &lt;code&gt;static&lt;/code&gt; fields that hold collections,
collections with no maximum size, &lt;code&gt;register&lt;/code&gt; without &lt;code&gt;unregister&lt;/code&gt;,
&lt;code&gt;ThreadLocal&lt;/code&gt; without &lt;code&gt;remove()&lt;/code&gt;, streams opened outside a
&lt;code&gt;try-with-resources&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Set a limit&lt;/strong&gt; on everything that grows: caches, queues, buffers.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Weak references&lt;/strong&gt;: a &lt;code&gt;WeakHashMap&lt;/code&gt; removes an entry when its key is
no longer used elsewhere. A trap noted in the javadoc: if the value
refers to its own key, the entry never goes away.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Watch&lt;/strong&gt; the heap after GC in production: a slow leak shows over
hours, not over one minute.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Tested with Java 8 (compiling, and the file case), 11, 17, 21 and 25&lt;br&gt;
(Temurin 11.0.32, 17.0.20, 21.0.9, 25.0.4), on macOS; the file case&lt;br&gt;
also in Docker (&lt;code&gt;eclipse-temurin:8&lt;/code&gt; and &lt;code&gt;:25&lt;/code&gt;).&lt;/p&gt;

&lt;p&gt;Sources:&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/troubleshoot/troubleshooting-memory-leaks.html" rel="noopener noreferrer"&gt;Oracle's troubleshooting guide on memory leaks&lt;/a&gt;,&lt;br&gt;
the &lt;a href="https://docs.oracle.com/en/java/javase/25/docs/specs/man/jcmd.html" rel="noopener noreferrer"&gt;documentation of &lt;code&gt;jcmd&lt;/code&gt;&lt;/a&gt;,&lt;br&gt;
and the JDK 25 javadoc of&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/ThreadLocal.html" rel="noopener noreferrer"&gt;&lt;code&gt;ThreadLocal&lt;/code&gt;&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/LinkedHashMap.html" rel="noopener noreferrer"&gt;&lt;code&gt;LinkedHashMap&lt;/code&gt;&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/WeakHashMap.html" rel="noopener noreferrer"&gt;&lt;code&gt;WeakHashMap&lt;/code&gt;&lt;/a&gt;&lt;br&gt;
and &lt;a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/AutoCloseable.html" rel="noopener noreferrer"&gt;&lt;code&gt;AutoCloseable&lt;/code&gt;&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-heap-dump-eclipse-mat/" rel="noopener noreferrer"&gt;Java heap dump: find a memory leak with Eclipse MAT&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;Java OutOfMemoryError: every message, reproduced&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/read-java-gc-log/" rel="noopener noreferrer"&gt;Reading a Java GC log: every number explained&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-garbage-collector-myths/" rel="noopener noreferrer"&gt;Common myths about the Java garbage collector&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-garbage-collector-guide/" rel="noopener noreferrer"&gt;The Java garbage collector: an up-to-date guide (Java 25)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>java</category>
      <category>jvm</category>
      <category>debugging</category>
      <category>performance</category>
    </item>
    <item>
      <title>Reading a Java GC log: every number explained</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Thu, 22 Oct 2026 21:40:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/reading-a-java-gc-log-every-number-explained-2kn4</link>
      <guid>https://dev.to/aymenjamaaoui/reading-a-java-gc-log-every-number-explained-2kn4</guid>
      <description>&lt;p&gt;Turning on the GC log is easy. Reading it is harder: one G1 line holds&lt;br&gt;
about ten pieces of information, and the words change from one Java&lt;br&gt;
version to the next.&lt;/p&gt;

&lt;p&gt;This post reads real lines, written by three small programs of the&lt;br&gt;
public repository&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/tree/level-2/gc-logs" rel="noopener noreferrer"&gt;java-gc-lab&lt;/a&gt;:&lt;br&gt;
a normal load, very big objects, and a heap that is almost full.&lt;/p&gt;
&lt;h2&gt;
  
  
  Turn on the log
&lt;/h2&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -Xlog:gc*:file=gc.log:time,uptime,level,tags -jar app.jar
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;gc*&lt;/code&gt;: all the GC messages (&lt;code&gt;gc&lt;/code&gt; alone gives one line per GC);&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;file=gc.log&lt;/code&gt;: in a file, with rotation built in (5 files of about
20 MB by default);&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;time,uptime,level,tags&lt;/code&gt;: the "decorations" at the start of each
line: the date and time, the time since the JVM started, the level and
the tags. If you set nothing, the JVM uses &lt;code&gt;uptime&lt;/code&gt;, &lt;code&gt;level&lt;/code&gt; and
&lt;code&gt;tags&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A pause line, with these decorations:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;[2026-10-22T23:23:46.842+0200][0.356s][info][gc          ] GC(1) Pause Young (Normal) (G1 Evacuation Pause) 117M-&amp;gt;24M(256M) 1.660ms
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The exact time (&lt;code&gt;time&lt;/code&gt;) helps to link a pause to an event of the&lt;br&gt;
application, for example a slow request in another log.&lt;/p&gt;
&lt;h2&gt;
  
  
  One line, word by word
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/read-java-gc-log/" rel="noopener noreferrer"&gt;See the diagram in the original post.&lt;/a&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Part&lt;/th&gt;
&lt;th&gt;Meaning&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;[0.469s]&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the time since the JVM started (&lt;code&gt;uptime&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GC(1)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the number of the GC: all the lines of one GC have the same one&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Pause Young (Normal)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the type of pause: here a normal young pause. You also see &lt;code&gt;Concurrent Start&lt;/code&gt;, &lt;code&gt;Prepare Mixed&lt;/code&gt;, &lt;code&gt;Mixed&lt;/code&gt;, &lt;code&gt;Remark&lt;/code&gt;, &lt;code&gt;Cleanup&lt;/code&gt; and &lt;code&gt;Full&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;(G1 Evacuation Pause)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the cause of the GC, here the usual one. Other causes: &lt;code&gt;G1 Humongous Allocation&lt;/code&gt;, &lt;code&gt;System.gc()&lt;/code&gt;, &lt;code&gt;G1 Compaction Pause&lt;/code&gt; (full GC)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;117M-&amp;gt;23M(256M)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the heap used before the GC, after the GC, and the heap size&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;5.790ms&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the length of the pause: the application is stopped during this time&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The words young, mixed and full are explained in&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/gc-generations-cycles-young-old-minor-major-full/" rel="noopener noreferrer"&gt;the post about generations&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  The 4 numbers to follow
&lt;/h2&gt;

&lt;p&gt;Here are the start and the end of the log (another run than the line&lt;br&gt;
above, so the numbers change a little) of&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/blob/level-2/gc-logs/NormalLoad.java" rel="noopener noreferrer"&gt;NormalLoad.java&lt;/a&gt;,&lt;br&gt;
an application that keeps about 16 MB of data and creates short-lived&lt;br&gt;
objects all the time:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -Xmx256m -Xlog:gc gc-logs/NormalLoad.java
[0.341s][info][gc] GC(0) Pause Young (Normal) (G1 Evacuation Pause) 47M-&amp;gt;18M(256M) 3.090ms
[0.469s][info][gc] GC(1) Pause Young (Normal) (G1 Evacuation Pause) 117M-&amp;gt;23M(256M) 5.790ms
[0.646s][info][gc] GC(2) Pause Young (Normal) (G1 Evacuation Pause) 149M-&amp;gt;24M(256M) 4.129ms
…
[3.240s][info][gc] GC(15) Pause Young (Normal) (G1 Evacuation Pause) 171M-&amp;gt;24M(256M) 0.635ms
[3.478s][info][gc] GC(16) Pause Young (Normal) (G1 Evacuation Pause) 171M-&amp;gt;24M(256M) 12.874ms
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;The GC rate&lt;/strong&gt;: 17 GCs in a little more than 3 seconds, about 5 per
second. It goes up when the application creates more objects, or
when the heap is too small.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The pause time&lt;/strong&gt;: from 0.4 to 12.9 ms here. Look at the longest
ones first: they are the ones that users feel.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The heap after the GC&lt;/strong&gt;: 23 to 24 MB, stable. It is roughly the
size of the live data. If it goes up from one GC to the next, it is a
leak (see
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;the post about OutOfMemoryError&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The allocation rate&lt;/strong&gt;: the heap before a GC, minus the heap after
the previous GC, divided by the time between them. Between GC(0) and
GC(1): (117 − 18) MB in 0.128 s, so about 770 MB/s. No line gives it
directly: you have to compute it.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Warning signs
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Humongous objects
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -Xmx256m -Xlog:gc gc-logs/Humongous.java
[0.306s][info][gc] GC(0) Pause Young (Concurrent Start) (G1 Humongous Allocation) 146M-&amp;gt;9M(256M) 1.583ms
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For G1, a "humongous" object is at least half a region. It does not go&lt;br&gt;
through eden: it gets its own regions, directly in the old generation.&lt;br&gt;
Here the program creates 2 MB arrays with 1 MB regions&lt;br&gt;
(&lt;code&gt;Heap Region Size: 1M&lt;/code&gt; at startup with &lt;code&gt;-Xlog:gc*&lt;/code&gt;), and the&lt;br&gt;
allocation itself starts the GC. Many &lt;code&gt;G1 Humongous Allocation&lt;/code&gt; lines&lt;br&gt;
point to big arrays or big buffers created often.&lt;/p&gt;

&lt;h3&gt;
  
  
  An evacuation failure, then Pause Full
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -Xmx64m -Xlog:gc gc-logs/NearTheLimit.java
[0.295s][info][gc] GC(5) Pause Young (Prepare Mixed) (G1 Evacuation Pause) (Evacuation Failure: Allocation) 61M-&amp;gt;47M(64M) 0.250ms
[1.348s][info][gc] GC(175) Pause Full (G1 Compaction Pause) 62M-&amp;gt;45M(64M) 5.691ms
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The program keeps about 30 MB of data, plus one 2 MB array every ten&lt;br&gt;
rounds (12 MB at the end), in a 64 MB heap: this is most of the 45 MB&lt;br&gt;
that the full GC leaves. G1 no longer&lt;br&gt;
finds enough room to copy the live objects: this is an evacuation&lt;br&gt;
failure. The reason is &lt;code&gt;Allocation&lt;/code&gt; (no room) or &lt;code&gt;Pinned&lt;/code&gt; (an object&lt;br&gt;
held in place by native code). In the worst case, if a GC frees nothing at all, G1 starts&lt;br&gt;
a full GC, which compacts the whole heap and can be very slow.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Before Java 18:&lt;/strong&gt; the evacuation failure was called&lt;br&gt;
&lt;code&gt;to-space exhausted&lt;/code&gt;. On Java 11 and 17, it was a separate line&lt;br&gt;
(&lt;code&gt;GC(7) To-space exhausted&lt;/code&gt;); on Java 8, the end of the pause line.&lt;br&gt;
Since Java 18 (&lt;a href="https://bugs.openjdk.org/browse/JDK-8269022" rel="noopener noreferrer"&gt;JDK-8269022&lt;/a&gt;),&lt;br&gt;
the pause line writes &lt;code&gt;(Evacuation Failure)&lt;/code&gt; (seen on Java 21 in my&lt;br&gt;
tests), and Java 25 adds the reason.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;A &lt;code&gt;Pause Full&lt;/code&gt; line with G1, when it does not come from &lt;code&gt;System.gc()&lt;/code&gt;,&lt;br&gt;
is always worth a look: the heap is too small for the live data, or&lt;br&gt;
there is &lt;a href="https://aymenjamaaoui.dev/en/blog/java-memory-leaks/" rel="noopener noreferrer"&gt;a leak&lt;/a&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Pauses that get longer
&lt;/h3&gt;

&lt;p&gt;If the last number of the lines goes up over the hours, with the same&lt;br&gt;
type of pause, the GC has more and more work: more live data to copy,&lt;br&gt;
or a heap that fills up. Follow it closely.&lt;/p&gt;

&lt;h2&gt;
  
  
  The tools
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;JFR&lt;/strong&gt; (Java Flight Recorder), in the JDK: start it with
&lt;code&gt;-XX:StartFlightRecording&lt;/code&gt;, and read the recording with
&lt;a href="https://www.oracle.com/java/technologies/jdk-mission-control.html" rel="noopener noreferrer"&gt;JDK Mission Control&lt;/a&gt;.
It shows the GC pauses with the rest of the application. More details
in &lt;a href="https://aymenjamaaoui.dev/en/blog/java-tools-jfr-jcmd-visualvm/" rel="noopener noreferrer"&gt;the post about tools&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Third-party tools also read the log files and draw charts, for
example GCeasy (an online service) or GCViewer (open source).&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What has changed
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What you still read&lt;/th&gt;
&lt;th&gt;What is true today&lt;/th&gt;
&lt;th&gt;Since&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;-XX:+PrintGCDetails&lt;/code&gt;, &lt;code&gt;-Xloggc:gc.log&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;-Xlog:gc*&lt;/code&gt;, &lt;code&gt;-Xlog:gc*:file=gc.log&lt;/code&gt; (the old options are deprecated or refused, see &lt;a href="https://aymenjamaaoui.dev/en/blog/jvm-options-that-matter/" rel="noopener noreferrer"&gt;the JVM options&lt;/a&gt;)&lt;/td&gt;
&lt;td&gt;Java 9&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;to-space exhausted&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;Evacuation Failure&lt;/code&gt;, then &lt;code&gt;Evacuation Failure: &amp;lt;reason&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Java 18 (JDK-8269022), the reason on Java 25 in my tests&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;-XX:+PrintGCDateStamps&lt;/code&gt; to get the time&lt;/td&gt;
&lt;td&gt;the &lt;code&gt;time&lt;/code&gt; decoration of &lt;code&gt;-Xlog&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Java 9&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Tested with Java 8 (Corretto 8u504), 11, 17, 21 and 25 (Temurin&lt;br&gt;
11.0.32, 17.0.20, 21.0.9, 25.0.4), on macOS, with G1.&lt;/p&gt;

&lt;p&gt;Sources: the &lt;a href="https://docs.oracle.com/en/java/javase/25/docs/specs/man/java.html" rel="noopener noreferrer"&gt;documentation of the &lt;code&gt;java&lt;/code&gt; command&lt;/a&gt;&lt;br&gt;
(JDK 25, &lt;code&gt;-Xlog&lt;/code&gt;), the&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/gctuning/garbage-first-g1-garbage-collector1.html" rel="noopener noreferrer"&gt;G1 chapter of Oracle's GC guide&lt;/a&gt;&lt;br&gt;
(humongous objects, evacuation failure, full GC),&lt;br&gt;
&lt;a href="https://bugs.openjdk.org/browse/JDK-8269022" rel="noopener noreferrer"&gt;JDK-8269022&lt;/a&gt; (the new name&lt;br&gt;
of the evacuation failure).&lt;/p&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/gc-generations-cycles-young-old-minor-major-full/" rel="noopener noreferrer"&gt;GC generations and cycles: young, old, minor, major, full&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;Java OutOfMemoryError: every message, reproduced&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/jvm-options-that-matter/" rel="noopener noreferrer"&gt;JVM options that matter, and the ones that no longer work&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-garbage-collector-guide/" rel="noopener noreferrer"&gt;The Java garbage collector: an up-to-date guide (Java 25)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>java</category>
      <category>jvm</category>
      <category>debugging</category>
      <category>monitoring</category>
    </item>
    <item>
      <title>Java OutOfMemoryError: every message, reproduced</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Thu, 22 Oct 2026 20:40:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/java-outofmemoryerror-every-message-reproduced-d20</link>
      <guid>https://dev.to/aymenjamaaoui/java-outofmemoryerror-every-message-reproduced-d20</guid>
      <description>&lt;p&gt;An &lt;code&gt;OutOfMemoryError&lt;/code&gt; is not one single problem. The text after the&lt;br&gt;
colon tells you which memory area is full: the heap, the Metaspace,&lt;br&gt;
the direct memory or the threads. And each area is checked and fixed&lt;br&gt;
in a different way.&lt;/p&gt;

&lt;p&gt;For each message, I wrote a small program that causes it. They are in&lt;br&gt;
the public repository&lt;br&gt;
&lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/tree/level-2/oom" rel="noopener noreferrer"&gt;java-gc-lab&lt;/a&gt;,&lt;br&gt;
one file per message, to run with &lt;code&gt;java&lt;/code&gt; without compiling first (Java&lt;br&gt;
11 or later; on Java 8, compile them with &lt;code&gt;javac&lt;/code&gt; first).&lt;/p&gt;
&lt;h2&gt;
  
  
  The message tells you which area is full
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;See the diagram in the original post.&lt;/a&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Message&lt;/th&gt;
&lt;th&gt;Full area&lt;/th&gt;
&lt;th&gt;First check&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Java heap space&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the heap&lt;/td&gt;
&lt;td&gt;the heap after each GC (&lt;code&gt;-Xlog:gc*&lt;/code&gt;, &lt;code&gt;jcmd &amp;lt;pid&amp;gt; GC.heap_info&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GC overhead limit exceeded&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the heap, almost full all the time&lt;/td&gt;
&lt;td&gt;the same: the GC runs nonstop&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Metaspace&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the class metadata&lt;/td&gt;
&lt;td&gt;&lt;code&gt;jcmd &amp;lt;pid&amp;gt; VM.metaspace&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Cannot reserve … bytes of direct buffer memory&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the direct memory&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;-XX:MaxDirectMemorySize&lt;/code&gt;, &lt;code&gt;jcmd &amp;lt;pid&amp;gt; VM.native_memory&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;unable to create native thread&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;the threads of the system&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;jcmd &amp;lt;pid&amp;gt; Thread.print&lt;/code&gt;, the system limits&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;
&lt;h2&gt;
  
  
  Java heap space
&lt;/h2&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -Xmx64m oom/HeapSpace.java
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java.lang.OutOfMemoryError: Java heap space
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;The program keeps 1 MB arrays in a list: the GC cannot free anything,&lt;br&gt;
and the 64 MB heap is full in less than a second.&lt;/p&gt;

&lt;p&gt;Oracle's guide is clear: this message does not always mean a memory&lt;br&gt;
leak. The heap can simply be too small for the application. But in an&lt;br&gt;
application that runs for a long time, it is often the sign that it&lt;br&gt;
keeps references to objects without meaning to.&lt;/p&gt;

&lt;p&gt;To know which one it is, look at the heap &lt;strong&gt;after&lt;/strong&gt; each GC: with&lt;br&gt;
&lt;code&gt;-Xlog:gc*&lt;/code&gt;, or with &lt;code&gt;jcmd &amp;lt;pid&amp;gt; GC.heap_info&lt;/code&gt; on a running&lt;br&gt;
application. If it always goes back to the same level, the heap is just&lt;br&gt;
too small. If it goes up from one GC to the next, something keeps the&lt;br&gt;
objects.&lt;/p&gt;
&lt;h2&gt;
  
  
  GC overhead limit exceeded
&lt;/h2&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -Xmx32m -XX:+UseParallelGC oom/GcOverhead.java
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java.lang.OutOfMemoryError: GC overhead limit exceeded
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;Here, the heap fills up slowly, with small objects. The GC runs&lt;br&gt;
nonstop and frees almost nothing. The JVM then prefers to stop rather&lt;br&gt;
than go on without making progress: according to the docs, it throws&lt;br&gt;
this error if more than 98% of the time goes to the GC and less than 2%&lt;br&gt;
of the heap is recovered, for five GCs in a row.&lt;/p&gt;

&lt;p&gt;This message is not guaranteed. With the same program and the Parallel&lt;br&gt;
GC, here is what I get:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;code&gt;-Xmx&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;Java 8&lt;/th&gt;
&lt;th&gt;Java 11&lt;/th&gt;
&lt;th&gt;Java 17&lt;/th&gt;
&lt;th&gt;Java 21&lt;/th&gt;
&lt;th&gt;Java 25&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;16m&lt;/td&gt;
&lt;td&gt;GC overhead&lt;/td&gt;
&lt;td&gt;Java heap space&lt;/td&gt;
&lt;td&gt;Java heap space&lt;/td&gt;
&lt;td&gt;Java heap space&lt;/td&gt;
&lt;td&gt;Java heap space&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;32m&lt;/td&gt;
&lt;td&gt;no error after 60 s&lt;/td&gt;
&lt;td&gt;GC overhead&lt;/td&gt;
&lt;td&gt;GC overhead&lt;/td&gt;
&lt;td&gt;GC overhead&lt;/td&gt;
&lt;td&gt;no error after 60 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;128m&lt;/td&gt;
&lt;td&gt;no error after 60 s&lt;/td&gt;
&lt;td&gt;GC overhead&lt;/td&gt;
&lt;td&gt;GC overhead&lt;/td&gt;
&lt;td&gt;GC overhead&lt;/td&gt;
&lt;td&gt;Java heap space&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;"No error after 60 s" is the worst case: the JVM spends its time in the&lt;br&gt;
GC and the application does nothing, with no error.&lt;/p&gt;

&lt;p&gt;For a long time, only Parallel threw this error. G1, the default GC,&lt;br&gt;
has it too since Java 26, with a backport in Java 25.0.3&lt;br&gt;
(&lt;a href="https://bugs.openjdk.org/browse/JDK-8212084" rel="noopener noreferrer"&gt;JDK-8212084&lt;/a&gt;). But in my&lt;br&gt;
tests with G1 on Java 25.0.4, from &lt;code&gt;-Xmx16m&lt;/code&gt; to &lt;code&gt;-Xmx256m&lt;/code&gt;, I always&lt;br&gt;
get &lt;code&gt;Java heap space&lt;/code&gt;. According to the guide, the usual cause is the&lt;br&gt;
same: live data that barely fits in the heap.&lt;/p&gt;
&lt;h2&gt;
  
  
  Metaspace
&lt;/h2&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -XX:MaxMetaspaceSize=32m oom/MetaspaceFull.java
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java.lang.OutOfMemoryError: Metaspace
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;The Metaspace holds the class metadata, in native memory. The program&lt;br&gt;
creates a new class loader and a new class in it, again and again;&lt;br&gt;
since it keeps them, nothing can be unloaded.&lt;/p&gt;

&lt;p&gt;By default, the Metaspace has no limit. If a limit is set with&lt;br&gt;
&lt;code&gt;-XX:MaxMetaspaceSize&lt;/code&gt;, the guide advises to raise it. If the Metaspace&lt;br&gt;
keeps growing (&lt;code&gt;jcmd &amp;lt;pid&amp;gt; VM.metaspace&lt;/code&gt;), the problem is more likely&lt;br&gt;
classes that cannot be unloaded, as in this program.&lt;/p&gt;
&lt;h2&gt;
  
  
  Direct buffer memory
&lt;/h2&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -XX:MaxDirectMemorySize=32m oom/DirectBuffer.java
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java.lang.OutOfMemoryError: Cannot reserve 1048576 bytes of direct buffer memory (allocated: 32514048, limit: 33554432)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;Direct buffers (&lt;code&gt;ByteBuffer.allocateDirect&lt;/code&gt;) live outside the heap.&lt;br&gt;
Their limit is &lt;code&gt;-XX:MaxDirectMemorySize&lt;/code&gt;; without this option, the JVM&lt;br&gt;
chooses it.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Before Java 17:&lt;/strong&gt; on Java 8 and 11, the message was just&lt;br&gt;
&lt;code&gt;Direct buffer memory&lt;/code&gt;. Since Java 17, in my tests, it gives the size&lt;br&gt;
asked for, the memory already taken and the limit, which helps a lot.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;To see this memory on a running application:&lt;br&gt;
&lt;code&gt;-XX:NativeMemoryTracking=summary&lt;/code&gt; at startup, then&lt;br&gt;
&lt;code&gt;jcmd &amp;lt;pid&amp;gt; VM.native_memory&lt;/code&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  Unable to create native thread
&lt;/h2&gt;

&lt;p&gt;This program starts threads until the system says no. Do not run it on&lt;br&gt;
your machine without a limit: I ran it in a container limited to 200&lt;br&gt;
processes.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;docker run --rm --pids-limit 200 -v "$PWD/oom":/oom eclipse-temurin:25 java /oom/NativeThreads.java
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java.lang.OutOfMemoryError: unable to create native thread: possibly out of memory or process/resource limits reached
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Before Java 11:&lt;/strong&gt; on Java 8, the message was&lt;br&gt;
&lt;code&gt;unable to create new native thread&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Each thread started with &lt;code&gt;new Thread&lt;/code&gt; is a thread of the operating&lt;br&gt;
system, with its own stack outside the heap. So the cause is a limit of&lt;br&gt;
the system (number of processes or threads, memory), or an application&lt;br&gt;
that creates threads without end, for example a pool with no maximum&lt;br&gt;
size. &lt;code&gt;jcmd &amp;lt;pid&amp;gt; Thread.print&lt;/code&gt; shows all the threads, with their stack&lt;br&gt;
traces. Raising &lt;code&gt;-Xmx&lt;/code&gt; does not change a system limit.&lt;/p&gt;
&lt;h2&gt;
  
  
  The method, whatever the message
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Read the message&lt;/strong&gt;: it tells you which area is full (table at the
top).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Get a heap dump&lt;/strong&gt;: with &lt;code&gt;-XX:+HeapDumpOnOutOfMemoryError&lt;/code&gt;, the JVM
writes an &lt;code&gt;.hprof&lt;/code&gt; file. In my tests, it is written for
&lt;code&gt;Java heap space&lt;/code&gt;, &lt;code&gt;GC overhead limit exceeded&lt;/code&gt; and &lt;code&gt;Metaspace&lt;/code&gt;, but
not for direct buffers. &lt;code&gt;-XX:HeapDumpPath&lt;/code&gt; sets where it is written.
Keep some disk space free: the file can be several GB.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Look at &lt;a href="https://aymenjamaaoui.dev/en/blog/read-java-gc-log/" rel="noopener noreferrer"&gt;the heap after each GC&lt;/a&gt;&lt;/strong&gt; over time, and above all
after mixed or full GCs (a young GC does not clean the old
generation): stable, the heap is too small; if it keeps going up, it
is a leak (see below).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Fix&lt;/strong&gt;: give more room to the right area, or find what keeps the
objects.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;
  
  
  Heap too small, or a leak?
&lt;/h3&gt;

&lt;p&gt;With &lt;code&gt;-Xlog:gc&lt;/code&gt;, each GC writes one line. The number that matters is&lt;br&gt;
the one &lt;strong&gt;after the arrow&lt;/strong&gt;: the heap after the GC, so roughly the data&lt;br&gt;
that is still alive.&lt;/p&gt;

&lt;p&gt;With &lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/blob/level-2/oom/SteadyLoad.java" rel="noopener noreferrer"&gt;SteadyLoad.java&lt;/a&gt;,&lt;br&gt;
the live data does not change. After each GC, the heap goes back to the&lt;br&gt;
same level:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -Xmx64m -Xlog:gc oom/SteadyLoad.java
GC(2) Pause Young (Normal) (G1 Evacuation Pause) 41M-&amp;gt;24M(64M) 0.379ms
GC(5) Pause Young (Normal) (G1 Evacuation Pause) 47M-&amp;gt;24M(64M) 0.538ms
GC(9) Pause Young (Normal) (G1 Evacuation Pause) 54M-&amp;gt;24M(64M) 0.624ms
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With &lt;a href="https://gitlab.com/aymenjamaaoui/java-gc-lab/-/blob/level-2/oom/SlowLeak.java" rel="noopener noreferrer"&gt;SlowLeak.java&lt;/a&gt;,&lt;br&gt;
the program keeps 1 MB more in each round. After each GC, the heap goes&lt;br&gt;
up, until &lt;code&gt;Java heap space&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;java -Xmx64m -Xlog:gc oom/SlowLeak.java
GC(1) Pause Young (Normal) (G1 Evacuation Pause) 30M-&amp;gt;5M(64M) 2.292ms
GC(4) Pause Young (Normal) (G1 Evacuation Pause) 42M-&amp;gt;11M(64M) 0.916ms
GC(8) Pause Young (Normal) (G1 Evacuation Pause) 50M-&amp;gt;19M(64M) 0.938ms
GC(12) Pause Young (Normal) (G1 Evacuation Pause) 54M-&amp;gt;29M(64M) 1.283ms
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On an application that is already running, without a restart,&lt;br&gt;
&lt;code&gt;jstat -gcutil &amp;lt;pid&amp;gt; 1s&lt;/code&gt; prints the use of each area every second: in&lt;br&gt;
the second case, the &lt;code&gt;O&lt;/code&gt; column (the old generation, in %) goes up the&lt;br&gt;
same way. Its docs say that it is experimental and unsupported.&lt;/p&gt;

&lt;p&gt;Raising &lt;a href="https://aymenjamaaoui.dev/en/blog/jvm-options-that-matter/" rel="noopener noreferrer"&gt;&lt;code&gt;-Xmx&lt;/code&gt;&lt;/a&gt; is not a mistake in itself: it is even the first action&lt;br&gt;
that Oracle's guide gives for &lt;code&gt;Java heap space&lt;/code&gt;. The mistake is to&lt;br&gt;
raise it again and again when the heap goes up after each GC: the leak&lt;br&gt;
is still there, it just takes longer to fill the heap.&lt;/p&gt;

&lt;h2&gt;
  
  
  What has changed
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What you still read&lt;/th&gt;
&lt;th&gt;What is true today&lt;/th&gt;
&lt;th&gt;Since&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OutOfMemoryError: Direct buffer memory&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Cannot reserve … bytes of direct buffer memory (allocated: …, limit: …)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Java 17 in my tests (11 still had the old one)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;unable to create new native thread&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;unable to create native thread: possibly out of memory or process/resource limits reached&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Java 11 in my tests (8 had the old one)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;GC overhead limit exceeded&lt;/code&gt; comes only from Parallel&lt;/td&gt;
&lt;td&gt;G1 can throw it too&lt;/td&gt;
&lt;td&gt;Java 26, and Java 25.0.3 as a backport&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PermGen space&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Metaspace&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Java 8&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Tested with Java 8 (Corretto 8u504), 11, 17, 21 and 25 (Temurin&lt;br&gt;
11.0.32, 17.0.20, 21.0.9, 25.0.4), on macOS; the thread case in Docker&lt;br&gt;
(&lt;code&gt;eclipse-temurin&lt;/code&gt;).&lt;/p&gt;

&lt;p&gt;Sources:&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/troubleshoot/troubleshooting-memory-leaks.html" rel="noopener noreferrer"&gt;Oracle's troubleshooting guide on memory leaks&lt;/a&gt;,&lt;br&gt;
the documentation of the&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/docs/specs/man/java.html" rel="noopener noreferrer"&gt;&lt;code&gt;java&lt;/code&gt;&lt;/a&gt;,&lt;br&gt;
&lt;a href="https://docs.oracle.com/en/java/javase/25/docs/specs/man/jcmd.html" rel="noopener noreferrer"&gt;&lt;code&gt;jcmd&lt;/code&gt;&lt;/a&gt;&lt;br&gt;
and &lt;a href="https://docs.oracle.com/en/java/javase/25/docs/specs/man/jstat.html" rel="noopener noreferrer"&gt;&lt;code&gt;jstat&lt;/code&gt;&lt;/a&gt;&lt;br&gt;
commands (JDK 25), &lt;a href="https://bugs.openjdk.org/browse/JDK-8212084" rel="noopener noreferrer"&gt;JDK-8212084&lt;/a&gt;&lt;br&gt;
(G1 and the overhead limit).&lt;/p&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/jvm-memory-heap-stack-metaspace/" rel="noopener noreferrer"&gt;JVM memory: heap, stack and Metaspace&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/jvm-options-that-matter/" rel="noopener noreferrer"&gt;JVM options that matter, and the ones that no longer work&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-garbage-collector-guide/" rel="noopener noreferrer"&gt;The Java garbage collector: an up-to-date guide (Java 25)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>java</category>
      <category>jvm</category>
      <category>debugging</category>
      <category>performance</category>
    </item>
    <item>
      <title>The Java garbage collector: an up-to-date guide (Java 25)</title>
      <dc:creator>Aymen Jamaaoui</dc:creator>
      <pubDate>Thu, 22 Oct 2026 14:40:00 +0000</pubDate>
      <link>https://dev.to/aymenjamaaoui/the-java-garbage-collector-an-up-to-date-guide-java-25-1370</link>
      <guid>https://dev.to/aymenjamaaoui/the-java-garbage-collector-an-up-to-date-guide-java-25-1370</guid>
      <description>&lt;p&gt;There are many posts about the Java garbage collector, and many of them&lt;br&gt;
are old: PermGen, CMS, &lt;code&gt;-XX:+PrintGCDetails&lt;/code&gt;… This guide sums up what is&lt;br&gt;
true in &lt;strong&gt;Java 25&lt;/strong&gt;, in a few lines per topic. Each part links to a&lt;br&gt;
longer post, where every fact is checked in the official documentation&lt;br&gt;
or on a real JVM.&lt;/p&gt;

&lt;p&gt;I update this guide when the series moves on, or when a new Java version&lt;br&gt;
changes the rules.&lt;/p&gt;

&lt;h2&gt;
  
  
  JVM memory
&lt;/h2&gt;

&lt;p&gt;The JVM keeps its data in several areas:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;the &lt;strong&gt;stack&lt;/strong&gt;: one per thread, with one &lt;em&gt;frame&lt;/em&gt; per method call
(parameters, local variables). It is freed by itself, without the GC.
Too many nested calls give a &lt;code&gt;StackOverflowError&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;the &lt;strong&gt;heap&lt;/strong&gt;: the objects created with &lt;code&gt;new&lt;/code&gt;, shared by all threads.
This is the area of the garbage collector. Its maximum size is set
with &lt;code&gt;-Xmx&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;the &lt;strong&gt;Metaspace&lt;/strong&gt;: the description of the classes, in native memory,
outside the heap. It replaced PermGen in Java 8.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The JVM also uses native memory for thread stacks, the code compiled by&lt;br&gt;
the JIT, direct buffers and its own internal data. &lt;code&gt;-Xmx&lt;/code&gt; only limits&lt;br&gt;
the heap: the Java process always uses more.&lt;/p&gt;

&lt;p&gt;→ &lt;a href="https://aymenjamaaoui.dev/en/blog/jvm-memory-heap-stack-metaspace/" rel="noopener noreferrer"&gt;JVM memory: heap, stack and Metaspace&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Generations and cycles
&lt;/h2&gt;

&lt;p&gt;Most objects die young. So the JVM keeps recent objects in the &lt;strong&gt;young&lt;br&gt;
generation&lt;/strong&gt; (eden and two survivor spaces) and long-lived ones in the&lt;br&gt;
&lt;strong&gt;old generation&lt;/strong&gt;:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://aymenjamaaoui.dev/en/blog/java-garbage-collector-guide/" rel="noopener noreferrer"&gt;See the diagram in the original post.&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;An object is born in eden, moves from one survivor space to the other at&lt;br&gt;
each GC, and is then promoted to the old generation after a number of&lt;br&gt;
copies (15 at most by default).&lt;/p&gt;

&lt;p&gt;In Oracle's guide, a &lt;strong&gt;minor collection&lt;/strong&gt; cleans only the young&lt;br&gt;
generation, and a &lt;strong&gt;major collection&lt;/strong&gt; cleans the whole heap. G1, the&lt;br&gt;
default GC, does not use these words in its logs: it talks about Young,&lt;br&gt;
Mixed and Full pauses. And it splits the heap into &lt;strong&gt;regions&lt;/strong&gt; of the&lt;br&gt;
same size, instead of two big blocks.&lt;/p&gt;

&lt;p&gt;→ &lt;a href="https://aymenjamaaoui.dev/en/blog/gc-generations-cycles-young-old-minor-major-full/" rel="noopener noreferrer"&gt;GC generations and cycles: young, old, minor, major, full&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The garbage collectors
&lt;/h2&gt;

&lt;p&gt;Java 25 offers several GCs, each one for a need:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;G1&lt;/strong&gt;, the default GC since Java 9: when response time matters more
than throughput;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;ZGC&lt;/strong&gt; (generational: its only mode since Java 24) and &lt;strong&gt;Shenandoah&lt;/strong&gt;:
very short pauses, for latency;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Parallel&lt;/strong&gt;: throughput first;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Serial&lt;/strong&gt;: a single thread, for small machines;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Epsilon&lt;/strong&gt;: never frees anything, for tests.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;CMS is gone since Java 14. Also watch the automatic choice: on a machine&lt;br&gt;
with a single processor or less than 1792 MB of memory, the JVM picks&lt;br&gt;
Serial instead of G1. So a small container can run with a different GC&lt;br&gt;
than the developer's machine. To check it: &lt;code&gt;-Xlog:gc&lt;/code&gt; writes the GC in&lt;br&gt;
use on its first line (&lt;code&gt;Using G1&lt;/code&gt;).&lt;/p&gt;

&lt;p&gt;→ &lt;a href="https://aymenjamaaoui.dev/en/blog/java-garbage-collectors-2026/" rel="noopener noreferrer"&gt;Java garbage collectors in 2026: which one is running yours?&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Useful options
&lt;/h2&gt;

&lt;p&gt;A few options are enough in most cases:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;-Xms&lt;/code&gt; and &lt;code&gt;-Xmx&lt;/code&gt;: the initial and maximum heap size, often the same
value on a server;&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;-Xlog:gc*:file=gc.log&lt;/code&gt;: GC logs to a file, with rotation built in;&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;-XX:+HeapDumpOnOutOfMemoryError&lt;/code&gt; and &lt;code&gt;-XX:HeapDumpPath&lt;/code&gt;: a heap dump
when the heap is full;&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;-XX:MaxRAMPercentage&lt;/code&gt;: the maximum heap as a percentage of memory
(25% by default), useful in a container.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Many old options no longer work. Some are only deprecated: the JVM keeps&lt;br&gt;
&lt;code&gt;-XX:+PrintGCDetails&lt;/code&gt; and &lt;code&gt;-Xloggc&lt;/code&gt; as aliases of &lt;code&gt;-Xlog&lt;/code&gt;, with a&lt;br&gt;
warning. Others stop the JVM at startup in Java 17, 21 and 25: &lt;code&gt;-XX:MaxPermSize&lt;/code&gt;, &lt;code&gt;-XX:+UseConcMarkSweepGC&lt;/code&gt;,&lt;br&gt;
&lt;code&gt;-XX:+PrintGCDateStamps&lt;/code&gt;… To test a configuration, just run&lt;br&gt;
&lt;code&gt;java &amp;lt;options&amp;gt; -version&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;→ &lt;a href="https://aymenjamaaoui.dev/en/blog/jvm-options-that-matter/" rel="noopener noreferrer"&gt;JVM options that matter, and the ones that no longer work&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Common myths
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;System.gc()&lt;/code&gt; is only a request. But with G1, Parallel and Serial, it
usually starts a full GC, which is expensive.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;finalize()&lt;/code&gt; is deprecated for removal: use try-with-resources or
&lt;code&gt;Cleaner&lt;/code&gt; instead.&lt;/li&gt;
&lt;li&gt;More heap often helps, as long as it fits in the memory of the machine
or the container.&lt;/li&gt;
&lt;li&gt;Tuning the GC is not the first thing to do: G1 with its default
settings, then the logs, then the application.&lt;/li&gt;
&lt;li&gt;The GC does not prevent memory leaks: an object that is still
referenced is never freed.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;→ &lt;a href="https://aymenjamaaoui.dev/en/blog/java-garbage-collector-myths/" rel="noopener noreferrer"&gt;Common myths about the Java garbage collector&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  What is the difference between the heap and the stack?
&lt;/h3&gt;

&lt;p&gt;The stack belongs to one thread: it holds the local variables and is&lt;br&gt;
emptied when the method ends. The heap is shared by all threads: it&lt;br&gt;
holds the objects, and the GC cleans it. A local variable of an object&lt;br&gt;
type is on the stack, but the object itself is in the heap.&lt;/p&gt;

&lt;h3&gt;
  
  
  What is the default GC in Java 25?
&lt;/h3&gt;

&lt;p&gt;G1, on a "server-class" machine: at least two processors and at least&lt;br&gt;
1792 MB of memory. Otherwise, the JVM picks Serial.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can I force the GC?
&lt;/h3&gt;

&lt;p&gt;No. &lt;code&gt;System.gc()&lt;/code&gt; is a request, with no guarantee. With G1, Parallel and&lt;br&gt;
Serial, it usually gives a full GC. With &lt;code&gt;-XX:+DisableExplicitGC&lt;/code&gt;, the&lt;br&gt;
JVM ignores these calls.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does my application freeze for a moment?
&lt;/h3&gt;

&lt;p&gt;GC pauses are one possible cause, not the only one. To find out, look at&lt;br&gt;
the GC logs (&lt;code&gt;-Xlog:gc*&lt;/code&gt;): each pause is written there with its&lt;br&gt;
duration. With G1, a &lt;code&gt;Pause Full&lt;/code&gt; that does not come from &lt;code&gt;System.gc()&lt;/code&gt;&lt;br&gt;
is a sign that the heap is too full, and the docs warn that it can be&lt;br&gt;
very slow. According to this guide, Full GCs that keep coming back mean&lt;br&gt;
that the application allocates more objects than G1 can reclaim in&lt;br&gt;
time: often, concurrent marking does not finish early enough, and many&lt;br&gt;
humongous (very large) objects make it worse. The guide's options: a&lt;br&gt;
bigger heap, fewer humongous objects, or starting marking earlier. And&lt;br&gt;
if the heap stays full after each GC, look for&lt;br&gt;
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-memory-leaks/" rel="noopener noreferrer"&gt;a memory leak&lt;/a&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Which GC for a Spring Boot application?
&lt;/h3&gt;

&lt;p&gt;Spring Boot does not choose the GC: the JVM does, with the same rules as&lt;br&gt;
for any Java application. A Spring Boot 3.5 application on Java 25&lt;br&gt;
starts with G1, and with Serial if the JVM sees only one processor.&lt;br&gt;
Start with G1 and its default settings, and check the GC in use with&lt;br&gt;
&lt;code&gt;-Xlog:gc&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What comes next in the series
&lt;/h2&gt;

&lt;p&gt;This guide covers the basics. To go further, the posts already out:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;understand and diagnose&lt;/strong&gt;:
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-outofmemoryerror-messages/" rel="noopener noreferrer"&gt;the kinds of &lt;code&gt;OutOfMemoryError&lt;/code&gt;&lt;/a&gt;,
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-memory-leaks/" rel="noopener noreferrer"&gt;memory leaks&lt;/a&gt;, &lt;a href="https://aymenjamaaoui.dev/en/blog/read-java-gc-log/" rel="noopener noreferrer"&gt;reading GC logs&lt;/a&gt;, &lt;a href="https://aymenjamaaoui.dev/en/blog/java-tools-jfr-jcmd-visualvm/" rel="noopener noreferrer"&gt;the tools (JFR, jcmd, VisualVM)&lt;/a&gt; and
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-heap-dump-eclipse-mat/" rel="noopener noreferrer"&gt;heap dump analysis&lt;/a&gt;;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;measure and tune&lt;/strong&gt;:
&lt;a href="https://aymenjamaaoui.dev/en/blog/java-docker-kubernetes-oomkilled/" rel="noopener noreferrer"&gt;Java in Docker and Kubernetes&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Coming next: off-heap memory, G1 or ZGC with measures, tuning a Spring&lt;br&gt;
Boot and Kafka service, and the GC with virtual threads. These posts will&lt;br&gt;
be added to this guide when they come out.&lt;/p&gt;

</description>
      <category>java</category>
      <category>jvm</category>
      <category>performance</category>
      <category>tutorial</category>
    </item>
  </channel>
</rss>
