<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Java on Vitalii Sukach</title><link>https://vitaliisukach.dev/tags/java/</link><description>Recent content in Java on Vitalii Sukach</description><generator>Hugo</generator><language>en-us</language><lastBuildDate>Sun, 15 Nov 2026 10:00:00 +0000</lastBuildDate><atom:link href="https://vitaliisukach.dev/tags/java/index.xml" rel="self" type="application/rss+xml"/><item><title>Your AI Assistant Is Just Another Team That Ignores Your Bounded Context</title><link>https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/</link><pubDate>Sun, 15 Nov 2026 10:00:00 +0000</pubDate><guid>https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/</guid><description>AI assistants cross DDD boundaries like a new team that never read the design docs. Make the domain explicit for the AI, then enforce it with tests.</description><content:encoded><![CDATA[<p><img alt="A cheerful robot with a &ldquo;New team – Day 1&rdquo; badge breaks through the wall of a garden labelled &ldquo;Loyalty&rdquo;, carrying a glowing jar of points and dropping coins behind it. It ignores the open gate nearby with the sign &ldquo;LoyaltyService – please use this entrance&rdquo;, and an unread AGENTS.md scroll lies on the ground. Two surprised developers with coffee mugs watch." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/image-01.jpg"></p>
<blockquote>
<p><strong>TL;DR</strong></p>
<ul>
<li>An AI assistant takes the shortest path through your code, and that path usually crosses a boundary.</li>
<li>It sees code, not intent. If the rules live in people&rsquo;s heads, the AI can&rsquo;t follow them.</li>
<li>Write the bounded context down in an <code>AGENTS.md</code> next to the code: language, invariants, public API, forbidden dependencies.</li>
<li>Prompts are suggestions, tests are guarantees. Enforce the boundary with ArchUnit.</li>
</ul></blockquote>
<h2 id="the-ai-wrote-a-feature-that-works-and-breaks-four-rules">The AI wrote a feature that works and breaks four rules</h2>
<p>The ticket was simple: &ldquo;Customers get 2x loyalty points on their birthday.&rdquo; An AI assistant opened the checkout module, found the loyalty repository, and produced this:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">CheckoutService</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">OrderRepository</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">LoyaltyAccountRepository</span><span class="w"> </span><span class="n">loyaltyAccountRepository</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// constructor omitted</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">completeCheckout</span><span class="p">(</span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="p">,</span><span class="w"> </span><span class="n">Customer</span><span class="w"> </span><span class="n">customer</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">order</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="n">account</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">loyaltyAccountRepository</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="p">.</span><span class="na">findByCustomerId</span><span class="p">(</span><span class="n">customer</span><span class="p">.</span><span class="na">getId</span><span class="p">()).</span><span class="na">orElseThrow</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="kt">long</span><span class="w"> </span><span class="n">points</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">order</span><span class="p">.</span><span class="na">getTotal</span><span class="p">().</span><span class="na">longValue</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">MonthDay</span><span class="p">.</span><span class="na">from</span><span class="p">(</span><span class="n">customer</span><span class="p">.</span><span class="na">getBirthday</span><span class="p">()).</span><span class="na">equals</span><span class="p">(</span><span class="n">MonthDay</span><span class="p">.</span><span class="na">now</span><span class="p">()))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">points</span><span class="w"> </span><span class="o">*=</span><span class="w"> </span><span class="n">2</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">account</span><span class="p">.</span><span class="na">setBalance</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">points</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">loyaltyAccountRepository</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">account</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>It compiles. The tests pass. The feature works in the demo. Here is what it breaks:</p>
<ul>
<li><strong>Checkout reaches into Loyalty&rsquo;s persistence.</strong> <code>LoyaltyAccountRepository</code> is an internal detail of another context.</li>
<li><strong>Points before payment.</strong> The order is saved, not paid. A failed card still earns points.</li>
<li><strong>Checkout changes the balance itself.</strong> Calling <code>setBalance()</code> from checkout skips every rule <code>LoyaltyService</code> is supposed to enforce.</li>
<li><strong>No event.</strong> <code>PointsEarned</code> is never published, so the email service and analytics never hear about it.</li>
</ul>
<p><img alt="Diagram: CheckoutService in the Checkout context has two paths into the Loyalty context. The intended path goes to LoyaltyService, the public API that returns DTOs. The AI&rsquo;s shortcut, marked with a red cross, goes straight to the hidden LoyaltyAccountRepository and LoyaltyAccount. The rules it breaks: uses another context&rsquo;s repository, points before payment, sets the balance directly, publishes no event." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-shortcut.jpg"></p>
<p>None of this is new. A team that joined last month and never read the design docs would write the same code, for the same reason: nobody told them where the boundary was.</p>
<h2 id="why-the-ai-crosses-the-line">Why the AI crosses the line</h2>
<p><strong>The shortest path wins.</strong> The assistant is asked to make a feature work. A repository that&rsquo;s already on the classpath is the shortest path to a working feature. Nothing in the code says &ldquo;don&rsquo;t.&rdquo;</p>
<p><strong>It sees code, not intent.</strong> Your bounded contexts exist in a whiteboard photo, a Confluence page and the heads of three senior engineers. The AI reads <code>src/main/java</code>. If a public setter exists, the AI reads that as permission to call it.</p>
<p><strong>There is no ubiquitous language in the prompt.</strong> &ldquo;Add birthday points at checkout&rdquo; puts the rule in checkout. A domain expert would say &ldquo;Loyalty awards double points for orders paid on the customer&rsquo;s birthday.&rdquo; Same feature, different owner.</p>
<p>This is exactly how a new team behaves when it joins without onboarding. We already know the fix for that team. It works for the AI too.</p>
<h2 id="step-1-ask-the-ai-to-discover-the-domain-first">Step 1: Ask the AI to discover the domain first</h2>
<p>Before writing rules, find out what the code already says. Use the AI as a reader, not a writer.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Read the packages under com.shop.domain.loyalty.
</span></span><span class="line"><span class="cl">Build a glossary of the domain terms you find: class names, method
</span></span><span class="line"><span class="cl">names, enum values, event names. For each term give a one-line
</span></span><span class="line"><span class="cl">definition based only on the code. Mark terms that mean different
</span></span><span class="line"><span class="cl">things in different places, and terms that look like technical
</span></span><span class="line"><span class="cl">names rather than business language (e.g. &#34;updateRecord&#34;).
</span></span><span class="line"><span class="cl">Do not suggest changes yet.
</span></span></code></pre></div><p>Then look for the leaks:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">List every class outside com.shop.domain.loyalty that imports a
</span></span><span class="line"><span class="cl">Loyalty entity or repository, or reads/writes the loyalty_account
</span></span><span class="line"><span class="cl">table through a repository, JdbcTemplate or native query.
</span></span><span class="line"><span class="cl">Calls to LoyaltyService that only get DTOs back are fine. Skip them.
</span></span><span class="line"><span class="cl">For each one, show the file, the line, and whether it reads or
</span></span><span class="line"><span class="cl">writes. Group the results by calling module.
</span></span></code></pre></div><p>The second list is your boundary violations. Controllers and app-layer services that call <code>LoyaltyService</code> and get DTOs back are not on it, because that&rsquo;s the intended way in. The list is often longer than expected. Each entry is either a missing public API or a missing event.</p>
<h2 id="step-2-write-the-context-down-where-the-ai-will-read-it">Step 2: Write the context down where the AI will read it</h2>
<p>Put an <code>AGENTS.md</code> in the Loyalty domain package, <code>com/shop/domain/loyalty/</code>. It&rsquo;s a shared convention: Codex, Cursor, GitHub Copilot, Gemini CLI and other assistants read it when they work in that directory. Keep it short and specific.</p>
<p>Recent versions of Claude Code read <code>AGENTS.md</code> too, but only when the project has no <code>CLAUDE.md</code>. If your repo already has one, Claude skips <code>AGENTS.md</code> by default. Don&rsquo;t copy the rules into a second file, because two copies drift apart. Add a <code>CLAUDE.md</code> next to <code>AGENTS.md</code> that imports it:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="ni">@AGENTS</span>.md
</span></span></code></pre></div><p>Now every assistant on the team reads the same rules, and you maintain them in one place.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="gh"># Loyalty context
</span></span></span><span class="line"><span class="cl"><span class="gh"></span>Purpose: award and redeem points. Loyalty owns the balance. Nobody else writes it.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Language
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">-</span> Points: whole, non-negative amount. Never &#34;credits&#34; or &#34;bonus&#34;.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Earn: add points for a paid order. Redeem: spend points at checkout.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Earning rule: how many points an order is worth (base rate, birthday 2x).
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Invariants
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">1.</span> balance &gt;= 0, always.
</span></span><span class="line"><span class="cl"><span class="k">2.</span> Points are earned only for paid orders. Only com.shop.listener calls earnForPaidOrder().
</span></span><span class="line"><span class="cl"><span class="k">3.</span> Only LoyaltyService changes a LoyaltyAccount. The entity holds data, no logic.
</span></span><span class="line"><span class="cl"><span class="k">4.</span> Every state change publishes an event in the same transaction.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Public API
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">-</span> LoyaltyService: balanceOf(CustomerId), redeem(CustomerId, Points),
</span></span><span class="line"><span class="cl">  earnForPaidOrder(...) (listeners only). Returns DTOs, never entities.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Events out: PointsEarned, PointsRedeemed.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Loyalty doesn&#39;t listen to other domains. App-layer listeners call its service.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Forbidden
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">-</span> Code outside domain/loyalty using its entity or repository packages.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Loyalty using other domains&#39; entities or repositories. Use their service or events.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Writing loyalty tables from SQL, scripts or admin tools.
</span></span></code></pre></div><p>Two things matter here. The language section gives the AI the words to use in names and commits. The forbidden section names the shortcuts you&rsquo;ve already seen it take.</p>
<p>A real system has more than one context. Don&rsquo;t put them all in one file. Give each domain package its own <code>AGENTS.md</code>, and keep a short context map at the root:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">src/main/java/com/shop/
</span></span><span class="line"><span class="cl">├── AGENTS.md          ← context map: one line per domain + global rules
</span></span><span class="line"><span class="cl">├── controller/        ← REST controllers
</span></span><span class="line"><span class="cl">├── service/           ← use cases that combine several domains
</span></span><span class="line"><span class="cl">├── dto/               ← request/response DTOs for the frontend
</span></span><span class="line"><span class="cl">├── listener/          ← event listeners that connect domains
</span></span><span class="line"><span class="cl">├── common/            ← shared kernel: Money, CustomerId, OrderId
</span></span><span class="line"><span class="cl">└── domain/
</span></span><span class="line"><span class="cl">    ├── loyalty/
</span></span><span class="line"><span class="cl">    │   ├── AGENTS.md  ← Loyalty only
</span></span><span class="line"><span class="cl">    │   ├── service/   ← LoyaltyService: the only entry point
</span></span><span class="line"><span class="cl">    │   ├── dto/       ← what the service returns, plus events
</span></span><span class="line"><span class="cl">    │   ├── entity/    ← LoyaltyAccount (hidden)
</span></span><span class="line"><span class="cl">    │   └── repository/ ← hidden
</span></span><span class="line"><span class="cl">    ├── ordering/      ← same shape, own AGENTS.md
</span></span><span class="line"><span class="cl">    └── customer/      ← same shape, own AGENTS.md
</span></span></code></pre></div><p>The top-level packages are a thin application layer. When the frontend needs a balance plus order details on one page, a top-level service calls <code>LoyaltyService</code> and <code>OrderService</code> and builds the response DTO. When one domain&rsquo;s event should trigger work in another, a listener in <code>listener/</code> connects them. Neither layer ever injects a domain&rsquo;s repository.</p>
<p><img alt="Diagram: the application layer in com.shop contains controller/, service/, dto/ and listener/. Arrows point down into the domains in com.shop.domain: loyalty/, ordering/ and customer/. Each domain has public service/ and dto/ packages and hidden entity/ and repository/ packages. ArchUnit enforces that nothing outside a domain touches its entity/ or repository/, and that no domain depends on the application layer." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-layers.jpg"></p>
<p>The root file says what each domain owns and how others use it: its service or its events. Global rules go here too: domains never depend on the top-level packages, and a domain&rsquo;s service returns DTOs, never entities. Each domain file covers only its own language, invariants and dependencies.</p>
<p>Domains still need some shared language. <code>earnForPaidOrder()</code> takes <code>Money</code>, <code>CustomerId</code> and <code>OrderId</code>, and Ordering uses the same types. These live in <code>common/</code>, which DDD calls a shared kernel: a small set of types every domain may use.</p>
<p>Keep it to immutable value records like these, with validation and no business logic. No entities, services or frontend DTOs belong there. Every team depends on it, so a change to <code>common/</code> needs every team&rsquo;s agreement.</p>
<p>Say this in the root <code>AGENTS.md</code>; without that rule, an assistant will start moving anything that two domains need into <code>common/</code>.</p>
<p>This split matters for three reasons. Assistants load a nested file only when they work in that folder, so a change to Checkout doesn&rsquo;t pull in fifteen other contexts. Each context keeps its own vocabulary, so &ldquo;Account&rdquo; in Loyalty never gets mixed up with &ldquo;Account&rdquo; in Billing. And each team owns its file.</p>
<p>If you use Claude Code and your repo already has a <code>CLAUDE.md</code>, repeat the trick from above in every domain: put a one-line <code>CLAUDE.md</code> with <code>@AGENTS.md</code> next to each domain&rsquo;s <code>AGENTS.md</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">domain/
</span></span><span class="line"><span class="cl">├── loyalty/
</span></span><span class="line"><span class="cl">│   ├── AGENTS.md
</span></span><span class="line"><span class="cl">│   └── CLAUDE.md      ← contains only: @AGENTS.md
</span></span><span class="line"><span class="cl">└── ordering/
</span></span><span class="line"><span class="cl">    ├── AGENTS.md
</span></span><span class="line"><span class="cl">    └── CLAUDE.md      ← contains only: @AGENTS.md
</span></span></code></pre></div><p>It&rsquo;s tempting to import every domain&rsquo;s <code>AGENTS.md</code> from the root <code>CLAUDE.md</code> instead. Don&rsquo;t. Claude Code loads the root file and everything it imports at the start of every session, so every context&rsquo;s rules would be loaded all the time. A <code>CLAUDE.md</code> inside a domain folder is loaded only when Claude works on files in that folder.</p>
<h2 id="step-3-make-the-ai-work-inside-the-context">Step 3: Make the AI work inside the context</h2>
<p>Now rewrite the feature request. Point it at the context and ask it to reason about invariants before it writes code.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Read com/shop/domain/loyalty/AGENTS.md first.
</span></span><span class="line"><span class="cl">Feature: Loyalty awards double points for orders paid on the
</span></span><span class="line"><span class="cl">customer&#39;s birthday.
</span></span><span class="line"><span class="cl">Before writing code:
</span></span><span class="line"><span class="cl">1. Say which bounded context owns this rule and why.
</span></span><span class="line"><span class="cl">2. List every invariant from AGENTS.md this change touches.
</span></span><span class="line"><span class="cl">3. List the classes you plan to change. Flag any outside
</span></span><span class="line"><span class="cl">   domain/loyalty.
</span></span><span class="line"><span class="cl">Wait for my confirmation. Then implement it inside the
</span></span><span class="line"><span class="cl">LoyaltyService with unit tests for each invariant.
</span></span></code></pre></div><p>The &ldquo;wait for confirmation&rdquo; step is where you catch a wrong plan. It costs one message instead of a code review.</p>
<p>The entity only holds data:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">LoyaltyAccount</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="c1">// com.shop.domain.loyalty.entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">MonthDay</span><span class="w"> </span><span class="n">birthday</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Points</span><span class="w"> </span><span class="n">balance</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// getters and setters, no logic</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p><code>Points</code> is a record that rejects negative values in its constructor, so <code>balance &gt;= 0</code> holds no matter who sets the balance.</p>
<p>The rules live in <code>LoyaltyService</code>. It&rsquo;s the only class that changes a <code>LoyaltyAccount</code>, and every change publishes an event in the same transaction:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">LoyaltyService</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="c1">// com.shop.domain.loyalty.service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">LoyaltyAccountRepository</span><span class="w"> </span><span class="n">accounts</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ApplicationEventPublisher</span><span class="w"> </span><span class="n">events</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// constructor and balanceOf() omitted</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">earnForPaidOrder</span><span class="p">(</span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">OrderId</span><span class="w"> </span><span class="n">orderId</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                                 </span><span class="n">Money</span><span class="w"> </span><span class="n">paidAmount</span><span class="p">,</span><span class="w"> </span><span class="n">LocalDate</span><span class="w"> </span><span class="n">paidOn</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="n">account</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">load</span><span class="p">(</span><span class="n">customerId</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Points</span><span class="w"> </span><span class="n">earned</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Points</span><span class="p">.</span><span class="na">forAmount</span><span class="p">(</span><span class="n">paidAmount</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">MonthDay</span><span class="p">.</span><span class="na">from</span><span class="p">(</span><span class="n">paidOn</span><span class="p">).</span><span class="na">equals</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBirthday</span><span class="p">()))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">earned</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">earned</span><span class="p">.</span><span class="na">times</span><span class="p">(</span><span class="n">2</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">account</span><span class="p">.</span><span class="na">setBalance</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">().</span><span class="na">plus</span><span class="p">(</span><span class="n">earned</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">accounts</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">account</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">events</span><span class="p">.</span><span class="na">publishEvent</span><span class="p">(</span><span class="k">new</span><span class="w"> </span><span class="n">PointsEarned</span><span class="p">(</span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">orderId</span><span class="p">,</span><span class="w"> </span><span class="n">earned</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">public</span><span class="w"> </span><span class="n">PointsDto</span><span class="w"> </span><span class="nf">redeem</span><span class="p">(</span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">Points</span><span class="w"> </span><span class="n">points</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="n">account</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">load</span><span class="p">(</span><span class="n">customerId</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">().</span><span class="na">isLessThan</span><span class="p">(</span><span class="n">points</span><span class="p">))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="k">throw</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">InsufficientPointsException</span><span class="p">(</span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">points</span><span class="p">,</span><span class="w"> </span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">account</span><span class="p">.</span><span class="na">setBalance</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">().</span><span class="na">minus</span><span class="p">(</span><span class="n">points</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">accounts</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">account</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">events</span><span class="p">.</span><span class="na">publishEvent</span><span class="p">(</span><span class="k">new</span><span class="w"> </span><span class="n">PointsRedeemed</span><span class="p">(</span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">points</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">PointsDto</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="nf">load</span><span class="p">(</span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="n">accounts</span><span class="p">.</span><span class="na">findByCustomerId</span><span class="p">(</span><span class="n">customerId</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="p">.</span><span class="na">orElseThrow</span><span class="p">(()</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">LoyaltyAccountNotFoundException</span><span class="p">(</span><span class="n">customerId</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>The setters are public, so in principle anyone could call them. Two things stop that: the entity package is closed to code outside Loyalty, and inside Loyalty only <code>LoyaltyService</code> may call the setters. Step 5 turns both into tests.</p>
<p>The balance change and the event are in one transaction. Listeners annotated with <code>@TransactionalEventListener</code> run only after that transaction commits, so a rolled-back change never sends an event.</p>
<p>Neither domain knows about the other. Ordering publishes <code>OrderPaid</code> without knowing who listens. Loyalty exposes <code>earnForPaidOrder()</code> without knowing where paid orders come from. The rule that links them, &ldquo;a paid order earns points&rdquo;, lives in the application layer, in a listener that combines the two domains. It translates the event into a call and does nothing else:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Component</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">class</span> <span class="nc">OrderPaidListener</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="c1">// com.shop.listener</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">LoyaltyService</span><span class="w"> </span><span class="n">loyalty</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">OrderPaidListener</span><span class="p">(</span><span class="n">LoyaltyService</span><span class="w"> </span><span class="n">loyalty</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">this</span><span class="p">.</span><span class="na">loyalty</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">loyalty</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@TransactionalEventListener</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="p">(</span><span class="n">propagation</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Propagation</span><span class="p">.</span><span class="na">REQUIRES_NEW</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">void</span><span class="w"> </span><span class="nf">on</span><span class="p">(</span><span class="n">OrderPaid</span><span class="w"> </span><span class="n">event</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">loyalty</span><span class="p">.</span><span class="na">earnForPaidOrder</span><span class="p">(</span><span class="n">event</span><span class="p">.</span><span class="na">customerId</span><span class="p">(),</span><span class="w"> </span><span class="n">event</span><span class="p">.</span><span class="na">orderId</span><span class="p">(),</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="n">event</span><span class="p">.</span><span class="na">amount</span><span class="p">(),</span><span class="w"> </span><span class="n">event</span><span class="p">.</span><span class="na">paidOn</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Checkout doesn&rsquo;t know Loyalty exists. A failed payment never produces <code>OrderPaid</code>, so it never produces points.</p>
<p><img alt="Diagram: OrderService in Ordering commits a successful payment and publishes OrderPaid after commit. OrderPaidListener in com.shop.listener receives it and calls LoyaltyService, which loads the account, doubles the points on the customer&rsquo;s birthday, updates the balance, saves, and publishes PointsEarned to email and analytics. A failed payment rolls back, so there is no OrderPaid and no points." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-event-flow.jpg"></p>
<p><code>earnForPaidOrder()</code> has to be public so the listener can call it. That also means a controller could call it and award points without a paid order. Step 5 closes that gap with a test.</p>
<h2 id="step-4-review-in-a-fresh-session">Step 4: Review in a fresh session</h2>
<p>Don&rsquo;t ask the session that wrote the code to review it. It has the same blind spots it had five minutes ago. Open a new session, give it the rules and the diff, and nothing else.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">You are reviewing a change to the Loyalty bounded context.
</span></span><span class="line"><span class="cl">Read com/shop/domain/loyalty/AGENTS.md, then run: git diff main...HEAD
</span></span><span class="line"><span class="cl">For each invariant and each &#34;Forbidden&#34; rule in AGENTS.md,
</span></span><span class="line"><span class="cl">answer: kept, broken, or not affected. For &#34;broken&#34;, quote the
</span></span><span class="line"><span class="cl">line. Then list any new terms in names or comments that are not
</span></span><span class="line"><span class="cl">in the Language section. Do not comment on style.
</span></span></code></pre></div><p>A reviewer with a checklist finds more than a reviewer with a vibe. That&rsquo;s true for people and for models.</p>
<h2 id="step-5-enforce-the-boundary-with-tests">Step 5: Enforce the boundary with tests</h2>
<p>Everything so far makes a good outcome more likely. None of it makes a bad outcome impossible. The next prompt, the next model or the next tired developer can still call <code>loyaltyAccountRepository</code> from checkout.</p>
<p><img alt="Diagram: five steps rising like stairs. Steps 1 to 4 are prompts, which are suggestions: Discover (glossary and leak list), Write it down (AGENTS.md per domain), Plan first (invariants before code), Fresh review (checklist from AGENTS.md). Step 5, Enforce (ArchUnit tests in the build), is the only guarantee. An arrow runs from &ldquo;a good outcome is more likely&rdquo; to &ldquo;a bad outcome fails the build&rdquo;." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-guardrails.jpg"></p>
<p>Prompts are suggestions, tests are guarantees. Turn the forbidden section of <code>AGENTS.md</code> into ArchUnit rules:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@AnalyzeClasses</span><span class="p">(</span><span class="n">packages</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;com.shop&#34;</span><span class="p">,</span><span class="w"> </span><span class="n">importOptions</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ImportOption</span><span class="p">.</span><span class="na">DoNotIncludeTests</span><span class="p">.</span><span class="na">class</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">class</span> <span class="nc">LoyaltyBoundaryTest</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">internalsStayInside</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">classes</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">resideInAnyPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain.loyalty.entity..&#34;</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                            </span><span class="s">&#34;com.shop.domain.loyalty.repository..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">onlyBeAccessed</span><span class="p">().</span><span class="na">byClassesThat</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain.loyalty..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;domain/loyalty/AGENTS.md: use LoyaltyService&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">onlyServiceChangesAccount</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">methods</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">areDeclaredIn</span><span class="p">(</span><span class="n">LoyaltyAccount</span><span class="p">.</span><span class="na">class</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">and</span><span class="p">().</span><span class="na">haveNameMatching</span><span class="p">(</span><span class="s">&#34;set[A-Z].*&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">onlyBeCalled</span><span class="p">().</span><span class="na">byClassesThat</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain.loyalty.service..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;domain/loyalty/AGENTS.md: invariant 3&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">onlyListenersEarnPoints</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">methods</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">areDeclaredIn</span><span class="p">(</span><span class="n">LoyaltyService</span><span class="p">.</span><span class="na">class</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">and</span><span class="p">().</span><span class="na">haveName</span><span class="p">(</span><span class="s">&#34;earnForPaidOrder&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">onlyBeCalled</span><span class="p">().</span><span class="na">byClassesThat</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.listener..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;domain/loyalty/AGENTS.md: invariant 2&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">domainsDoNotDependOnAppLayer</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">noClasses</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">dependOnClassesThat</span><span class="p">().</span><span class="na">resideInAnyPackage</span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                            </span><span class="s">&#34;com.shop.controller..&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;com.shop.service..&#34;</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                            </span><span class="s">&#34;com.shop.dto..&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;com.shop.listener..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;dependencies point one way: app layer -&gt; domain&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>(<code>classes</code>, <code>noClasses</code> and <code>methods</code> are static imports from <code>ArchRuleDefinition</code>.)</p>
<p>The <code>because()</code> text points back to <code>AGENTS.md</code>. When the AI breaks a rule, the failing build tells it which rule and where it&rsquo;s written. Most assistants will read that and fix the code on their own.</p>
<h2 id="takeaways">Takeaways</h2>
<ul>
<li>Treat the AI as a new team. It needs onboarding, not more detailed tickets.</li>
<li>Use the AI to discover the domain before you ask it to change it. The glossary and the leak list are useful even without AI.</li>
<li>Keep <code>AGENTS.md</code> next to the code it describes: language, invariants, public API, forbidden dependencies.</li>
<li>Ask for affected invariants before code, and review in a fresh session against the written rules.</li>
<li>Every rule you care about should end up as a test. Prompts are suggestions, tests are guarantees.</li>
</ul>
]]></content:encoded></item><item><title>5 JPA/Hibernate Mistakes That Quietly Kill Your Spring Boot Performance</title><link>https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/</link><pubDate>Sat, 07 Nov 2026 10:00:00 +0000</pubDate><guid>https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/</guid><description>Open Session in View, EAGER to-ones, in-memory pagination, deleteBy and read-only entities: 5 JPA defaults that only hurt with real data.</description><content:encoded><![CDATA[<p><em>Everything works in dev. Then production gets real data.</em></p>
<p><img alt="A cartoon bear waiter rushes tiny plates tagged &ldquo;3 ms&rdquo; out of a kitchen where a blue elephant relaxes, while a long line of customers waits at the door marked API" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-01.jpg"></p>
<p>Here&rsquo;s how it usually goes. Spring Boot app, Spring Data JPA, Postgres behind it. Every query in the log takes 3 ms. The database is bored. And yet the API is slow, the connection pool runs dry at lunchtime, and the nightly export job is still running at breakfast.</p>
<p>Nobody wrote a slow query. Hibernate just did a lot of things nobody asked it to do, very quickly, many times.</p>
<p>In <a href="/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/">5 PostgreSQL Mistakes I See in Every Spring Boot App</a> I covered the database side, including the cartesian product you get from <code>JOIN FETCH</code> on several collections and <code>IDENTITY</code> quietly turning off batch inserts. This one is about the JPA side: five defaults and habits I find in almost every Spring Boot codebase I review, and what each of them actually makes Hibernate do.</p>
<p>The examples use Spring Boot 4, Hibernate ORM 7 and Java 21, with SQL logging on:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">logging.level.org.hibernate.SQL</span><span class="o">=</span><span class="s">DEBUG</span>
</span></span><span class="line"><span class="cl"><span class="na">logging.level.org.hibernate.orm.jdbc.bind</span><span class="o">=</span><span class="s">TRACE</span>
</span></span></code></pre></div><h3 id="mistake-1-leaving-open-session-in-view-on">Mistake 1: Leaving Open Session in View on</h3>
<p><img alt="Ten bears hold all ten DB connection keys while waiting on hold for the pricing service, as a bored elephant sits at reception and a queue of people waits" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-02.jpg"></p>
<p>Here&rsquo;s an endpoint that looks completely harmless:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@RestController</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@RequestMapping</span><span class="p">(</span><span class="s">&#34;/orders&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">class</span> <span class="nc">OrderController</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">OrderService</span><span class="w"> </span><span class="n">orderService</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">PricingClient</span><span class="w"> </span><span class="n">pricingClient</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">OrderController</span><span class="p">(</span><span class="n">OrderService</span><span class="w"> </span><span class="n">orderService</span><span class="p">,</span><span class="w"> </span><span class="n">PricingClient</span><span class="w"> </span><span class="n">pricingClient</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">this</span><span class="p">.</span><span class="na">orderService</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderService</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">this</span><span class="p">.</span><span class="na">pricingClient</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">pricingClient</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@GetMapping</span><span class="p">(</span><span class="s">&#34;/{id}&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">OrderView</span><span class="w"> </span><span class="nf">get</span><span class="p">(</span><span class="nd">@PathVariable</span><span class="w"> </span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderService</span><span class="p">.</span><span class="na">findOrder</span><span class="p">(</span><span class="n">id</span><span class="p">);</span><span class="w">                                   </span><span class="c1">// @Transactional, ~5 ms</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">BigDecimal</span><span class="w"> </span><span class="n">delivery</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">pricingClient</span><span class="p">.</span><span class="na">estimateDelivery</span><span class="p">(</span><span class="n">order</span><span class="p">.</span><span class="na">getShippingCountry</span><span class="p">());</span><span class="w"> </span><span class="c1">// HTTP call, ~300 ms</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="n">OrderView</span><span class="p">.</span><span class="na">from</span><span class="p">(</span><span class="n">order</span><span class="p">,</span><span class="w"> </span><span class="n">delivery</span><span class="p">);</span><span class="w">                                     </span><span class="c1">// walks order.getItems()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>The service method is <code>@Transactional(readOnly = true)</code> and does one <code>findById</code>. The transaction is over the moment it returns. So the connection goes back to the pool, right?</p>
<p>No. <code>spring.jpa.open-in-view</code> is <code>true</code> by default, so Spring registers an <code>OpenEntityManagerInViewInterceptor</code> for every web request. It opens the <code>EntityManager</code> when the request starts and closes it after the response is written. Spring also configures Hibernate to hold on to the JDBC connection once it has one, until the session closes. Here&rsquo;s the log:</p>
<pre tabindex="0"><code>select o1_0.id,o1_0.created_at,c1_0.id,c1_0.email,c1_0.name,o1_0.shipping_country,o1_0.status from orders o1_0 left join customers c1_0 on c1_0.id=o1_0.customer_id where o1_0.id=?
                                  -- transaction committed, connection still held
                                  -- ~300 ms waiting for the pricing service
select i1_0.order_id,i1_0.id,i1_0.price,i1_0.product_id,i1_0.quantity from order_items i1_0 where i1_0.order_id=?
</code></pre><p>The second query runs from <code>OrderView.from()</code> in the controller, outside any transaction, because the session is still open and the lazy <code>items</code> collection can still load. If you return the entity directly, Jackson does the same thing during serialization.</p>
<p>Now the arithmetic. The request does about 15 ms of SQL but holds a connection for about 320 ms. HikariCP&rsquo;s default pool has 10 connections, so the whole service tops out at 10 / 0.32 s ≈ <strong>31 requests per second</strong>. With the connection held only for the SQL it would be around 660. At 50 requests per second, threads start queueing for a connection, and 30 seconds later:</p>
<pre tabindex="0"><code>HikariPool-1 - Connection is not available, request timed out after 30000ms (total=10, active=10, idle=0, waiting=42)
</code></pre><p>Meanwhile, <code>pg_stat_activity</code> shows your ten connections as <code>idle</code>. The database isn&rsquo;t slow. It&rsquo;s waiting for you.</p>
<p><img alt="Request timeline: with Open Session in View the connection is held from the first query until the response is written, without it only during the service call" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/diagram-osiv.jpg"></p>
<p><strong>The fix:</strong> turn it off, and load everything the response needs inside the service:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">spring.jpa.open-in-view</span><span class="o">=</span><span class="s">false</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">interface</span> <span class="nc">OrderRepository</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">JpaRepository</span><span class="o">&lt;</span><span class="n">Order</span><span class="p">,</span><span class="w"> </span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@EntityGraph</span><span class="p">(</span><span class="n">attributePaths</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="s">&#34;customer&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;items&#34;</span><span class="p">})</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Optional</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findWithCustomerAndItemsById</span><span class="p">(</span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="p">(</span><span class="n">readOnly</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="n">OrderDetails</span><span class="w"> </span><span class="nf">findOrder</span><span class="p">(</span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">findWithCustomerAndItemsById</span><span class="p">(</span><span class="n">id</span><span class="p">).</span><span class="na">orElseThrow</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">OrderDetails</span><span class="p">.</span><span class="na">from</span><span class="p">(</span><span class="n">order</span><span class="p">);</span><span class="w">   </span><span class="c1">// map to a DTO while the session is still open</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>The first thing you&rsquo;ll see after switching it off is <code>LazyInitializationException</code> in places you didn&rsquo;t know were lazy-loading. That&rsquo;s the point. Each one is a hidden query that used to run from a controller or a JSON serializer. Fetch it explicitly in the service, and it stops being hidden.</p>
<p><strong>How to check your app:</strong></p>
<ul>
<li>If you never set the property, Spring Boot tells you at startup: <code>spring.jpa.open-in-view is enabled by default. Therefore, database queries may be performed during view rendering.</code></li>
<li>Compare HikariCP&rsquo;s <code>hikaricp.connections.usage</code> metric (how long a connection is held) with your SQL time. If usage is 10× the query time, something is holding connections.</li>
</ul>
<p><strong>Read more:</strong> <a href="https://docs.spring.io/spring-boot/reference/data/sql.html#data.sql.jpa-and-spring-data.open-entity-manager-in-view">Spring Boot reference: Open EntityManager in View</a></p>
<h3 id="mistake-2-trusting-the-default-fetch-type-on-manytoone">Mistake 2: Trusting the default fetch type on @ManyToOne</h3>
<p><img alt="A bear waits for a single envelope while a blue elephant delivers a chain of boxes: Payment, Order, Customer, Country" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-03.jpg"></p>
<p>Collections are lazy by default. To-one associations aren&rsquo;t. The JPA spec says <code>@ManyToOne</code> and <code>@OneToOne</code> are <code>EAGER</code> unless you say otherwise, and most entities I see never say otherwise:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="c1">// Payment.java</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Table</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;payments&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">Payment</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@GeneratedValue</span><span class="p">(</span><span class="n">strategy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">GenerationType</span><span class="p">.</span><span class="na">SEQUENCE</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ManyToOne</span><span class="w">                          </span><span class="c1">// EAGER by default</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@JoinColumn</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order_id&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Enumerated</span><span class="p">(</span><span class="n">EnumType</span><span class="p">.</span><span class="na">STRING</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">PaymentStatus</span><span class="w"> </span><span class="n">status</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">BigDecimal</span><span class="w"> </span><span class="n">amount</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="c1">// Order.java</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Table</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;orders&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">Order</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@GeneratedValue</span><span class="p">(</span><span class="n">strategy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">GenerationType</span><span class="p">.</span><span class="na">SEQUENCE</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ManyToOne</span><span class="w">                          </span><span class="c1">// EAGER by default</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@JoinColumn</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;customer_id&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Customer</span><span class="w"> </span><span class="n">customer</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@OneToMany</span><span class="p">(</span><span class="n">mappedBy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order&#34;</span><span class="p">)</span><span class="w">      </span><span class="c1">// LAZY by default</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">List</span><span class="o">&lt;</span><span class="n">OrderItem</span><span class="o">&gt;</span><span class="w"> </span><span class="n">items</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">ArrayList</span><span class="o">&lt;&gt;</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Enumerated</span><span class="p">(</span><span class="n">EnumType</span><span class="p">.</span><span class="na">STRING</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">OrderStatus</span><span class="w"> </span><span class="n">status</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">String</span><span class="w"> </span><span class="n">shippingCountry</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Instant</span><span class="w"> </span><span class="n">createdAt</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p><code>paymentRepository.findById(42L)</code> gives you a chain of joins:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">select</span><span class="w"> </span><span class="n">p1_0</span><span class="p">.</span><span class="n">id</span><span class="p">,</span><span class="n">p1_0</span><span class="p">.</span><span class="n">amount</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">id</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">created_at</span><span class="p">,</span><span class="n">c1_0</span><span class="p">.</span><span class="n">id</span><span class="p">,</span><span class="n">c1_0</span><span class="p">.</span><span class="n">email</span><span class="p">,</span><span class="n">c1_0</span><span class="p">.</span><span class="n">name</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">shipping_country</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">status</span><span class="p">,</span><span class="n">p1_0</span><span class="p">.</span><span class="n">status</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">from</span><span class="w"> </span><span class="n">payments</span><span class="w"> </span><span class="n">p1_0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">left</span><span class="w"> </span><span class="k">join</span><span class="w"> </span><span class="n">orders</span><span class="w"> </span><span class="n">o1_0</span><span class="w"> </span><span class="k">on</span><span class="w"> </span><span class="n">o1_0</span><span class="p">.</span><span class="n">id</span><span class="o">=</span><span class="n">p1_0</span><span class="p">.</span><span class="n">order_id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">left</span><span class="w"> </span><span class="k">join</span><span class="w"> </span><span class="n">customers</span><span class="w"> </span><span class="n">c1_0</span><span class="w"> </span><span class="k">on</span><span class="w"> </span><span class="n">c1_0</span><span class="p">.</span><span class="n">id</span><span class="o">=</span><span class="n">o1_0</span><span class="p">.</span><span class="n">customer_id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">where</span><span class="w"> </span><span class="n">p1_0</span><span class="p">.</span><span class="n">id</span><span class="o">=?</span><span class="w">
</span></span></span></code></pre></div><p>For one row that&rsquo;s tolerable, and that&rsquo;s why nobody notices. But the chain grows every time someone adds a to-one anywhere above it. Add <code>Customer.country</code> and every <code>findById</code> on <code>Payment</code> now joins four tables.</p>
<p>The real damage shows up with a query. Here&rsquo;s a retry job that needs pending payments, just their IDs and amounts:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="n">List</span><span class="o">&lt;</span><span class="n">Payment</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findAllByStatus</span><span class="p">(</span><span class="n">PaymentStatus</span><span class="w"> </span><span class="n">status</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>JPQL doesn&rsquo;t turn <code>EAGER</code> mappings into joins. Hibernate runs the query you wrote, and then, because it promised to load <code>order</code> eagerly, it loads every order with a separate select:</p>
<pre tabindex="0"><code>select p1_0.id,p1_0.amount,p1_0.order_id,p1_0.status from payments p1_0 where p1_0.status=?
select o1_0.id,o1_0.created_at,c1_0.id,c1_0.email,c1_0.name,o1_0.shipping_country,o1_0.status from orders o1_0 left join customers c1_0 on c1_0.id=o1_0.customer_id where o1_0.id=?
select o1_0.id,o1_0.created_at,c1_0.id,c1_0.email,c1_0.name,o1_0.shipping_country,o1_0.status from orders o1_0 left join customers c1_0 on c1_0.id=o1_0.customer_id where o1_0.id=?
... 498 more
</code></pre><p>500 pending payments, <strong>501 queries</strong>, and the code never calls <code>getOrder()</code> once. It&rsquo;s N+1 without a single lazy load, which is why people don&rsquo;t recognize it.</p>
<p><strong>The fix:</strong> <code>LAZY</code> on every to-one, no exceptions, then fetch explicitly where you actually need the parent:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@ManyToOne</span><span class="p">(</span><span class="n">fetch</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">FetchType</span><span class="p">.</span><span class="na">LAZY</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@JoinColumn</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order_id&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">private</span><span class="w"> </span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="p">;</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;&#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">    select p from Payment p
</span></span></span><span class="line"><span class="cl"><span class="s">    join fetch p.order o
</span></span></span><span class="line"><span class="cl"><span class="s">    join fetch o.customer
</span></span></span><span class="line"><span class="cl"><span class="s">    where p.status = :status
</span></span></span><span class="line"><span class="cl"><span class="s">    &#34;&#34;&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">List</span><span class="o">&lt;</span><span class="n">Payment</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findAllWithOrderAndCustomerByStatus</span><span class="p">(</span><span class="n">PaymentStatus</span><span class="w"> </span><span class="n">status</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>Fetch-joining to-ones is cheap: still one row per payment, no multiplication. (Collections are a different story. That&rsquo;s the cartesian product from the PostgreSQL article.) And if hydration cost is new to you, <a href="/posts/when-one-fast-query-becomes-a-production-nightmare-the-dehydration-problem-in-hibernate/">The Dehydration Problem in Hibernate</a> explains why loading entities you don&rsquo;t use is expensive even when the SQL is fast.</p>
<p>One trap: on the inverse side of a <code>@OneToOne</code> (the one with <code>mappedBy</code>), Hibernate can&rsquo;t know whether the related row exists without querying, so it may load it eagerly even with <code>LAZY</code>. Map the association from the owning side only, or share the primary key with <code>@MapsId</code>.</p>
<p><strong>How to check your app:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">grep -rn -E <span class="s2">&#34;@(ManyToOne|OneToOne)&#34;</span> src/main/java <span class="p">|</span> grep -v <span class="s2">&#34;LAZY&#34;</span>
</span></span></code></pre></div><p>Then make the query count part of a test. Turn on statistics in the test profile:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">spring.jpa.properties.hibernate.generate_statistics</span><span class="o">=</span><span class="s">true</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import static</span><span class="w"> </span><span class="nn">org.assertj.core.api.Assertions.assertThat</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">jakarta.persistence.EntityManagerFactory</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.hibernate.SessionFactory</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.hibernate.stat.Statistics</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.junit.jupiter.api.Test</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.springframework.beans.factory.annotation.Autowired</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.springframework.boot.test.context.SpringBootTest</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@SpringBootTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">class</span> <span class="nc">PaymentQueryCountTest</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Autowired</span><span class="w"> </span><span class="n">PaymentRepository</span><span class="w"> </span><span class="n">paymentRepository</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Autowired</span><span class="w"> </span><span class="n">EntityManagerFactory</span><span class="w"> </span><span class="n">entityManagerFactory</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Test</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">void</span><span class="w"> </span><span class="nf">loadingPendingPaymentsIsOneQuery</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Statistics</span><span class="w"> </span><span class="n">stats</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">entityManagerFactory</span><span class="p">.</span><span class="na">unwrap</span><span class="p">(</span><span class="n">SessionFactory</span><span class="p">.</span><span class="na">class</span><span class="p">).</span><span class="na">getStatistics</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">stats</span><span class="p">.</span><span class="na">clear</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">paymentRepository</span><span class="p">.</span><span class="na">findAllByStatus</span><span class="p">(</span><span class="n">PaymentStatus</span><span class="p">.</span><span class="na">PENDING</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">assertThat</span><span class="p">(</span><span class="n">stats</span><span class="p">.</span><span class="na">getPrepareStatementCount</span><span class="p">()).</span><span class="na">isEqualTo</span><span class="p">(</span><span class="n">1</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>I&rsquo;ll reuse this test for the next mistakes. It&rsquo;s the cheapest performance test you&rsquo;ll ever write.</p>
<p><strong>Read more:</strong> <a href="https://docs.hibernate.org/orm/7.0/userguide/html_single/Hibernate_User_Guide.html#fetching">Hibernate ORM 7 User Guide: Fetching</a></p>
<h3 id="mistake-3-paginating-a-join-fetch-of-a-collection">Mistake 3: Paginating a JOIN FETCH of a collection</h3>
<p><img alt="A truck dumps a mountain of 500,000 boxes, and a bear picks 20 of them into a basket labeled Page 1 while the rest go into a dumpster" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-04.jpg"></p>
<p>An order list screen, 20 per page, with items, because the screen shows them:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Query</span><span class="p">(</span><span class="n">value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;&#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">        select o from Order o
</span></span></span><span class="line"><span class="cl"><span class="s">        join fetch o.items
</span></span></span><span class="line"><span class="cl"><span class="s">        where o.status = :status
</span></span></span><span class="line"><span class="cl"><span class="s">        &#34;&#34;&#34;</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="n">countQuery</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;select count(o) from Order o where o.status = :status&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">Page</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findWithItemsByStatus</span><span class="p">(</span><span class="n">OrderStatus</span><span class="w"> </span><span class="n">status</span><span class="p">,</span><span class="w"> </span><span class="n">Pageable</span><span class="w"> </span><span class="n">pageable</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>Called with <code>PageRequest.of(0, 20, Sort.by(&quot;createdAt&quot;).descending())</code>. Here&rsquo;s the SQL:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">select</span><span class="w"> </span><span class="n">o1_0</span><span class="p">.</span><span class="n">id</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">created_at</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">customer_id</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">shipping_country</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">status</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="n">i1_0</span><span class="p">.</span><span class="n">order_id</span><span class="p">,</span><span class="n">i1_0</span><span class="p">.</span><span class="n">id</span><span class="p">,</span><span class="n">i1_0</span><span class="p">.</span><span class="n">price</span><span class="p">,</span><span class="n">i1_0</span><span class="p">.</span><span class="n">product_id</span><span class="p">,</span><span class="n">i1_0</span><span class="p">.</span><span class="n">quantity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">from</span><span class="w"> </span><span class="n">orders</span><span class="w"> </span><span class="n">o1_0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">join</span><span class="w"> </span><span class="n">order_items</span><span class="w"> </span><span class="n">i1_0</span><span class="w"> </span><span class="k">on</span><span class="w"> </span><span class="n">o1_0</span><span class="p">.</span><span class="n">id</span><span class="o">=</span><span class="n">i1_0</span><span class="p">.</span><span class="n">order_id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">where</span><span class="w"> </span><span class="n">o1_0</span><span class="p">.</span><span class="n">status</span><span class="o">=?</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">order</span><span class="w"> </span><span class="k">by</span><span class="w"> </span><span class="n">o1_0</span><span class="p">.</span><span class="n">created_at</span><span class="w"> </span><span class="k">desc</span><span class="w">
</span></span></span></code></pre></div><p>No <code>LIMIT</code>. No <code>OFFSET</code>. And that&rsquo;s deliberate: a <code>LIMIT 20</code> in SQL would cut rows, not orders. Twenty rows might be two orders with ten items each, or one order cut in half. So Hibernate fetches everything, builds every entity, and does the pagination in memory. The only trace is a warning:</p>
<pre tabindex="0"><code>WARN  HHH90003004: firstResult/maxResults specified with collection fetch; applying in memory
</code></pre><p>This is the behavior up to Hibernate 7.3. Starting with 7.4, the docs say the limit is applied in memory only when the database doesn&rsquo;t support <code>LIMIT</code> inside a subquery, so on newer versions check your SQL log before assuming you&rsquo;re affected.</p>
<p>With 50,000 open orders and 10 items each, page 1 of 20 orders loads <strong>500,000 rows</strong>. They go over the network, Hibernate hydrates 550,000 entities into the persistence context, keeps 20 orders, and throws the rest away. Page 2 costs exactly the same. In dev, with 30 orders, it&rsquo;s instant.</p>
<p><img alt="The database returns 500,000 rows, Hibernate builds every entity and keeps 20 for the page" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/diagram-pagination.jpg"></p>
<p><strong>The fix:</strong> page the IDs, then fetch the entities by ID.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;select o.id from Order o where o.status = :status&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">Page</span><span class="o">&lt;</span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findIdsByStatus</span><span class="p">(</span><span class="n">OrderStatus</span><span class="w"> </span><span class="n">status</span><span class="p">,</span><span class="w"> </span><span class="n">Pageable</span><span class="w"> </span><span class="n">pageable</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;select o from Order o join fetch o.items where o.id in :ids&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">List</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findWithItemsByIdIn</span><span class="p">(</span><span class="n">Collection</span><span class="o">&lt;</span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="n">ids</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="p">(</span><span class="n">readOnly</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="n">Page</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findOrders</span><span class="p">(</span><span class="n">OrderStatus</span><span class="w"> </span><span class="n">status</span><span class="p">,</span><span class="w"> </span><span class="n">Pageable</span><span class="w"> </span><span class="n">pageable</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Page</span><span class="o">&lt;</span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="n">ids</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">findIdsByStatus</span><span class="p">(</span><span class="n">status</span><span class="p">,</span><span class="w"> </span><span class="n">pageable</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Map</span><span class="o">&lt;</span><span class="n">Long</span><span class="p">,</span><span class="w"> </span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="n">byId</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">findWithItemsByIdIn</span><span class="p">(</span><span class="n">ids</span><span class="p">.</span><span class="na">getContent</span><span class="p">()).</span><span class="na">stream</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">.</span><span class="na">collect</span><span class="p">(</span><span class="n">Collectors</span><span class="p">.</span><span class="na">toMap</span><span class="p">(</span><span class="n">Order</span><span class="p">::</span><span class="n">getId</span><span class="p">,</span><span class="w"> </span><span class="n">Function</span><span class="p">.</span><span class="na">identity</span><span class="p">()));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">ids</span><span class="p">.</span><span class="na">map</span><span class="p">(</span><span class="n">byId</span><span class="p">::</span><span class="n">get</span><span class="p">);</span><span class="w">   </span><span class="c1">// keeps the sort order of the ID page</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Now the database does the paging:</p>
<pre tabindex="0"><code>select o1_0.id from orders o1_0 where o1_0.status=? order by o1_0.created_at desc offset ? rows fetch first ? rows only
select count(o1_0.id) from orders o1_0 where o1_0.status=?
select o1_0.id,...,i1_0.quantity from orders o1_0 join order_items i1_0 on o1_0.id=i1_0.order_id where o1_0.id in (?,?,?,...)
</code></pre><p>Three queries and about 200 rows instead of 500,000. Since Hibernate 6, duplicate roots from a fetch join are removed automatically, so you don&rsquo;t need <code>distinct</code> in the second query.</p>
<p>The other option is to not fetch-join the collection at all. Page the orders normally and let batch fetching load the items for the whole page in one <code>IN</code> query:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@BatchSize</span><span class="p">(</span><span class="n">size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">50</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@OneToMany</span><span class="p">(</span><span class="n">mappedBy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">private</span><span class="w"> </span><span class="n">List</span><span class="o">&lt;</span><span class="n">OrderItem</span><span class="o">&gt;</span><span class="w"> </span><span class="n">items</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">ArrayList</span><span class="o">&lt;&gt;</span><span class="p">();</span><span class="w">
</span></span></span></code></pre></div><p>Or globally with <code>hibernate.default_batch_fetch_size</code>, which I covered in the <a href="/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/">PostgreSQL article</a>.</p>
<p><strong>How to check your app:</strong> make Hibernate fail instead of warn, at least in tests:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">spring.jpa.properties.hibernate.query.fail_on_pagination_over_collection_fetch</span><span class="o">=</span><span class="s">true</span>
</span></span></code></pre></div><p>And search your production logs for <code>HHH90003004</code> today. If it&rsquo;s there, it&rsquo;s been there for a while.</p>
<p><strong>Read more:</strong> <a href="https://docs.hibernate.org/orm/7.0/userguide/html_single/Hibernate_User_Guide.html#hql-limit-offset">Hibernate ORM 7 User Guide: Limits and offsets</a></p>
<h3 id="mistake-4-deleting-with-derived-deleteby-methods">Mistake 4: Deleting with derived deleteBy&hellip;() methods</h3>
<p><img alt="At 4 AM a bear removes warehouse items one by one with tweezers under a counter reading 87,412 of 120,001, next to an untouched DELETE WHERE button" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-05.jpg"></p>
<p>I mentioned this one in the <a href="/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/">PostgreSQL article</a>, from the database&rsquo;s point of view. Here&rsquo;s what happens before the <code>DELETE</code> even reaches the database.</p>
<p>The orders aggregate, mapped the way most aggregates are:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@OneToMany</span><span class="p">(</span><span class="n">mappedBy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order&#34;</span><span class="p">,</span><span class="w"> </span><span class="n">cascade</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">CascadeType</span><span class="p">.</span><span class="na">ALL</span><span class="p">,</span><span class="w"> </span><span class="n">orphanRemoval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">private</span><span class="w"> </span><span class="n">List</span><span class="o">&lt;</span><span class="n">OrderItem</span><span class="o">&gt;</span><span class="w"> </span><span class="n">items</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">ArrayList</span><span class="o">&lt;&gt;</span><span class="p">();</span><span class="w">
</span></span></span></code></pre></div><p>And a nightly purge that reads like plain English:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">interface</span> <span class="nc">OrderRepository</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">JpaRepository</span><span class="o">&lt;</span><span class="n">Order</span><span class="p">,</span><span class="w"> </span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">long</span><span class="w"> </span><span class="nf">deleteByCreatedAtBefore</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">purgeOrdersOlderThan</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">deleteByCreatedAtBefore</span><span class="p">(</span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Spring Data doesn&rsquo;t turn that into <code>DELETE ... WHERE</code>. It selects the orders, then calls <code>EntityManager.remove()</code> on each one. <code>remove()</code> cascades to <code>items</code>, and to cascade, Hibernate first has to load each collection. Then, at flush, every row gets its own <code>DELETE</code>:</p>
<pre tabindex="0"><code>select o1_0.id,o1_0.created_at,o1_0.customer_id,o1_0.shipping_country,o1_0.status from orders o1_0 where o1_0.created_at&lt;?
select i1_0.order_id,i1_0.id,i1_0.price,i1_0.product_id,i1_0.quantity from order_items i1_0 where i1_0.order_id=?
... 9,999 more
delete from order_items where id=?
... 99,999 more
delete from orders where id=?
... 9,999 more
</code></pre><p>For 10,000 orders with 10 items each, that adds up fast:</p>
<p><img alt="deleteByCreatedAtBefore runs 120,001 statements: 1 select of orders, 10,000 selects of items, 100,000 item deletes and 10,000 order deletes, while two bulk deletes run 2" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/diagram-delete.jpg"></p>
<p>Plus 110,000 managed entities in memory, plus every <code>@PreRemove</code> callback, plus an Envers audit row per deleted entity if you use Envers. Setting <code>hibernate.jdbc.batch_size</code> groups the deletes into fewer round trips, but the selects, the memory and the statement count stay the same. And on the Postgres side you now have 110,000 dead tuples to vacuum. <a href="/posts/your-delete-insert-is-burning-postgresqls-cpu-here-s-what-s-actually-happening-on-the-page/">Your DELETE + INSERT Is Burning PostgreSQL&rsquo;s CPU</a> shows what that does on the page.</p>
<p><strong>The fix:</strong> bulk deletes, children first:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">interface</span> <span class="nc">OrderRepository</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">JpaRepository</span><span class="o">&lt;</span><span class="n">Order</span><span class="p">,</span><span class="w"> </span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Modifying</span><span class="p">(</span><span class="n">flushAutomatically</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w"> </span><span class="n">clearAutomatically</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;&#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">        delete from OrderItem i
</span></span></span><span class="line"><span class="cl"><span class="s">        where i.order.id in (select o.id from Order o where o.createdAt &lt; :cutoff)
</span></span></span><span class="line"><span class="cl"><span class="s">        &#34;&#34;&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">int</span><span class="w"> </span><span class="nf">deleteItemsOfOrdersCreatedBefore</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Modifying</span><span class="p">(</span><span class="n">flushAutomatically</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w"> </span><span class="n">clearAutomatically</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;delete from Order o where o.createdAt &lt; :cutoff&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">int</span><span class="w"> </span><span class="nf">deleteOrdersCreatedBefore</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="nf">purgeOrdersOlderThan</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">deleteItemsOfOrdersCreatedBefore</span><span class="p">(</span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">deleteOrdersCreatedBefore</span><span class="p">(</span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Two statements. But a bulk delete is fast precisely because it skips everything JPA normally does, so know what you&rsquo;re giving up:</p>
<ul>
<li><strong>No cascades.</strong> Nothing else gets deleted for you. If <code>payments</code> references <code>orders</code>, you get a foreign key violation, or orphans if there&rsquo;s no FK. Delete in the right order yourself, or let the database cascade: <code>ON DELETE CASCADE</code> on the FK plus <code>@OnDelete(action = OnDeleteAction.CASCADE)</code> on <code>OrderItem.order</code>, and then you only delete orders.</li>
<li><strong>No lifecycle callbacks.</strong> <code>@PreRemove</code>, entity listeners and Envers don&rsquo;t run. In regulated domains, where the audit trail is a compliance requirement, check with whoever owns that requirement before you switch.</li>
<li><strong>No persistence context.</strong> Entities already loaded in this session don&rsquo;t know they were deleted. <code>clearAutomatically = true</code> clears the context after the delete, and <code>flushAutomatically = true</code> writes pending changes first, so the clear doesn&rsquo;t throw them away.</li>
</ul>
<p>For millions of rows, delete in chunks instead of one giant statement. The PostgreSQL article has the pattern.</p>
<p><strong>How to check your app:</strong> <code>grep -rn -E &quot;(delete|remove)(All)?By|deleteAll\(&quot; src/main/java</code>, then run the statistics test from Mistake 2 around your purge with 3 orders of 2 items each. If <code>getPrepareStatementCount()</code> says 13 instead of 2, you&rsquo;ve found it.</p>
<p><strong>Read more:</strong> <a href="https://docs.spring.io/spring-data/jpa/reference/jpa/query-methods.html#jpa.modifying-queries.derived-delete">Spring Data JPA: Derived delete queries</a></p>
<h3 id="mistake-5-loading-managed-entities-just-to-read-them">Mistake 5: Loading managed entities just to read them</h3>
<p><img alt="A bear takes a polaroid of every box on a conveyor belt to CSV export, until the warehouse is buried in photos and the heap gauge hits 98%" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-06.jpg"></p>
<p>A nightly export: one day of orders to CSV. Streaming, so it must be memory-safe, right?</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">interface</span> <span class="nc">OrderRepository</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">JpaRepository</span><span class="o">&lt;</span><span class="n">Order</span><span class="p">,</span><span class="w"> </span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Stream</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">streamByCreatedAtBetween</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">from</span><span class="p">,</span><span class="w"> </span><span class="n">Instant</span><span class="w"> </span><span class="n">to</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Stream</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">streamByCreatedAtBefore</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">exportDay</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">from</span><span class="p">,</span><span class="w"> </span><span class="n">Instant</span><span class="w"> </span><span class="n">to</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">try</span><span class="w"> </span><span class="p">(</span><span class="n">Stream</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="n">orders</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">streamByCreatedAtBetween</span><span class="p">(</span><span class="n">from</span><span class="p">,</span><span class="w"> </span><span class="n">to</span><span class="p">))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">orders</span><span class="p">.</span><span class="na">forEach</span><span class="p">(</span><span class="n">order</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">csv</span><span class="p">.</span><span class="na">write</span><span class="p">(</span><span class="n">order</span><span class="p">.</span><span class="na">getId</span><span class="p">(),</span><span class="w"> </span><span class="n">order</span><span class="p">.</span><span class="na">getStatus</span><span class="p">(),</span><span class="w"> </span><span class="n">order</span><span class="p">.</span><span class="na">getCreatedAt</span><span class="p">()));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Every <code>Order</code> you load is a managed entity. For each one, Hibernate keeps the entity itself, an entry in the persistence context, and a snapshot: a copy of every field&rsquo;s value at load time, used for dirty checking. The stream doesn&rsquo;t change that. Entities stay in the persistence context until the transaction ends, whether you still hold a reference or not.</p>
<p>So for 1,000,000 orders you hold <strong>2,000,000 objects</strong> (entities plus snapshots) until commit. Then the flush at commit compares every field of every entity against its snapshot, to update nothing. And if the loop runs any JPQL query, Hibernate auto-flushes before it, which means dirty-checking everything loaded so far. Every time. That&rsquo;s how a linear job becomes quadratic.</p>
<p><strong>The fix:</strong> read DTOs when you only read.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">record</span> <span class="nc">OrderExportRow</span><span class="p">(</span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">,</span><span class="w"> </span><span class="n">OrderStatus</span><span class="w"> </span><span class="n">status</span><span class="p">,</span><span class="w"> </span><span class="n">Instant</span><span class="w"> </span><span class="n">createdAt</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;&#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">    select new com.example.orders.OrderExportRow(o.id, o.status, o.createdAt)
</span></span></span><span class="line"><span class="cl"><span class="s">    from Order o
</span></span></span><span class="line"><span class="cl"><span class="s">    where o.createdAt &gt;= :from and o.createdAt &lt; :to
</span></span></span><span class="line"><span class="cl"><span class="s">    &#34;&#34;&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@QueryHints</span><span class="p">(</span><span class="nd">@QueryHint</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">HibernateHints</span><span class="p">.</span><span class="na">HINT_FETCH_SIZE</span><span class="p">,</span><span class="w"> </span><span class="n">value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;1000&#34;</span><span class="p">))</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">Stream</span><span class="o">&lt;</span><span class="n">OrderExportRow</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">streamExportRows</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">from</span><span class="p">,</span><span class="w"> </span><span class="n">Instant</span><span class="w"> </span><span class="n">to</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>No managed entities, no snapshots, no dirty checking. Memory stays flat. The fetch size matters too: without it, the Postgres JDBC driver reads the entire result set into memory before your stream sees the first row. (It only streams inside a transaction, with auto-commit off.)</p>
<p>The other tools, for the cases where you need entities:</p>
<ul>
<li><strong><code>@Transactional(readOnly = true)</code>.</strong> Spring marks the Hibernate session read-only and sets flush mode to manual, so entities load without snapshots and nothing is flushed at commit. They still sit in the persistence context, though. Good for normal read endpoints, not enough on its own for a million rows.</li>
<li><strong><code>flush()</code> + <code>clear()</code> every few hundred entities</strong> when the job modifies what it loads:</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">recalculateTotals</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">int</span><span class="w"> </span><span class="n">processed</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">0</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">try</span><span class="w"> </span><span class="p">(</span><span class="n">Stream</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="n">orders</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">streamByCreatedAtBefore</span><span class="p">(</span><span class="n">cutoff</span><span class="p">))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">Iterable</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="p">)</span><span class="w"> </span><span class="n">orders</span><span class="p">::</span><span class="n">iterator</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">order</span><span class="p">.</span><span class="na">recalculateTotal</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">++</span><span class="n">processed</span><span class="w"> </span><span class="o">%</span><span class="w"> </span><span class="n">500</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">0</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="n">entityManager</span><span class="p">.</span><span class="na">flush</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="n">entityManager</span><span class="p">.</span><span class="na">clear</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><ul>
<li><strong><code>StatelessSession</code></strong> for pure batch work: no persistence context, no snapshots, no cascades, no lazy loading. You call <code>update()</code> yourself, and it runs outside Spring&rsquo;s transaction management.</li>
</ul>
<p><strong>How to check your app:</strong> run the job in staging with statistics on and look at the session metrics Hibernate logs at the end:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">spring.jpa.properties.hibernate.generate_statistics</span><span class="o">=</span><span class="s">true</span>
</span></span><span class="line"><span class="cl"><span class="na">logging.level.org.hibernate.engine.internal.StatisticalLoggingSessionEventListener</span><span class="o">=</span><span class="s">INFO</span>
</span></span></code></pre></div><p>For the export above, you&rsquo;ll see something like this:</p>
<pre tabindex="0"><code>Session Metrics {
    ...
    1843000000 nanoseconds spent executing 1 flushes (flushing a total of 1000000 entities and 1000000 collections);
}
</code></pre><p>If a read-only job flushes a million entities, it&rsquo;s loading entities it should be reading as DTOs.</p>
<p><strong>Read more:</strong> <a href="https://docs.spring.io/spring-data/jpa/reference/repositories/projections.html">Spring Data JPA: Projections</a></p>
<h3 id="bonus-lomboks-data-on-entities">Bonus: Lombok&rsquo;s @Data on entities</h3>
<p><img alt="A bear types log.debug(order) and an avalanche of boxes bursts out of the laptop, burying the elephant, with a counter showing 51 queries" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-07.jpg"></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Data</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Table</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;orders&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">Order</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="cm">/* customer, items, ... */</span><span class="w"> </span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Then, somewhere in a service:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="n">log</span><span class="p">.</span><span class="na">debug</span><span class="p">(</span><span class="s">&#34;Saving order {}&#34;</span><span class="p">,</span><span class="w"> </span><span class="n">order</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p><code>@Data</code> generates a <code>toString()</code> that prints every field. Printing <code>items</code> initializes the lazy collection, and printing each item&rsquo;s lazy <code>product</code> initializes that too. An order with 50 items: <strong>51 queries from one log line</strong>. If <code>OrderItem</code> also has <code>@Data</code>, its <code>toString()</code> prints <code>order</code>, which prints <code>items</code>, which prints <code>order</code>, and you get a <code>StackOverflowError</code>. And all of this only happens when DEBUG is on, which is exactly when you&rsquo;re investigating a production problem.</p>
<p>The generated <code>equals()</code> and <code>hashCode()</code> are just as bad: they use every field, so they touch lazy associations, and the hash code changes when the ID is assigned on persist, which loses the entity inside a <code>HashSet</code>.</p>
<p>Use <code>@Getter</code> and <code>@Setter</code>, and write these three yourself:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Override</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">boolean</span><span class="w"> </span><span class="nf">equals</span><span class="p">(</span><span class="n">Object</span><span class="w"> </span><span class="n">o</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="k">this</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">o</span><span class="p">)</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="kc">true</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="p">(</span><span class="n">o</span><span class="w"> </span><span class="k">instanceof</span><span class="w"> </span><span class="n">Order</span><span class="w"> </span><span class="n">other</span><span class="p">))</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="kc">false</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">id</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="kc">null</span><span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span><span class="n">id</span><span class="p">.</span><span class="na">equals</span><span class="p">(</span><span class="n">other</span><span class="p">.</span><span class="na">getId</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Override</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="nf">hashCode</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">getClass</span><span class="p">().</span><span class="na">hashCode</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Override</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="n">String</span><span class="w"> </span><span class="nf">toString</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="s">&#34;Order{id=&#34;</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">id</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="s">&#34;, status=&#34;</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">status</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="s">&#34;}&#34;</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p><strong>Read more:</strong> <a href="https://docs.hibernate.org/orm/7.0/userguide/html_single/Hibernate_User_Guide.html#mapping-model-pojo-equalshashcode">Hibernate ORM 7 User Guide: Implementing equals() and hashCode()</a></p>
<h3 id="a-quick-checklist">A quick checklist</h3>
<ul>
<li>Is <code>spring.jpa.open-in-view=false</code> set explicitly?</li>
<li>Does every <code>@ManyToOne</code> and <code>@OneToOne</code> say <code>fetch = FetchType.LAZY</code>?</li>
<li>Is <code>HHH90003004</code> anywhere in your production logs?</li>
<li>Any derived <code>deleteBy...()</code> or <code>deleteAll()</code> on tables with more than a few thousand rows?</li>
<li>Do your export and batch jobs read DTOs, or a million managed entities?</li>
<li>Is there a query-count test for your three busiest endpoints?</li>
</ul>
<p>None of these are Hibernate bugs. Every one is a default, or a convenience method, doing exactly what it was designed to do, on data it was never tested with. If you fixed these and want the next layer down, <a href="/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/">5 PostgreSQL Mistakes I See in Every Spring Boot App</a> covers what the database does with the queries Hibernate sends, <a href="/posts/when-one-fast-query-becomes-a-production-nightmare-the-dehydration-problem-in-hibernate/">The Dehydration Problem in Hibernate</a> goes deep on hydration cost, and <a href="/posts/5-spring-boot-mistakes-i-see-in-every-codebase/">5 Spring Boot Mistakes I See in Every Codebase</a> covers the transaction boundaries all of this depends on.</p>
]]></content:encoded></item><item><title>How to Make Sure They Can Never Fire You</title><link>https://vitaliisukach.dev/posts/how-to-make-sure-they-can-never-fire-you/</link><pubDate>Thu, 29 Oct 2026 10:00:00 +0000</pubDate><guid>https://vitaliisukach.dev/posts/how-to-make-sure-they-can-never-fire-you/</guid><description>Unreadable code is job security, right? A funny story about Timofei, a 412-line method, and how to count the tests your code needs.</description><content:encoded><![CDATA[<p><em>A short story about Timofei, job security, and cyclomatic complexity. You&rsquo;ve worked with Timofei. There&rsquo;s a chance you are Timofei.</em></p>
<p><img alt="Timofei in sunglasses next to a monitor full of spaghetti, saying &ldquo;I understand my code.&rdquo;" loading="lazy" src="https://vitaliisukach.dev/posts/how-to-make-sure-they-can-never-fire-you/image-01.jpg"></p>
<h3 id="chapter-1-the-untouchable">Chapter 1: The Untouchable</h3>
<p>Every team has a Timofei.</p>
<p>Timofei is a senior developer. We know this because Timofei says so. Timofei has worked in IT his whole life, and he knows everything. Just ask him. Actually, you don&rsquo;t have to ask, he will tell you anyway. He has been at the company since the very beginning, and he writes code the way Picasso painted: every piece is a masterpiece, and nobody can tell where the nose is supposed to be. Timofei does not write comments, because &ldquo;good code is self-explanatory&rdquo;. Timofei does not split methods, because &ldquo;jumping between files slows me down&rdquo;. Timofei does not need code review, because he has never once lost an argument in one. He just keeps typing until the reviewer gets tired.</p>
<p>Timofei&rsquo;s masterpiece is called <code>placeBet()</code>. It has 412 lines. It calculates stakes, applies betting taxes, checks the player&rsquo;s age, handles VIP cashback, adds live-betting fees, sends notifications, and on Tuesdays (nobody knows why) it rounds the odds differently.</p>
<p>When someone asks how it works, Timofei leans back, crosses his arms and says the sentence that became the team motto:</p>
<blockquote>
<p>&ldquo;I understand my code. If you don&rsquo;t, that&rsquo;s your problem.&rdquo;</p></blockquote>
<p>And honestly? He&rsquo;s right. He does understand it. It works. It&rsquo;s been in production for two years.</p>
<p>And here&rsquo;s the genius part. Nobody else understands <code>placeBet()</code>, so nobody can replace Timofei. Every time management talks about budget cuts, somebody asks &ldquo;but who will support the betting engine?&rdquo;, and Timofei&rsquo;s name quietly disappears from the list. He doesn&rsquo;t need a performance review. He has 412 lines of job security.</p>
<p>That&rsquo;s the whole career strategy, and it&rsquo;s simple: write code that only you can read, and they can never fire you.</p>
<p>What could possibly go wrong?</p>
<h3 id="chapter-2-the-new-guy">Chapter 2: The New Guy</h3>
<p><img alt="A junior developer with a ticket &ldquo;Add ONE condition, estimate: 1 point&rdquo; standing in front of a hedge maze labelled placeBet()" loading="lazy" src="https://vitaliisukach.dev/posts/how-to-make-sure-they-can-never-fire-you/image-02.jpg"></p>
<p>Meet Tom. Tom joined the team on Monday. On Tuesday, Tom got his first ticket:</p>
<blockquote>
<p><strong>TICKET-4521:</strong> Players from Poland get live betting without the live fee. Estimate: 1 point. <em>&ldquo;Should be quick&rdquo; — Timofei</em></p></blockquote>
<p>One condition. One <code>if</code>. Tom opened <code>placeBet()</code>.</p>
<p>At line 40 Tom found a <code>for</code> loop. Inside the loop there was an <code>if</code>. Inside the <code>if</code> there was an <code>else if</code>, and inside that an <code>if</code> with three <code>&amp;&amp;</code> and one <code>||</code> that Tom read four times and still couldn&rsquo;t explain out loud. At line 180 there was a variable called <code>flag2</code>. At line 230 <code>flag2</code> was set to <code>!flag2</code>, for reasons. At line 301 there was a comment: <code>// don't touch</code>. Nothing else, just that.</p>
<p>Tom found where the live fee was calculated. Then he found the <em>second</em> place where the live fee was calculated. Then a third one, inside a <code>catch</code> block.</p>
<p>Tom asked Timofei. Timofei said &ldquo;it&rsquo;s obvious, just read the code&rdquo; and went to lunch.</p>
<p>The ticket took eleven days. The PR had 3 lines of code and 40 comments. Tom&rsquo;s estimate for the next ticket was 8 points, and the team lead asked him in the retro why he was &ldquo;so slow&rdquo;.</p>
<h3 id="chapter-3-the-tests">Chapter 3: The Tests</h3>
<p><img alt="Timofei holding a tiny cocktail umbrella under a storm of 47 execution paths, with one green test" loading="lazy" src="https://vitaliisukach.dev/posts/how-to-make-sure-they-can-never-fire-you/image-03.jpg"></p>
<p>During the post-mortem for the Polish live betting feature (it charged Polish VIP players twice, but only on live bets, and only if one of the matches on the slip was suspended), somebody asked a dangerous question:</p>
<p>&ldquo;Where are the tests for <code>placeBet()</code>?&rdquo;</p>
<p>Timofei proudly opened <code>BetServiceTest.java</code>. It had one test. It was called <code>placeBet_works()</code>. It created a slip with one active football bet, no VIP status, no live betting, and checked that the total was not null.</p>
<p>It was green. It had always been green. It was green the day Polish VIPs were charged twice.</p>
<p>&ldquo;We have coverage,&rdquo; Timofei said, and showed the report: 61% line coverage. The other 39% was &ldquo;obvious stuff, it doesn&rsquo;t need tests&rdquo;.</p>
<p>Nobody in the room knew how many tests the method actually needed. Five? Ten? A hundred? You can&rsquo;t really answer that question by staring at 412 lines of nested <code>if</code>s. <em>(Spoiler: there is an exact answer, and it&rsquo;s coming.)</em></p>
<h3 id="chapter-4-3-am">Chapter 4: 3 AM</h3>
<p><img alt="A junior developer at 3 AM in front of unreadable code, while Timofei&rsquo;s phone shows an out-of-office reply: &ldquo;Just read the code. It&rsquo;s self-explanatory.&rdquo;" loading="lazy" src="https://vitaliisukach.dev/posts/how-to-make-sure-they-can-never-fire-you/image-04.jpg"></p>
<p>Saturday, 3:07 AM. The pager goes off. Bets are failing for every player who has a casino game on the slip. In the middle of a Champions League weekend. The revenue graph looks like a ski jump.</p>
<p>Timofei is on a beach. Timofei&rsquo;s auto-reply says: <em>&ldquo;Out of office until the 14th. Just read the code, it&rsquo;s self-explanatory 🍹&rdquo;</em>.</p>
<p>Tom is on call. Tom opens <code>placeBet()</code> and starts tracing. The age check is in one branch. But there&rsquo;s also an <code>adminOverride</code> flag that skips the age check. Except when <code>legacyMode2</code> is on. Except when it&rsquo;s a live bet, where a different branch calculates the casino tax again, and that branch throws an exception if the player object has no birth date, and that exception is caught by a <code>catch</code> that sends a notification, and the notification fails, and the failure is caught by another <code>catch</code> that returns <code>null</code>.</p>
<p>Tom fixes it at 6:40 AM by adding another <code>if</code>. The method now has 413 lines. The complexity just went up again, and the next person to read this code will have one more path to keep in their head.</p>
<p>That&rsquo;s how these methods grow. Nobody sits down and writes a monster on purpose. It grows one <code>if</code> per incident.</p>
<p>That Monday, the word &ldquo;Timofei&rdquo; appeared in a management meeting for the first time. Not in the budget cuts list. In the risks list.</p>
<h3 id="chapter-5-who-wrote-this">Chapter 5: Who Wrote This?!</h3>
<p><img alt="Timofei screaming &ldquo;WHO WROTE THIS?!&rdquo; at a git blame tooltip that says &ldquo;Timofei, 8 months ago, small fix, trust me&rdquo;, while the junior eats popcorn" loading="lazy" src="https://vitaliisukach.dev/posts/how-to-make-sure-they-can-never-fire-you/image-05.jpg"></p>
<p>Timofei comes back from vacation. Tan, relaxed, ready to fix whatever &ldquo;the juniors broke&rdquo;. He opens <code>placeBet()</code> to review Tom&rsquo;s 3 AM fix.</p>
<p>He scrolls. He scrolls back. He reads line 287 out loud, slowly. He reads it again.</p>
<p>&ldquo;Who wrote this garbage?&rdquo;</p>
<p>He clicks <em>git blame</em>.</p>
<p><strong>Timofei. 8 months ago. Commit message: &ldquo;small fix, trust me&rdquo;.</strong></p>
<p>Tom eats popcorn very quietly.</p>
<p>So much for job security. The one person who could never be replaced couldn&rsquo;t read his own code either. It turns out that if nobody can maintain your code, neither can you.</p>
<p>This is the part of the story that I like the most, because it&rsquo;s the part everybody has lived through. &ldquo;I understand my code&rdquo; has an expiration date. For most people it&rsquo;s about three weeks. After that, your own code is written by a stranger who had context you no longer have. Timofei wasn&rsquo;t writing code for &ldquo;people who don&rsquo;t get it&rdquo;. He was writing code for nobody, including future Timofei.</p>
<p>So what was actually wrong with <code>placeBet()</code>? It wasn&rsquo;t the length, exactly. You can have a 400-line method that&rsquo;s boring and fine (a long list of field mappings, for example). It wasn&rsquo;t the naming, although <code>flag2</code> didn&rsquo;t help.</p>
<p>The problem was the number of different ways to go through it. That number is what turned Timofei&rsquo;s job security into everyone&rsquo;s 3 AM. It has a name, a formula, and a tool that will happily scream at Timofei in CI.</p>
<p>It&rsquo;s called <strong>cyclomatic complexity</strong>.</p>
<hr>
<h3 id="what-cyclomatic-complexity-actually-is">What cyclomatic complexity actually is</h3>
<p>Cyclomatic complexity (CC) was introduced by Thomas McCabe in 1976. The idea is simple: <strong>it counts the number of linearly independent paths through a piece of code.</strong> In plain words, it&rsquo;s how many different routes the execution can take through a method.</p>
<p>Code with no branches has exactly one route: top to bottom. Every <code>if</code> adds a fork in the road. Every loop adds a fork (&ldquo;go around again, or leave?&rdquo;). Every <code>&amp;&amp;</code> and <code>||</code> adds a fork too, because of short-circuit evaluation: <code>a &amp;&amp; b</code> doesn&rsquo;t evaluate <code>b</code> when <code>a</code> is false, so there are two different routes there.</p>
<p>There are two ways to calculate it, and they give the same answer.</p>
<p><strong>The formal way, using the control flow graph:</strong></p>
<pre tabindex="0"><code>M = E − N + 2P
</code></pre><ul>
<li><code>E</code> is the number of edges (arrows) in the graph</li>
<li><code>N</code> is the number of nodes (blocks of code)</li>
<li><code>P</code> is the number of connected components, which for a single method is just 1</li>
</ul>
<p><strong>The practical way, which is what you&rsquo;ll actually use:</strong></p>
<pre tabindex="0"><code>M = number of decision points + 1
</code></pre><p>Let&rsquo;s do both on a small method so you can see that they agree.</p>
<h3 id="counting-it-by-hand">Counting it by hand</h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="n">String</span><span class="w"> </span><span class="nf">betLabel</span><span class="p">(</span><span class="n">BetSlip</span><span class="w"> </span><span class="n">slip</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">slip</span><span class="p">.</span><span class="na">isLive</span><span class="p">())</span><span class="w"> </span><span class="p">{</span><span class="w">                     </span><span class="c1">// decision 1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="s">&#34;LIVE&#34;</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="n">Bet</span><span class="w"> </span><span class="n">bet</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">slip</span><span class="p">.</span><span class="na">bets</span><span class="p">())</span><span class="w"> </span><span class="p">{</span><span class="w">            </span><span class="c1">// decision 2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">bet</span><span class="p">.</span><span class="na">isLongshot</span><span class="p">())</span><span class="w"> </span><span class="p">{</span><span class="w">              </span><span class="c1">// decision 3</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="k">return</span><span class="w"> </span><span class="s">&#34;LONGSHOT&#34;</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="s">&#34;STANDARD&#34;</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Three decision points, plus one. <strong>CC = 4.</strong></p>
<p>Now the same method drawn as a graph:</p>
<p><img alt="Control flow graph of betLabel with 7 nodes and 9 edges, showing M = 9 − 7 + 2 = 4" loading="lazy" src="https://vitaliisukach.dev/posts/how-to-make-sure-they-can-never-fire-you/image-06.jpg"></p>
<p>Seven nodes, nine edges: <code>9 − 7 + 2 = 4</code>. Same answer.</p>
<p>And those 4 paths are real things you can name:</p>
<ol>
<li>Live slip → <code>&quot;LIVE&quot;</code></li>
<li>Not live, no bets → <code>&quot;STANDARD&quot;</code></li>
<li>Not live, has a longshot bet → <code>&quot;LONGSHOT&quot;</code></li>
<li>Not live, has bets, none of them longshots → <code>&quot;STANDARD&quot;</code></li>
</ol>
<p>That&rsquo;s four test cases. Not &ldquo;one test, it&rsquo;s green&rdquo;, not &ldquo;a hundred tests to be safe&rdquo;. Four. This is the most practical thing about cyclomatic complexity: <strong>it tells you how many tests a method needs for every branch to be taken in both directions.</strong> Strictly speaking, CC is an upper bound for full branch coverage and a lower bound for full path coverage. In practice, &ldquo;CC tests per method&rdquo; is a very good starting number.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Test</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">liveSlipGetsLiveLabel</span><span class="p">()</span><span class="w">               </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Test</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">emptySlipGetsStandardLabel</span><span class="p">()</span><span class="w">          </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Test</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">longshotBetGetsLongshotLabel</span><span class="p">()</span><span class="w">        </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Test</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">regularBetsGetStandardLabel</span><span class="p">()</span><span class="w">         </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>If you write fewer tests than CC, some path is untested. That&rsquo;s not an opinion, it&rsquo;s arithmetic.</p>
<h3 id="what-counts-as-a-decision-point">What counts as a decision point</h3>
<p>This is where people get confused, so here&rsquo;s the list for Java. Each of these adds <strong>+1</strong>:</p>
<table>
  <thead>
      <tr>
          <th>Construct</th>
          <th>Why</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td><code>if</code></td>
          <td>two ways out</td>
      </tr>
      <tr>
          <td><code>else if</code></td>
          <td>it&rsquo;s another <code>if</code></td>
      </tr>
      <tr>
          <td><code>for</code>, <code>for-each</code>, <code>while</code>, <code>do-while</code></td>
          <td>loop again or exit</td>
      </tr>
      <tr>
          <td><code>case</code> in a <code>switch</code> (each one)</td>
          <td>each case is a separate route</td>
      </tr>
      <tr>
          <td><code>catch</code></td>
          <td>the exceptional route</td>
      </tr>
      <tr>
          <td><code>? :</code> (ternary)</td>
          <td>it&rsquo;s an <code>if</code> in disguise</td>
      </tr>
      <tr>
          <td><code>&amp;&amp;</code>, <code>||</code> in a condition</td>
          <td>short-circuit creates a route</td>
      </tr>
  </tbody>
</table>
<p>And these do <strong>not</strong> add anything:</p>
<table>
  <thead>
      <tr>
          <th>Construct</th>
          <th>Why not</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td><code>else</code></td>
          <td>it&rsquo;s the other side of an <code>if</code> that was already counted</td>
      </tr>
      <tr>
          <td><code>default</code> in a <code>switch</code></td>
          <td>it&rsquo;s the fallback, not a new decision</td>
      </tr>
      <tr>
          <td><code>try</code>, <code>finally</code></td>
          <td>they always run</td>
      </tr>
      <tr>
          <td><code>return</code>, <code>throw</code>, <code>break</code></td>
          <td>they end a route, they don&rsquo;t create one</td>
      </tr>
      <tr>
          <td>method calls</td>
          <td>the complexity lives in the called method</td>
      </tr>
  </tbody>
</table>
<p>One honest note: tools disagree on details. Checkstyle can count a whole <code>switch</code> as one decision if you set <code>switchBlockAsSingleDecisionPoint</code>. Some tools count <code>&amp;&amp;</code> and <code>||</code>, and some older ones don&rsquo;t. Don&rsquo;t argue with your linter about 11 vs 12. Argue about 12 vs 47.</p>
<h3 id="lets-count-timofei">Let&rsquo;s count Timofei</h3>
<p>Here&rsquo;s <code>placeBet()</code>, shrunk down to fit in a blog post. The real one was 412 lines with CC 47. This is just the trailer:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="n">BigDecimal</span><span class="w"> </span><span class="nf">placeBet</span><span class="p">(</span><span class="n">BetSlip</span><span class="w"> </span><span class="n">slip</span><span class="p">,</span><span class="w"> </span><span class="n">Player</span><span class="w"> </span><span class="n">player</span><span class="p">,</span><span class="w"> </span><span class="kt">boolean</span><span class="w"> </span><span class="n">live</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">BigDecimal</span><span class="w"> </span><span class="n">total</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">.</span><span class="na">ZERO</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">slip</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="kc">null</span><span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span><span class="n">slip</span><span class="p">.</span><span class="na">getBets</span><span class="p">()</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="kc">null</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">                     </span><span class="c1">// +2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="n">Bet</span><span class="w"> </span><span class="n">bet</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">slip</span><span class="p">.</span><span class="na">getBets</span><span class="p">())</span><span class="w"> </span><span class="p">{</span><span class="w">                              </span><span class="c1">// +1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">bet</span><span class="p">.</span><span class="na">isActive</span><span class="p">())</span><span class="w"> </span><span class="p">{</span><span class="w">                                     </span><span class="c1">// +1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">bet</span><span class="p">.</span><span class="na">getCategory</span><span class="p">()</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">Category</span><span class="p">.</span><span class="na">SPORTS</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">           </span><span class="c1">// +1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="n">total</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">total</span><span class="p">.</span><span class="na">add</span><span class="p">(</span><span class="n">bet</span><span class="p">.</span><span class="na">getStake</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="p">}</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">bet</span><span class="p">.</span><span class="na">getCategory</span><span class="p">()</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">Category</span><span class="p">.</span><span class="na">CASINO</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">    </span><span class="c1">// +1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">player</span><span class="p">.</span><span class="na">getAge</span><span class="p">()</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="n">21</span><span class="w"> </span><span class="o">||</span><span class="w"> </span><span class="n">player</span><span class="p">.</span><span class="na">isAdminOverride</span><span class="p">())</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="c1">// +2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                        </span><span class="n">total</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">total</span><span class="p">.</span><span class="na">add</span><span class="p">(</span><span class="n">bet</span><span class="p">.</span><span class="na">getStake</span><span class="p">().</span><span class="na">multiply</span><span class="p">(</span><span class="n">CASINO_TAX</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">}</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                        </span><span class="k">throw</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">IllegalStateException</span><span class="p">(</span><span class="s">&#34;Too young&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="p">}</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="n">total</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">total</span><span class="p">.</span><span class="na">add</span><span class="p">(</span><span class="n">bet</span><span class="p">.</span><span class="na">getStake</span><span class="p">().</span><span class="na">multiply</span><span class="p">(</span><span class="n">DEFAULT_TAX</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">player</span><span class="p">.</span><span class="na">isVip</span><span class="p">()</span><span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span><span class="o">!</span><span class="n">live</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">                                </span><span class="c1">// +2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">total</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">total</span><span class="p">.</span><span class="na">multiply</span><span class="p">(</span><span class="n">VIP_CASHBACK</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">live</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">                                            </span><span class="c1">// +1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">total</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">total</span><span class="p">.</span><span class="na">add</span><span class="p">(</span><span class="n">LIVE_FEE</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">try</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">notifier</span><span class="p">.</span><span class="na">send</span><span class="p">(</span><span class="n">player</span><span class="p">,</span><span class="w"> </span><span class="n">total</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w"> </span><span class="k">catch</span><span class="w"> </span><span class="p">(</span><span class="n">NotificationException</span><span class="w"> </span><span class="n">e</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">                           </span><span class="c1">// +1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">log</span><span class="p">.</span><span class="na">warn</span><span class="p">(</span><span class="s">&#34;whatever&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">total</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>12 decision points + 1 = <strong>CC 13</strong>. Thirteen tests for this tiny version. Timofei had one.</p>
<p>Also notice what CC <em>doesn&rsquo;t</em> tell you directly but you can feel anyway: to understand the casino branch you have to keep in your head that the slip is not null, the bets are not null, you&rsquo;re inside a loop, the bet is active, and it&rsquo;s not sports. That&rsquo;s five things of context before you even get to the age check. That&rsquo;s what Tom was drowning in.</p>
<h3 id="how-much-is-too-much">How much is too much</h3>
<p><img alt="A gauge called the Complexity-O-Meter with zones 1–10 chill, 11–20 careful, 21–50 risky, 50+ nope, and the needle on 47" loading="lazy" src="https://vitaliisukach.dev/posts/how-to-make-sure-they-can-never-fire-you/image-07.jpg"></p>
<p>McCabe himself suggested 10 as the upper limit for a method, and that number stuck. The commonly used scale (from the Software Engineering Institute) looks like this:</p>
<table>
  <thead>
      <tr>
          <th>CC</th>
          <th>What it means</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>1–10</td>
          <td>Simple, low risk, easy to test</td>
      </tr>
      <tr>
          <td>11–20</td>
          <td>More complex, moderate risk</td>
      </tr>
      <tr>
          <td>21–50</td>
          <td>Complex, high risk</td>
      </tr>
      <tr>
          <td>50+</td>
          <td>Untestable in practice, very high risk</td>
      </tr>
  </tbody>
</table>
<p>These aren&rsquo;t laws of physics. A <code>switch</code> mapping 15 enum values to 15 strings has CC 16 and is perfectly readable. But when a method with nested <code>if</code>s goes above 10, it&rsquo;s almost always a sign that it&rsquo;s doing more than one thing. Studies over the years have consistently found a correlation between high complexity and defect density, which matches every on-call shift I&rsquo;ve ever had.</p>
<h3 id="how-to-bring-it-down">How to bring it down</h3>
<p>The goal is not to make the number smaller for the sake of the number. The goal is that <strong>every method fits in one person&rsquo;s head</strong> and can be tested with a reasonable number of tests. The total amount of logic in the system usually stays about the same. You&rsquo;re just cutting it into pieces that can be understood one at a time.</p>
<p><img alt="Before: a purple monster with tentacles labelled if, for, &amp;&amp;, catch. After: five small friendly blobs, each with CC 1–3" loading="lazy" src="https://vitaliisukach.dev/posts/how-to-make-sure-they-can-never-fire-you/image-08.jpg"></p>
<h4 id="1-extract-method">1. Extract method</h4>
<p>The simplest and most effective one. Find a block that does one thing and give it a name.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="n">BigDecimal</span><span class="w"> </span><span class="nf">placeBet</span><span class="p">(</span><span class="n">BetSlip</span><span class="w"> </span><span class="n">slip</span><span class="p">,</span><span class="w"> </span><span class="n">Player</span><span class="w"> </span><span class="n">player</span><span class="p">,</span><span class="w"> </span><span class="kt">boolean</span><span class="w"> </span><span class="n">live</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">slip</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="kc">null</span><span class="w"> </span><span class="o">||</span><span class="w"> </span><span class="n">slip</span><span class="p">.</span><span class="na">getBets</span><span class="p">()</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="kc">null</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">                     </span><span class="c1">// CC 3</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">.</span><span class="na">ZERO</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">BigDecimal</span><span class="w"> </span><span class="n">total</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">slip</span><span class="p">.</span><span class="na">getBets</span><span class="p">().</span><span class="na">stream</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">.</span><span class="na">filter</span><span class="p">(</span><span class="n">Bet</span><span class="p">::</span><span class="n">isActive</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">.</span><span class="na">map</span><span class="p">(</span><span class="n">bet</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">bet</span><span class="p">.</span><span class="na">getCategory</span><span class="p">().</span><span class="na">stake</span><span class="p">(</span><span class="n">bet</span><span class="p">,</span><span class="w"> </span><span class="n">player</span><span class="p">))</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">.</span><span class="na">reduce</span><span class="p">(</span><span class="n">BigDecimal</span><span class="p">.</span><span class="na">ZERO</span><span class="p">,</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">::</span><span class="n">add</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">total</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">applyFees</span><span class="p">(</span><span class="n">total</span><span class="p">,</span><span class="w"> </span><span class="n">player</span><span class="p">,</span><span class="w"> </span><span class="n">live</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">notifyQuietly</span><span class="p">(</span><span class="n">player</span><span class="p">,</span><span class="w"> </span><span class="n">total</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">total</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">private</span><span class="w"> </span><span class="n">BigDecimal</span><span class="w"> </span><span class="nf">applyFees</span><span class="p">(</span><span class="n">BigDecimal</span><span class="w"> </span><span class="n">total</span><span class="p">,</span><span class="w"> </span><span class="n">Player</span><span class="w"> </span><span class="n">player</span><span class="p">,</span><span class="w"> </span><span class="kt">boolean</span><span class="w"> </span><span class="n">live</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">live</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">                                                       </span><span class="c1">// CC 3</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="n">total</span><span class="p">.</span><span class="na">add</span><span class="p">(</span><span class="n">LIVE_FEE</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">player</span><span class="p">.</span><span class="na">isVip</span><span class="p">())</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="n">total</span><span class="p">.</span><span class="na">multiply</span><span class="p">(</span><span class="n">VIP_CASHBACK</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">total</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">private</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">notifyQuietly</span><span class="p">(</span><span class="n">Player</span><span class="w"> </span><span class="n">player</span><span class="p">,</span><span class="w"> </span><span class="n">BigDecimal</span><span class="w"> </span><span class="n">total</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">try</span><span class="w"> </span><span class="p">{</span><span class="w">                                                             </span><span class="c1">// CC 2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">notifier</span><span class="p">.</span><span class="na">send</span><span class="p">(</span><span class="n">player</span><span class="p">,</span><span class="w"> </span><span class="n">total</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w"> </span><span class="k">catch</span><span class="w"> </span><span class="p">(</span><span class="n">NotificationException</span><span class="w"> </span><span class="n">e</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">log</span><span class="p">.</span><span class="na">warn</span><span class="p">(</span><span class="s">&#34;Failed to notify player {} about bet total&#34;</span><span class="p">,</span><span class="w"> </span><span class="n">player</span><span class="p">.</span><span class="na">getId</span><span class="p">(),</span><span class="w"> </span><span class="n">e</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p><code>placeBet()</code> now reads like a table of contents. You can understand what it does in five seconds, and you only go deeper into the part you actually care about. Tom&rsquo;s ticket about Polish live betting would have been a change in <code>applyFees()</code> with three tests next to it.</p>
<p>Notice that <code>applyFees()</code> also untangled the <code>isVip() &amp;&amp; !live</code> / <code>else if (live)</code> combo. Same behavior, but now the order of the checks tells the story: live first, then VIP. Untangling boolean logic often removes decisions on its own.</p>
<h4 id="2-replace-conditionals-with-polymorphism">2. Replace conditionals with polymorphism</h4>
<p>The <code>if (SPORTS) ... else if (CASINO) ... else</code> chain is a classic sign that the logic belongs to the type itself. In Java, an enum with behavior handles this really well:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">enum</span><span class="w"> </span><span class="n">Category</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">SPORTS</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nd">@Override</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">BigDecimal</span><span class="w"> </span><span class="nf">stake</span><span class="p">(</span><span class="n">Bet</span><span class="w"> </span><span class="n">bet</span><span class="p">,</span><span class="w"> </span><span class="n">Player</span><span class="w"> </span><span class="n">player</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">                    </span><span class="c1">// CC 1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="k">return</span><span class="w"> </span><span class="n">bet</span><span class="p">.</span><span class="na">getStake</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">CASINO</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nd">@Override</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">BigDecimal</span><span class="w"> </span><span class="nf">stake</span><span class="p">(</span><span class="n">Bet</span><span class="w"> </span><span class="n">bet</span><span class="p">,</span><span class="w"> </span><span class="n">Player</span><span class="w"> </span><span class="n">player</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">                    </span><span class="c1">// CC 2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">player</span><span class="p">.</span><span class="na">canPlayCasino</span><span class="p">())</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="k">throw</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">IllegalStateException</span><span class="p">(</span><span class="s">&#34;Too young&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="k">return</span><span class="w"> </span><span class="n">bet</span><span class="p">.</span><span class="na">getStake</span><span class="p">().</span><span class="na">multiply</span><span class="p">(</span><span class="n">Taxes</span><span class="p">.</span><span class="na">CASINO</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">OTHER</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nd">@Override</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">BigDecimal</span><span class="w"> </span><span class="nf">stake</span><span class="p">(</span><span class="n">Bet</span><span class="w"> </span><span class="n">bet</span><span class="p">,</span><span class="w"> </span><span class="n">Player</span><span class="w"> </span><span class="n">player</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">                    </span><span class="c1">// CC 1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="k">return</span><span class="w"> </span><span class="n">bet</span><span class="p">.</span><span class="na">getStake</span><span class="p">().</span><span class="na">multiply</span><span class="p">(</span><span class="n">Taxes</span><span class="p">.</span><span class="na">DEFAULT</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">};</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">abstract</span><span class="w"> </span><span class="n">BigDecimal</span><span class="w"> </span><span class="nf">stake</span><span class="p">(</span><span class="n">Bet</span><span class="w"> </span><span class="n">bet</span><span class="p">,</span><span class="w"> </span><span class="n">Player</span><span class="w"> </span><span class="n">player</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Adding a new game category no longer means finding the right <code>else if</code> in a 400-line method. You add a constant, and the compiler forces you to implement <code>stake()</code>.</p>
<p>If you&rsquo;re on Java 21, sealed interfaces with pattern matching are another option. They&rsquo;re a great fit when the variants carry different data:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">sealed</span><span class="w"> </span><span class="kd">interface</span> <span class="nc">Market</span><span class="w"> </span><span class="n">permits</span><span class="w"> </span><span class="n">PreMatch</span><span class="p">,</span><span class="w"> </span><span class="n">Live</span><span class="p">,</span><span class="w"> </span><span class="n">Outright</span><span class="w"> </span><span class="p">{}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">record</span> <span class="nc">PreMatch</span><span class="p">()</span><span class="w"> </span><span class="kd">implements</span><span class="w"> </span><span class="n">Market</span><span class="w"> </span><span class="p">{}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">record</span> <span class="nc">Live</span><span class="p">(</span><span class="n">Duration</span><span class="w"> </span><span class="n">betDelay</span><span class="p">)</span><span class="w"> </span><span class="kd">implements</span><span class="w"> </span><span class="n">Market</span><span class="w"> </span><span class="p">{}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">record</span> <span class="nc">Outright</span><span class="p">(</span><span class="n">String</span><span class="w"> </span><span class="n">tournamentId</span><span class="p">)</span><span class="w"> </span><span class="kd">implements</span><span class="w"> </span><span class="n">Market</span><span class="w"> </span><span class="p">{}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">BigDecimal</span><span class="w"> </span><span class="nf">fee</span><span class="p">(</span><span class="n">Market</span><span class="w"> </span><span class="n">market</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="k">switch</span><span class="w"> </span><span class="p">(</span><span class="n">market</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">case</span><span class="w"> </span><span class="n">PreMatch</span><span class="w"> </span><span class="n">p</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">.</span><span class="na">ZERO</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">case</span><span class="w"> </span><span class="n">Live</span><span class="w"> </span><span class="n">l</span><span class="w">     </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">LIVE_FEE</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">case</span><span class="w"> </span><span class="n">Outright</span><span class="w"> </span><span class="n">o</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">.</span><span class="na">ZERO</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">};</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Strictly by the numbers this <code>switch</code> still has CC 4, because each <code>case</code> counts. But it&rsquo;s flat, there&rsquo;s no nesting, and the compiler tells you when you forget a case. Which brings us to an important point a bit later.</p>
<h4 id="3-move-the-condition-to-where-the-data-lives">3. Move the condition to where the data lives</h4>
<p><code>player.getAge() &gt;= 21 || player.isAdminOverride()</code> is a business rule about players, sitting inside a betting method. Give it a name and put it on <code>Player</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kt">boolean</span><span class="w"> </span><span class="nf">canPlayCasino</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">                                      </span><span class="c1">// CC 2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">age</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="n">21</span><span class="w"> </span><span class="o">||</span><span class="w"> </span><span class="n">adminOverride</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>The complexity didn&rsquo;t disappear, it moved. But now it&rsquo;s in one place, it has a name that explains the intent, and it&rsquo;s tested once instead of being copy-pasted into three branches of <code>placeBet()</code> (which, remember, is exactly what happened with the live fee).</p>
<h4 id="4-replace-branching-with-data">4. Replace branching with data</h4>
<p>A lot of <code>switch</code> and <code>if/else if</code> chains are really just lookup tables wearing a costume:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="c1">// CC 5</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">BigDecimal</span><span class="w"> </span><span class="nf">bettingTaxRate</span><span class="p">(</span><span class="n">Country</span><span class="w"> </span><span class="n">country</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">country</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">Country</span><span class="p">.</span><span class="na">UA</span><span class="p">)</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">(</span><span class="s">&#34;0.18&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">else</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">country</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">Country</span><span class="p">.</span><span class="na">GB</span><span class="p">)</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">(</span><span class="s">&#34;0.15&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">else</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">country</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">Country</span><span class="p">.</span><span class="na">PL</span><span class="p">)</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">(</span><span class="s">&#34;0.12&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">else</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">country</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">Country</span><span class="p">.</span><span class="na">DE</span><span class="p">)</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">(</span><span class="s">&#34;0.053&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">DEFAULT_BETTING_TAX</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="c1">// CC 1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">private</span><span class="w"> </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">Map</span><span class="o">&lt;</span><span class="n">Country</span><span class="p">,</span><span class="w"> </span><span class="n">BigDecimal</span><span class="o">&gt;</span><span class="w"> </span><span class="n">BETTING_TAX</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Map</span><span class="p">.</span><span class="na">of</span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Country</span><span class="p">.</span><span class="na">UA</span><span class="p">,</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">(</span><span class="s">&#34;0.18&#34;</span><span class="p">),</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Country</span><span class="p">.</span><span class="na">GB</span><span class="p">,</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">(</span><span class="s">&#34;0.15&#34;</span><span class="p">),</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Country</span><span class="p">.</span><span class="na">PL</span><span class="p">,</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">(</span><span class="s">&#34;0.12&#34;</span><span class="p">),</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Country</span><span class="p">.</span><span class="na">DE</span><span class="p">,</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">BigDecimal</span><span class="p">(</span><span class="s">&#34;0.053&#34;</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">BigDecimal</span><span class="w"> </span><span class="nf">bettingTaxRate</span><span class="p">(</span><span class="n">Country</span><span class="w"> </span><span class="n">country</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">BETTING_TAX</span><span class="p">.</span><span class="na">getOrDefault</span><span class="p">(</span><span class="n">country</span><span class="p">,</span><span class="w"> </span><span class="n">DEFAULT_BETTING_TAX</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>This one is a real reduction. The decisions are gone, not moved. And when rates live in data, they can come from config or a database later without touching code.</p>
<h4 id="5-guard-clauses-and-a-little-honesty">5. Guard clauses (and a little honesty)</h4>
<p>You&rsquo;ll see &ldquo;use guard clauses&rdquo; in every list of tips for reducing complexity. Here&rsquo;s the thing: guard clauses usually <strong>don&rsquo;t</strong> change the cyclomatic complexity number. This:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">bet</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="kc">null</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">bet</span><span class="p">.</span><span class="na">isWon</span><span class="p">())</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">bet</span><span class="p">.</span><span class="na">isPaidOut</span><span class="p">())</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">payOut</span><span class="p">(</span><span class="n">bet</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>and this:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">bet</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="kc">null</span><span class="p">)</span><span class="w"> </span><span class="k">return</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">bet</span><span class="p">.</span><span class="na">isWon</span><span class="p">())</span><span class="w"> </span><span class="k">return</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">bet</span><span class="p">.</span><span class="na">isPaidOut</span><span class="p">())</span><span class="w"> </span><span class="k">return</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">payOut</span><span class="p">(</span><span class="n">bet</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>both have CC 4. Same number of decisions. But the second one is clearly easier to read, because you never have to remember three levels of &ldquo;we&rsquo;re inside of&hellip;&rdquo;. That&rsquo;s a real improvement that cyclomatic complexity just can&rsquo;t see. Which leads to&hellip;</p>
<h3 id="cyclomatic-complexitys-younger-sibling">Cyclomatic complexity&rsquo;s younger sibling</h3>
<p>Cyclomatic complexity measures <strong>how hard code is to test</strong>. It doesn&rsquo;t measure very well <strong>how hard code is to read</strong>. A flat <code>switch</code> with 12 cases and a pyramid of 4 nested <code>if</code>s can have similar CC, but one of them makes you want to quit your job.</p>
<p>That&rsquo;s why SonarSource introduced <strong>cognitive complexity</strong> in 2017. It also adds +1 for each branch, but it adds <em>extra</em> points for nesting, and it counts a whole <code>switch</code> as just +1:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="c1">// Cyclomatic: 4    Cognitive: 6</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">a</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">                    </span><span class="c1">// +1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="n">Bet</span><span class="w"> </span><span class="n">bet</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">bets</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">  </span><span class="c1">// +2 (nested once)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">b</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">            </span><span class="c1">// +3 (nested twice)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">...</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="c1">// Cyclomatic: 13   Cognitive: 1</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">return</span><span class="w"> </span><span class="k">switch</span><span class="w"> </span><span class="p">(</span><span class="n">status</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">case</span><span class="w"> </span><span class="n">PENDING</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">...;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">case</span><span class="w"> </span><span class="n">WON</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">...;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// ... 10 more cases</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">};</span><span class="w">
</span></span></span></code></pre></div><p>Use both. Cyclomatic complexity tells you how many tests to write. Cognitive complexity tells you how much your colleagues will curse you. Timofei&rsquo;s method was terrible on both.</p>
<h3 id="making-the-robots-tell-timofei">Making the robots tell Timofei</h3>
<p>Nobody wants to be the person who says &ldquo;your method is too complex&rdquo; in every code review. Let a tool do it. Then it&rsquo;s not personal, it&rsquo;s the build.</p>
<p><strong>Checkstyle</strong> (<code>config/checkstyle/checkstyle.xml</code>):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-xml" data-lang="xml"><span class="line"><span class="cl"><span class="nt">&lt;module</span> <span class="na">name=</span><span class="s">&#34;TreeWalker&#34;</span><span class="nt">&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&lt;module</span> <span class="na">name=</span><span class="s">&#34;CyclomaticComplexity&#34;</span><span class="nt">&gt;</span>
</span></span><span class="line"><span class="cl">        <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&#34;max&#34;</span> <span class="na">value=</span><span class="s">&#34;10&#34;</span><span class="nt">/&gt;</span>
</span></span><span class="line"><span class="cl">        <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&#34;switchBlockAsSingleDecisionPoint&#34;</span> <span class="na">value=</span><span class="s">&#34;true&#34;</span><span class="nt">/&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&lt;/module&gt;</span>
</span></span><span class="line"><span class="cl"><span class="nt">&lt;/module&gt;</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-groovy" data-lang="groovy"><span class="line"><span class="cl"><span class="c1">// build.gradle
</span></span></span><span class="line"><span class="cl"><span class="c1"></span><span class="n">plugins</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">    <span class="n">id</span> <span class="s1">&#39;checkstyle&#39;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">checkstyle</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">    <span class="n">maxWarnings</span> <span class="o">=</span> <span class="mi">0</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span></code></pre></div><p><strong>PMD</strong> has the same rule, with separate limits for methods and whole classes:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-xml" data-lang="xml"><span class="line"><span class="cl"><span class="nt">&lt;rule</span> <span class="na">ref=</span><span class="s">&#34;category/java/design.xml/CyclomaticComplexity&#34;</span><span class="nt">&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&lt;properties&gt;</span>
</span></span><span class="line"><span class="cl">        <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&#34;methodReportLevel&#34;</span> <span class="na">value=</span><span class="s">&#34;10&#34;</span><span class="nt">/&gt;</span>
</span></span><span class="line"><span class="cl">        <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">&#34;classReportLevel&#34;</span> <span class="na">value=</span><span class="s">&#34;80&#34;</span><span class="nt">/&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&lt;/properties&gt;</span>
</span></span><span class="line"><span class="cl"><span class="nt">&lt;/rule&gt;</span>
</span></span><span class="line"><span class="cl"><span class="nt">&lt;rule</span> <span class="na">ref=</span><span class="s">&#34;category/java/design.xml/CognitiveComplexity&#34;</span><span class="nt">/&gt;</span>
</span></span></code></pre></div><p><strong>SonarQube / SonarCloud</strong> has both rules out of the box: S1541 for cyclomatic complexity and S3776 for cognitive complexity (default threshold 15).</p>
<p><strong>In IntelliJ IDEA</strong>, the <em>MetricsReloaded</em> plugin shows CC for every method in the project and lets you sort by it. Run it once on your codebase. The top 10 will be very familiar to whoever is on call most often.</p>
<p>On a legacy project you can&rsquo;t turn on <code>max=10</code> and fail the build tomorrow. Start with whatever your worst method is (say, 47), set the limit there so things can&rsquo;t get worse, and lower it a little every sprint. The boy scout rule, but enforced by CI.</p>
<h3 id="epilogue">Epilogue</h3>
<p>Timofei still works on the team. But <code>placeBet()</code> is now five methods and an enum, the biggest of them has CC 3, and there are 19 tests where there used to be one.</p>
<p>Last week Tom got a ticket to add a new game category. It was 1 point. It took 1 point.</p>
<p>Timofei reviewed it. He said &ldquo;looks fine&rdquo;, and then, after a pause, &ldquo;that&rsquo;s actually easy to read&rdquo;.</p>
<p>He still says &ldquo;I understand my code&rdquo;. He just added a second part: &ldquo;&hellip;and so does the build&rdquo;.</p>
<p>Funny thing: nobody worries about replacing Timofei anymore, and nobody wants to. He&rsquo;s the person who made <code>placeBet()</code> easy enough for a junior to change in his second week. That&rsquo;s the real way to make sure they never fire you. Not by being the only one who understands the code, but by being the one who made everyone else understand it.</p>
<h3 id="quick-checklist">Quick checklist</h3>
<ul>
<li>Do you know the CC of the five methods that cause the most incidents? (They&rsquo;re probably the same five.)</li>
<li>Does any method have fewer tests than its cyclomatic complexity?</li>
<li>Is there a CC limit in your build, even a high one?</li>
<li>Do you have <code>if/else if</code> chains on an enum or a type field that could be polymorphism or a <code>Map</code>?</li>
<li>Is the same business rule (age checks, VIP checks, live fees) copy-pasted into several branches?</li>
<li>When you write &ldquo;I understand this&rdquo;, would you still understand it in three weeks, at 3 AM, without your sunglasses?</li>
<li>Is your job security based on code nobody else can read? Then it&rsquo;s not job security, it&rsquo;s a hostage situation.</li>
</ul>
]]></content:encoded></item><item><title>RAG in Java with LangChain4j: Teaching a Local LLM About a Company That Doesn’t Exist</title><link>https://vitaliisukach.dev/posts/rag-in-java-with-langchain4j-teaching-a-local-llm-about-a-company-that-doesnt-exist/</link><pubDate>Sat, 17 Oct 2026 13:01:45 +0000</pubDate><guid>https://vitaliisukach.dev/posts/rag-in-java-with-langchain4j-teaching-a-local-llm-about-a-company-that-doesnt-exist/</guid><description>&lt;p>&lt;em>Chunks, vectors, a bit of geometry, and no magic. Everything runs on your laptop.&lt;/em>&lt;/p>
&lt;p>&lt;img loading="lazy" src="https://vitaliisukach.dev/posts/rag-in-java-with-langchain4j-teaching-a-local-llm-about-a-company-that-doesnt-exist/image-01.png">&lt;/p>
&lt;p>Ask an LLM “When does the nightly settlement batch run at Harbourline Payments?” and one of two things happens.&lt;/p>
&lt;p>The polite model says it doesn’t know. The confident model says “Usually around midnight!” with the energy of a student who didn’t read the book but really wants a good mark.&lt;/p>
&lt;p>Both are fair, because Harbourline Payments doesn’t exist. I made it up. It’s a fictional company with a fictional engineering handbook: founders, services, deploy rules, on-call pay, and even a famous incident called “the Double Tap”. No model has seen this text during training.&lt;/p></description><content:encoded><![CDATA[<p><em>Chunks, vectors, a bit of geometry, and no magic. Everything runs on your laptop.</em></p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/rag-in-java-with-langchain4j-teaching-a-local-llm-about-a-company-that-doesnt-exist/image-01.png"></p>
<p>Ask an LLM “When does the nightly settlement batch run at Harbourline Payments?” and one of two things happens.</p>
<p>The polite model says it doesn’t know. The confident model says “Usually around midnight!” with the energy of a student who didn’t read the book but really wants a good mark.</p>
<p>Both are fair, because Harbourline Payments doesn’t exist. I made it up. It’s a fictional company with a fictional engineering handbook: founders, services, deploy rules, on-call pay, and even a famous incident called “the Double Tap”. No model has seen this text during training.</p>
<p>That’s exactly why it’s a good test. If the model answers “02:30 UK time” correctly, it didn’t remember it. It <strong>found</strong> it. That’s RAG.</p>
<p>In this article we’ll build a small RAG service in Java with Spring Boot, LangChain4j, PostgreSQL with pgvector, and Ollama. No cloud, no API keys, no bill at the end of the month.</p>
<p>The full code is on GitHub: <a href="https://github.com/SukachVitally/rag-demo">SukachVitally/rag-demo</a>.</p>
<h3 id="what-is-rag-in-oneexam">What is RAG, in one exam</h3>
<p>RAG stands for <strong>Retrieval-Augmented Generation</strong>. Long name, simple idea.</p>
<p>Think about two exams:</p>
<ul>
<li><strong>Closed-book exam.</strong> The student answers from memory. This is a normal LLM. It knows a lot, but only what it learned during training. It knows nothing about your company’s wiki, last week’s incident, or your internal rules. If it doesn’t know, it may still try to sound smart.</li>
<li><strong>Open-book exam.</strong> Before answering, the student finds the right pages in the book and reads them. This is RAG.</li>
</ul>
<p>So RAG doesn’t make the model smarter. It gives the model a cheat sheet for each question: “Here are 5 pieces of text that look relevant. Answer using only these.”</p>
<p>Why not just put the whole handbook into the prompt? For one small file you can. But real knowledge bases have thousands of documents. They don’t fit into the context window, and even when they do, you pay for every token on every question. RAG sends only the few pieces that matter.</p>
<h3 id="the-bigidea">The big idea</h3>
<p>The whole thing is two flows.</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/rag-in-java-with-langchain4j-teaching-a-local-llm-about-a-company-that-doesnt-exist/image-02.png"></p>
<p><strong>Ingest (once per document):</strong></p>
<ol>
<li>Take the text and split it into small pieces called <strong>chunks</strong>.</li>
<li>Ask an <strong>embedding model</strong> to turn each chunk into a vector: a long list of numbers.</li>
<li>Save each chunk together with its vector in the database.</li>
</ol>
<p><strong>Ask (every question):</strong></p>
<ol>
<li>Ask the <strong>same</strong> embedding model to turn the question into a vector.</li>
<li>Find the chunks whose vectors are <strong>closest</strong> to the question vector.</li>
<li>Send the question and those chunks to a <strong>chat model</strong> and ask it to answer using only these chunks.</li>
</ol>
<p>That’s it. The rest of this article is details.</p>
<p>Notice that there are <strong>two different models</strong>:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/rag-in-java-with-langchain4j-teaching-a-local-llm-about-a-company-that-doesnt-exist/image-03.png"></p>
<p>The embedding model is small and fast. The chat model is the big one. Both run locally in Ollama.</p>
<h3 id="wait-what-is-thisvector">Wait, what is this vector?</h3>
<p>This is the most interesting part, so let’s slow down a little.</p>
<p>An embedding model reads a piece of text and returns a fixed-size array of numbers. nomic-embed-text returns <strong>768</strong> numbers for any text, whether it&rsquo;s one word or a full paragraph:</p>
<pre tabindex="0"><code>&#34;settlement batch runs at 02:30&#34;  →  [-0.064, 0.142, 0.009, ... 765 more ...]
</code></pre><p>The model is trained so that texts with <strong>similar meaning</strong> get vectors that point in a <strong>similar direction</strong>. “When does the nightly batch run?” and “settlement-service runs the nightly batch at 02:30” share almost no grammar, but their meaning is close, so their vectors are close too.</p>
<p>Now the fun part. It’s natural to think that each number means something: dimension 17 is “money”, dimension 302 is “time of day”, dimension 555 is “how angry the on-call engineer is”. It doesn’t work like that.</p>
<p><strong>No single dimension has a physical meaning.</strong> Nobody designed these axes. The model learned the layout by itself during training. Meaning is spread across all 768 numbers at once, a bit like a smell is spread across many different molecules. You can’t point at one number and say “this is the time part”. Only the vector as a whole means something, and only when you compare it with other vectors.</p>
<p>Here’s a 2D sketch of what that looks like. The real space has 768 dimensions, and I have only two axes on my screen:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/rag-in-java-with-langchain4j-teaching-a-local-llm-about-a-company-that-doesnt-exist/image-04.png"></p>
<p>The question vector points almost in the same direction as the “settlement batch runs at 02:30” chunk. The sourdough recipe chunk points somewhere else entirely. So for a computer, “similar meaning” becomes simple geometry: <strong>a small angle between two vectors</strong>.</p>
<p>The usual way to measure this is <strong>cosine similarity</strong>, the cosine of that angle:</p>
<ul>
<li>1: same direction, very similar</li>
<li>0: unrelated</li>
<li>-1: opposite direction</li>
</ul>
<p>LangChain4j turns it into a friendlier score from 0 to 1: (1 + cos θ) / 2. That&rsquo;s the score you&rsquo;ll see in the API response later.</p>
<p>One important rule: vectors from different embedding models are <strong>not compatible</strong>. Each model builds its own space with its own layout. If you change the embedding model, you have to re-embed all your documents. It’s like changing the map projection: the old coordinates don’t match the new map.</p>
<h3 id="the-stack">The stack</h3>
<ul>
<li><strong>Java 25</strong> and <strong>Spring Boot 4.1</strong>: the usual REST app.</li>
<li><strong>LangChain4j 1.22</strong>: the Java library that does the AI work.</li>
<li><strong>Ollama</strong>: runs both models locally.</li>
<li><strong>PostgreSQL 17 + pgvector</strong>: stores chunks and vectors, and searches by similarity.</li>
<li><strong>Testcontainers</strong>: for functional tests with a real database.</li>
</ul>
<p>Run the infrastructure with one command:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/rag-demo/blob/main/docker-compose.yaml"><em>docker-compose.yaml</em></a></p>
<pre tabindex="0"><code>services:
  db:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_DB: rag
      POSTGRES_USER: rag
      POSTGRES_PASSWORD: rag
    ports: [&#34;5432:5432&#34;]
  ollama:
    image: ollama/ollama
    ports: [&#34;11434:11434&#34;]
    volumes:
      - ollama-models:/root/.ollama   # keeps downloaded models between restarts
  ollama-init:
    image: ollama/ollama
    depends_on: [ollama]
    environment:
      OLLAMA_HOST: ollama:11434
    entrypoint: [&#34;sh&#34;, &#34;-c&#34;, &#34;sleep 5 &amp;&amp; ollama pull nomic-embed-text &amp;&amp; ollama pull llama3.1:8b&#34;]
volumes:
  ollama-models:
</code></pre><p>The ollama-init container is a one-off job that downloads the models. The first time it pulls a few GB, so it&rsquo;s a good moment to make some tea.</p>
<h3 id="langchain4j-ai-lego-forjava">LangChain4j: AI LEGO for Java</h3>
<p>LangChain4j is to AI roughly what Spring Data is to databases. It gives you small interfaces with many implementations, so your code doesn’t depend on a specific vendor.</p>
<p>The demo uses four building blocks, plus one helper that glues three of them together:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/rag-in-java-with-langchain4j-teaching-a-local-llm-about-a-company-that-doesnt-exist/image-05.png"></p>
<ul>
<li><strong>DocumentSplitter</strong> cuts text into chunks.</li>
<li><strong>EmbeddingModel</strong> turns text into a vector. Here it&rsquo;s OllamaEmbeddingModel.</li>
<li><strong><code>EmbeddingStore&lt;TextSegment&gt;</code></strong> saves vectors and finds the nearest ones. Here it&rsquo;s PgVectorEmbeddingStore.</li>
<li><strong>ChatModel</strong> sends a prompt and gets an answer. Here it&rsquo;s OllamaChatModel.</li>
<li><strong>EmbeddingStoreIngestor</strong> runs split → embed → store in one call.</li>
</ul>
<p>The nice part is the bottom of that picture. Want OpenAI instead of Ollama? Change one bean. Want Qdrant instead of Postgres? Change one bean. The services don’t care.</p>
<h3 id="dependencies">Dependencies</h3>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/rag-demo/blob/main/build.gradle"><em>build.gradle</em></a></p>
<pre tabindex="0"><code>dependencies {
    implementation &#39;org.springframework.boot:spring-boot-starter-jdbc&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-webmvc&#39;
    implementation &#39;dev.langchain4j:langchain4j:1.22.0&#39;
    implementation &#39;dev.langchain4j:langchain4j-ollama:1.22.0&#39;
    implementation &#39;dev.langchain4j:langchain4j-pgvector:1.22.0-beta32&#39;
    runtimeOnly &#39;org.postgresql:postgresql&#39;
}
</code></pre><p>Three LangChain4j modules: the core, the Ollama integration and the pgvector store. That’s all.</p>
<h3 id="wiring-thebeans">Wiring the beans</h3>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/rag-demo/blob/main/src/main/java/org/example/ragdemo/config/LangChain4jConfig.java"><em>LangChain4jConfig.java</em></a></p>
<pre tabindex="0"><code>@Configuration
public class LangChain4jConfig {
    public static final String CHUNK_TABLE = &#34;chunk_embedding&#34;;
    @Bean
    EmbeddingModel embeddingModel(OllamaClientProperty property) {
        return OllamaEmbeddingModel.builder()
                .baseUrl(property.baseUrl())
                .modelName(property.embedModel())
                .build();
    }
    @Bean
    ChatModel chatModel(OllamaClientProperty property) {
        return OllamaChatModel.builder()
                .baseUrl(property.baseUrl())
                .modelName(property.chatModel())
                .build();
    }
    @Bean
    DocumentSplitter documentSplitter(ChunkProperty property) {
        return DocumentSplitters.recursive(property.size(), property.overlap());
    }
    @Bean
    EmbeddingStore&lt;TextSegment&gt; embeddingStore(DataSource dataSource) {
        return PgVectorEmbeddingStore.datasourceBuilder()
                .datasource(dataSource)
                .table(CHUNK_TABLE)
                .createTable(false)
                .skipCreateVectorExtension(true)
                .metadataStorageConfig(DefaultMetadataStorageConfig.builder()
                        .storageMode(MetadataStorageMode.COMBINED_JSONB)
                        .columnDefinitions(List.of(&#34;metadata JSONB NULL&#34;))
                        .build())
                .build();
    }
}
</code></pre><p>The embedding store reuses Spring’s DataSource, so there&rsquo;s one connection pool and one config. I also told it <strong>not</strong> to create the table (createTable(false)) because I prefer to own the schema myself:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/rag-demo/blob/main/src/main/resources/schema.sql"><em>schema.sql</em></a></p>
<pre tabindex="0"><code>CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE IF NOT EXISTS chunk_embedding (
    embedding_id UUID PRIMARY KEY,
    embedding    vector(768) NOT NULL,
    text         TEXT NULL,
    metadata     JSONB NULL
);
CREATE INDEX IF NOT EXISTS chunk_embedding_hnsw
    ON chunk_embedding USING hnsw (embedding vector_cosine_ops);
</code></pre><p>Two things to notice:</p>
<ul>
<li>vector(768) is the pgvector column type. 768 must match the embedding model&rsquo;s output. If you switch to a model with 1024 dimensions, this column has to change too.</li>
<li>The <strong>HNSW index</strong> with vector_cosine_ops makes nearest-neighbour search fast. Without it, Postgres compares the question with every row. That&rsquo;s fine for 9 chunks, but not for 9 million. HNSW is an approximate search: it trades a tiny bit of accuracy for a lot of speed.</li>
</ul>
<p>Everything is configurable in application.yaml:</p>
<pre tabindex="0"><code>app:
  olama-client:
    base-url: http://localhost:11434
    embed-model: nomic-embed-text
    chat-model: llama3.1:8b
  chunk:
    size: 1000
    overlap: 150
</code></pre><h3 id="part-1-ingest-or-feeding-thedatabase">Part 1: Ingest, or feeding the database</h3>
<p>Here’s what happens to a document on the way in:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/rag-in-java-with-langchain4j-teaching-a-local-llm-about-a-company-that-doesnt-exist/image-06.png"></p>
<h3 id="why-chunks">Why chunks?</h3>
<p>Why not embed the whole document as one vector? Because one vector for a whole handbook would be an average of everything: founders, deploy rules, on-call pay, the sourdough recipe someone accidentally uploaded. It would be “kind of about everything”, and that means it’s close to nothing.</p>
<p>Small chunks keep the meaning sharp. One chunk is about the settlement batch, another is about deploy windows. Now the search can find the right one.</p>
<p>The demo uses DocumentSplitters.recursive(1000, 150):</p>
<ul>
<li><strong>1000</strong>: the maximum chunk size in characters.</li>
<li><strong>150</strong>: overlap. Each chunk repeats about 150 characters from the end of the previous one. So if an important sentence lands on a border, it’s still complete in at least one chunk.</li>
<li><strong>Recursive</strong> means it tries to cut nicely. First by paragraphs. If a paragraph is too big, then by lines, then by sentences, then by words. It cuts the text like a polite butcher, not with a chainsaw.</li>
</ul>
<h3 id="the-ingestservice">The ingest service</h3>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/rag-demo/blob/main/src/main/java/org/example/ragdemo/service/IngestService.java"><em>IngestService.java</em></a></p>
<pre tabindex="0"><code>@Service
@RequiredArgsConstructor
public class IngestService {
    public static final String SOURCE = &#34;source&#34;;
    private final DocumentSplitter splitter;
    private final EmbeddingModel embeddingModel;
    private final EmbeddingStore&lt;TextSegment&gt; store;
    
    public int ingest(String source, String text) {
        if (text.isBlank()) return 0;
        var chunks = new AtomicInteger();
        EmbeddingStoreIngestor.builder()
                .documentSplitter(splitter)
                .textSegmentTransformer(segment -&gt; { chunks.incrementAndGet(); return segment; })
                .embeddingModel(embeddingModel)
                .embeddingStore(store)
                .build()
                .ingest(Document.from(text, Metadata.from(SOURCE, source)));
        return chunks.get();
    }
}
</code></pre><p>EmbeddingStoreIngestor does all three steps for us: split, embed, store. The textSegmentTransformer is a hook that runs for every chunk. Here I only use it to count chunks for the API response, but it&rsquo;s also the right place to clean text or add extra metadata.</p>
<p>The source metadata (the file name) travels with every chunk into the metadata JSONB column. Later it lets the answer say <em>where</em> the information came from.</p>
<p>The controller is a plain multipart upload:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/rag-demo/blob/main/src/main/java/org/example/ragdemo/controller/RagController.java"><em>RagController.java</em></a></p>
<pre tabindex="0"><code>@PostMapping(value = &#34;/ingest&#34;, consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public Map&lt;String, Object&gt; upload(@RequestParam MultipartFile file) throws IOException {
    String text = new String(file.getBytes(), StandardCharsets.UTF_8);
    return Map.of(&#34;chunks&#34;, ingest.ingest(file.getOriginalFilename(), text));
}
</code></pre><p>Let’s feed it the Harbourline handbook:</p>
<pre tabindex="0"><code>curl -F file=@docs/notes.md http://localhost:8080/api/ingest
</code></pre><pre tabindex="0"><code>{ &#34;chunks&#34;: 9 }
</code></pre><p>Nine chunks, nine vectors, nine rows. The database now knows about a company that doesn’t exist.</p>
<h3 id="part-2-ask-or-the-open-book-exam">Part 2: Ask, or the open-book exam</h3>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/rag-demo/blob/main/src/main/java/org/example/ragdemo/service/RagService.java"><em>RagService.java</em></a></p>
<pre tabindex="0"><code>@Service
@RequiredArgsConstructor
public class RagService {
    private final EmbeddingModel embeddingModel;
    private final EmbeddingStore&lt;TextSegment&gt; store;
    private final ChatModel chatModel;
    private static final String SYSTEM = &#34;&#34;&#34;
        Answer using ONLY the provided context. If the answer is not in the
        context, say you don&#39;t know. Cite sources as [1], [2]...&#34;&#34;&#34;;
    
public record Answer(String answer, List&lt;Hit&gt; sources) {}
    public Answer ask(String question) {
        var q = embeddingModel.embed(question).content();
        var hits = store.search(EmbeddingSearchRequest.builder().queryEmbedding(q).maxResults(5).build())
                .matches().stream()
                .map(m -&gt; new Hit(m.embedded().metadata().getString(IngestService.SOURCE), m.embedded().text(), m.score()))
                .toList();
        var ctx = new StringBuilder();
        for (int i = 0; i &lt; hits.size(); i++)
            ctx.append(&#34;[&#34;).append(i + 1).append(&#34;] (&#34;).append(hits.get(i).source()).append(&#34;)\n&#34;)
                    .append(hits.get(i).content()).append(&#34;\n\n&#34;);
        String prompt = &#34;Context:\n&#34; + ctx + &#34;\nQuestion: &#34; + question;
        return new Answer(chatModel.chat(SystemMessage.from(SYSTEM), UserMessage.from(prompt)).aiMessage().text(), hits);
    }
}
</code></pre><p>This is the heart of the project, and it follows the plan exactly:</p>
<ol>
<li><strong>Embed the question</strong> with the same model we used for the chunks. Same model means same space, so the distances make sense.</li>
<li><strong>Search</strong> the store for the 5 nearest vectors. Under the hood, pgvector uses the HNSW index and cosine distance.</li>
<li><strong>Build the context</strong>: number each chunk and add its source.</li>
<li><strong>Ask the chat model</strong> with a strict system message: use only the context, say “I don’t know” if the answer isn’t there, and cite sources.</li>
</ol>
<p>This is roughly what llama actually receives:</p>
<pre tabindex="0"><code>SYSTEM:
Answer using ONLY the provided context. If the answer is not in the
context, say you don&#39;t know. Cite sources as [1], [2]...
</code></pre><pre tabindex="0"><code>USER:
Context:
[1] (notes.md)
... settlement-service — runs the nightly settlement batch at 02:30 UK time ...
</code></pre><pre tabindex="0"><code>[2] (notes.md)
...
</code></pre><pre tabindex="0"><code>Question: When does the nightly settlement batch run?
</code></pre><p>The chat model never sees the database, the vectors or the other chunks. It sees a small, focused cheat sheet and a question. Its job is now easy: read and summarise.</p>
<p>Let’s try it:</p>
<pre tabindex="0"><code>curl -H &#39;Content-Type: application/json&#39; \
     -d &#39;{&#34;question&#34;: &#34;When does the nightly settlement batch run?&#34;}&#39; \
     http://localhost:8080/api/ask
</code></pre><pre tabindex="0"><code>{
  &#34;answer&#34;: &#34;According to the context in [3] (notes.md), the nightly settlement batch runs at 02:30 UK time.&#34;,
  &#34;sources&#34;: [
    { &#34;source&#34;: &#34;notes.md&#34;, &#34;content&#34;: &#34;...&#34;, &#34;score&#34;: 0.79 }
  ]
}
</code></pre><p>02:30 UK time. Correct, and with a source. Open-book exam passed. 🎓</p>
<p>The sources list matters as much as the answer. You can show it to users, so they can check where the answer came from instead of trusting the model blindly. Trust, but verify, especially with an 8B model.</p>
<h3 id="things-to-keep-inmind">Things to keep in mind</h3>
<p>The demo is small on purpose. Before you take it to production, think about these:</p>
<ul>
<li><strong>Chunk size is a trade-off.</strong> Too small, and a chunk loses context (“it runs at 02:30”, but what is “it”?). Too big, and the meaning gets blurry again. 1000/150 is a reasonable start, not a law.</li>
<li><strong>The top 5 are always returned,</strong> even when nothing is relevant. Ask about pizza, and you’ll still get the 5 “least irrelevant” chunks. The strict system prompt helps the model say “I don’t know”. In a real system I’d also add a minimum score (EmbeddingSearchRequest supports minScore).</li>
<li><strong>Changing the embedding model means re-ingesting everything.</strong> Different model, different space, different vector(N) column.</li>
<li><strong>Re-uploading the same file creates duplicates.</strong> The demo only appends. A real system needs to update or delete chunks by source.</li>
<li><strong>Garbage in, garbage out.</strong> RAG is only as good as the documents you give it. If the wiki is wrong, the answer will be wrong, but now with a citation.</li>
</ul>
<h3 id="summary">Summary</h3>
<p>RAG sounds like a fancy AI term, but in code it’s a short pipeline:</p>
<ul>
<li><strong>Ingest:</strong> split text into chunks → embed each chunk into a vector → store the text and vector in pgvector.</li>
<li><strong>Ask:</strong> embed the question → find the closest chunk vectors → give the question and those chunks to the chat model → answer with sources.</li>
</ul>
<p>The vectors are the only “magic” part. They are 768 numbers with no human meaning in any single dimension, but their direction captures meaning. Similar text means a small angle, and a small angle is something a database can search.</p>
<p>LangChain4j turns each step into one small interface, so the whole service is a handful of Spring beans. You can swap Ollama for OpenAI, or pgvector for Qdrant, without touching the business code.</p>
<p>And now a local 8B model knows when Harbourline’s settlement batch runs. Harbourline still doesn’t exist, but at least its batch is on time. ⏰</p>
<p>The full code is on GitHub: <a href="https://github.com/SukachVitally/rag-demo">SukachVitally/rag-demo</a>. Clone it, run docker compose up -d, upload your own notes and ask them questions.</p>
]]></content:encoded></item><item><title>Building an MCP Server in Java with Spring AI: Let Claude Code Use Your Database Without Seeing a Password</title><link>https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/</link><pubDate>Fri, 25 Sep 2026 14:46:28 +0000</pubDate><guid>https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/</guid><description>&lt;p>&lt;em>Four annotated methods, one security config, and no JSON-RPC code of your own.&lt;/em>&lt;/p>
&lt;p>&lt;img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-01.png">&lt;/p>
&lt;p>In my &lt;a href="https://medium.com/@sukach.v.v/mcp-the-protocol-that-finally-taught-ai-to-stop-being-useless-759de3745b79">previous article&lt;/a> I built an MCP server from scratch in Python. I wrote the JSON-RPC 2.0 message handling, declared tool schemas by hand and wired up the STDIO transport myself. It’s a good way to learn how the protocol works on the wire.&lt;/p>
&lt;p>Python isn’t the only option, though. Most of the systems I work on are Java and Spring, and that’s where the data lives. So this time I built the same kind of server in Java.&lt;/p></description><content:encoded><![CDATA[<p><em>Four annotated methods, one security config, and no JSON-RPC code of your own.</em></p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-01.png"></p>
<p>In my <a href="https://medium.com/@sukach.v.v/mcp-the-protocol-that-finally-taught-ai-to-stop-being-useless-759de3745b79">previous article</a> I built an MCP server from scratch in Python. I wrote the JSON-RPC 2.0 message handling, declared tool schemas by hand and wired up the STDIO transport myself. It’s a good way to learn how the protocol works on the wire.</p>
<p>Python isn’t the only option, though. Most of the systems I work on are Java and Spring, and that’s where the data lives. So this time I built the same kind of server in Java.</p>
<p>It turns out you don’t need to implement JSON-RPC yourself. Spring AI has a Boot starter for MCP servers. It handles the protocol, the transport, schema generation and tool registration. You write ordinary Spring beans and add a few annotations.</p>
<p>The full code is on GitHub: <a href="https://github.com/SukachVitally/mcp-demo">SukachVitally/mcp-demo</a>.</p>
<h3 id="why-bother-the-server-is-theboundary">Why bother: the server is the boundary</h3>
<p>The business logic here is deliberately boring. It’s a task list: you create tasks, move them through statuses, and finish or cancel them. Swap in your own domain; the MCP part stays the same.</p>
<p>The point is how Claude Code reaches the data:</p>
<pre tabindex="0"><code>Claude Code ──HTTP + API key──▶ MCP server (Spring) ──JDBC──▶ PostgreSQL
</code></pre><ul>
<li><strong>Claude never sees database credentials.</strong> The server holds the connection. Claude holds only an API key that works for the MCP endpoint and nothing else.</li>
<li><strong>Claude can only do what you expose.</strong> There’s no SQL console. If you don’t write a delete_task tool, tasks can&rsquo;t be deleted, however the prompt is phrased.</li>
<li><strong>Your validation and transactions still apply.</strong> Every call goes through the same service layer as the rest of your application.</li>
</ul>
<p>Giving an agent a database URL and a password is quick, but you can’t take it back. An MCP server gives the agent a small, typed and auditable API instead.</p>
<h3 id="what-werebuilding">What we’re building</h3>
<p>A PostgreSQL table of tasks. Each task has a name and one of four statuses: NEW, IN_PROGRESS, DONE or CANCELLED. The server exposes four tools:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-02.png"></p>
<p>Stack: Java 25, Spring Boot 4, Spring AI 2.0 MCP server, PostgreSQL 18 with Liquibase, and Spring Security.</p>
<h3 id="step-1-dependencies">Step 1: Dependencies</h3>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/build.gradle"><em>build.gradle</em></a></p>
<pre tabindex="0"><code>dependencies {
    implementation &#39;org.springframework.boot:spring-boot-starter-data-jpa&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-liquibase&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-webmvc&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-security&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-validation&#39;
    implementation platform(&#39;org.springframework.ai:spring-ai-bom:2.0.1&#39;)
    implementation &#39;org.springframework.ai:spring-ai-starter-mcp-server-webmvc&#39;
    implementation &#39;org.springaicommunity:mcp-server-security-spring-boot:0.1.14&#39;
    runtimeOnly &#39;org.postgresql:postgresql&#39;
}
</code></pre><p>Two lines do the MCP work:</p>
<ul>
<li>spring-ai-starter-mcp-server-webmvc is the MCP server over HTTP on Spring MVC. There&rsquo;s a -webflux variant for reactive apps, and a plain spring-ai-starter-mcp-server for stdio.</li>
<li>mcp-server-security-spring-boot from the <a href="https://github.com/spring-ai-community/mcp-security">spring-ai-community/mcp-security</a> project adds API-key and OAuth2 support on top of Spring Security. We&rsquo;ll come back to it.</li>
</ul>
<h3 id="step-2-configure-theserver">Step 2: Configure the server</h3>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/resources/application.yaml"><em>application.yaml</em></a></p>
<pre tabindex="0"><code>spring:
  ai:
    mcp:
      server:
        protocol: STATELESS
        type: sync
        name: &#34;Task MCP demo&#34;
        instructions: &gt;-
          Manages a simple task list. Create tasks with add_task, look them up with get_task or
          get_task_list, and move them through the statuses NEW, IN_PROGRESS, DONE and CANCELLED
          with update_task_status.
        streamable-http:
          mcp-endpoint: /mcp
</code></pre><p>What these settings mean:</p>
<ul>
<li><strong>protocol: STATELESS</strong>: plain HTTP request and response, with no session kept between calls. Our tools never need to push anything back to the client, so we don&rsquo;t need sessions, and the server scales horizontally like any other REST service. Use STREAMABLE if you need server-to-client messages. The older SSE option is deprecated since Spring AI 2.0.</li>
<li><strong>type: sync</strong>: tools are ordinary blocking methods. With async, they return Reactor Mono/Flux types instead.</li>
<li><strong>instructions</strong>: sent to the client when it connects. It&rsquo;s the server&rsquo;s short explanation to the model of how the tools fit together. Treat it as part of the prompt.</li>
<li><strong>mcp-endpoint: /mcp</strong>: the URL that Claude Code will call.</li>
</ul>
<h3 id="step-3-business-logic-keep-itboring">Step 3: Business logic (keep it boring)</h3>
<p>Nothing here knows about MCP. It’s a normal JPA entity, repository and service:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/service/TaskService.java"><em>TaskService.java</em></a></p>
<pre tabindex="0"><code>@Service
@Validated
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class TaskService {
    public static final int NAME_MAX_LEN
GTH = 255;
    private final TaskRepository repository;
    private final TaskMapper mapper;
    @Transactional
    public TaskDto create(@NotBlank @Size(max = NAME_MAX_LENGTH) String name) {
        var entity = new TaskEntity();
        entity.setName(name);
        entity.setStatus(TaskStatus.NEW);
        return mapper.toDto(repository.save(entity));
    }
    @Transactional
    public TaskDto updateStatus(Long id, @NotNull TaskStatus status) {
        var entity = findEntity(id);
        entity.setStatus(status);
        return mapper.toDto(entity);
    }
    // get(id), getList(), findEntity(id) throws TaskNotFoundException ...
}
</code></pre><p>The service returns a small record, not the entity:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/dto/TaskDto.java"><em>TaskDto.java</em></a></p>
<pre tabindex="0"><code>public record TaskDto(Long id, String name, TaskStatus status) {}
</code></pre><p>That matters more than it looks. Whatever a tool returns is serialized and handed to the model, so the DTO decides exactly which fields leave your system.</p>
<h3 id="step-4-taskmcptool-the-actual-mcpserver">Step 4: TaskMcpTool, the actual MCP server</h3>
<p>This is the whole MCP layer:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/mcp/TaskMcpTool.java"><em>TaskMcpTool.java</em></a></p>
<pre tabindex="0"><code>@Component
@RequiredArgsConstructor
public class TaskMcpTool {
    private final TaskService service;
    @McpTool(name = &#34;add_task&#34;, description = &#34;Create a new task with status NEW and return it&#34;)
    public TaskDto add(@McpToolParam(description = &#34;Task name, 1-255 characters&#34;) String name) {
        return service.create(name);
    }
    @McpTool(name = &#34;get_task&#34;, description = &#34;Get a task by its id. Fails if the task does not exist&#34;)
    public TaskDto get(@McpToolParam(description = &#34;Task id&#34;) Long id) {
        return service.get(id);
    }
    @McpTool(name = &#34;update_task_status&#34;,
            description = &#34;Change the status of a task and return the updated task. Fails if the task does not exist&#34;)
    public TaskDto updateStatus(@McpToolParam(description = &#34;Task id&#34;) Long id,
                                @McpToolParam(description = &#34;New task status&#34;) TaskStatus status) {
        return service.updateStatus(id, status);
    }
    @McpTool(name = &#34;get_task_list&#34;, description = &#34;List all tasks&#34;)
    public List&lt;TaskDto&gt; getList() {
        return service.getList();
    }
}
</code></pre><p>Only a thin adapter: each method delegates to the service. Most of the work happens in the annotations.</p>
<h3 id="how-the-tools-get-registered">How the tools get registered</h3>
<p>The class is a plain @Component. When the application starts, Spring AI&rsquo;s annotation scanner finds every bean method annotated with @McpTool and registers it as an MCP tool. You don&rsquo;t need a registry, a ToolCallback list or any manual wiring. To add a tool, write another annotated method.</p>
<h3 id="mcptool-the-name-and-description-the-modelsees">@McpTool: the name and description the model sees</h3>
<ul>
<li><strong>name</strong> is the tool id the model calls. I use snake_case verbs (add_task, get_task_list) because that&rsquo;s the convention across MCP servers, and models pick such names up reliably. Without a name, the Java method name is used, and add on its own tells the model very little.</li>
<li><strong>description</strong> is the most important string in the class. It&rsquo;s the only thing the model reads when deciding which tool to call and what to expect back. Say what the tool does, what it returns and when it fails (&ldquo;Fails if the task does not exist&rdquo;). A vague description gives you a model that guesses.</li>
</ul>
<h3 id="mcptoolparam-the-schema-is-generated-foryou">@McpToolParam: the schema is generated for you</h3>
<p>Each parameter gets a description, and Spring AI builds a JSON Schema from the Java type. Here’s what the server actually returns for update_task_status when Claude Code asks for tools/list:</p>
<pre tabindex="0"><code>{
  &#34;name&#34;: &#34;update_task_status&#34;,
  &#34;description&#34;: &#34;Change the status of a task and return the updated task. Fails if the task does not exist&#34;,
  &#34;inputSchema&#34;: {
    &#34;type&#34;: &#34;object&#34;,
    &#34;properties&#34;: {
      &#34;id&#34;:     { &#34;type&#34;: &#34;integer&#34;, &#34;format&#34;: &#34;int64&#34;, &#34;description&#34;: &#34;Task id&#34; },
      &#34;status&#34;: { &#34;type&#34;: &#34;string&#34;,
                  &#34;enum&#34;: [&#34;NEW&#34;, &#34;IN_PROGRESS&#34;, &#34;DONE&#34;, &#34;CANCELLED&#34;],
                  &#34;description&#34;: &#34;New task status&#34; }
    },
    &#34;required&#34;: [&#34;id&#34;, &#34;status&#34;]
  }
}
</code></pre><p>Things to notice:</p>
<ul>
<li><strong>Long became</strong> <strong>integer with</strong> <strong>int64 format.</strong> You don&rsquo;t write any schema by hand.</li>
<li><strong>Parameters are required by default</strong> (required = true). Set @McpToolParam(required = false) for optional ones.</li>
<li><strong>The</strong> <strong>TaskStatus enum became a JSON</strong> <strong>enum.</strong> The model sees the four allowed values up front, so it can&rsquo;t invent a status like DELETED. If it tries, the call is rejected by schema validation before your method runs:</li>
</ul>
<pre tabindex="0"><code>Tool (update_task_status) input validation failed: ... /status: does not 
have a value in the enumeration [&#34;NEW&#34;, &#34;IN_PROGRESS&#34;, &#34;DONE&#34;, &#34;CANCELLED&#34;]
</code></pre><p>Use enums for anything with a fixed set of values. You get validation and documentation in one place.</p>
<h3 id="return-values-anderrors">Return values and errors</h3>
<p>You return a normal Java object, and Spring AI serializes it to JSON as the tool result. <code>TaskDto</code> and <code>List&lt;TaskDto&gt;</code> just work.</p>
<p>Exceptions work too. When TaskService throws TaskNotFoundException, the client doesn&rsquo;t get a stack trace or a broken JSON-RPC response. It gets a tool result with isError: true and the exception message as the text:</p>
<pre tabindex="0"><code>{ 
  &#34;content&#34;: [{ &#34;type&#34;: &#34;text&#34;, &#34;text&#34;: &#34;Task with id -1 is not found&#34; }], 
  &#34;isError&#34;: true 
}
</code></pre><p>That’s the behaviour you want: the model reads the message, understands what went wrong and can recover, for example by calling get_task_list to find the right id. Write exception messages for the model to read, not just for your logs.</p>
<p>The same applies to Bean Validation. A blank name fails @NotBlank in the service and comes back to the model as an error result, not a 500.</p>
<h3 id="a-tip-add-behaviour-hints">A tip: add behaviour hints</h3>
<p>If you look at the full tools/list response, every tool reports &ldquo;readOnlyHint&rdquo;: false, &ldquo;destructiveHint&rdquo;: true, including get_task_list. Those are the defaults. Clients such as Claude Code can use these hints to decide how cautious to be, so it&rsquo;s worth being honest about read-only tools:</p>
<pre tabindex="0"><code>@McpTool(name = &#34;get_task_list&#34;, description = &#34;List all tasks&#34;,
        annotations = @McpTool.McpAnnotations(readOnlyHint = true, 
                                              destructiveHint = false))
</code></pre><p>These are hints, not enforcement. What actually protects your data is the fact that the tool only reads.</p>
<h3 id="step-5-securityconfig-briefly">Step 5: SecurityConfig, briefly</h3>
<p>By default, an HTTP MCP endpoint is an unauthenticated JSON-RPC endpoint. Anyone who can reach /mcp can call your tools. The mcp-security library closes it with a few lines:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/config/SecurityConfig.java"><em>SecurityConfig.java</em></a></p>
<pre tabindex="0"><code>@Configuration
@EnableWebSecurity
class SecurityConfig {
    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http,
                                            ApiKeyEntityRepository&lt;ApiKeyEntityImpl&gt; apiKeyRepository) {
        return http
                .authorizeHttpRequests(auth -&gt; auth.anyRequest().authenticated())
                .with(mcpServerApiKey(), apiKey -&gt; apiKey.apiKeyRepository(apiKeyRepository))
                .build();
    }
    @Bean
    ApiKeyEntityRepository&lt;ApiKeyEntityImpl&gt; apiKeyRepository(@Value(&#34;${app.mcp.api-key.secret}&#34;) String secret) {
        var key = ApiKeyEntityImpl.builder()
                .name(&#34;demo key&#34;)
                .id(&#34;demo&#34;)
                .secret(secret)
                .build();
        return new InMemoryApiKeyEntityRepository&lt;&gt;(List.of(key));
    }
}
</code></pre><ul>
<li>mcpServerApiKey() plugs API-key authentication into the normal Spring Security filter chain.</li>
<li>The client sends an X-API-key header in the form <code>&lt;id&gt;.&lt;secret&gt;</code>, so <code>demo.&lt;your secret&gt;</code> here. Requests without it get 401.</li>
</ul>
<h3 id="step-6-run-it-and-connect-claudecode">Step 6: Run it and connect Claude Code</h3>
<p>Start PostgreSQL and the app:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/docker-compose.yaml"><em>docker-compose.yaml</em></a><em>,</em><a href="https://github.com/SukachVitally/mcp-demo/blob/main/.env.tpl"><em>.env.tpl</em></a><em>,</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/README.md"><em>README</em></a></p>
<pre tabindex="0"><code>cp .env.tpl .env          # sets MCP_API_KEY_SECRET
docker compose up -d
./gradlew bootRun
</code></pre><p>Register the server with Claude Code:</p>
<pre tabindex="0"><code>claude mcp add --transport http todos http://localhost:8080/mcp \
  --header &#34;X-API-key: demo.mcp-demo-test-secret&#34;
</code></pre><p>Then ask in plain language:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-03.png"></p>
<p>“Add todo with name test” becomes an add_task call. &ldquo;Update task with id 1 to DONE&rdquo; becomes update_task_status with a valid enum value. Claude never saw a JDBC URL, a username or a password.</p>
<p>To inspect the server without Claude, use the MCP Inspector (npx @modelcontextprotocol/inspector). Choose the Streamable HTTP transport and add the same header.</p>
<h3 id="testing">Testing</h3>
<p>Because the server speaks standard MCP, the tests can use the official Java MCP client against a real server started by @SpringBootTest, with PostgreSQL in Testcontainers:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/test/java/org/example/mcpdemo/mcp/TaskMcpToolTest.java"><em>TaskMcpToolTest.java</em></a></p>
<pre tabindex="0"><code>var transport = HttpClientStreamableHttpTransport
        .builder(&#34;http://localhost:&#34; + port)
        .httpRequestCustomizer((builder, method, endpoint, body, context) -&gt;
                builder.header(&#34;X-API-key&#34;, &#34;demo.&#34; + API_KEY_SECRET))
        .build();
client = McpClient.sync(transport).build();
client.initialize();
var result = client.callTool(McpSchema.CallToolRequest.builder(&#34;get_task&#34;)
        .arguments(Map.of(&#34;id&#34;, -1L)).build());
assertThat(result.isError()).isTrue();
</code></pre><p>This covers the whole chain in one test: authentication, schema, serialization, error mapping and the database.</p>
<h3 id="takeaways">Takeaways</h3>
<ul>
<li><strong>You don’t write JSON-RPC in Java.</strong> spring-ai-starter-mcp-server-webmvc handles the protocol, the transport and tool discovery.</li>
<li><strong>An MCP tool is an annotated Spring bean method.</strong> @McpTool names and describes it, and @McpToolParam describes its inputs. The JSON Schema is generated from your Java types.</li>
<li><strong>Descriptions and error messages are prompts.</strong> The model reads them, so write them for the model.</li>
<li><strong>Use enums and DTOs</strong> to control what the model can send in and what it gets back.</li>
<li><strong>Secure the endpoint.</strong> API keys via mcp-security take ten lines, and OAuth2 is available when you need it.</li>
<li><strong>The MCP server is the security boundary.</strong> Claude Code works with your data through the operations you choose, never with your credentials.</li>
</ul>
<p>The Python version showed how MCP works on the wire. The Spring version shows how little code you need once a framework handles it. Take the repo, replace tasks with your own domain, and give your agent an API instead of a password.</p>
<p><strong>Links</strong></p>
<ul>
<li>Demo code: <a href="https://github.com/SukachVitally/mcp-demo">github.com/SukachVitally/mcp-demo</a></li>
<li>Spring AI MCP Server Boot Starter: <a href="https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html">docs.spring.io</a></li>
<li>MCP security for Spring: <a href="https://github.com/spring-ai-community/mcp-security/tree/main">github.com/spring-ai-community/mcp-security</a></li>
<li>Previous article, MCP in Python from scratch: <a href="https://medium.com/@sukach.v.v/mcp-the-protocol-that-finally-taught-ai-to-stop-being-useless-759de3745b79">MCP: The Protocol That Finally Taught AI to Stop Being Useless</a></li>
</ul>
]]></content:encoded></item><item><title>The Java Memory Model, Explained Without the Headache</title><link>https://vitaliisukach.dev/posts/the-java-memory-model-explained-without-the-headache/</link><pubDate>Thu, 03 Sep 2026 16:18:18 +0000</pubDate><guid>https://vitaliisukach.dev/posts/the-java-memory-model-explained-without-the-headache/</guid><description>&lt;h4 id="what-actually-happens-to-your-data-between-two-threadsand-the-small-set-of-tools-that-let-you-controlit">What actually happens to your data between two threads — and the small set of tools that let you control it&lt;/h4>
&lt;p>&lt;img loading="lazy" src="https://vitaliisukach.dev/posts/the-java-memory-model-explained-without-the-headache/image-01.png">&lt;/p>
&lt;p>Ask ten Java developers what “the Java Memory Model” means and you’ll get two different answers.&lt;/p>
&lt;p>Half of them will draw a box called &lt;em>Heap&lt;/em> and another called &lt;em>Stack&lt;/em>. The other half will start talking about volatile and happens-before.&lt;/p>
&lt;p>Both groups are talking about something real, but only the second group is talking about the actual &lt;strong>Java Memory Model (JMM)&lt;/strong>. The first group is describing the &lt;strong>runtime data areas&lt;/strong> — where objects physically live.&lt;/p></description><content:encoded><![CDATA[<h4 id="what-actually-happens-to-your-data-between-two-threadsand-the-small-set-of-tools-that-let-you-controlit">What actually happens to your data between two threads — and the small set of tools that let you control it</h4>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/the-java-memory-model-explained-without-the-headache/image-01.png"></p>
<p>Ask ten Java developers what “the Java Memory Model” means and you’ll get two different answers.</p>
<p>Half of them will draw a box called <em>Heap</em> and another called <em>Stack</em>. The other half will start talking about volatile and happens-before.</p>
<p>Both groups are talking about something real, but only the second group is talking about the actual <strong>Java Memory Model (JMM)</strong>. The first group is describing the <strong>runtime data areas</strong> — where objects physically live.</p>
<p>You need both to write correct concurrent code, so let’s go through them in order. Memory layout first, because it’s the easier one, then the JMM proper.</p>
<h3 id="part-1-where-your-datalives">Part 1: Where your data lives</h3>
<p>When the JVM starts, it carves the process memory into a few distinct regions. Each has an owner and a lifetime.</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/the-java-memory-model-explained-without-the-headache/image-02.png"></p>
<p><strong>Heap</strong> — every object and array you ever create lives here. It’s shared, which is exactly why concurrency is hard. Garbage collection happens here. Modern collectors split it further (young generation, old generation, or regions in G1/ZGC), but that’s a GC detail, not a memory model one.</p>
<p><strong>Metaspace</strong> — class metadata, bytecode, and static fields. It sits in native memory since Java 8, which is why PermGen errors disappeared and Metaspace OOM errors appeared instead.</p>
<p><strong>Thread stack</strong> — each thread gets its own. Every method call pushes a frame containing local variables, parameters, and the return address. Frame pops when the method returns. This is where StackOverflowError comes from. Nothing here is shared, so locals are never a concurrency problem — unless the <em>value</em> they point to is a shared object.</p>
<p><strong>PC register</strong> — the address of the instruction the thread is currently executing. One per thread.</p>
<p><strong>Native method stack</strong> — the same idea, but for native (JNI) calls.</p>
<p>One thing worth burning in:</p>
<pre tabindex="0"><code>Order order = new Order();
</code></pre><p>The variable order is a reference sitting on the <strong>stack</strong>. The Order object itself sits on the <strong>heap</strong>. Two threads can hold two separate stack references pointing to the same heap object. That&rsquo;s the whole source of the trouble.</p>
<h3 id="part-2-the-actual-java-memorymodel">Part 2: The actual Java Memory Model</h3>
<p>The runtime areas tell you <em>where</em> data sits. They tell you nothing about <em>when</em> one thread sees a write made by another.</p>
<p>That question is what the JMM answers. It’s a specification (JSR-133, in Chapter 17 of the Java Language Specification) that defines exactly what guarantees you get about reads and writes across threads.</p>
<h4 id="the-problem-it-exists-tosolve">The problem it exists to solve</h4>
<p>Modern CPUs are fast because they cheat, aggressively and correctly. Two things they do:</p>
<p><strong>1. Caching.</strong> Each core has its own L1/L2 cache. When a thread writes to a field, that write may sit in the core’s cache or store buffer for a while before it becomes visible to other cores.</p>
<p><strong>2. Reordering.</strong> The compiler, the JIT, and the CPU are all allowed to reorder instructions, as long as the result looks the same <em>for a single thread</em>. That last clause is the trap — nobody promised anything about how it looks to other threads.</p>
<p>So the JMM works with an abstraction:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/the-java-memory-model-explained-without-the-headache/image-03.png"></p>
<p><em>Thread A and Thread B never see each other’s working memory. Everything they share has to travel through main memory — and the JMM decides when it does.</em></p>
<p>Every thread has a conceptual <strong>working memory</strong> (registers, cache, store buffers) holding copies of the variables it touches. Threads never talk to each other directly — they communicate only through <strong>main memory</strong>. The JMM specifies when a value must be flushed to main memory and when it must be re-read from it.</p>
<p>Here’s the classic demonstration:</p>
<pre tabindex="0"><code>public class StopFlag {
    private boolean running = true;   // no volatile
    
    public void run() {
        while (running) {
            // do work
        }
        System.out.println(&#34;stopped&#34;);
    }
    public void stop() {
        running = false;
    }
}
</code></pre><p>Thread A runs run(). Thread B calls stop(). Very often, thread A never stops.</p>
<p>Nothing is broken. The JIT sees that running is never modified inside the loop, so it&rsquo;s free to hoist the read out:</p>
<pre tabindex="0"><code>boolean r = running;
while (r) { /* work */ }   // now an infinite loop
</code></pre><p>Without a memory model rule forcing it, the JVM has no obligation to ever re-read that field. Your bug is not a race in the “two writes collided” sense — it’s a <strong>visibility</strong> failure.</p>
<h4 id="the-three-guarantees">The three guarantees</h4>
<p>Every concurrency problem in Java falls into one of these buckets.</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/the-java-memory-model-explained-without-the-headache/image-04.png"></p>
<p>count++ is the textbook atomicity failure — it&rsquo;s three operations (read, add, write), and two threads can interleave in the middle. Two increments, one result.</p>
<h3 id="the-base-components-of-thejmm">The base components of the JMM</h3>
<p>Here’s the toolbox. It’s smaller than most people expect.</p>
<h4 id="1-happens-beforethe-rule-that-underpins-everything">1. happens-before — the rule that underpins everything</h4>
<p>Everything else is a special case of this one relation. If action <strong>A</strong> <em>happens-before</em> action <strong>B</strong>, then:</p>
<ul>
<li>everything A wrote is visible to B, and</li>
<li>A is guaranteed to appear to occur before B.</li>
</ul>
<p>It is <strong>not</strong> just “A ran earlier in wall-clock time.” Two actions can be ordered in time and still have no happens-before relationship, which means B may see stale data.</p>
<p>The rules the JLS gives you:</p>
<ol>
<li><strong>Program order</strong> — within one thread, each statement happens-before the ones written after it.</li>
<li><strong>Monitor lock</strong> — unlocking a monitor happens-before any later lock of the <em>same</em> monitor.</li>
<li><strong>volatile</strong> — a write to a volatile field happens-before every later read of that field.</li>
<li><strong>Thread start</strong> — Thread.start() happens-before anything in the started thread.</li>
<li><strong>Thread join</strong> — everything in a thread happens-before another thread’s successful join() on it.</li>
<li><strong>Interruption</strong> — a call to interrupt() happens-before the interrupted thread detects it.</li>
<li><strong>Constructor / finalizer</strong> — the end of a constructor happens-before the start of that object’s finalizer.</li>
<li><strong>Transitivity</strong> — if A hb B and B hb C, then A hb C.</li>
</ol>
<p>That last one does most of the practical work. It’s why writing a plain field and <em>then</em> a volatile flag safely publishes the plain field.</p>
<h4 id="2-volatilevisibility-and-ordering-no-atomicity">2. volatile — visibility and ordering, no atomicity</h4>
<pre tabindex="0"><code>private volatile boolean running = true;
</code></pre><p>This single keyword fixes the StopFlag example. It gives you:</p>
<ul>
<li><strong>Visibility</strong> — a write goes to main memory immediately; a read comes from main memory, never a cache.</li>
<li><strong>Ordering</strong> — the JVM inserts memory barriers so reads and writes can’t be reordered across the volatile access.</li>
</ul>
<p>What it does <strong>not</strong> give you is atomicity:</p>
<pre tabindex="0"><code>private volatile int count = 0;
public void increment() {
    count++;   // STILL BROKEN
}
</code></pre><p>Use volatile for flags and for single-writer state. For compound operations, use something else.</p>
<h4 id="3-synchronizedall-three-guarantees">3. synchronized — all three guarantees</h4>
<pre tabindex="0"><code>private int count = 0;
public synchronized void increment() {
    count++;   // correct
}
public synchronized int get() {
    return count;   // also needs to be synchronized
}
</code></pre><p>Entering the monitor gives mutual exclusion (atomicity). Exiting flushes to main memory, entering invalidates the local copy (visibility). Barriers around the block prevent reordering out of it.</p>
<p>The most common mistake here is synchronizing the writer but not the reader. Both sides need the <em>same</em> lock, or there’s no happens-before edge between them.</p>
<p>ReentrantLock gives you the same memory guarantees, plus tryLock, timeouts, fairness, and multiple conditions.</p>
<h4 id="4-finalsafe-publication-forfree"><strong>4.</strong> <strong>final — safe publication for free</strong></h4>
<pre tabindex="0"><code>public class Config {
    private final String url;
    public Config(String url) {
        this.url = url;   // guaranteed visible after construction
    }
}
</code></pre><p>The JMM guarantees that any thread that sees a properly constructed object sees the correct values of its final fields — no synchronization required. This is why immutable objects are the easiest possible concurrency strategy.</p>
<p>The catch is “properly constructed.” If the constructor leaks this (registering a listener, starting a thread), the guarantee is void.</p>
<h4 id="5-atomics-and-varhandle">5. Atomics and VarHandle</h4>
<p>java.util.concurrent.atomic gives you lock-free compound operations built on CPU compare-and-swap instructions:</p>
<pre tabindex="0"><code>private final AtomicInteger count = new AtomicInteger();
public void increment() {
    count.incrementAndGet();   // atomic, visible, ordered
}
</code></pre><p>Under contention LongAdder usually beats AtomicLong — it spreads writes across cells and sums them on read, avoiding cache-line contention. VarHandle (Java 9+) is the modern, supported way to reach for finer-grained modes like getAcquire / setRelease when you know exactly what you&rsquo;re doing.</p>
<h3 id="three-bugs-thisexplains">Three bugs this explains</h3>
<p><strong>Unsafe publication.</strong> Building an object and handing the reference to another thread without a happens-before edge. The other thread can see a non-null reference to a half-initialized object — fields still at their defaults. Publish through a volatile field, a lock, a final field, or a concurrent collection.</p>
<p><strong>Double-checked locking without</strong> <strong>volatile.</strong> The infamous one:</p>
<pre tabindex="0"><code>private static volatile Singleton instance;   // volatile is mandatory
public static Singleton getInstance() {
    if (instance == null) {
        synchronized (Singleton.class) {
            if (instance == null) {
                instance = new Singleton();
            }
        }
    }
    return instance;
}
</code></pre><p>Drop the volatile and it breaks, because instance = new Singleton() is three steps — allocate, construct, assign — and the last two can be reordered. Another thread can grab a reference to an object whose constructor hasn&rsquo;t finished.</p>
<p><strong>Check-then-act.</strong> if (!map.containsKey(k)) map.put(k, v); is two atomic operations, not one atomic operation. Use putIfAbsent or computeIfAbsent.</p>
<h3 id="the-practical-cheatsheet">The practical cheat sheet</h3>
<ul>
<li><strong>Shared and mutable?</strong> It needs synchronization. Every time.</li>
<li><strong>One thread writes a flag, others read it?</strong> volatile.</li>
<li><strong>Compound operation on one variable?</strong> An atomic class.</li>
<li><strong>Compound operation across several variables?</strong> synchronized or ReentrantLock.</li>
<li><strong>Can you make it immutable instead?</strong> Do that. final fields, no setters, no shared mutation, no memory model to reason about.</li>
<li><strong>Reading is also access.</strong> Unsynchronized reads of synchronized state are still broken.</li>
<li><strong>“It works on my machine” proves nothing.</strong> x86 has a strong memory model that hides many of these bugs. ARM (Apple Silicon, Graviton) doesn’t. Code that ran fine for years on Intel servers can fail the week you move it to ARM instances.</li>
</ul>
<h3 id="wrapping-up">Wrapping up</h3>
<p>The runtime areas — heap, stacks, metaspace — tell you where your data sits. The Java Memory Model tells you when one thread’s writes become visible to another, and it comes down to a handful of pieces: happens-before as the underlying rule, and volatile, synchronized, final, and the atomics as the tools that create it.</p>
<p>You don’t need to memorize the specification. You need one habit: whenever two threads touch the same data, ask what creates the happens-before edge between them. If you can’t name it, it isn’t there.</p>
<p><em>If this was useful, the natural next step is Brian Goetz’s</em> Java Concurrency in Practice <em>— still the best treatment of this material, twenty years on.</em></p>
]]></content:encoded></item><item><title>DateTime Handling in Java and PostgreSQL: A Practical Guide</title><link>https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/</link><pubDate>Sat, 15 Aug 2026 14:24:50 +0000</pubDate><guid>https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/</guid><description>&lt;p>&lt;em>Everything I wish someone had told me before I stored a meeting time in a&lt;/em> &lt;em>timestamp column.&lt;/em>&lt;/p>
&lt;p>&lt;img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-01.png">&lt;/p>
&lt;p>There is a specific kind of bug that only shows up in production, only in October, and only for users in one country. It gets closed as “not reproducible” twice before someone finally sits down with a coffee and reads the column definition.&lt;/p>
&lt;p>It is almost always a datetime bug.&lt;/p>
&lt;p>The frustrating part is that both Java and PostgreSQL have &lt;em>excellent&lt;/em> date/time support. java.time is one of the best-designed APIs in the JDK. PostgreSQL&amp;rsquo;s temporal types are precise and well documented. The bugs happen at the seam — in the assumptions each side makes about what the other means, and in the two or three words in the type names that mean the opposite of what you&amp;rsquo;d guess.&lt;/p></description><content:encoded><![CDATA[<p><em>Everything I wish someone had told me before I stored a meeting time in a</em> <em>timestamp column.</em></p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-01.png"></p>
<p>There is a specific kind of bug that only shows up in production, only in October, and only for users in one country. It gets closed as “not reproducible” twice before someone finally sits down with a coffee and reads the column definition.</p>
<p>It is almost always a datetime bug.</p>
<p>The frustrating part is that both Java and PostgreSQL have <em>excellent</em> date/time support. java.time is one of the best-designed APIs in the JDK. PostgreSQL&rsquo;s temporal types are precise and well documented. The bugs happen at the seam — in the assumptions each side makes about what the other means, and in the two or three words in the type names that mean the opposite of what you&rsquo;d guess.</p>
<p>This guide walks through both models, then spends real time on the part that actually causes outages: time zones.</p>
<p>Every code output and query result below was executed — Java 21 and PostgreSQL 16 — not written from memory.</p>
<h3 id="part-1-the-javaside">Part 1: The Java Side</h3>
<h4 id="ask-three-questions-get-onetype">Ask three questions, get one type</h4>
<p>Every java.time class is an answer to some combination of three questions:</p>
<ol>
<li>Do I know the <strong>date</strong>?</li>
<li>Do I know the <strong>time of day</strong>?</li>
<li>Do I know which <strong>point on the global timeline</strong> this is?</li>
</ol>
<p>That last one is the important one, and it’s the one people skip. Here’s the map:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-02.png"></p>
<p>The single most useful sentence in this article: <strong>LocalDateTime is not a point in time.</strong> 2026-08-15T12:00 is twelve o&rsquo;clock <em>somewhere</em>, and until you say where, it refers to a 26-hour-wide smear across the planet. If you have an Instant and you call .toLocalDateTime(), you have thrown away information and the compiler will not warn you.</p>
<h4 id="instant-is-the-boring-correctdefault">Instant is the boring, correct default</h4>
<pre tabindex="0"><code>Instant now = Instant.now();     // 2026-08-15T10:00:00.123456789Z
</code></pre><p>An Instant is nanoseconds since the epoch. No zone, no offset, no calendar. When it prints with a Z, that isn&rsquo;t a stored time zone — it&rsquo;s the ISO-8601 way of rendering an epoch value.</p>
<p>Anything that <em>happened</em> — a login, a payment, a row insert — is an Instant. Reach for something else only when you have a reason.</p>
<h4 id="zoneid-vs-zoneoffset-not-the-samething">ZoneId vs ZoneOffset: not the same thing</h4>
<p>This distinction matters more than any other in this article.</p>
<pre tabindex="0"><code>ZoneId.of(&#34;Europe/London&#34;)  // -&gt; java.time.ZoneRegion
ZoneId.of(&#34;+01:00&#34;)         // -&gt; java.time.ZoneOffset
</code></pre><p>A <strong>ZoneOffset</strong> is a fixed number of hours and minutes from UTC. +01:00. That&rsquo;s the whole thing. It&rsquo;s a fact about one moment.</p>
<p>A <strong>ZoneId</strong> (specifically a ZoneRegion, like Europe/London) is a <em>rulebook</em>. It knows that London was +00:00 in January, +01:00 in August, and it knows the exact instants at which it flips — going back decades and forward as far as legislators have declared.</p>
<p>ZoneOffset is a value. ZoneId is a function from instant to offset. Confusing them is the root cause of most scheduling bugs.</p>
<h4 id="offsetdatetime-vs-zoneddatetime">OffsetDateTime vs ZonedDateTime</h4>
<p>Both identify a real instant. The difference is what survives.</p>
<pre tabindex="0"><code>ZonedDateTime nyc = ZonedDateTime.of(2026, 7, 4, 12, 0, 0, 0,
                                     ZoneId.of(&#34;America/New_York&#34;));
nyc                    // 2026-07-04T12:00-04:00[America/New_York]
nyc.toOffsetDateTime() // 2026-07-04T12:00-04:00
nyc.toInstant()        // 2026-07-04T16:00:00Z
</code></pre><p>All three describe the same moment. But the ZonedDateTime still knows it&rsquo;s in New York, so if you add six months to it, it will correctly land on -05:00. The OffsetDateTime has been flattened — it remembers <em>that</em> the offset was -04:00, not <em>why</em>. Add six months and you get a wrong wall-clock time.</p>
<p>Rule of thumb: ZonedDateTime for calculating, OffsetDateTime for transporting, Instant for storing.</p>
<h4 id="duration-vsperiod">Duration vs Period</h4>
<pre tabindex="0"><code>LocalDate.of(2026, 1, 31).plusMonths(1)  // 2026-02-28
</code></pre><p>Duration is exact elapsed time — seconds and nanos. Period is calendar time — years, months, days. &ldquo;One month&rdquo; is not a fixed number of seconds, and plusMonths clamps rather than overflowing. Both behaviors are correct; mixing them up is not.</p>
<p>This distinction resurfaces the moment DST enters the picture, and we’ll come back to it.</p>
<h4 id="a-word-on-the-oldapi">A word on the old API</h4>
<p>java.util.Date is a mislabeled Instant (it has no time zone despite what toString() implies). Calendar is mutable and lenient. java.sql.Timestamp extends java.util.Date and adds nanoseconds while breaking the equals contract.</p>
<p>If you’re on a legacy codebase, convert at the boundary and never let them into your domain:</p>
<pre tabindex="0"><code>Instant i = oldDate.toInstant();
Date    d = Date.from(instant);
</code></pre><h3 id="part-2-the-postgresql-side">Part 2: The PostgreSQL Side</h3>
<h4 id="timestamptz-does-not-store-a-timezone">timestamptz does not store a time zone</h4>
<p>This is the single biggest source of confusion, and it comes straight from the type name. TIMESTAMP WITH TIME ZONE is an 8-byte value. So is TIMESTAMP WITHOUT TIME ZONE. There is no room in there for a zone, and PostgreSQL doesn&rsquo;t try:</p>
<pre tabindex="0"><code>SELECT pg_column_size(&#39;2026-08-15 12:00:00&#39;::timestamp)     AS ts_bytes,     
       --  8
       pg_column_size(&#39;2026-08-15 12:00:00+02&#39;::timestamptz) AS tstz_bytes,  
       --  8
       pg_column_size(&#39;12:00:00+02&#39;::timetz)                 AS timetz_bytes; 
       -- 12
</code></pre><p>What timestamptz actually does is <strong>convert to UTC on write and convert back on read</strong>. The offset you supplied on input is used and then discarded. From the <a href="https://www.postgresql.org/docs/current/datatype-datetime.html">official docs</a>:</p>
<blockquote>
<p><em>In either case, the value is stored internally as UTC, and the originally stated or assumed time zone is not retained.</em></p></blockquote>
<p>A better mental model: timestamptz is Instant. timestamp is LocalDateTime. The names lie; the semantics don&rsquo;t.</p>
<h4 id="the-demo-that-makes-itclick">The demo that makes it click</h4>
<p>Insert the same two literals into both column types, with the session zone set to London:</p>
<pre tabindex="0"><code>SET TimeZone = &#39;Europe/London&#39;;
CREATE TABLE t (id int, ts timestamp, tstz timestamptz);
INSERT INTO t VALUES (1, &#39;2026-08-15 12:00:00&#39;,    &#39;2026-08-15 12:00:00&#39;);
INSERT INTO t VALUES (2, &#39;2026-08-15 12:00:00+00&#39;, &#39;2026-08-15 12:00:00+00&#39;);
SELECT * FROM t;
</code></pre><pre tabindex="0"><code> id |         ts          |          tstz
----+---------------------+------------------------
  1 | 2026-08-15 12:00:00 | 2026-08-15 12:00:00+01
  2 | 2026-08-15 12:00:00 | 2026-08-15 13:00:00+01
</code></pre><p>Two things happened. Row 1’s tstz had no offset, so PostgreSQL <em>assumed</em> the session zone. Row 2&rsquo;s explicit +00 was honoured and re-rendered as 13:00+01. Meanwhile the ts column ignored the offset entirely and stored the digits.</p>
<p>Now reconnect from New York and run the identical SELECT:</p>
<pre tabindex="0"><code> id |         ts          |          tstz
----+---------------------+------------------------
  1 | 2026-08-15 12:00:00 | 2026-08-15 07:00:00-04
  2 | 2026-08-15 12:00:00 | 2026-08-15 08:00:00-04
</code></pre><p>The tstz column re-renders per client. The ts column is frozen. <strong>Neither row changed on disk.</strong></p>
<p>That last point deserves emphasis, because it’s where the panic starts: when a developer sees a different value than QA saw, the instinct is “the data is corrupted.” It isn’t. Two clients with different TimeZone settings are looking at the same UTC value through different windows.</p>
<h4 id="at-time-zone-runs-bothways">AT TIME ZONE runs both ways</h4>
<p>AT TIME ZONE is the one operator you need, and its behavior flips depending on the input type:</p>
<pre tabindex="0"><code>-- timestamptz -&gt; timestamp: &#34;what does the clock read there?&#34;
SELECT &#39;2026-08-15 12:00:00+00&#39;::timestamptz AT TIME ZONE &#39;Asia/Tokyo&#39;;
-- 2026-08-15 21:00:00   (type: timestamp without time zone)
</code></pre><pre tabindex="0"><code>-- timestamp -&gt; timestamptz: &#34;this wall clock reading WAS in Tokyo&#34;
SELECT &#39;2026-08-15 12:00:00&#39;::timestamp AT TIME ZONE &#39;Asia/Tokyo&#39;;
-- 2026-08-15 03:00:00+00   (type: timestamp with time zone)
</code></pre><p>One removes zone context, the other attaches it. Read it as “interpret this value in that zone.” The function form timezone(&lsquo;Asia/Tokyo&rsquo;, value) is identical.</p>
<h4 id="the-rest-of-thefamily">The rest of the family</h4>
<ul>
<li><strong>date</strong> — 4 bytes, no zone, no ambiguity. Great for things that are genuinely dates.</li>
<li><strong>time</strong> — time of day, no zone.</li>
<li><strong>timetz</strong> — 12 bytes, and <a href="https://www.postgresql.org/docs/current/datatype-datetime.html">PostgreSQL itself recommends against it</a>. A time of day with an offset but no date can&rsquo;t resolve DST, so it&rsquo;s not meaningfully anchored. It won&rsquo;t even accept a zone name:</li>
</ul>
<pre tabindex="0"><code>SELECT &#39;12:00:00 Europe/London&#39;::timetz; -- ERROR: invalid input syntax for type time with time zone
</code></pre><ul>
<li><strong>interval</strong> — 16 bytes storing months, days, and microseconds <em>separately</em>, which is exactly why it can be DST-aware.</li>
</ul>
<h4 id="now-vs-localtimestamp">now() vs localtimestamp</h4>
<pre tabindex="0"><code>SELECT pg_typeof(now()),            -- timestamp with time zone
       pg_typeof(current_timestamp), -- timestamp with time zone
       pg_typeof(localtimestamp),    -- timestamp without time zone
       pg_typeof(current_date);      -- date
</code></pre><p>now() and current_timestamp are timestamptz and are safe. localtimestamp and current_date are evaluated in the session zone, which means a DEFAULT current_date column produces different answers for different clients. Be deliberate.</p>
<h4 id="so-which-do-youpick">So which do you pick?</h4>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-03.png"></p>
<p>The short version: <strong>use</strong> <strong>timestamptz for essentially everything.</strong> Reach for timestamp only when you genuinely mean a floating wall-clock time that must not shift — &ldquo;the store opens at 09:00 local, whatever local means at that branch&rdquo; — and store the zone ID beside it.</p>
<h3 id="part-3-time-zonesproperly">Part 3: Time Zones, Properly</h3>
<p>This is where the real complexity lives, so let’s slow down.</p>
<h4 id="three-things-called-timezone">Three things called “time zone”</h4>
<ol>
<li><strong>An offset</strong> — +01:00. A number.</li>
<li><strong>An IANA zone ID</strong> — Europe/London. A named set of historical and future rules. PostgreSQL ships ~499 of these in pg_timezone_names; Java reads the same tzdata.</li>
<li><strong>An abbreviation</strong> — EST, BST, IST. Ambiguous, unversioned, and a trap.</li>
</ol>
<p>That third one is genuinely dangerous:</p>
<pre tabindex="0"><code>SELECT &#39;2026-08-15 12:00:00 EST&#39;::timestamptz,               -- 2026-08-15 17:00:00+00
       &#39;2026-08-15 12:00:00 America/New_York&#39;::timestamptz;  -- 2026-08-15 16:00:00+00
</code></pre><p>One hour apart. EST is a <em>fixed</em> -05:00 in PostgreSQL — it does not mean &ldquo;Eastern time,&rdquo; it means &ldquo;Eastern Standard Time, always.&rdquo; In August, New York is on -04:00. If you accept zone abbreviations from user input, you have already shipped a bug. (IST is worse — it can mean India, Ireland, or Israel depending on who you ask.)</p>
<p><strong>Always use full IANA names.</strong></p>
<p>Offsets aren’t zones either. Nepal is +05:45; the Chatham Islands are +12:45:</p>
<pre tabindex="0"><code>ZonedDateTime.of(2026,8,15,12,0,0,0, ZoneId.of(&#34;Asia/Kathmandu&#34;))
// 2026-08-15T12:00+05:45[Asia/Kathmandu]
</code></pre><p>If your API contract says “offset in whole hours,” it’s wrong.</p>
<h3 id="where-postgresqls-session-zone-comesfrom">Where PostgreSQL’s session zone comes from</h3>
<p>The TimeZone GUC is a <strong>per-connection setting</strong>. Its value is decided by, in order: an explicit SET TimeZone, the connection&rsquo;s startup parameters, the postgresql.conf value, and finally the server&rsquo;s OS zone.</p>
<p>That last fallback is why the same query returns different results on a developer laptop and in CI. And with connection pooling, SET TimeZone on a borrowed connection leaks to whoever gets it next.</p>
<p>Pin it. Set timezone = &lsquo;UTC&rsquo; in postgresql.conf, and add it to the JDBC URL so it survives pool reuse:</p>
<pre tabindex="0"><code>jdbc:postgresql://host:5432/db?options=-c%20TimeZone%3DUTC
</code></pre><p>Then make the client responsible for rendering. Formatting a timestamp for a human is a presentation concern, not a database one.</p>
<h4 id="the-spring-forward-gap">The spring-forward gap</h4>
<p>On 29 March 2026, London jumps from 01:00 to 02:00. The local times between them <strong>do not exist</strong>.</p>
<p>Ask Java for one anyway:</p>
<pre tabindex="0"><code>LocalDateTime gap = LocalDateTime.of(2026, 3, 29, 1, 30);
gap.atZone(ZoneId.of(&#34;Europe/London&#34;));
// 2026-03-29T02:30+01:00[Europe/London]
ZoneId.of(&#34;Europe/London&#34;).getRules().getTransition(gap);
// Transition[Gap at 2026-03-29T01:00Z to +01:00]
</code></pre><p>Java doesn’t throw. It silently pushes the value forward by the length of the gap. PostgreSQL does the same thing:</p>
<pre tabindex="0"><code>SET TimeZone=&#39;Europe/London&#39;;
SELECT &#39;2026-03-29 01:30:00&#39;::timestamptz;
-- 2026-03-29 02:30:00+01
</code></pre><p>Both are “correct” — but neither told you. If a user sets a 01:30 alarm on that date, you should be validating with getTransition() and telling them, not letting the platform quietly reschedule.</p>
<h4 id="the-fall-back-overlapwhere-java-and-postgresql-disagree">The fall-back overlap — where Java and PostgreSQL disagree</h4>
<p>On 25 October 2026, London goes from 02:00 back to 01:00. Local times between 01:00 and 02:00 happen <strong>twice</strong>, one hour apart.</p>
<p>Java’s rules expose both:</p>
<pre tabindex="0"><code>ZoneId london = ZoneId.of(&#34;Europe/London&#34;);
LocalDateTime overlap = LocalDateTime.of(2026, 10, 25, 1, 30);
london.getRules().getValidOffsets(overlap);
// [+01:00, Z]
ZonedDateTime earlier = overlap.atZone(london);
// 2026-10-25T01:30+01:00[Europe/London]  instant = 2026-10-25T00:30:00Z
ZonedDateTime later = earlier.withLaterOffsetAtOverlap();
// 2026-10-25T01:30Z[Europe/London]       instant = 2026-10-25T01:30:00Z
</code></pre><p>Java’s default for an ambiguous local time is the <strong>earlier</strong> offset — 00:30Z.</p>
<p>Now ask PostgreSQL the same question:</p>
<pre tabindex="0"><code>SELECT &#39;2026-10-25 01:30:00&#39;::timestamp AT TIME ZONE &#39;Europe/London&#39;;
-- 2026-10-25 01:30:00+00
</code></pre><p>PostgreSQL picked 01:30Z — the <strong>later</strong> one.</p>
<p>Same input, same tzdata, one hour apart. If your application resolves an ambiguous local time in Java and your reporting job resolves it in SQL, they will disagree for one hour, twice a year, in every DST zone.</p>
<p>There is no clever fix. The lesson is: <strong>never let a</strong> <strong>LocalDateTime cross the boundary and get resolved on the other side.</strong> Resolve to an Instant in exactly one place, with explicit overlap handling, and send the instant.</p>
<h4 id="dst-arithmetic-plusdays-is-not-plushours24">DST arithmetic: plusDays is not plusHours(24)</h4>
<pre tabindex="0"><code>ZonedDateTime start = ZonedDateTime.of(2026, 3, 28, 12, 0, 0, 0, london);
// 2026-03-28T12:00Z[Europe/London]
start.plusDays(1);                 // 2026-03-29T12:00+01:00  (23 real hours)
start.plus(Duration.ofDays(1));    // 2026-03-29T13:00+01:00  (24 real hours)
start.plusHours(24);               // 2026-03-29T13:00+01:00
</code></pre><p>plusDays preserves the wall clock. Duration preserves elapsed time. PostgreSQL draws the same line, using the same value:</p>
<pre tabindex="0"><code>SET TimeZone=&#39;Europe/London&#39;;
SELECT &#39;2026-03-28 12:00:00+00&#39;::timestamptz + interval &#39;1 day&#39;,   -- 2026-03-29 12:00:00+01
       &#39;2026-03-28 12:00:00+00&#39;::timestamptz + interval &#39;24 hours&#39;; -- 2026-03-29 13:00:00+01
</code></pre><p>This is one place the two platforms agree beautifully — interval &lsquo;1 day&rsquo; and plusDays(1) mean the same thing, and interval &lsquo;24 hours&rsquo; and Duration.ofDays(1) mean the same thing. &ldquo;Every day at 9am&rdquo; is plusDays / interval &lsquo;1 day&rsquo;. &ldquo;Every 24 hours&rdquo; is Duration / interval &lsquo;24 hours&rsquo;. Pick the one the product actually means.</p>
<h4 id="future-events-an-instant-is-notenough">Future events: an instant is not enough</h4>
<pre tabindex="0"><code>ZoneId ny = ZoneId.of(&#34;America/New_York&#34;);
ZonedDateTime.of(2027, 1, 15, 9, 0, 0, 0, ny).withZoneSameInstant(UTC); // 2027-01-15T14:00Z
ZonedDateTime.of(2027, 7, 15, 9, 0, 0, 0, ny).withZoneSameInstant(UTC); // 2027-07-15T13:00Z
</code></pre><p>“9am in New York” is a different UTC instant depending on the date. So if a user schedules a recurring 9am standup and a government later changes DST rules — which happens several times a year somewhere — the stored instant becomes wrong.</p>
<p>For <strong>past events</strong>, store the instant. That’s history; it can’t change.</p>
<p>For <strong>future user-scheduled events</strong>, store three things:</p>
<pre tabindex="0"><code>CREATE TABLE meetings (
  id            bigserial PRIMARY KEY,
  local_start   timestamp   NOT NULL,  -- 2027-01-15 09:00
  zone_id       text        NOT NULL,  -- &#39;America/New_York&#39;
  computed_utc  timestamptz NOT NULL   -- cache; recompute on tzdata update
);
</code></pre><p>The first two are the truth. The third is a derived index for querying, refreshed when tzdata changes.</p>
<h4 id="tzdata-is-a-movingtarget">tzdata is a moving target</h4>
<p>Java bundles a copy of the IANA database (2025b on the JDK I ran this on); PostgreSQL bundles its own; your OS has a third. They drift. When Java and PostgreSQL are on different tzdata versions, they will resolve recently-changed zones differently.</p>
<p>Check what you have:</p>
<pre tabindex="0"><code>ZoneRulesProvider.getVersions(&#34;Europe/London&#34;).lastKey();  // 2025b
</code></pre><pre tabindex="0"><code>SELECT name, utc_offset, is_dst FROM pg_timezone_names WHERE name = &#39;Europe/London&#39;;
</code></pre><p>Pin tzdata in your base images, and treat a tzdata bump as a deployment that requires recomputing cached future instants.</p>
<h3 id="part-4-wiring-java-to-postgresql">Part 4: Wiring Java to PostgreSQL</h3>
<h4 id="the-mappingtable">The mapping table</h4>
<p>Per the <a href="https://jdbc.postgresql.org/documentation/query/">pgJDBC documentation</a>:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-04.png"></p>
<p>Note the omission, in the driver’s own words:</p>
<blockquote>
<p><em>ZonedDateTime, Instant and OffsetTime / TIME WITH TIME ZONE are not supported.</em></p></blockquote>
<p>So don’t hand the driver an Instant and hope — depending on the driver version you&rsquo;ll either get a Can&rsquo;t infer the SQL type to use for an instance of java.time.Instant exception or undocumented behavior. Convert explicitly at the boundary instead:</p>
<pre tabindex="0"><code>// write
ps.setObject(1, instant.atOffset(ZoneOffset.UTC));
// read
Instant i = rs.getObject(&#34;occurred_at&#34;, OffsetDateTime.class).toInstant();
</code></pre><p>Note that reading a timestamptz gives you an OffsetDateTime normalized to UTC — the driver&rsquo;s offset is always Z, because that&rsquo;s what the backend holds. The offset carries no information. Convert straight to Instant and don&rsquo;t be tempted to read meaning into it.</p>
<h4 id="avoid-settimestamp--gettimestamp">Avoid setTimestamp / getTimestamp</h4>
<p>The java.sql.Timestamp overloads convert using the <strong>JVM default time zone</strong> unless you pass an explicit Calendar. That makes your persistence layer&rsquo;s correctness depend on the container&rsquo;s TZ environment variable. Use the java.time setObject/getObject methods instead — they&rsquo;re unambiguous.</p>
<p>If you must keep the JVM zone from mattering at all, set it explicitly at startup:</p>
<pre tabindex="0"><code>-Duser.timezone=UTC
</code></pre><p>Belt and braces, not a substitute for correct types.</p>
<h4 id="precision-java-has-nanos-postgresql-hasmicros">Precision: Java has nanos, PostgreSQL has micros</h4>
<pre tabindex="0"><code>Instant.parse(&#34;2026-08-15T10:00:00.123456789Z&#34;)           // .123456789
    .truncatedTo(ChronoUnit.MICROS)                        // .123456
</code></pre><p>PostgreSQL stores microseconds. Those last three digits are gone on the round trip, and PostgreSQL may <strong>round</strong> rather than truncate:</p>
<pre tabindex="0"><code>SELECT &#39;2026-08-15 10:00:00.123456789&#39;::timestamptz;  -- 10:00:00.123457
</code></pre><p>If you have an equality test or an optimistic-lock check comparing an in-memory Instant to one that&rsquo;s been through the database, truncate to micros <em>before</em> you persist so both sides agree.</p>
<h4 id="dont-wrap-the-column-in-afunction">Don’t wrap the column in a function</h4>
<p>Because timestamptz is stored as UTC, &ldquo;give me everything that happened on 1 Feb in New York&rdquo; tempts you into this:</p>
<pre tabindex="0"><code>EXPLAIN SELECT count(*) FROM events
WHERE (occurred_at AT TIME ZONE &#39;America/New_York&#39;)::date = DATE &#39;2026-02-01&#39;;
--  Seq Scan on events
</code></pre><p>Index gone. Compute the boundary instants instead and do a half-open range scan:</p>
<pre tabindex="0"><code>SELECT (DATE &#39;2026-02-01&#39; + time &#39;00:00&#39;) AT TIME ZONE &#39;America/New_York&#39;,  -- 2026-02-01 05:00+00
       (DATE &#39;2026-02-02&#39; + time &#39;00:00&#39;) AT TIME ZONE &#39;America/New_York&#39;;  -- 2026-02-02 05:00+00
EXPLAIN SELECT count(*) FROM events
WHERE occurred_at &gt;= &#39;2026-02-01 05:00:00+00&#39;
  AND occurred_at &lt;  &#39;2026-02-02 05:00:00+00&#39;;
--  Index Only Scan using events_occurred_at_idx
</code></pre><p>Note that this “day” is 24 hours only because February has no DST transition. On a transition day it’s 23 or 25 — which the boundary-instant approach handles correctly and a naive + interval &lsquo;24 hours&rsquo; does not. Half-open ranges (&gt;= and &lt;) also dodge the microsecond-boundary problem that BETWEEN creates.</p>
<h3 id="part-5-jpa-and-hibernate">Part 5: JPA and Hibernate</h3>
<p>Hibernate 6 made zoned types a first-class concern via TimeZoneStorageType:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-05.png"></p>
<p>For PostgreSQL, the practical consequence is settled by the database, not the ORM: timestamptz discards the offset, so under DEFAULT your OffsetDateTime round-trips as UTC. Which is fine — as long as you expected it.</p>
<p>Sensible defaults:</p>
<pre tabindex="0"><code>spring:
  jpa:
    properties:
      hibernate:
        jdbc:
          time_zone: UTC
        timezone:
          default_storage: NORMALIZE_UTC
</code></pre><p>And in the entity, be explicit about intent:</p>
<pre tabindex="0"><code>@Entity
public class Booking {
    
    // A moment. Maps to timestamptz.
    @Column(nullable = false)
    private Instant createdAt;
    
    // A date. Not a moment.
    @Column(nullable = false)
    private LocalDate serviceDate;
    
    // A wall-clock time that must not shift. Maps to timestamp.
    @Column(nullable = false)
    private LocalDateTime localStart;
    
    @Column(nullable = false)
    private String zoneId;   // &#39;Europe/London&#39;
    
    public ZonedDateTime start() {
        return localStart.atZone(ZoneId.of(zoneId));
    }
}
</code></pre><p>If you genuinely need the user’s original offset preserved, @TimeZoneStorage(TimeZoneStorageType.COLUMN) with @TimeZoneColumn writes it to a companion column. Use it when the offset is <em>data</em> — an audit trail of what the user&rsquo;s device claimed — not as a default.</p>
<h3 id="part-6-testing-thisstuff">Part 6: Testing This Stuff</h3>
<p>Datetime bugs are only cheap if you catch them before the clocks change. Three habits do most of the work.</p>
<h4 id="1-inject-aclock">1. Inject a Clock</h4>
<p>Instant.now() scattered through business logic is untestable. Inject java.time.Clock and you can move time at will:</p>
<pre tabindex="0"><code>@Bean Clock clock() { return Clock.systemUTC(); }
// in a test
Clock fixed = Clock.fixed(Instant.parse(&#34;2026-10-25T00:30:00Z&#34;), ZoneOffset.UTC);
</code></pre><h4 id="2-run-ci-in-a-hostile-timezone">2. Run CI in a hostile time zone</h4>
<p>If your JVM, your database, and your CI runner are all UTC, every zone bug hides until production. Force one of them somewhere awkward:</p>
<pre tabindex="0"><code>-Duser.timezone=Pacific/Chatham
</code></pre><p>+12:45 and it observes DST. If your test suite survives Chatham, it will survive most things. Do the same for the PostgreSQL container:</p>
<pre tabindex="0"><code>@Container
static PostgreSQLContainer&lt;?&gt; pg = new PostgreSQLContainer&lt;&gt;(&#34;postgres:16&#34;)
        .withEnv(&#34;TZ&#34;, &#34;Asia/Kathmandu&#34;)
        .withUrlParam(&#34;options&#34;, &#34;-c TimeZone=Asia/Kathmandu&#34;);
</code></pre><p>The point isn’t that production runs there — it’s that a test which only passes in UTC is a test that has proven nothing about zone handling.</p>
<h4 id="3-write-the-four-transition-tests">3. Write the four transition tests</h4>
<p>For any code that converts between local and instant, pin these explicitly:</p>
<pre tabindex="0"><code>static final ZoneId LONDON = ZoneId.of(&#34;Europe/London&#34;);
@Test void gapTimesAreRejectedNotSilentlyShifted() {
    LocalDateTime gap = LocalDateTime.of(2026, 3, 29, 1, 30);
    assertThat(LONDON.getRules().getValidOffsets(gap)).isEmpty();
    assertThatThrownBy(() -&gt; scheduler.schedule(gap, LONDON))
        .isInstanceOf(NonExistentLocalTimeException.class);
}
@Test void overlapTimesResolveToTheDocumentedChoice() {
    LocalDateTime overlap = LocalDateTime.of(2026, 10, 25, 1, 30);
    assertThat(LONDON.getRules().getValidOffsets(overlap)).hasSize(2);
    assertThat(scheduler.resolve(overlap, LONDON))
        .isEqualTo(Instant.parse(&#34;2026-10-25T00:30:00Z&#34;)); // earlier, by policy
}
@Test void dailyRecurrenceKeepsWallClockAcrossDst() {
    ZonedDateTime start = ZonedDateTime.of(2026, 3, 28, 9, 0, 0, 0, LONDON);
    assertThat(recurrence.next(start).toLocalTime()).isEqualTo(LocalTime.of(9, 0));
}
@Test void instantSurvivesTheDatabaseRoundTrip() {
    Instant original = Instant.now().truncatedTo(ChronoUnit.MICROS);
    repository.save(new Event(original));
    assertThat(repository.findLatest().occurredAt()).isEqualTo(original);
}
</code></pre><p>The fourth one catches more real bugs than you’d expect — it’s the one that fails when someone quietly changes a column from timestamptz to timestamp.</p>
<h3 id="the-shortversion">The Short Version</h3>
<p>If you skim one section, make it this one.</p>
<p><strong>Schema</strong></p>
<ul>
<li>timestamptz by default. It&rsquo;s the same 8 bytes and it&rsquo;s unambiguous.</li>
<li>timestamp only for wall-clock times that must not shift — and store the zone ID beside it.</li>
<li>date for dates. timetz for nothing.</li>
<li>Pin timezone = &lsquo;UTC&rsquo; in postgresql.conf and in the JDBC URL.</li>
</ul>
<p><strong>Java</strong></p>
<ul>
<li>Instant for things that happened. LocalDate for dates. ZonedDateTime for scheduling. OffsetDateTime at the JDBC boundary.</li>
<li>LocalDateTime is not a point in time. Treat every use as a question to answer, not an answer.</li>
<li>Never accept zone abbreviations. Full IANA names only.</li>
<li>plusDays ≠ plus(Duration.ofDays(1)). Know which one your product means.</li>
</ul>
<p><strong>The seam</strong></p>
<ul>
<li>pgJDBC speaks LocalDate/LocalTime/LocalDateTime/OffsetDateTime. Convert Instant explicitly.</li>
<li>Avoid setTimestamp/getTimestamp — they use the JVM default zone.</li>
<li>Truncate to microseconds before persisting.</li>
<li>Don’t wrap indexed timestamp columns in AT TIME ZONE; compute boundary instants instead.</li>
</ul>
<p><strong>And the one that bites hardest</strong></p>
<p>Java resolves an ambiguous local time to the <em>earlier</em> offset. PostgreSQL picks the <em>later</em> one. Resolve ambiguity in exactly one place, deliberately, and pass instants across the boundary — never local times.</p>
<p>Store the instant, render the local time, and keep the zone rules in exactly one layer. Most datetime bugs are just that rule, broken somewhere.</p>
<p><em>All examples verified on OpenJDK 21.0.10 (tzdata 2025b) and PostgreSQL 16.13.</em></p>
<p><strong>Sources</strong></p>
<ul>
<li><a href="https://www.postgresql.org/docs/current/datatype-datetime.html">PostgreSQL: Date/Time Types</a></li>
<li><a href="https://jdbc.postgresql.org/documentation/query/">pgJDBC: Using Java 8 Date and Time classes</a></li>
<li><a href="https://docs.hibernate.org/orm/6.4/javadocs/org/hibernate/annotations/TimeZoneStorageType.html">Hibernate</a> <a href="https://docs.hibernate.org/orm/6.4/javadocs/org/hibernate/annotations/TimeZoneStorageType.html">TimeZoneStorageType Javadoc</a></li>
<li><a href="https://docs.hibernate.org/orm/6.2/migration-guide/">Hibernate 6 migration guide</a></li>
<li><a href="https://thorben-janssen.com/hibernate-6-offsetdatetime-and-zoneddatetime/">Thorben Janssen: TimezoneStorageType</a></li>
</ul>
]]></content:encoded></item><item><title>From Source to Running JVM: How Gradle Builds Your Java Application</title><link>https://vitaliisukach.dev/posts/from-source-to-running-jvm-how-gradle-builds-your-java-application/</link><pubDate>Sun, 19 Jul 2026 11:14:16 +0000</pubDate><guid>https://vitaliisukach.dev/posts/from-source-to-running-jvm-how-gradle-builds-your-java-application/</guid><description>&lt;p>Build phases, task graphs, dependency resolution, and what actually happens when the JVM opens your JAR&lt;/p>
&lt;p>You type gradle build, wait a few seconds, and out comes a JAR. Most Java developers use this pipeline every day without ever looking inside it. But when a build gets slow, a dependency conflict appears, or a NoClassDefFoundError shows up in production at 2 AM, understanding the machinery underneath is the difference between guessing and fixing.&lt;/p></description><content:encoded><![CDATA[<p>Build phases, task graphs, dependency resolution, and what actually happens when the JVM opens your JAR</p>
<p>You type gradle build, wait a few seconds, and out comes a JAR. Most Java developers use this pipeline every day without ever looking inside it. But when a build gets slow, a dependency conflict appears, or a NoClassDefFoundError shows up in production at 2 AM, understanding the machinery underneath is the difference between guessing and fixing.</p>
<p>This article walks the full journey: Gradle’s three build phases, the Java plugin’s task graph, how dependency resolution actually works stage by stage, what a JAR file really is, and how the JVM reads and executes it.</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/from-source-to-running-jvm-how-gradle-builds-your-java-application/image-01.png"></p>
<h3 id="part-1-the-three-phases-every-gradle-build-goesthrough">Part 1: The Three Phases Every Gradle Build Goes Through</h3>
<p>Before a single line of your code is compiled, Gradle itself runs through a fixed lifecycle of three phases. This is true for every build, every plugin, every project.</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/from-source-to-running-jvm-how-gradle-builds-your-java-application/image-02.png"></p>
<h4 id="phase-1initialization">Phase 1 — Initialization</h4>
<p>Gradle reads settings.gradle(.kts) and answers one question: <em>which projects are part of this build?</em> For a single-module app that&rsquo;s trivial; for a multi-module monorepo this is where include(&quot;:core&quot;, &ldquo;:api&rdquo;, &ldquo;:app&rdquo;) gets evaluated and a Project object is created for each module.</p>
<h4 id="phase-2configuration">Phase 2 — Configuration</h4>
<p>Now every build.gradle(.kts) script executes top to bottom. This is the phase people misunderstand most. Your build script is <em>code that runs</em> — and it runs here, on every invocation, regardless of which task you asked for. The output of this phase is the <strong>task graph</strong>: a directed acyclic graph (DAG) of all tasks and their dependencies. Tasks are registered and wired together, but none of their actions execute yet.</p>
<blockquote>
<p><em>A</em> <em>println at the top level of build.gradle prints during Configuration — even if you run</em> <em>gradle help. Task actions run later. This trips up nearly everyone once.</em></p></blockquote>
<h4 id="phase-3execution">Phase 3 — Execution</h4>
<p>Gradle takes the task you requested, computes the minimal subgraph of tasks needed to produce it, and executes them in dependency order. Tasks whose inputs and outputs haven’t changed since the last run are marked UP-TO-DATE and skipped entirely — this is Gradle&rsquo;s incremental build engine, and it&rsquo;s why the second build is always faster than the first.</p>
<h3 id="part-2-the-java-plugin-taskgraph">Part 2: The Java Plugin Task Graph</h3>
<p>Applying the java plugin registers a standard chain of tasks. When you run gradle build, this is the graph that gets executed:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/from-source-to-running-jvm-how-gradle-builds-your-java-application/image-03.png"></p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/from-source-to-running-jvm-how-gradle-builds-your-java-application/image-04.png"></p>
<p>The practical shortcuts worth memorizing:</p>
<pre tabindex="0"><code># fastest feedback: compile only
gradle compileJava
# package without running tests
gradle jar
# full build, skip test execution
gradle build -x test
# nuke build/ and start clean
gradle clean build
</code></pre><h3 id="part-3-how-gradle-dependency-resolution-actuallyworks">Part 3: How Gradle Dependency Resolution Actually Works</h3>
<p>This is the part of Gradle most developers treat as magic. You write three lines in a dependencies block, and somehow the right JARs appear on your classpath. Here&rsquo;s the machinery, stage by stage.</p>
<h4 id="configurations-buckets-of-dependencies">Configurations: buckets of dependencies</h4>
<p>Every dependency you declare goes into a named <strong>configuration</strong> — a bucket with specific rules about where those dependencies are visible:</p>
<pre tabindex="0"><code>dependencies {
    implementation &#39;org.springframework.boot:spring-boot-starter-web:3.3.1&#39;
    api &#39;com.fasterxml.jackson.core:jackson-databind:2.17.1&#39;
    compileOnly &#39;org.projectlombok:lombok:1.18.32&#39;
    annotationProcessor &#39;org.projectlombok:lombok:1.18.32&#39;
    runtimeOnly &#39;org.postgresql:postgresql:42.7.3&#39;
    testImplementation &#39;org.junit.jupiter:junit-jupiter:5.10.2&#39;
}
</code></pre><p><img loading="lazy" src="https://vitaliisukach.dev/posts/from-source-to-running-jvm-how-gradle-builds-your-java-application/image-05.png"></p>
<p>The implementation vs api distinction matters in multi-module builds: implementation dependencies don&rsquo;t appear on the compile classpath of modules that depend on yours. That means fewer recompilations when they change, and a cleaner API boundary. Default to implementation; reach for api only when a type from that dependency appears in your public method signatures.</p>
<h4 id="the-resolution-stages">The resolution stages</h4>
<p>Declared dependencies are just coordinates on paper. Resolution is the process of turning them into actual files, and it happens <strong>lazily</strong> — only when a task first needs a classpath (typically compileJava during Execution). The stages:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/from-source-to-running-jvm-how-gradle-builds-your-java-application/image-06.png"></p>
<p><strong>Stage 1 — Graph construction.</strong> For each declared coordinate (group:name:version), Gradle queries your repositories <em>in the order they&rsquo;re declared</em> and downloads only the <em>metadata</em> first: the POM file or Gradle Module Metadata. That metadata lists the dependency&rsquo;s own dependencies, so Gradle recursively walks outward until the full transitive graph is known. No JARs have been downloaded yet — just descriptors.</p>
<p><strong>Stage 2 — Conflict resolution.</strong> Real dependency graphs always contain the same library requested at different versions (your app wants Jackson 2.17, some transitive path wants 2.15). Gradle’s default strategy is <em>highest version wins</em> — unlike Maven, which picks the “nearest” declaration in the tree. This default is usually right, but you can override it:</p>
<pre tabindex="0"><code>configurations.all {
    resolutionStrategy {
        // hard-pin a version, overriding everything
        force &#39;com.fasterxml.jackson.core:jackson-databind:2.17.1&#39;
        // or turn conflicts into build failures
        failOnVersionConflict()
    }
}
</code></pre><p><strong>Stage 3 — Constraints and rules.</strong> Before the graph is finalized, Gradle applies platforms (BOMs), version constraints, exclusions, and dependency substitutions. This is how Spring Boot keeps hundreds of libraries version-aligned with one line:</p>
<pre tabindex="0"><code>dependencies {
    implementation platform(&#39;org.springframework.boot:spring-boot-dependencies:3.3.1&#39;)
    // now version numbers can be omitted — the BOM supplies them
    implementation &#39;org.springframework.boot:spring-boot-starter-web&#39;
}
</code></pre><p>Exclusions cut unwanted transitive branches at the declaration site:</p>
<pre tabindex="0"><code>implementation(&#39;org.springframework.boot:spring-boot-starter-web&#39;) {
    exclude group: &#39;org.springframework.boot&#39;, module: &#39;spring-boot-starter-tomcat&#39;
}
</code></pre><p><strong>Stage 4 — Artifact download.</strong> Only now, with the final graph settled, does Gradle download the actual JAR files — and only for modules that survived resolution. Everything lands in the shared cache at ~/.gradle/caches/modules-2, keyed by checksum, shared across all projects on your machine. A dependency is downloaded once, ever, per machine (dynamic versions like 1.+ and snapshots get re-checked periodically).</p>
<p><strong>Stage 5 — Classpath assembly.</strong> The resolved files are ordered into a classpath and handed to whichever task requested them: compileClasspath to javac, runtimeClasspath to the test JVM, and so on.</p>
<h4 id="debugging-resolution">Debugging resolution</h4>
<p>Two commands answer 90% of “why is this version on my classpath” questions:</p>
<pre tabindex="0"><code># full resolved tree per configuration
gradle dependencies --configuration runtimeClasspath
# trace one library: who pulls it in, which versions were requested,
# and why the winner won
gradle dependencyInsight --dependency jackson-databind
</code></pre><h3 id="part-4-what-a-jar-file-reallyis">Part 4: What a JAR File Really Is</h3>
<p>The output of the jar task is nothing exotic — it&rsquo;s a ZIP archive with an agreed-upon internal layout. Rename it to .zip and any archive tool will open it:</p>
<pre tabindex="0"><code>myapp.jar
├── META-INF/
│   └── MANIFEST.MF          ← metadata
├── com/example/App.class     ← bytecode, path = package name
├── com/example/util/Helper.class
└── application.properties    ← resources sit alongside classes
</code></pre><p>The manifest is a plain-text key-value file. The line that matters most for a runnable JAR:</p>
<pre tabindex="0"><code>Manifest-Version: 1.0
Main-Class: com.example.App
</code></pre><p>One important caveat: the plain jar task packages <em>only your classes</em>. Your dependencies are not inside. For a self-contained deployable artifact you need a fat JAR — with the Shadow plugin, or Spring Boot&rsquo;s bootJar, which nests dependency JARs and adds its own launcher.</p>
<pre tabindex="0"><code>plugins {
    id &#39;com.github.johnrengelman.shadow&#39; version &#39;8.1.1&#39;
}
// gradle shadowJar → one JAR containing everything
</code></pre><h3 id="part-5-how-the-jvm-reads-yourjar">Part 5: How the JVM Reads Your JAR</h3>
<p>You run java -jar myapp.jar. Here&rsquo;s the sequence, and it&rsquo;s more interesting than it looks.</p>
<h4 id="step-1the-launcher-reads-themanifest">Step 1 — The launcher reads the manifest</h4>
<p>The java launcher opens the JAR as a ZIP, reads META-INF/MANIFEST.MF, and extracts Main-Class. Note a classic gotcha: with -jar, any -cp argument on the command line is <strong>silently ignored</strong>. The JAR itself (plus manifest Class-Path entries) becomes the entire application classpath.</p>
<h4 id="step-2the-classloader-hierarchy">Step 2 — The classloader hierarchy</h4>
<p>Classes are loaded by a chain of classloaders using <strong>parent-first delegation</strong>: every load request travels up to the top of the chain first, and only comes back down if no ancestor can satisfy it.</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/from-source-to-running-jvm-how-gradle-builds-your-java-application/image-07.png"></p>
<h4 id="step-3lazyloading">Step 3 — Lazy loading</h4>
<p>The JVM does <strong>not</strong> load every class in the JAR at startup. A class is loaded the first time it’s actively used — instantiated, statically referenced, reflected upon. This is why a missing transitive dependency can let your app boot cleanly and then blow up with NoClassDefFoundError twenty minutes later, the first time a rarely-used code path runs.</p>
<h4 id="step-4load-link-initialize">Step 4 — Load, Link, Initialize</h4>
<p>Per the JVM specification, every class goes through three phases before it’s usable:</p>
<ol>
<li><strong>Loading</strong> — the class bytes are read from the JAR, parsed, and a Class object is created in metaspace.</li>
<li><strong>Linking</strong> — three sub-steps:
<ul>
<li>Verification: the bytecode is checked for structural and type safety (stack shapes, valid jumps, access rules).</li>
<li>Preparation: static fields are allocated and set to defaults — 0, null, false. Not your values yet.</li>
<li>Resolution: symbolic references to other classes, methods, and fields are resolved to concrete ones (often lazily).</li>
</ul>
</li>
<li><strong>Initialization</strong> — static initializer blocks and static field assignments run, in source order, exactly once, on first active use. This is the point where static { &hellip; } blocks fire.</li>
</ol>
<h3 id="step-5main-and-thejit">Step 5 — main() and the JIT</h3>
<p>Once Main-Class is loaded, linked, and initialized, the JVM invokes main(String[] args) on the main thread. Execution starts in the interpreter. As methods get hot — called thousands of times — the JIT compiler (tiered: C1 first for fast, lightly-optimized code, then C2 for aggressively optimized code) compiles them to native machine code. That&rsquo;s why JVM applications famously get <em>faster</em> after warm-up.</p>
<h3 id="the-wholepicture">The Whole Picture</h3>
<pre tabindex="0"><code>src/main/java  ──javac──▶  build/classes  ──jar──▶  myapp.jar
                                                        │
                                             java -jar myapp.jar
                                                        │
                       read MANIFEST.MF → find Main-Class
                                                        │
                 classloader delegation (parent-first)
                                                        │
                 Load → Link (verify/prepare/resolve) → Init
                                                        │
                            main() runs, classes load lazily,
                            JIT compiles hot paths as you go
</code></pre><p>None of this is knowledge you need daily. But the day your build takes four minutes instead of forty seconds, or two versions of the same library fight on your classpath, or a class mysteriously fails to load in production — this is the map you’ll be reading. Better to have seen it before that day arrives.</p>
]]></content:encoded></item></channel></rss>