DEV Community: AnkitDevCode

The Idempotency Pattern: Making Retries Safe in Distributed Systems

AnkitDevCode — Fri, 11 Sep 2026 12:12:56 +0000

Introduction

Networks fail. Timeouts happen. Clients retry. Message brokers may redeliver messages.In distributed systems, you often can't know whether a request actually succeeded. The server may have completed the operation, but the response could have been lost.

The obvious solution is to retry. But retries are safe only when an operation is idempotent—running it multiple times produces the same result as running it once.

The Idempotency Pattern makes retries safe and helps build reliable distributed systems. This article explains the problem, common failure scenarios, how the pattern works, and how it supports safe scaling and loose coupling.

The Problem Statement

The "At-Least-Once" Reality

Most distributed systems deliver messages or requests at least once, not exactly once.

Retries, message broker redelivery, Outbox relays, and failover mechanisms can all cause the same request to be processed more than once. This is a practical trade-off because guaranteeing exactly-once delivery across a network is extremely difficult.

So the responsibility often moves to the receiver: it must safely handle duplicate requests.

If a service isn't designed for duplicates, a single retry can accidentally perform the same operation twice—with serious consequences such as duplicate payments, orders, or updates.

sequenceDiagram
    participant Client
    participant PaymentService
    participant Database

    Client->>PaymentService: POST /charge ($100)
    PaymentService->>Database: charge card, deduct balance
    Database-->>PaymentService: OK
    Note over PaymentService,Client: Response lost on the way back<br/>(timeout, network blip, crash)
    Client--xClient: Times out, assumes failure
    Client->>PaymentService: Retry: POST /charge ($100)
    PaymentService->>Database: charge card, deduct balance AGAIN
    Database-->>PaymentService: OK
    PaymentService-->>Client: 200 OK

The customer is charged twice for a single purchase—not because the payment failed, but because the client retried the request after not receiving the original response.

Why "Just Don't Retry" Isn't an Option

You might think: "If retries cause duplicates, why not avoid retries?"
Because that simply creates a different problem.

Many failures are temporary— a brief network interruption, a service restart, or a load balancer hiccup. Without retries, these temporary failures become permanent errors for the user, leading to failed requests and lost business.

So retries are an important part of building resilient distributed systems.

The real solution isn't to avoid retries. It's to make operations safe to repeat.

That's exactly what idempotency provides: the same request can be processed multiple times without causing unintended side effects.

flowchart LR
    A[Request sent] --> B{Response received?}
    B -->|Yes| C[Done]
    B -->|No| D[Did the operation execute?]
    D -->|Unknown| E[Retry]
    E --> F{Idempotent?}
    F -->|Yes| G[Safe to retry]
    F -->|No| H[Duplicate side effect]

Where This Bites in Practice

Idempotency becomes important anywhere a request can be retried, redelivered, or reprocessed.

Scenario	What can go wrong without idempotency
Payment processing	A timed-out payment request is retried → the customer is charged twice.
Order placement	A mobile app retries after a network failure → two identical orders are created.
Message consumers (Kafka/SQS/RabbitMQ)	A broker redelivers a message → the same event is processed twice, such as deducting inventory twice.
Outbox relay	The relay publishes an event but crashes before marking it as published → the event is published again after restart.
Email/notifications	A retry sends the same notification multiple times.
Distributed sagas	A saga step is retried after a coordinator failure → an action such as a refund may be applied twice.
API gateways/load balancers	A gateway retries a timed-out request while the original request is still running → the operation executes twice.
Batch/ETL jobs	A failed job is restarted from the beginning → records already processed may be inserted or updated again.

The Common Problem

All of these scenarios have the same root cause:

The same operation can be executed more than once, and the system cannot tell whether it is a new request or a retry of an operation that already succeeded.

This is why idempotency matters. It allows a system to safely retry or reprocess an operation without creating unintended side effects.

The Idempotency Pattern — The Solution

Core Idea

Attach a unique idempotency key to every request that can cause a side effect.

The server stores the key along with the result of the operation. If the same key is received again, the server knows it is a retry.

Instead of executing the operation again, it returns the original result.

In simple terms:

Same idempotency key = same operation → execute once, return the same result on retries.

flowchart LR
    A[Client generates<br/>idempotency key] --> B[Send request<br/>+ Idempotency-Key header]
    B --> C{Server: key seen before?}
    C -->|No| D[Execute operation]
    D --> E[Store key + result]
    E --> F[Return result]
    C -->|Yes| G[Skip execution]
    G --> H[Return stored result]

The key insight is that the client decides whether a request represents a new operation or a retry because the client knows its own intent.

The client generates an idempotency key once for each logical operation— for example, when the user clicks "Place Order".

If the request needs to be retried, the client sends the same key again. The server uses that key to recognize the request as a retry and returns the original result instead of executing the operation again.

Sequence Diagram: Idempotent Payment

sequenceDiagram
    participant Client
    participant PaymentService
    participant IdempotencyStore as Idempotency Store
    participant Database

    Client->>PaymentService: POST /charge<br/>Idempotency-Key: abc-123
    PaymentService->>IdempotencyStore: has key "abc-123"?
    IdempotencyStore-->>PaymentService: not found
    PaymentService->>Database: BEGIN TX
    PaymentService->>Database: charge card, deduct balance
    PaymentService->>IdempotencyStore: store key "abc-123" + result (same TX)
    PaymentService->>Database: COMMIT
    PaymentService-->>Client: 200 OK (charge succeeded)

    Note over Client: Response lost / times out
    Client->>PaymentService: Retry: POST /charge<br/>Idempotency-Key: abc-123

    PaymentService->>IdempotencyStore: has key "abc-123"?
    IdempotencyStore-->>PaymentService: found — return stored result
    PaymentService-->>Client: 200 OK (same result, no re-charge)

Notice that the idempotency check, business operation, and idempotency record should be handled in the same local transaction. This is important.

If the idempotency check and business write happen in separate transactions, you introduce a dual-write problem— the same kind of consistency problem that the Outbox Pattern addresses.

For a database-backed implementation, the idempotency record and the business side effect should be committed atomically.

Either both are committed, or neither is.

The Idempotency Store

The idempotency store keeps track of requests that have already been processed. It can be implemented using a database table, Redis, or another durable store, depending on the system's requirements.

A simple database-backed implementation might look like this:

idempotency_key	status	response_body	created_at	expires_at
`abc-123`	`completed`	`{"chargeId":"ch_1"}`	`2026-09-10T10:00:00Z`	`2026-09-17T10:00:00Z`

Typical fields include:

idempotency_key — A client-generated unique key representing one logical operation. The same key is reused for all retries of that operation.
status — Tracks the processing state, such as in_progress or completed. Some systems may also store failed, depending on how failed requests should be handled.
response_body — Stores the result that can be returned when the same request is retried.
created_at — Records when the idempotency entry was created.
expires_at — Defines how long the key should be retained. Idempotency records are usually kept for a bounded period rather than forever.

The exact fields and storage mechanism depend on the system. The important requirement is that the store can reliably recognize a previously processed key and return the appropriate result without repeating the side effect.

Handling the "In-Flight" Race

What happens if a retry arrives while the original request is still being processed?

Without proper coordination, both requests could see that the idempotency key does not exist and execute the business operation at the same time.

A common solution is to enforce a unique constraint on the idempotency key:

flowchart LR
    %% Request A (Primary Winner)
    subgraph ReqA ["Request A (Primary)"]
        A1["Incoming Request"] --> A2["Try INSERT idempotency key"]
        A2 -->|Success| A3["Mark status = in_progress"]
        A3 --> A4["Execute Business Logic"]
        A4 --> A5["Update status = completed"]
        A5 --> A6["Persist Response"]
    end

    %% Request B (Concurrent)
    subgraph ReqB ["Request B (Concurrent)"]
        B1["Incoming Request"] --> B2["Try INSERT idempotency key"]
        B2 -->|Constraint Violation| B3["Lookup existing key in Idempotency Table"]
        B3 --> B4{"Status Check"}
        B4 -->|Completed| B5["Return Cached Response"]
        B4 -->|In Progress| B6["Retry with Backoff / Return 409"]
    end

    %% Race condition visualization
    A2 -.->|Unique Key Conflict| B2

    %% Styling
    style A1 fill:#e0f2fe,stroke:#0369a1,stroke-width:2px,color:#0c4a6e
    style A2 fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    style A3 fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    style A4 fill:#f3e8ff,stroke:#7e22ce,stroke-width:2px,color:#3b0764
    style A5 fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d
    style A6 fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d

    style B1 fill:#e0f2fe,stroke:#0369a1,stroke-width:2px,color:#0c4a6e
    style B2 fill:#fee2e2,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d
    style B3 fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    style B4 fill:#f3e8ff,stroke:#7e22ce,stroke-width:2px,color:#3b0764
    style B5 fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d
    style B6 fill:#fee2e2,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d

The first request successfully creates the idempotency record and becomes the owner of the operation.

If another request arrives with the same key while the operation is still running, the unique constraint prevents it from creating another record. The second request must not execute the business operation. Depending on the system, it can wait, poll for the result, or return an in_progress/conflict response.

Once the first request completes, the record is updated with the final status and response.

One key → one active operation → no parallel execution of the same logical request.

Different Layers Where Idempotency Applies

Idempotency isn't a single technique — it shows up differently depending on where in the stack you apply it:

1. HTTP API level (client-supplied key)
Client sends an Idempotency-Key header (this is literally how Stripe's and PayPal's payment APIs work). Best for client-initiated actions like charges, orders, and transfers.

2. Message consumer level (message ID / offset)
When consuming from Kafka, SQS, or RabbitMQ, use the message's unique ID (or a business key embedded in the payload) to check "have I already processed this message?" before applying its side effects — critical because brokers guarantee at-least-once delivery by design.

flowchart LR
    Broker((Broker)) --> Consumer[Consumer Service]
    Consumer --> Check{"Seen in<br/>processed_messages?"}

    Check -->|No| Process["1. Apply Side Effect<br/>2. Record message_id (Same TX)"]
    Check -->|Yes| Skip[Skip — Duplicate Message]

    style Broker fill:#f3e8ff,stroke:#7e22ce,stroke-width:2px,color:#3b0764
    style Consumer fill:#e0f2fe,stroke:#0369a1,stroke-width:2px,color:#0c4a6e
    style Check fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    style Process fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d
    style Skip fill:#fee2e2,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d

3. Natural idempotency via design (idempotent-by-construction)
Some operations are inherently safe to repeat without requiring an external deduplication store, explicit state tracking, or distributed locks:

Absolute vs. relative state changes: An absolute update like UPDATE accounts SET status = 'active' is idempotent because applying it multiple times leaves the row in the exact same state. Conversely, a relative update like UPDATE accounts SET balance = balance - 100 is non-idempotent because each execution subtracts more funds. (Note: While absolute updates are mathematically idempotent, ensure they don't blindly overwrite concurrent state changes made by other transactions).
Database constraints and upserts: Using clauses like INSERT ... ON CONFLICT DO NOTHING or ON CONFLICT DO UPDATE anchored to a unique business key (such as an order_number) turns duplicate write attempts into safe, predictable outcomes.
RESTful HTTP semantics: Designing APIs around PUT /resource/{id} (which replaces the target resource entirely with the provided payload) ensures idempotency because sending the exact same payload twice yields the identical end state. In contrast, POST /resource is designed for creation and is non-idempotent, spawning a new resource with a new identifier on every call.

How This Achieves Loose Coupling

Idempotency reduces the amount of coordination required between components in a distributed system.

Clients and servers can evolve independently. A client can safely retry after a timeout, connection failure, or 5xx response without knowing whether the server already processed the request. The server guarantees that repeating the same operation won't create another side effect.
Producers and consumers don't need exactly-once delivery. In event-driven systems, the broker can use simple at-least-once delivery and redeliver messages when necessary. The consumer handles duplicates using its own idempotency mechanism.
Failures become easier to recover from. A service, relay, or workflow can retry an operation after a crash without needing to know exactly where the previous attempt stopped. Idempotency makes repeating the operation safe.

In short:

At-least-once delivery + idempotent processing = reliable systems with less coordination.

Each component can retry independently, while the receiver ensures that repeated requests or messages don't produce repeated side effects.

How This Achieves Scaling

Idempotency makes it easier to scale distributed systems because requests and messages can be retried or processed by different instances without repeating their side effects.

Safe horizontal scaling and failover. A request can be retried against any healthy service instance. The idempotency key ensures that another instance doesn't perform the same operation again.
Simpler retry handling. Clients and services can use retries with exponential backoff without worrying that a retry will automatically create another side effect. Retry limits and backoff are still important to avoid overwhelming the system.
At-least-once messaging becomes practical. Brokers such as Kafka, SQS, and RabbitMQ can use at-least-once delivery and redeliver messages when necessary. Idempotent consumers prevent those redeliveries from causing duplicate effects.
Parallel processing with less coordination. Multiple consumer instances can process messages concurrently. If a message is delivered more than once—for example, during a consumer restart or rebalance—the idempotency check prevents the side effect from being applied twice.
Reduces the impact of retries during failures. Under heavy load, timeouts and retries can increase. Without idempotency, those retries may create additional work or duplicate side effects. Idempotency prevents the same operation from being applied repeatedly, helping the system recover more safely.

The key idea is:

Idempotency allows the system to scale and recover using retries and at-least-once delivery without requiring every component to coordinate exactly-once execution.

Trade-offs to Be Aware Of

Extra storage and lookup cost. Idempotency requires storing and checking a key, which adds a small amount of latency, database/storage usage, and operational overhead.
Key expiration and retention. Idempotency records cannot be kept forever. You need a retention period that is long enough to cover realistic retry delays while preventing unbounded storage growth.
Client responsibility. The client must generate the key once for each logical operation and reuse the same key for all retries. Generating a new key for every retry makes the server treat each retry as a new operation.
Not automatic for multi-step workflows. Idempotency protects an individual operation; it does not automatically make an entire workflow idempotent. In a saga or multi-step process, each side-effecting step should be designed to handle retries safely, along with the workflow's coordination and recovery logic.
External side effects require additional handling. A local idempotency record cannot be committed atomically with an external API call. If the external system supports idempotency, the same key should be propagated downstream. Otherwise, reconciliation or another coordination mechanism may be required.
Concurrency requires careful implementation. A naive check → process → save approach is vulnerable to race conditions when the same key arrives concurrently. Use an atomic claim, unique constraint, or another concurrency-control mechanism to ensure that only one request can own the operation.

Idempotency + Outbox: Natural Partners

These two patterns are frequently used together because they solve two closely related reliability problems:

Idempotency prevents the same operation from producing duplicate side effects when requests or messages are retried.
Outbox ensures that an event generated by a successful database transaction is reliably published to a message broker.

Together, they provide a robust approach for building systems that can safely retry operations and reliably propagate the resulting events.

flowchart TD
    A[Business Operation] --> B["Outbox Pattern:<br/>Atomically write state + event locally"]
    B --> C["Relay Worker:<br/>Publishes event (at-least-once)"]
    C --> D["Idempotent Consumer:<br/>Dedupes by message_id"]
    D --> E["Reliable Exactly-Once Effect<br/>(without distributed transactions)"]

    style A fill:#f3e8ff,stroke:#7e22ce,stroke-width:2px,color:#3b0764
    style B fill:#e0f2fe,stroke:#0369a1,stroke-width:2px,color:#0c4a6e
    style C fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    style D fill:#e0f2fe,stroke:#0369a1,stroke-width:2px,color:#0c4a6e
    style E fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d

Outbox guarantees an event is never lost. Idempotency guarantees that even if the event (or the retry of a request) arrives more than once, the end effect is as if it arrived exactly once. Together, they turn "at-least-once, unreliable network" into "reliable, correct, exactly-once-effect" system behavior — without needing expensive distributed transactions anywhere.

Summary

Without Idempotency	With Idempotency
Retries can cause duplicate side effects such as double charges or duplicate orders	Retries with the same key can safely return the original result without repeating the side effect
Avoiding retries may seem safer, but reduces resilience	Retries can be used safely with appropriate limits, backoff, and jitter
Systems may try to achieve exactly-once processing across unreliable networks	At-least-once delivery + idempotent processing provides reliable effective behavior
Client and server need tighter coordination around retry outcomes	Client can retry independently; the server handles duplicate requests
Retries during failures can amplify load and duplicate side effects	Duplicate requests are absorbed, reducing the impact of retries and redelivery

The key idea behind the Idempotency Pattern is to avoid making the network guarantee exactly-once execution. Instead, the system accepts that requests or messages may be delivered more than once and makes the processing itself safe to repeat.

In practice:

At-least-once delivery + idempotent processing = reliable retry behavior

This simple shift makes retries, message redelivery, failover, and horizontal scaling much easier to design. Instead of trying to prevent every duplicate delivery, the system ensures that duplicates do not produce duplicate side effects.

The Outbox Pattern: Solving the Dual-Write Problem in Distributed Systems

AnkitDevCode — Thu, 10 Sep 2026 16:36:42 +0000

Introduction

In a microservices architecture, a single business operation often needs to update a database and notify other services through a message broker, REST API, or another integration mechanism.

For example, when an order is created, the Order Service must save the order and publish an OrderCreated event.

The challenge is that these are two separate operations involving two different systems. The database update may succeed while event publishing fails—or the event may be published while the database transaction rolls back.

This is the dual-write problem.

The Outbox Pattern solves this by storing the business data and the event in the same database transaction, and publishing the event asynchronously from the outbox.

In this article, we'll see how the dual-write problem occurs, how the Outbox Pattern solves it, and how to handle retries, duplicate events, idempotency, and scalability.

Note: Throughout this article, we’ll use event publishing as the primary example for simplicity. The same underlying problem can occur whenever a database change needs to trigger an interaction with another system—for example, a REST API call, webhook, message broker, or other external operation. The examples will focus on events, but the core principles apply more broadly.

The Problem Statement

The Dual-Write Problem

Imagine an OrderService that, when an order is placed, must:

Insert a row into the orders table.
Publish an OrderCreated event so that InventoryService, NotificationService, and BillingService can react.

The naive implementation looks like this:

sequenceDiagram
    participant Client
    participant OrderService
    participant Database
    participant MessageBroker as Message Broker

    Client->>OrderService: POST /orders
    OrderService->>Database: INSERT INTO orders
    Database-->>OrderService: OK
    OrderService->>MessageBroker: publish(OrderCreated)
    MessageBroker-->>OrderService: ACK
    OrderService-->>Client: 201 Created

This looks fine — until you ask: what happens if step 2 succeeds but step 3 fails, or vice versa?

Failure Scenarios

The dual-write problem becomes clearer when we look at what can go wrong.

Scenario A — Database commit succeeds, but event publishing fails
The order is successfully saved in the database, but the broker is unavailable, the network fails, or the application crashes before publishing the event.
The order exists, but downstream services such as InventoryService and BillingService may never know about it.

Scenario B — Event publishing succeeds, but the database transaction rolls back
Downstream services may start processing an OrderCreated event even though the order was never successfully committed to the Order Service's database.

This can lead to inconsistent or invalid state in downstream services.
Now you have phantom orders in every consuming service.

Scenario C — The application crashes between the two operations
Even if you reorder operations (publish first, write DB second, or wrap both in a "try/catch and retry"), a crash between the two non-atomic operations always leaves a window where state is inconsistent. You cannot make two independent I/O calls to two independent systems (a database and a broker) atomic using application-level logic alone. There is no distributed transaction spanning both by default.

Scenario D — Retries can create duplicate events
To defend against Scenario A, an engineer adds a retry: "if publish fails, try again." But now imagine the publish actually succeeded, only the ACK was lost. The retry sends a second OrderCreated event. Now inventory gets reserved twice.

If the consumer is not idempotent, it could perform the same business operation twice—for example, attempting to reserve inventory twice.

This is why reliable event-driven systems typically combine the Outbox Pattern with retries and idempotent consumers.

flowchart LR
    A[Business Operation]

    A --> B[(Database)]
    A --> C[Message Broker]

    B -->|Write| D{Atomic?}
    C -->|Publish| D

    D -->|No| E[⚠️ Dual-Write Problem]

    E --> F[Database succeeds<br/>Event fails]
    E --> G[Event succeeds<br/>Database rolls back]
    E --> H[Retry / crash<br/>causes duplicates]

Where This Bites in Practice

The dual-write problem can appear anywhere a business operation must persist state and publish an event.

Scenario	What can go wrong without an Outbox
E-commerce checkout	Order is saved, but `OrderCreated` is not published → inventory may not be reserved and downstream services never learn about the order.
Payments	Payment is recorded, but the event sent to fraud detection is lost → the transaction may not be evaluated by the fraud service.
User signup	User is created, but `UserRegistered` is not published → the email or onboarding service never receives the event.
Saga / distributed workflows	A saga step commits its local state but fails to publish the event that triggers the next step → the workflow can get stuck waiting for an event that never arrives.
CQRS / read-model synchronization	The write-side database is updated, but the event used to update the read model is lost → the read model can become stale or inconsistent.
Audit / compliance	A state change is committed, but the corresponding audit event is lost → the audit trail may contain gaps.

Despite the different use cases, the underlying problem is the same:

A business operation changes local state and publishes an event, but those two actions cannot be committed atomically as part of the same local transaction.

That is the problem the Outbox Pattern is designed to address.

The Outbox Pattern — The Solution

Core Idea

Instead of writing to the database and separately publishing to the broker, you do only one atomic operation: write your business data and the event into the same local database, in the same ACID transaction.

A dedicated background process then reads that "outbox" table and reliably relays the events to the message broker, retrying as needed, after the transaction has safely committed.

flowchart LR
    subgraph "Step 1: Single Atomic Transaction"
        A[OrderService] -->|"BEGIN TX"| B[(orders table)]
        A -->|"same TX"| C[(outbox table)]
        B --> D["COMMIT"]
        C --> D
    end
    D --> E[Message Relay / Poller]
    E -->|"reads unpublished rows"| C
    E -->|"publishes"| F[Message Broker]
    F --> G[Inventory Service]
    F --> H[Billing Service]
    F --> I[Notification Service]
    E -->|"marks row as published"| C

Because orders and outbox live in the same database, a single local ACID transaction guarantees: if the order is saved, the outbox event is saved too — and if the transaction rolls back, neither exists. There is no window where one happens without the other.

The Outbox Table

A typical outbox table looks like this:

erDiagram
    OUTBOX_EVENT {
        bigint id PK
        string aggregate_type
        string aggregate_id
        string event_type
        json payload
        timestamp created_at
        timestamp published_at
    }

The important part is that the order record and the outbox record are created in the same database transaction.

Sequence Diagram: End-to-End Flow

sequenceDiagram
    participant Client
    participant OrderService
    participant DB as Database (orders + outbox)
    participant Relay as Message Relay
    participant Broker as Message Broker
    participant Consumer as Downstream Service

    Client->>OrderService: POST /orders
    OrderService->>DB: BEGIN TX
    OrderService->>DB: INSERT INTO orders
    OrderService->>DB: INSERT INTO outbox (event)
    OrderService->>DB: COMMIT
    DB-->>OrderService: OK
    OrderService-->>Client: 201 Created

    loop Poll / CDC stream
        Relay->>DB: SELECT unpublished outbox rows
        DB-->>Relay: rows
        Relay->>Broker: publish(event)
        Broker-->>Relay: ACK
        Relay->>DB: mark published
    end

    Broker->>Consumer: OrderCreated event
    Consumer->>Consumer: reserve inventory / charge / notify

Notice: the client gets a response the instant the local transaction commits. Publishing to the broker happens asynchronously and reliably in the background — the client is never blocked on the broker being available.

Two Ways to Implement the Relay

Once the transaction commits, we need a relay to move events from the outbox table to the message broker. There are two common approaches.

1. Polling Publisher
A background process periodically queries the outbox table for events that have not yet been published.

SELECT * FROM outbox_events WHERE published_at IS NULL ORDER BY created_at LIMIT 100;

This approach is simple and easy to implement, but frequent polling can add database load and introduce some publishing latency.

It is often a good choice when the event volume is moderate and simplicity is more important than achieving very low latency.

2. Change Data Capture (CDC) — e.g., Debezium
A CDC tool tails the database's transaction log (e.g., MySQL binlog, Postgres WAL) and streams outbox inserts directly to the broker in near real-time, without polling the table at all.

CDC can provide lower latency and better scalability than frequent polling, particularly for high-throughput systems. However, it also introduces additional infrastructure and operational complexity.

flowchart TD
    subgraph Polling Approach
        P1[Scheduled Job] -->|"SELECT ... WHERE published_at IS NULL"| P2[(Outbox Table)]
        P1 --> P3[Broker]
    end
    subgraph CDC Approach
        C1[Debezium / CDC Connector] -->|"tails WAL/binlog"| C2[(Outbox Table)]
        C1 --> C3[Broker]
    end

CDC is generally preferred in high-throughput systems: no polling overhead, lower latency, and it captures changes at the storage engine level so nothing is missed even under load.

How This Achieves Loose Coupling

The Outbox Pattern isn't just a reliability trick — it's structurally what makes event-driven microservices loosely coupled:

Producer doesn't know who's listening. OrderService never calls InventoryService or BillingService directly. It just writes an event to its own outbox. Any number of new consumers can subscribe later with zero changes to OrderService.
No synchronous dependency chain. If BillingService is down, OrderService is completely unaffected — it already committed its transaction and moved on. Compare this to direct service-to-service calls, where a downstream outage cascades upstream.
Producer and consumer can evolve independently. As long as the event schema is respected (ideally versioned), each service can be deployed, scaled, and changed on its own timeline.
Failure isolation. A bug or outage in the message broker or in a consumer doesn't threaten the producer's data integrity — the outbox table is durable, local, and transactionally consistent regardless of what's happening downstream.

flowchart LR
    O[OrderService] -->|writes event, no direct call| Outbox[(Outbox)]
    Outbox --> Relay
    Relay --> Broker((Broker))
    Broker --> S1[Inventory Service]
    Broker --> S2[Billing Service]
    Broker --> S3[Notification Service]
    Broker --> S4[Analytics Service - added later, zero changes upstream]

How This Achieves Scaling

Producer scaling is decoupled from consumer scaling. OrderService throughput is governed only by its own DB, not by how fast BillingService can process events. Consumers can scale horizontally (more partitions, more consumer instances) independently, at their own pace.
Backpressure absorption. If a downstream consumer is slow or temporarily down, events simply queue up in the broker/outbox — they aren't lost, and the producer keeps accepting new requests without slowing down.
Horizontal scaling of the relay itself. Multiple relay instances can process the outbox table in parallel by sharding on aggregate_id, with row-level locking (SELECT ... FOR UPDATE SKIP LOCKED) to avoid double-publishing.
CDC-based relays scale near-linearly with database throughput since they read the transaction log rather than executing repeated table scans.
New consumers scale the system's capabilities, not its coupling. Adding a 5th, 10th, or 20th downstream service to react to OrderCreated costs nothing on the producer side — it's purely an additive subscription to the broker topic.

Trade-offs to Be Aware Of

No pattern is free. Be honest about these costs when adopting Outbox:

At-least-once delivery, not exactly-once. A crash between publishing and marking a row as published can cause the same event to be sent twice. Consumers must be idempotent (e.g., dedupe using an event ID).
Added latency. Events aren't published in the same millisecond as the DB write — there's a small delay (milliseconds with CDC, potentially seconds with polling).
Extra infrastructure. You now need a relay process (or CDC pipeline like Debezium + Kafka Connect) to operate and monitor.
Ordering guarantees need care. If ordering matters (e.g., events for the same order must be processed in sequence), you need to partition by aggregate_id so all events for the same entity go to the same broker partition/consumer.
Outbox table growth. Published rows need to be archived or deleted periodically to avoid unbounded table growth.

Summary

Without Outbox	With Outbox
Two independent, non-atomic writes (DB + broker)	One atomic local transaction (DB + outbox row)
Silent event loss or duplication under failure	Reliable, at-least-once delivery via relay/CDC
Producer implicitly coupled to broker availability	Producer only depends on its own database
Hard to add new consumers safely	New consumers subscribe freely, no upstream changes
Scaling is tangled between producer and consumer	Producer and consumer scale independently

The Outbox Pattern converts a distributed atomicity problem (which is hard) into a local atomicity problem (which databases already solve well), then hands off reliable delivery to a purpose-built relay. That's the whole trick — and it's why it underpins so much of reliable event-driven architecture today.

Java Thread Coordination

AnkitDevCode — Wed, 09 Sep 2026 14:09:49 +0000

Coordinating threads — making them wait for each other, hand off data, or run in a controlled order — is one of the harder parts of concurrent programming. Java's toolkit spans several layers: JVM-native primitives (wait/notify, join), the java.util.concurrent package (locks, latches, executors, atomics), and newer additions from Project Loom (virtual threads, structured concurrency). This guide covers the full set, organized bottom-up, with the key contract each API makes, why it matters, and a runnable example.

Core idea: thread coordination is about two things: controlling execution and making memory effects visible. Prefer the highest-level API that directly expresses the relationship you need.

1. Basic Thread Coordination

A useful mental model is:

join()      -> wait for a thread
sleep()     -> wait for time
interrupt() -> request cooperative cancellation

Thread.start() is also a coordination boundary: actions in the calling thread before start() happen-before actions in the started thread.

The oldest tools, defined directly on java.lang.Thread.

`Thread.start()`

start() schedules a new thread to execute run(). Calling run() directly does not create a new thread.

Thread worker = new Thread(() ->
        System.out.println(Thread.currentThread().getName()));

worker.start(); // concurrent execution
// worker.run(); // ordinary method call; no new thread

`Thread.join()`

Blocks the calling thread until the target thread terminates.

join() waits indefinitely; join(millis) / join(millis, nanos) time out — after which the caller resumes even if the thread is still alive, so check isAlive() if that matters.
Implemented internally via wait(), so it responds to interruption with InterruptedException.

Thread worker = new Thread(() -> {
System.out.println("Working...");
});

worker.start();

worker.join(); // Main thread blocks here until worker finishes

System.out.println("Worker done, continuing.");

`Thread.sleep()`

Thread.sleep() pauses the current thread. It is not a synchronization mechanism and does not release monitors or explicit locks held by that thread.

synchronized (lock) {
    Thread.sleep(1_000); // lock is still held
}

Pauses the current thread without releasing any locks it holds.

Sleeps for at least the requested duration — not guaranteed to be exact.
Clears the interrupt flag when it throws InterruptedException; re-set it in your catch block if the thread needs to keep behaving as interrupted.

try {
    Thread.sleep(500); // Pause for 500 ms
} catch (InterruptedException e) {
    Thread.currentThread().interrupt(); // Restore interrupt status
}

`Thread.interrupt()`

Sets a thread's interrupt flag; does not forcibly stop it.

If blocked in wait/sleep/join, the target wakes immediately with InterruptedException and the flag clears.
If running normal code, cooperative polling (Thread.interrupted() / isInterrupted()) is required to notice it.

Thread worker = new Thread(() -> {
    while (!Thread.currentThread().isInterrupted()) {
        // Do work
    }

    System.out.println("Exiting cleanly on interrupt");
});

worker.start();

worker.interrupt(); // Request cooperative shutdown

2. Memory Visibility: `volatile`

Not a blocking mechanism, but foundational to coordination: a volatile field guarantees that writes by one thread are immediately visible to reads by others, and prevents the compiler/CPU from reordering around it. Many hand-rolled "flag" coordination patterns (e.g., a running flag checked in a loop) are broken without it.

public class Worker implements Runnable {

    private volatile boolean running = true;

    @Override
    public void run() {
        while (running) {
            // Do work
        }
    }

    public void stop() {
        running = false; // Guaranteed visible to the running thread
    }
}

volatile gives visibility, not atomicity — volatile int count; count++; is still a race. For that, use synchronized or the atomic classes below.

3. Monitor-Based Coordination (Intrinsic Locks)

Every object carries an implicit monitor — the original coordination mechanism, defined on Object.

`synchronized`

Acquires an object's (or a class's, for static methods) intrinsic lock on entry, releases it on exit — even via exception. Reentrant, and establishes happens-before visibility guarantees.

public class Counter {

    private int count = 0;

    public synchronized void increment() {
        count++;
    }

    public synchronized int get() {
        return count;
    }
}

`Object.wait()` / `notify()` / `notifyAll()`

wait() releases the monitor and suspends the thread until notify/notifyAll is called on the same object, or a timeout elapses. Must be called while holding the lock, or it throws IllegalMonitorStateException. Spurious wakeups are allowed by the JLS, so wait() must always sit in a while loop.

public class BoundedCell {

    private int value;
    private boolean hasValue = false;

    public synchronized void put(int v) throws InterruptedException {
        while (hasValue) {
            wait(); // Wait until the current value is consumed
        }

        value = v;
        hasValue = true;

        notifyAll(); // Wake any waiting consumer
    }

    public synchronized int take() throws InterruptedException {
        while (!hasValue) {
            wait(); // Wait until a value is produced
        }

        hasValue = false;

        notifyAll(); // Wake any waiting producer

        return value;
    }
}

notify() wakes exactly one arbitrary waiter; notifyAll() wakes all of them so each re-checks its own condition — generally the safer default.

`wait()` vs `sleep()`

sleep()
  -> pauses current thread
  -> does NOT release a lock

wait()
  -> releases the object's monitor
  -> waits for notification/timeout/interruption
  -> reacquires the monitor before returning

Always guard wait() with a condition loop:

while (!condition) {
    wait();
}

The condition must be re-checked after every wake-up.

4. Explicit Lock Coordination (`java.util.concurrent.locks`)

Added to overcome synchronized's rigidity: interruptible acquisition, timeouts, fairness, and multiple wait-sets per lock.

`ReentrantLock`

private final ReentrantLock lock = new ReentrantLock();

public void updateSharedState() {
    lock.lock();

    try {
        // Critical section
    } finally {
        lock.unlock(); // Must release manually, unlike synchronized
    }
}

// Non-blocking variant
if (lock.tryLock()) {
    try {
        // Got the lock
    } finally {
        lock.unlock();
    }
} else {
    // Do something else instead of blocking
}

When `ReentrantLock` is preferable

Start with synchronized for simple mutual exclusion. Reach for ReentrantLock when you specifically need capabilities such as:

tryLock()
timed acquisition
interruptible acquisition
configurable fairness
multiple independent Conditions

`Condition` — `await()` / `signal()` / `signalAll()`

A ReentrantLock can spawn multiple Conditions, letting you separate "buffer full" from "buffer empty" instead of waking every waiter indiscriminately.

private final ReentrantLock lock = new ReentrantLock();

private final Condition notFull = lock.newCondition();
private final Condition notEmpty = lock.newCondition();

private final int[] buffer = new int[10];

private int count = 0;
private int putIdx = 0;
private int takeIdx = 0;

public void put(int v) throws InterruptedException {
    lock.lock();

    try {
        while (count == buffer.length) {
            notFull.await(); // Wait until space is available
        }

        buffer[putIdx] = v;
        putIdx = (putIdx + 1) % buffer.length;
        count++;

        notEmpty.signal(); // Wake a waiting consumer
    } finally {
        lock.unlock();
    }
}

public int take() throws InterruptedException {
    lock.lock();

    try {
        while (count == 0) {
            notEmpty.await(); // Wait until an item is available
        }

        int v = buffer[takeIdx];
        takeIdx = (takeIdx + 1) % buffer.length;
        count--;

        notFull.signal(); // Wake a waiting producer

        return v;
    } finally {
        lock.unlock();
    }
}

`ReadWriteLock` / `ReentrantReadWriteLock`

Splits a lock into a read lock (shared, many readers concurrently) and a write lock (exclusive) — ideal for read-heavy shared state.

private final ReentrantReadWriteLock rwLock =
        new ReentrantReadWriteLock();

private final Map<String, String> cache = new HashMap<>();

public String read(String key) {
    rwLock.readLock().lock();

    try {
        return cache.get(key);
    } finally {
        rwLock.readLock().unlock();
    }
}

public void write(String key, String value) {
    rwLock.writeLock().lock();

    try {
        cache.put(key, value);
    } finally {
        rwLock.writeLock().unlock();
    }
}

`StampedLock` (Java 8+)

Adds a third, optimistic read mode: readers don't block at all, they just validate afterward that no write happened concurrently — much higher throughput for read-heavy, short-critical-section workloads than ReentrantReadWriteLock.

private final StampedLock stampedLock = new StampedLock();

private double x;
private double y;

public double distanceFromOrigin() {
    long stamp = stampedLock.tryOptimisticRead();

    double curX = x;
    double curY = y;

    if (!stampedLock.validate(stamp)) {
        // A write happened during the read
        stamp = stampedLock.readLock();

        try {
            curX = x;
            curY = y;
        } finally {
            stampedLock.unlockRead(stamp);
        }
    }

    return Math.sqrt(curX * curX + curY * curY);
}

public void move(double deltaX, double deltaY) {
    long stamp = stampedLock.writeLock();

    try {
        x += deltaX;
        y += deltaY;
    } finally {
        stampedLock.unlockWrite(stamp);
    }
}

Note: StampedLock is not reentrant — re-acquiring from the same thread will deadlock.

5. Atomic Variables & Compare-And-Swap (`java.util.concurrent.atomic`)

Lock-free coordination for single variables, built on hardware CAS (compare-and-swap) instructions — faster than locking under contention for simple counters/flags/references.

AtomicInteger counter = new AtomicInteger(0);

counter.incrementAndGet(); // Atomic ++

counter.compareAndSet(5, 10);
// Set to 10 only if the current value is 5

AtomicReference<String> current =
        new AtomicReference<>("idle");

current.compareAndSet("idle", "running");
// Classic state-transition guard

// updateAndGet applies a function atomically,
// retrying under contention
AtomicLong total = new AtomicLong(0);

total.updateAndGet(v -> v + computeDelta());

CAS mental model

A compare-and-set operation follows this conceptual loop:

read current value
      ↓
calculate new value
      ↓
CAS(oldValue, newValue)
      ↓
success?
 ├── yes -> done
 └── no  -> retry

CAS is excellent for single-variable state transitions, but becomes harder to reason about when several related variables must change together.

For very high-contention counters, LongAdder / DoubleAdder (also in java.util.concurrent.atomic) outperform AtomicLong by striping the counter across internal cells and summing on read.

LongAdder hits = new LongAdder();

hits.increment(); // Efficient under heavy contention from many threads

long total = hits.sum();
// Read current total; may reflect concurrent updates.
// Exact once updates have quiesced.

6. Synchronization Utilities (`java.util.concurrent`)

`CountDownLatch`

One-shot gate: initialized with a count; countDown() decrements it; await() blocks until zero. Cannot be reset.

CountDownLatch readySignal = new CountDownLatch(3);

for (int i = 0; i < 3; i++) {
    new Thread(() -> {
        // Do setup work

        readySignal.countDown();
    }).start();
}

readySignal.await();
// Blocks until all 3 workers signal that they are ready

System.out.println("All workers ready, starting run.");

Latch vs Barrier vs Phaser

A useful distinction:

CountDownLatch -> one-shot event gate
CyclicBarrier  -> reusable fixed-party checkpoint
Phaser         -> reusable checkpoint with dynamic parties/phases

`CyclicBarrier`

Blocks N threads until all reach the barrier, releases them together, and automatically resets for reuse across multiple phases.

CyclicBarrier barrier = new CyclicBarrier(
        4,
        () -> System.out.println(
                "All 4 threads reached the barrier — merging results"
        )
);

Runnable task = () -> {
    // Do phase-1 work

    try {
        barrier.await();
    } catch (Exception e) {
        // Handle interruption or barrier failure
    }

    // Do phase-2 work only after everyone has arrived
};

for (int i = 0; i < 4; i++) {
    new Thread(task).start();
}

`Phaser`

Reusable barrier with a dynamic number of parties (register/deregister at runtime) and multiple named phases.

Phaser phaser = new Phaser(1);
// "1" registers the main thread as a party

for (int i = 0; i < 3; i++) {
    phaser.register();

    new Thread(() -> {
        // Phase 0 work

        phaser.arriveAndAwaitAdvance();
        // Wait for all parties to finish phase 0

        // Phase 1 work

        phaser.arriveAndDeregister();
        // Complete phase 1 and remove this thread
    }).start();
}

phaser.arriveAndAwaitAdvance();
// Main thread joins phase 0 completion

phaser.arriveAndDeregister();
// Main thread completes its participation

`Semaphore`

Maintains a set of permits; not tied to a single owning thread, so it suits resource pools rather than pure mutual exclusion.

Semaphore connectionPool = new Semaphore(5);
// Allows up to 5 concurrent connections

void useConnection() throws InterruptedException {
    connectionPool.acquire();
    // Acquire one available slot

    try {
        // Use one of the 5 available connections
    } finally {
        connectionPool.release();
        // Return the slot to the pool
    }
}

7. Producer/Consumer: `BlockingQueue`

Bakes coordination directly into queue operations — put() blocks when full, take() blocks when empty — eliminating hand-written wait/notify logic.

BlockingQueue<String> queue = new ArrayBlockingQueue<>(100);

// Producer
new Thread(() -> {
    try {
        while (true) {
            queue.put(produceItem());
        }
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
    }
}).start();

// Consumer
new Thread(() -> {
    try {
        while (true) {
            consume(queue.take());
        }
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
    }
}).start();

Design principle: if a higher-level abstraction already expresses the coordination protocol, prefer it over hand-written wait()/notify().

SynchronousQueue is the zero-capacity special case: every put() must rendezvous directly with a matching take().

8. Task Coordination

`ExecutorService`

Decouples task submission from thread management.

ExecutorService pool = Executors.newFixedThreadPool(4);

List<Callable<Integer>> tasks = List.of(
        () -> compute(1),
        () -> compute(2),
        () -> compute(3)
);

List<Future<Integer>> results = pool.invokeAll(tasks);
// Blocks until all tasks complete

pool.shutdown();

pool.awaitTermination(1, TimeUnit.MINUTES);

Since Java 21, Executors.newVirtualThreadPerTaskExecutor() gives this same API cheap scaling to huge numbers of blocking tasks via virtual threads.

Executor lifecycle

An ExecutorService is a resource with a lifecycle. In production code, decide who owns it and who shuts it down.

create
  ↓
submit tasks
  ↓
shutdown()
  ↓
awaitTermination()

`Future`

Future<Integer> future = pool.submit(() -> compute(42));Integer result = future.get(5, TimeUnit.SECONDS); // blocks with timeout

`CompletionService`

Wraps an ExecutorService and a completion queue so you can process results as they finish, rather than in submission order — invokeAll blocks until everything is done, CompletionService lets you react incrementally.

CompletionService<Integer> ecs =
        new ExecutorCompletionService<>(pool);

for (Callable<Integer> task : tasks) {
    ecs.submit(task);
}

for (int i = 0; i < tasks.size(); i++) {
    Future<Integer> done = ecs.take();
    // Returns the Future of whichever task finishes next

    System.out.println("Got result: " + done.get());
}

`ScheduledExecutorService`

Coordinates tasks that run after a delay or on a recurring schedule.

ScheduledExecutorService scheduler =
        Executors.newScheduledThreadPool(2);

scheduler.schedule(
        () -> System.out.println("Runs once after 10 seconds"),
        10,
        TimeUnit.SECONDS
);

scheduler.scheduleAtFixedRate(
        () -> pingHealthCheck(),
        0,
        30,
        TimeUnit.SECONDS
);

`CompletableFuture`

Besides successful pipelines, learn its failure and cancellation operators:

future
    .exceptionally(ex -> fallbackValue())
    .whenComplete((value, ex) -> audit(value, ex));

Use thenCompose when the next operation itself returns a CompletableFuture:

fetchUser()
    .thenCompose(user -> fetchOrders(user.id()));

Use thenCombine when two independent futures need to be combined.

`CompletableFuture`

Composable, callback-driven async pipelines.

CompletableFuture<Integer> pipeline = CompletableFuture
        .supplyAsync(() -> fetchUserId())
        .thenApplyAsync(id -> fetchProfile(id))
        .thenApply(profile -> profile.getScore());

pipeline.thenAccept(
        score -> System.out.println("Score: " + score)
);

// Wait for several independent futures together
CompletableFuture<Void> all =
        CompletableFuture.allOf(future1, future2, future3);

all.join(); // Blocks until all three futures complete

9. Fork/Join Framework (`java.util.concurrent`)

Coordinates recursive divide-and-conquer parallelism, using a pool of worker threads that steal work from each other's queues (ForkJoinPool) for load balancing.

class SumTask extends RecursiveTask<Long> {

    private final int[] arr;
    private final int lo;
    private final int hi;

    SumTask(int[] arr, int lo, int hi) {
        this.arr = arr;
        this.lo = lo;
        this.hi = hi;
    }

    @Override
    protected Long compute() {
        if (hi - lo <= 1000) {
            long sum = 0;

            for (int i = lo; i < hi; i++) {
                sum += arr[i];
            }

            return sum;
        }

        int mid = (lo + hi) / 2;

        SumTask left = new SumTask(arr, lo, mid);
        SumTask right = new SumTask(arr, mid, hi);

        left.fork();
        // Execute the left task asynchronously

        long rightResult = right.compute();
        // Compute the right task in the current thread

        return left.join() + rightResult;
        // Wait for the left task and combine both results
    }
}

long total = ForkJoinPool.commonPool()
        .invoke(new SumTask(bigArray, 0, bigArray.length));

RecursiveAction is the equivalent for tasks with no return value.

10. Low-Level Coordination: `LockSupport`

The permit-based primitive that ReentrantLock and others are built on.

Thread target = Thread.currentThread();

Thread signaler = new Thread(() -> {
    // Do preparation work

    LockSupport.unpark(target);
    // Give a permit to the target thread,
    // even if the target has not parked yet
});

signaler.start();

LockSupport.park();
// Consumes the permit if one is already available;
// otherwise, blocks until unpark() is called.

Unlike wait/notify, there's no race between "signal arrives first" and "wait starts first" — the permit is stored. Still subject to spurious wakeups per its javadoc, so re-check conditions after park() returns.

11. Specialized: `Exchanger`

A rendezvous point where exactly two threads swap objects.

Exchanger<Buffer> exchanger = new Exchanger<>();

// Thread A: Fills a buffer, then swaps it for an empty one
Buffer filled = fillBuffer(new Buffer());

Buffer empty = exchanger.exchange(filled);
// Waits for Thread B and exchanges the filled buffer
// for the buffer supplied by Thread B

// Thread B: Takes the filled buffer and hands back an empty one
Buffer received = exchanger.exchange(new Buffer());
// Waits for Thread A and exchanges buffers

12. Thread-Confinement Tools

`ThreadLocal`

Gives each thread its own independent copy of a variable — sidesteps coordination entirely by avoiding sharing.

private static final ThreadLocal<SimpleDateFormat> FORMATTER =
        ThreadLocal.withInitial(
                () -> new SimpleDateFormat("yyyy-MM-dd")
        );

String format(Date d) {
    return FORMATTER.get().format(d);
    // Each thread gets its own formatter instance,
    // so no shared mutable state or locking is required.
}

`ScopedValue` (finalized in Java 25, JEP 506)

A safer, immutable alternative to ThreadLocal for passing context (like trace IDs) into child tasks — especially virtual threads spawned by structured concurrency — without the leak/inheritance pitfalls of InheritableThreadLocal.

static final ScopedValue<String> TRACE_ID =
        ScopedValue.newInstance();

ScopedValue.where(TRACE_ID, "req-42").run(() -> {
    // TRACE_ID.get() == "req-42" here
    // The value is available to child tasks
    // within the structured scope

    processRequest();
});

13. Virtual Threads

Virtual threads make thread-per-task programming practical for large numbers of mostly blocking tasks.

try (var executor =
         Executors.newVirtualThreadPerTaskExecutor()) {

    executor.submit(() -> callRemoteService());
    executor.submit(() -> callDatabase());
}

They are especially useful for I/O-bound workloads. They do not provide more CPU capacity for CPU-bound work.

A good rule:

I/O-bound, many concurrent tasks -> virtual threads can scale very well
CPU-bound -> parallelism is still limited by available CPU

13. Structured Concurrency: `StructuredTaskScope`

As of late 2026, StructuredTaskScope (java.util.concurrent) is still a preview API — it has re-previewed in every JDK release since 19, most recently as JEP 525 in JDK 26, with JEP 533 targeting JDK 27; it requires --enable-preview and its surface may still change before finalization. It ties the lifetimes of a group of subtasks (run on virtual threads) to a single block, so cancellation and error propagation happen as one unit instead of being scattered across manually-tracked Futures.

try (var scope = StructuredTaskScope.open()) {

    Subtask<User> userTask =
            scope.fork(() -> fetchUser(id));

    Subtask<Order> orderTask =
            scope.fork(() -> fetchOrders(id));

    scope.join();
    // Wait for both subtasks to complete
    // or fail according to the scope's shutdown policy

    User user = userTask.get();
    Order order = orderTask.get();
}

Because this is a moving target pre-finalization, check the current JEP before depending on exact method names in production code.

14. Supporting Concurrent Collections

Not coordination primitives per se, but purpose-built to avoid needing external synchronization for common shared data structures:

ConcurrentHashMap — thread-safe map with fine-grained internal locking/CAS; computeIfAbsent, merge, etc. are atomic per-key.
CopyOnWriteArrayList / CopyOnWriteArraySet — every mutation copies the underlying array; ideal for read-heavy, rarely-mutated lists (e.g., listener lists) since reads never block.
ConcurrentLinkedQueue — lock-free unbounded FIFO queue.

ConcurrentHashMap<String, Integer> counts =
        new ConcurrentHashMap<>();

counts.merge("key", 1, Integer::sum);
// Performs an atomic read-modify-write operation
// without requiring an external lock.

15. `VarHandle` (Java 9+)

Low-level API for fine-grained atomic and volatile access to individual fields or array elements — what libraries use to implement things like custom lock-free data structures, below even AtomicInteger in the stack.

private static final VarHandle COUNT;

static {
    try {
        COUNT = MethodHandles.lookup()
                .findVarHandle(MyClass.class, "count", int.class);
    } catch (ReflectiveOperationException e) {
        throw new ExceptionInInitializerError(e);
    }
}

private volatile int count;

void increment() {
    COUNT.getAndAdd(this, 1);
    // Atomic increment without requiring an AtomicInteger field
}

Rarely needed in application code — mostly relevant when writing high-performance libraries.

14. Happens-Before: The Memory Visibility Layer

Coordination is not only about blocking. Java also defines happens-before relationships that determine when one thread is guaranteed to observe another thread's actions.

Important examples:

Thread.start()
    actions before start()
          ↓
    actions in started thread

Thread.join()
    actions in terminated thread
          ↓
    actions after successful join()

monitor unlock
          ↓
matching monitor lock

volatile write
          ↓
subsequent read of same volatile variable

Higher-level concurrency utilities also define memory-consistency effects. This is why synchronization APIs provide more than "making a thread wait".

Atomicity vs visibility

Keep these concepts separate:

volatile
    -> visibility + ordering

AtomicInteger
    -> atomic operations + visibility guarantees

synchronized
    -> mutual exclusion + visibility + ordering

A variable can be visible to every thread and still be updated incorrectly if the operation itself is not atomic.

Common Mistakes

1. Using `sleep()` as synchronization

Thread.sleep(1000);
assumeOtherThreadFinished();

This is timing-based and unreliable. Prefer join(), a latch, a future, or another condition mechanism.

2. Using `if` instead of `while` around `wait()`

while (!ready) {
    wait();
}

The condition must always be re-checked.

3. Forgetting `unlock()` on exceptional paths

lock.lock();
try {
    update();
} finally {
    lock.unlock();
}

4. Assuming `volatile` makes compound operations atomic

volatile int count;
count++; // still a race

5. Swallowing interruption

catch (InterruptedException e) {
    Thread.currentThread().interrupt();
}

unless the method has a deliberate policy for handling the cancellation request.

6. Choosing low-level primitives too early

Prefer:

BlockingQueue
CountDownLatch
Semaphore
ExecutorService
CompletableFuture

when they directly express the problem.

Choosing the Right Tool

Need	Reach for
Wait for a thread to finish	`join()`
Visible flag across threads, no atomicity needed	`volatile`
Simple mutual exclusion	`synchronized`
Mutual exclusion + timeouts/interruptibility/fairness	`ReentrantLock`
Multiple distinct wait conditions on one lock	`Condition`
Many readers, few writers	`ReentrantReadWriteLock` / `StampedLock`
Lock-free counters/flags/state transitions	Atomic classes / `LongAdder`
One-time "wait for N events" gate	`CountDownLatch`
Reusable "wait for all threads at a checkpoint"	`CyclicBarrier`
Barrier with a dynamic, changing number of threads	`Phaser`
Limit concurrent access to a resource pool	`Semaphore`
Producer/consumer handoff	`BlockingQueue`
Managed thread pools + async task results	`ExecutorService` / `Future`
React to results as they finish, not in order	`CompletionService`
Delayed / recurring tasks	`ScheduledExecutorService`
Composable async pipelines	`CompletableFuture`
Recursive divide-and-conquer parallelism	`ForkJoinPool` / `RecursiveTask`
Building a custom synchronizer from scratch	`LockSupport`
One-to-one data swap between two threads	`Exchanger`
Per-thread state, no sharing at all	`ThreadLocal` / `ScopedValue`
Grouping subtasks as one cancellable unit	`StructuredTaskScope` (preview)
Thread-safe shared map/list without manual locking	`ConcurrentHashMap` / `CopyOnWriteArrayList`

Data Sharing between Threads

AnkitDevCode — Mon, 07 Sep 2026 11:23:38 +0000

In the previous article, [Java Memory Model: How Multithreading Changes the Rules], We saw that when multiple threads execute concurrently, understanding the Java code alone isn’t always enough. We also need to understand how threads interact with memory—and what guarantees the Java Memory Model provides.

Now, let’s take the next step.

How do threads actually share data?

When multiple threads are running inside the same Java application, they don't live in completely isolated worlds. They can access objects that exist in the shared heap.

At the same time, each thread has its own stack, which contains its method calls, local variables, and execution state.

This gives us a fundamental picture:

The one idea this whole article is built around:

Each thread has its own stack. Objects on the heap can be reached — and mutated — by more than one thread at the same time.

Everything about Java concurrency (race conditions, visibility issues, the need for synchronized, volatile, atomics, and immutability) grows out of that single sentence

1. The scaffolding (you already know this part)

Every thread has its own stack: each method call gets its own copy of local variables, method parameters, and references.
All objects live on a shared heap. Any thread holding a reference can read or mutate that object.
An instance or static field isn’t “shared” by definition — it becomes shared the moment more than one thread can reach the object or class that owns it.

Deep Dive: Stack vs. Heap Dynamics

Deep Dive: Local variable vs. Instance vs. Static

Before we dive into coding, let's break down the fundamental variable types you'll use every day in Java.

Deep Dive: Object vs. Reference

• The Object is the house. It is the actual structure built out of bricks and mortar, sitting on a plot of land. It occupies physical space in memory.
• The Reference is the address. It is a piece of paper with the address written on it (123 Heap Street). It is not the house itself; it just tells you where the house is so you can go find it.

Java is always pass-by-value, even for objects. For primitives, the value itself is copied, so each thread gets an independent value. For objects, the reference value is copied, so each thread has its own reference pointing to the same heap object. Therefore, a mutation through one reference can be seen through the other.

The Technical Boundaries

Local Variables are Thread-Safe by Design: Because they are allocated inside a private stack frame, if Thread-1 and Thread-2 execute the exact same method simultaneously, they each get a completely independent copy of that local variable(Any variable declared inside a method — including its parameters, primitives and references — lives in that method's stack frame) on their own stacks and cannot physically access by different thread's stack.**
- Primitives (int, boolean, double, ...) — the actual value sits directly in the stack frame.
- Object references (Foo f, String s, ...) — the reference (a pointer/handle) sits in the stack frame. The object it points to sits separately, on the heap.
Fields are Vulnerable: Fields do not belong to methods; they belong to objects (Instance) or classes (Static). Therefore, they are allocated on the Heap, exposing them to concurrent modification.

2. How Multiple Threads Can Access the Same Object

A reference can "escape" to another thread in several common ways:

Passed as a constructor or method argument
Stored in a static field
Stored in a field of an object that is itself shared
Placed into a shared collection (queue, map, list)
Captured by a lambda or Runnable passed to another thread

Once two threads hold a reference to the same object, the JVM provides no automatic coordination between them. You need explicit concurrency mechanisms such as synchronized, volatile, locks, atomic classes, or safe publication through concurrent collections.

Without proper synchronization, one thread's updates may not be visible to the other, or their operations may interleave unpredictably, leading to race conditions and corrupted state. This is where the Java Memory Model (JMM) rules from the previous article become critical.

3. What Shared Mutable State Really Means

The term shared mutable state is often used in concurrency, but the real issue comes down to two independent conditions:

Shared — multiple threads can access the same state.
Mutable — that state can be changed.

“State” itself isn't the problem; every object has state in the form of fields. The concurrency risk arises when the state is both shared and mutable.

	Immutable	Mutable
Not shared	✅ Safe	✅ Safe — thread-confined
Shared	✅ Safe — nothing to modify	⚠️ Requires coordination

The key takeaway is:

Shared + mutable = concurrency risk.

If the state is immutable, multiple threads can safely read it. If the state is not shared, each thread can modify its own copy without interfering with others.

(Shared + immutable) An object that is shared but immutable (e.g. a String, or a properly constructed immutable class) is generally safe to share between threads because its state cannot be changed. One important nuance: final fields alone don't automatically make a class immutable. The fields must refer to immutable objects (or otherwise safely encapsulated state), and the object must be properly constructed/publicized.

final class User {
 private final String name;
 private final List<String> roles;

 User(String name, List<String> roles) {
    this.name = name;
    this.roles = List.copyOf(roles);
 }
}

(Mutable + not shared) An object that is mutable but never shared (a local variable confined to one thread) is also safe — no other thread can see the changes.
(Mutable + shared) A shared mutable object is where concurrency problems can arise. If multiple threads access and modify the same state without proper coordination, their operations can race, causing lost updates, stale reads, or other inconsistent results. This is where synchronization and the Java Memory Model become important.

4. Different Ways Threads Can Share Data

Java provides several mechanisms for sharing or coordinating data between threads. Each approach has different trade-offs in terms of safety, performance, complexity, and ownership.

The important distinction is not whether data is shared, but how that shared data is accessed and modified.

1. Shared Mutable Objects — `synchronized` / Locks

Multiple threads can access the same object. If they modify its state, use synchronization(Intrinsic Lock- Java automatically acquires and releases the object's monitor lock.) to coordinate access.

synchronized void increment() {
    count++;
}

Locks such as ReentrantLock provide mutual exclusion and visibility, ensuring that changes made before unlocking become visible to a thread that subsequently acquires the same lock.

Provides features such as:

tryLock()
Interruptible lock acquisition
Fairness option
Multiple Conditions

class Counter {
    private int count;
    private final ReentrantLock lock = new ReentrantLock();
    void increment() {
        lock.lock();
        try {
            count++;
        } finally {
            lock.unlock();
        }
    }

    int getCount() {
        lock.lock();
        try {
            return count;
        } finally {
            lock.unlock();
        }
    }
}

If the workload is read-heavy with fewer writes, a ReentrantReadWriteLock can be a good choice.

It allows:

Multiple threads to read simultaneously
Only one thread to write at a time
Readers are blocked while a writer holds the write lock.

class Counter {

    private int count = 0;

    private final ReentrantReadWriteLock lock =
            new ReentrantReadWriteLock();

    void increment() {
        lock.writeLock().lock();
        try {
            count++;
        } finally {
            lock.writeLock().unlock();
        }
    }

    int getCount() {
        lock.readLock().lock();
        try {
            return count;
        } finally {
            lock.readLock().unlock();
        }
    }
}

these provides mutual exclusion and visibility.

2. `volatile` Fields

Use volatile when multiple threads need to see the latest value of a variable.

private volatile boolean running = true;

It provides visibility, but not atomicity.

So this is still unsafe:

count++;  // not atomic

3. Atomic Classes

Classes such as AtomicInteger provide atomic operations without explicit locks.

Use AtomicInteger when you need simple atomic operations on a shared integer, such as counters, flags, or sequence numbers.

class Counter {

    private final AtomicInteger count = new AtomicInteger(0);

    void increment() {
        count.incrementAndGet();
    }

    int getCount() {
        return count.get();
    }
}

One important limitation

AtomicInteger is excellent for simple atomic state changes, but it doesn't automatically make a group of operations atomic.

For example:

if (balance.get()>=100) {balance.addAndGet(-100);
}

The check and update are two separate operations. Another thread could change the balance between them.

For such a multi-step operation, a lock or a single appropriate atomic operation such as compareAndSet() may be required.

Simple rule

Locks protect a section of code; atomic classes provide atomic operations on individual pieces of shared state.

4. Concurrent Collections

Java provides collections designed for concurrent access:

ConcurrentHashMap
CopyOnWriteArrayList
BlockingQueue

They make common collection operations safe for concurrent use.

5. Immutable Objects

Immutable objects can be freely shared between threads because their state cannot change.

String name = "Ankit";

This is one of the simplest and safest approaches to concurrency.

Shared + Immutable = Safe to share

6. Message Passing

Instead of sharing mutable state directly, threads can communicate by passing messages.

BlockingQueue<Order> queue =
        new LinkedBlockingQueue<>();

One thread puts data into the queue, and another thread takes it.

Transfer data instead of sharing mutable state.

7. Thread Confinement / `ThreadLocal`

Sometimes the best approach is not to share the data at all.

ThreadLocal gives each thread its own value:

ThreadLocal<String> userId = new ThreadLocal<>();

Thread 1 → A
Thread 2 → B
Thread 3 → C

Each thread works with its own data, so no synchronization is needed.

5. Putting It Together

Java Memory Model: How Multithreading Changes the Rules

AnkitDevCode — Mon, 31 Aug 2026 16:28:22 +0000

Threads enable multiple tasks to make progress concurrently. However, concurrency raises a fundamental question:

When multiple threads access the same data, how do we know what each thread will see?

Consider this simple code:

int count = 0;

Thread 1 → count++;
Thread 2 → count++;

It looks straightforward, but once multiple threads are involved, things are no longer as simple as they appear.

To understand why, we need to understand the Java Memory Model (JMM).

What is the Java Memory Model?

The Java Memory Model is the set of rules that governs how threads read and write shared memory in a multi-threaded application.

It provides definitive answers to core concurrency questions:

Visibility: When does a change made by one thread become visible to another?
Ordering: Can the compiler or CPU reorder operations?
volatile: What guarantees does the volatile keyword actually provide?
synchronized: Why does locking a section of code flush memory updates?
Happens-before: What is the underlying contract that guarantees thread safety?
Silent failures: Why can code that looks correct in single-threaded tests break under real concurrency?

Key insight

The JMM is not a description of physical RAM. It is a formal specification that defines the rules of visibility, ordering, and atomicity across JVM threads, CPU caches, and hardware.

Without the JMM, modern CPU optimizations—such as caching, store buffers, and instruction reordering—would make multi-threaded program behavior effectively unpredictable.

Three core concepts

When discussing the Java Memory Model, three concepts are particularly important:

Atomicity
Visibility
Ordering

Understanding these explains a large part of Java concurrency.

1) Atomicity

An operation is atomic if it executes as a single, indivisible unit of work. It either happens completely, or it does not happen at all. No other thread can observe the operation in a partially completed state.

The problem
In Java, operations that look simple on the surface are often broken down into multiple CPU instructions. For example, count++ requires three steps:

read
modify
write

If two threads execute this sequence simultaneously, their steps can interleave, causing lost updates.

Java guarantees

Reads and writes for reference variables and most primitive variables are naturally atomic.
A notable exception: non-volatile long and double reads/writes are not guaranteed to be atomic on all platforms.

How to achieve atomicity

Use synchronized or ReentrantLock to prevent concurrent entry into a critical section.
Use atomic classes in java.util.concurrent.atomic (e.g., AtomicInteger, AtomicLong), which rely on hardware-level compare-and-swap (CAS).

2) Visibility

Visibility determines when a write made by one thread becomes visible to reads made by other threads.

The problem
Modern CPUs use high-speed caches (L1/L2/L3) and store buffers to maximize execution speed. If Thread A updates a variable, that update may remain in one core’s local cache and not be immediately flushed to main memory. If Thread B running on another core reads the same variable, it may see stale data.

Common symptom

Threads running forever in while (!flag) {} loops because they never observe another thread setting flag = true.

How to achieve visibility

Mark a variable as volatile: forces volatile writes to be made visible and volatile reads to observe the latest write according to the JMM.
Use synchronized or locks: entering/exiting a critical section creates the required memory synchronization effects.

This is where happens-before enters the picture. A simple way to interpret it is:

If action A happens-before action B, then B is guaranteed to observe the effects of A, and A is ordered before B according to the Java Memory Model.

Important: `volatile` is not atomic

volatile provides visibility and ordering guarantees, but it does not make compound operations atomic.

For example, this is still not an atomic increment:

volatile int count;

count++;

Atomicity vs. visibility (and ordering)

Different concurrency mechanisms solve different problems.

`volatile`

volatile primarily provides:

Visibility — a read sees the most recent volatile write (as defined by the JMM).
Ordering — it establishes required ordering constraints around volatile accesses.

However, volatile does not make compound operations atomic (such as count++).

Atomic classes

Classes such as:

AtomicInteger
AtomicLong
AtomicReference

provide atomic operations (for the operations they support), along with the necessary visibility and ordering guarantees.

Example:

AtomicInteger count = new AtomicInteger();

count.incrementAndGet(); // atomic

Note: atomic classes do not automatically make an arbitrary sequence of multiple operations atomic.

`synchronized`

synchronized provides:

Mutual exclusion — only one thread at a time can execute a critical section guarded by the same monitor.
Visibility — changes made before releasing the monitor become visible to a thread that subsequently acquires the same monitor.
Ordering — synchronization establishes happens-before relationships defined by the JMM.

Example:

class Counter {
    private int count;

    synchronized void increment() {
        count++;
    }

    synchronized int getCount() {
        return count;
    }
}

Here, count does not need to be volatile because both reads and writes are protected by the same monitor.

3) Ordering

Modern CPUs and compilers aggressively optimize code. The instructions we write are not always executed in the intuitive, line-by-line order. Ordering guarantees ensure that execution steps occur in a predictable, non-corrupting sequence across threads.

The problem
To maximize pipeline efficiency, the JIT compiler and CPU may reorder instructions. Reordering preserves the intended results of single-threaded code (the “as-if-serial” rule), but it can break multi-threaded logic when other threads can observe the reordering.

For example:

a = 1;
b = 2;

The compiler or hardware may reorder these operations when it is safe from a single-thread perspective, but with multiple threads the reordering can become observable. This is one reason the JMM defines rules around ordering between actions performed by different threads.

Happens-before

Happens-before defines when the result of one action is guaranteed to be visible to another action.

It does not necessarily mean “this physically happened earlier in time.” Instead, it means there is a defined ordering relationship.

Example:

Thread 1:
    write data
    release lock

Thread 2:
    acquire same lock
    read data

The JMM establishes a happens-before relationship between the unlock and a subsequent lock on the same monitor. Therefore, Thread 2 can reliably observe the relevant writes made before the unlock.

Common happens-before rules

Program order rule
Within a single thread, each action happens-before every action that comes later in the program.

// Executed by a single thread:
int x = 10;   // Action A
int y = 20;   // Action B (A happens-before B)

Volatile variable rule
A write to a volatile field happens-before every subsequent read of that same field.

class VolatileExample {
    private int data = 0;
    private volatile boolean ready = false;

    // Thread 1
    public void write() {
        data = 42;      // 1. Plain write
        ready = true;   // 2. Volatile write (release)
    }

    // Thread 2
    public void read() {
        if (ready) { // 3. Volatile read (acquire)
            System.out.println(data); // 4. Guaranteed to print 42
        }
    }
}

Why it works: writing to ready happens-before reading ready. By transitivity, the earlier plain write (data = 42) is also guaranteed to be visible.

Monitor lock rule (synchronized)
An unlock on a monitor (exiting a synchronized block/method) happens-before every subsequent lock on the same monitor.

class SynchronizedExample {
    private int count = 0;

    // Thread 1
    public synchronized void increment() {
        count++;
    }

    // Thread 2
    public synchronized int getCount() {
        return count;
    }
}

Thread start rule
A call to thread.start() happens-before any action inside the started thread’s run().

int data = 100;

Thread t = new Thread(() -> {
    // Guaranteed to see data = 100 because start() happens-before run()
    System.out.println(data);
});

t.start();

Thread join rule
All actions inside a thread happen-before another thread successfully returns from join() on that thread.

Thread t = new Thread(() -> {
    result = 500;
});

t.start();
t.join(); // wait for completion

// Guaranteed to see result = 500 because completion happens-before join returns
System.out.println(result);

A Practical Rule of Thumb

When writing concurrent Java code, ask yourself:

1. Is this data shared?

If not, concurrency is usually much easier.

2. Is the shared data mutable?

Immutable data is much easier to share safely.

3. Can multiple threads modify it?

If yes, you probably need a concurrency strategy.

4. Do I need atomicity?

Consider:

AtomicInteger
AtomicLong
AtomicReference

5. Do I need visibility?

Consider:

volatile
synchronized
Lock

6. Do multiple operations need to happen together?

Consider:

synchronized
Lock

7. Can I avoid shared mutable state altogether?

Often, that’s the best solution.

The Bigger Picture

The Java Memory Model is the foundation behind many of Java’s concurrency tools.

                 Java Memory Model
                        │
          ┌─────────────┼─────────────┐
          ↓             ↓             ↓
      Visibility     Ordering     Atomicity
          │             │             │
          └─────────────┼─────────────┘
                        ↓
                 Concurrency APIs
                        │
          ┌─────────────┼─────────────┐
          ↓             ↓             ↓
     synchronized    volatile      Atomics
          │
          ↓
       Locks
          │
          ↓
      Executors
          │
          ↓
 CompletableFuture
          │
          ↓
  Virtual Threads

Understanding the JMM makes these APIs much easier to reason about.

Instead of memorizing:

"Use volatile here."

you can ask:

What guarantee do I actually need?

Final Takeaway

Threads give Java the ability to execute multiple tasks concurrently.

But once multiple threads share memory, a new problem appears:

How do we make sure threads see and update shared data correctly?

That’s the problem the Java Memory Model helps define.

Java Concurrency: Threads

AnkitDevCode — Mon, 31 Aug 2026 15:18:08 +0000

Why Do We Need Threads?

Imagine you are running a restaurant with only one waiter.

A customer places an order.

The waiter takes the order to the kitchen and then stands there doing nothing while waiting for the food.

Only after the food is ready can the waiter serve that customer and move to the next one.

That is similar to what happens when a program executes everything sequentially:

Task A → wait → finish
Task B → wait → finish
Task C → wait → finish

But what if Task A is waiting for:

A database response
A network API
A file operation
A message from another service

The CPU may have other useful work to do while Task A is waiting.

So we naturally arrive at a question:

Why should one task block the progress of everything else?

This is where concurrency comes into the picture.

Instead of making one task wait before starting another, we can have multiple tasks making progress:

                 ┌── Task A → waiting for DB
                 │
Application ─────┼── Task B → running
                 │
                 └── Task C → running

And this is one of the fundamental reasons we have threads.

What Is a Thread?

A thread is an independent path of execution inside a process.

A Java application can have:

Java Process
│
├── Thread 1
├── Thread 2
├── Thread 3
└── Thread 4

Each thread can execute work independently while sharing resources such as:

Heap memory
Objects
Static variables
Other application resources

For example:

Thread thread = new Thread(() -> {
    System.out.println("Running in another thread");
});

thread.start();

Now the JVM can execute this work concurrently with other work.

The First Big Win: Concurrency

Threads can improve application responsiveness and throughput, especially when tasks spend significant time waiting for I/O.

But there is a catch.

Threads solved one problem and introduced a whole new class of problems.

The Dark Side of Threads (Dark Side of Shared Memory)

Once multiple threads start executing at the same time and sharing memory, our program becomes much harder to reason about.

With a single thread, execution is relatively predictable:

A → B → C → D

With multiple threads:

Thread 1: A → B →      → D
Thread 2:      X → Y → Z

The exact order can change from one execution to another.

This is where concurrency bugs begin.

1. Race Conditions

Consider:

count++;

It looks like one operation.

But conceptually it involves:

read count
    ↓
add 1
    ↓
write count

Now imagine two threads execute it at the same time.

Suppose:

count = 5

Both threads may read 5:

Thread 1 → reads 5
Thread 2 → reads 5

Thread 1 → writes 6
Thread 2 → writes 6

Expected:

Actual:

One update has been lost.

This is a race condition.

The result depends on the timing and interleaving of threads.

2. Visibility Problems

Another problem is visibility.

Modern CPUs use multiple levels of caches to improve performance.

A simplified view looks like:

          Main Memory
               │
       ┌───────┴───────┐
       ↓               ↓
   CPU Core 1       CPU Core 2
       │               │
     Cache           Cache
       │               │
   Thread A         Thread B

If one thread updates shared data, another thread needs the appropriate Java Memory Model guarantees to reliably observe that update.

This is why Java provides mechanisms such as:

volatile
synchronized
Lock
Atomic classes

For example:

private volatile boolean running = true;

volatile provides visibility and ordering guarantees for that variable.

But it does not make every compound operation atomic.

For example:

count++;

is still not made thread-safe merely by declaring count as volatile.

3. Deadlocks

Now introduce locks.

Imagine:

Thread 1
    │
    ├── holds Lock A
    │
    └── waits for Lock B

Thread 2
    │
    ├── holds Lock B
    │
    └── waits for Lock A

Neither thread can continue.

Thread 1 → waiting for Thread 2
Thread 2 → waiting for Thread 1

Forever.

This is a deadlock.

The application may appear completely frozen even though the process itself is still alive.

4. Livelock

A livelock is different.

The threads are not blocked.

They are actively doing something—but they aren't making progress.

Think about two people walking toward each other in a narrow hallway.

One moves left.

The other also moves left.

Then both move right.

Then both move right again.

They are active, but nobody gets anywhere.

That's roughly what a livelock looks like:

Thread A → changes state
Thread B → reacts
Thread A → reacts
Thread B → reacts
       ↓
No actual progress

5. Starvation

Another problem is starvation.

A thread may continuously fail to get the CPU time or lock access it needs because other threads keep getting priority.

For example:

Thread A → continuously gets access
Thread B → waits
Thread C → waits
Thread D → waits

Thread B may technically be runnable but rarely gets a chance to make progress.

Threads Also Have a Cost

Concurrency sounds great.

So why not simply create thousands or millions of threads?

Because traditional platform threads are relatively expensive resources.

A platform thread is associated with an operating-system thread, and each thread requires memory and scheduling resources.

For example:

for (int i = 0; i < 10_000; i++) {
    new Thread(() -> process()).start();
}

This is generally not a good design.

The exact memory cost varies by JVM, operating system, architecture, and configuration, but thousands of platform threads can consume substantial memory.

Context Switching

There is another cost.

Suppose the CPU is executing:

Thread A

The operating system may need to switch to:

Thread B

The system has to preserve and restore execution state.

Simplified:

Thread A running
      ↓
Save A's state
      ↓
Load B's state
      ↓
Thread B running

This is called context switching.

Context switching is necessary, but excessive switching adds overhead.

The CPU can end up spending more time managing execution than doing useful application work.

The Real Problem

We now have an interesting dilemma.

One thread

Simple
Safe
Easy to understand

       BUT

Poor concurrency
Waiting blocks progress

Many platform threads

High concurrency
Better utilization

       BUT

More memory
More scheduling overhead
Race conditions
Deadlocks
Visibility problems
Harder debugging

So we arrive at:

How can we get the benefits of concurrency without drowning in its complexity and resource cost?

And this question drives much of Java's concurrency evolution.

Java's Concurrency Evolution

Java didn't solve everything with one feature.

Instead, concurrency evolved step by step.

Threads
   ↓
Synchronization
   ↓
java.util.concurrent
   ↓
ExecutorService
   ↓
Thread Pools
   ↓
Future
   ↓
CompletableFuture
   ↓
Reactive Programming
   ↓
Virtual Threads
   ↓
Structured Concurrency

Each step addressed problems introduced by the previous approach.

Java 1.0 — Threads

The fundamental building block was the Thread API.

Thread thread = new Thread(() -> {
    doWork();
});

thread.start();

This gave developers the ability to execute work concurrently.

But manually creating and managing threads doesn't scale very well.

That led to the next question:

Instead of creating threads ourselves, can Java manage them for us?

Java 5 — Executors and `java.util.concurrent`

Java 5 introduced a major concurrency upgrade through:

java.util.concurrent

One of the most important additions was ExecutorService.

Instead of thinking:

"Create a thread."

we could think:

"Submit a task."

ExecutorService executor =
        Executors.newFixedThreadPool(10);

executor.submit(() -> {
    processOrder();
});

Now the application could reuse a limited number of threads.

             Tasks
        ┌──────┼──────┐
        ↓      ↓      ↓
      Task   Task   Task
        │      │      │
        └──────┼──────┘
               ↓
         Thread Pool
        ┌────┬────┬────┐
        │ T1 │ T2 │ T3 │
        └────┴────┴────┘

This reduced the need to constantly create new platform threads.

Thread Pools: Better, But Not Perfect

Thread pools solved the thread-creation problem.

But they introduced a new limitation.

Suppose we have:

100 platform threads

and all 100 are waiting for database or network responses.

Now we have:

100 threads
      ↓
100 blocked operations
      ↓
No thread available for new work

We can increase the pool size.

Maybe:

100 → 500 → 1000

But eventually we hit resource limits.

This is particularly important for modern applications where thousands of requests may spend most of their time waiting for I/O.

Java 8 — CompletableFuture

Java 8 introduced CompletableFuture.

It provided a way to compose asynchronous operations.

For example:

CompletableFuture
        .supplyAsync(() -> getUser())
        .thenApply(user -> getOrders(user))
        .thenApply(orders -> calculateTotal(orders));

Independent operations could also be executed concurrently:

CompletableFuture<User> user =
        getUserAsync();

CompletableFuture<List<Order>> orders =
        getOrdersAsync();

CompletableFuture.allOf(user, orders);

This helped applications avoid some unnecessary blocking and compose asynchronous workflows.

But there was a trade-off.

As asynchronous workflows became more complicated, the code could become harder to read and reason about.

Reactive Programming

The next major approach was reactive programming.

The basic idea was:

Don't keep a thread blocked while waiting for I/O.

Instead of returning a value directly:

User getUser();

you might return something like:

Mono<User>

or:

Flux<Order>

This allowed applications to handle large numbers of concurrent I/O operations using non-blocking execution.

Reactive programming can be extremely powerful.

But it introduces a different programming model and concepts such as:

Publishers
Subscribers
Operators
Schedulers
Backpressure
Reactive pipelines

For some applications, this complexity is worthwhile.

For others, developers wanted something simpler.

And this is where Project Loom changed the conversation.

Project Loom

Project Loom asked a fascinating question:

Can we make threads cheap enough that developers can use a simple synchronous programming model even when handling huge numbers of concurrent tasks?

The answer was:

Virtual Threads.

Java 21 — Virtual Threads

Virtual Threads became a standard feature in Java 21.

Instead of requiring one heavyweight platform thread for every concurrent task, the JVM can manage a very large number of lightweight virtual threads over a smaller number of platform threads.

Conceptually:

          Thousands of Tasks
                  ↓
          Virtual Threads
                  ↓
       ┌──────────┼──────────┐
       ↓          ↓          ↓
   Carrier 1   Carrier 2   Carrier 3
       │          │          │
       └──────────┼──────────┘
                  ↓
                 CPU

Creating a virtual thread is much cheaper than creating a platform thread.

For example:

Thread.startVirtualThread(() -> {
    callDatabase();
});

Or:

try (var executor =
         Executors.newVirtualThreadPerTaskExecutor()) {

    executor.submit(() -> callService());
}

Why Are Virtual Threads Important?

The interesting part isn't simply:

"Virtual threads are faster."

That's not the right way to think about them.

The real idea is:

Virtual threads make concurrency cheaper.

With platform threads, we often had to think carefully about:

How big should my thread pool be?
How many concurrent requests can I handle?
Will these threads consume too much memory?

Virtual threads change the economics of that decision.

You can often model application work more naturally:

One task
   ↓
One virtual thread
   ↓
Perform blocking-style I/O
   ↓
Virtual thread can be suspended
   ↓
Platform thread can execute other work

The JVM manages the underlying scheduling.

From "How Many Threads?" to "How Many Tasks?"

This is perhaps the biggest conceptual change.

Traditional approach

Limited platform threads
        ↓
Thread pool
        ↓
Tasks wait in queue

Virtual-thread approach

Many concurrent tasks
        ↓
Virtual threads
        ↓
JVM manages execution

The developer can focus more on:

What work needs to happen?

rather than:

How do I manually manage a scarce thread resource?

But Virtual Threads Don't Remove Concurrency Problems

This is extremely important.

Virtual threads do not magically eliminate:

Race conditions
Deadlocks
Incorrect synchronization
Shared mutable state
Poor database design
External service bottlenecks
CPU limitations

If you write:

count++;

from multiple concurrent threads, it can still be unsafe.

Virtual threads make threads cheaper.

They don't make shared mutable state safe.

The Next Step: Structured Concurrency

Once concurrency becomes cheap, another question appears:

How do we manage thousands of concurrent tasks safely?

Consider:

Request
│
├── User Service
├── Order Service
└── Payment Service

These tasks belong to the same request.

If the request is cancelled, it often makes sense for its child tasks to be cancelled too.

This is the idea behind Structured Concurrency.

Conceptually:

Parent Task
│
├── Child Task A
├── Child Task B
└── Child Task C

The lifetime of the child tasks is tied to the parent.

This makes concurrent code easier to reason about and manage.

The Bigger Picture

Java concurrency isn't a random collection of APIs.

It is an evolution.

Each generation tried to solve a problem created by the previous generation.

                 WHY?

Sequential execution
        ↓
"Why wait for everything?"
        ↓
Threads
        ↓
"Threads are difficult to manage."
        ↓
Executors / Thread Pools
        ↓
"Threads are still expensive when blocked."
        ↓
Async / CompletableFuture
        ↓
"Async code is becoming difficult to reason about."
        ↓
Reactive Programming
        ↓
"Can we get scalability with simpler code?"
        ↓
Virtual Threads
        ↓
"How do we structure thousands of concurrent tasks?"
        ↓
Structured Concurrency

The Core Lesson

The history of Java concurrency can be understood through one question:

How can we make more progress at the same time without making our applications too expensive or too complicated?

Threads gave us concurrency.

Executors gave us thread management.

Thread pools gave us controlled resource usage.

CompletableFuture gave us composable asynchronous workflows.

Reactive programming gave us highly scalable non-blocking pipelines.

Virtual threads made large-scale concurrency much cheaper while preserving a familiar programming model.

Structured concurrency aims to make that concurrency easier to manage.

Final Mental Model

Think of the evolution like this:

Threads
  │
  │  "Run things concurrently"
  ↓
Executors
  │
  │  "Manage threads"
  ↓
Thread Pools
  │
  │  "Reuse limited resources"
  ↓
CompletableFuture
  │
  │  "Compose async work"
  ↓
Reactive
  │
  │  "Handle massive non-blocking I/O"
  ↓
Virtual Threads
  │
  │  "Make concurrency lightweight"
  ↓
Structured Concurrency
     "Make concurrency manageable"

And that is the story of Java concurrency:

We started by creating threads.Then we learned how difficult threads could be.So we built abstractions around them.Then we made concurrency asynchronous.Then reactive.And eventually, Java made threads cheap again.

From Thread to Virtual Threads — Java's concurrency story is really the story of making concurrent programming easier, cheaper, and more scalable.

JPA Mapping with Hibernate- Many-to-Many Relationship

AnkitDevCode — Sat, 14 Mar 2026 11:56:20 +0000

In the previous section, we discussed the One-to-Many and Many-to-One Relationship Now, let’s look at the Many-to-many relationship

Introduction
The Relational Model Behind @ManyToMany
Unidirectional @ManyToMany — Simplest Form
Bidirectional @ManyToMany
equals() and hashCode() — The Critical Foundation
Intermediate Entity for Join Table With Extra Columns
Fetch Strategies & The N+1 Problem
Cascade Types — What to Use and When
Serialization — Avoiding Infinite Recursion
Performance Best Practices
Quick Reference — Best Practices vs Pitfalls
Conclusion

1. Introduction

A many-to-many (M:N) relationship is one of the most common yet most misunderstood associations in relational modeling. When mapped carelessly in JPA/Hibernate, it becomes a prime source of N+1 query problems, infinite JSON recursion, unnecessary eager loading, and subtle data-integrity bugs.

This article walks through every important aspect of @ManyToMany, from the simplest unidirectional form to a full intermediate-entity approach, and pairs every concept with the best practices that keep your application performant and maintainable.

2. The Relational Model Behind @ManyToMany

In a relational database, an M:N relationship is always implemented via a join table (also called a bridge or association table). For example, a Student ↔ Course relationship requires a student_course join table:

students           student_course         courses
──────────────     ─────────────────      ──────────────────
student_id (PK)    student_id  (FK) ─▶    course_id (PK)
name               course_id   (FK) ─▶    title
email              enrolled_at            credits
                   grade

If the join table carries extra columns (enrolled_at, grade), you must model it as a separate entity — a plain @JoinTable annotation cannot capture those columns.

3. Unidirectional @ManyToMany — Simplest Form

Use this when only one side needs to navigate to the other, and the join table has no extra columns.

3.1 Mapping

@Entity
public class Student {
    @Id @GeneratedValue
    private Long id;
    private String name;

    @ManyToMany
    @JoinTable(
        name = "student_course",
        joinColumns = @JoinColumn(name = "student_id"),
        inverseJoinColumns = @JoinColumn(name = "course_id")
    )
    private Set<Course> courses = new HashSet<>();   // ← Set, never List
}

@Entity
public class Course {
    @Id @GeneratedValue
    private Long id;
    private String title;
    // No back-reference here → unidirectional
}

✅ Best Practice — Use Set, not List

Always use Set<> for @ManyToMany collections. Hibernate's handling of List<> in many-to-many associations can throw MultipleBagFetchException when fetching multiple bag collections in the same query, and may produce duplicate records.

4. Bidirectional @ManyToMany

Bidirectional mapping lets both sides navigate to each other. Exactly one side must be the owning side (holds @JoinTable); the other is the inverse side (uses mappedBy).

4.1 Mapping

@Entity
public class Student {                            // OWNING SIDE
    @ManyToMany
    @JoinTable(
        name = "student_course",
        joinColumns = @JoinColumn(name = "student_id"),
        inverseJoinColumns = @JoinColumn(name = "course_id")
    )
    private Set<Course> courses = new HashSet<>();
}

@Entity
public class Course {                            // INVERSE SIDE
    @ManyToMany(mappedBy = "courses")            // mappedBy is mandatory
    private Set<Student> students = new HashSet<>();
}

❌ Pitfall — Forgetting mappedBy

Without mappedBy on the inverse side, JPA creates two independent join tables and double-inserts every link row. Always declare mappedBy on exactly one side.

4.2 Keeping Both Sides in Sync

In a bidirectional relationship you must update both sides programmatically in your helper methods, because the in-memory state is independent of the database state until flush:

// Add a convenience method on the owning side
public void enroll(Course course) {
    this.courses.add(course);
    course.getStudents().add(this);   // keep inverse in sync
}

public void unenroll(Course course) {
    this.courses.remove(course);
    course.getStudents().remove(this);
}

5. equals() and hashCode() — The Critical Foundation

Hibernate uses equals() and hashCode() to determine whether two entity instances represent the same row, especially when adding/removing from Set collections and when merging detached entities. The default Object identity implementation breaks all of this.

5.1 Correct Implementation (Business Key or UUID)

@Entity
public class Course {
    @Id @GeneratedValue
    private Long id;

    @NaturalId                     // Hibernate annotation
    @Column(nullable = false, unique = true)
    private String courseCode;     // e.g. "CS-101" — stable business key

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Course)) return false;
        Course other = (Course) o;
        return Objects.equals(courseCode, other.courseCode);
    }

    @Override
    public int hashCode() {
        return Objects.hashCode(courseCode);  // must be stable across states
    }
}

❌ Pitfall — Using id for hashCode

Never base hashCode on @Id if entities can be in a Set before being persisted. A transient entity has id = null, so its hashCode changes on persist, which silently corrupts any Set or HashMap that contained it.

6. Intermediate Entity for Join Table With Extra Columns

When the join table needs to store data (enrollment date, grade, seat number, etc.), replace the @ManyToMany shortcut with an explicit intermediate entity. This is the most robust and recommended pattern in production systems.

6.1 Composite Key Class

@Embeddable
public class EnrollmentId implements Serializable {
    @Column(name = "student_id")
    private Long studentId;

    @Column(name = "course_id")
    private Long courseId;

    // equals() + hashCode() required for @Embeddable PKs
    @Override public boolean equals(Object o) { ... }
    @Override public int hashCode() { ... }
}

6.2 Enrollment (Intermediate) Entity

@Entity
@Table(name = "student_course")
public class Enrollment {

    @EmbeddedId
    private EnrollmentId id = new EnrollmentId();

    @ManyToOne(fetch = FetchType.LAZY)
    @MapsId("studentId")
    private Student student;

    @ManyToOne(fetch = FetchType.LAZY)
    @MapsId("courseId")
    private Course course;

    @Column(nullable = false)
    private LocalDate enrolledAt;

    private BigDecimal grade;
}

6.3 Parent Entities

@Entity
public class Student {
    @OneToMany(mappedBy = "student", cascade = CascadeType.ALL, orphanRemoval = true)
    private Set<Enrollment> enrollments = new HashSet<>();

    public void enroll(Course course, LocalDate date) {
        Enrollment e = new Enrollment();
        e.setStudent(this);
        e.setCourse(course);
        e.setEnrolledAt(date);
        enrollments.add(e);
    }
}

@Entity
public class Course {
    @OneToMany(mappedBy = "course")   // no cascade from Course side
    private Set<Enrollment> enrollments = new HashSet<>();
}

✅ Best Practice — Cascade only from the aggregate root

Apply CascadeType.ALL + orphanRemoval only on the owning aggregate root side (Student). Do not cascade from Course — it is a separate aggregate and should not delete enrollments when a course is touched.

7. Fetch Strategies & The N+1 Problem

Fetch strategy is the single most impactful performance decision in any JPA application.

7.1 Always Use LAZY — Never EAGER

// ✅ Correct — LAZY is the safe default
@ManyToMany(fetch = FetchType.LAZY)
private Set<Course> courses = new HashSet<>();

// ❌ Wrong — loads ALL courses for ALL students every time a Student is loaded
@ManyToMany(fetch = FetchType.EAGER)
private Set<Course> courses;

7.2 Solving N+1 With JOIN FETCH

Even with LAZY loading, iterating a collection inside a loop produces one SQL query per iteration. Fix this with a JOIN FETCH JPQL query:

// N+1 — fires one extra query per student
List<Student> students = em.createQuery("SELECT s FROM Student s", Student.class)
                           .getResultList();
students.forEach(s -> s.getCourses().size()); // N hits

// ✅ Fixed — single JOIN query
List<Student> students = em.createQuery(
    "SELECT DISTINCT s FROM Student s JOIN FETCH s.courses",
    Student.class).getResultList();

7.3 Using @BatchSize as a Middle Ground

@ManyToMany(fetch = FetchType.LAZY)
@BatchSize(size = 25)   // loads 25 students' courses in one IN (...) query
private Set<Course> courses = new HashSet<>();

❌ Pitfall — MultipleBagFetchException

You cannot JOIN FETCH two List<> collections in the same JPQL query. Hibernate throws MultipleBagFetchException. Fix: change both to Set<>, or fetch one in JPQL and use @BatchSize for the second.

8. Cascade Types — What to Use and When

Cascade types control which JPA lifecycle operations (PERSIST, MERGE, REMOVE, etc.) are propagated from parent to child.

8.1 Recommended Cascade Matrix

Scenario	Cascade	orphanRemoval	Notes
Simple `@ManyToMany` (no extra cols)	`PERSIST, MERGE`	`false`	Do NOT use `REMOVE`
Intermediate entity (owned)	`ALL`	`true`	Only from aggregate root
Intermediate entity (shared)	`PERSIST, MERGE`	`false`	Shared = don't remove
`Course → Enrollment` (inverse)	(none)	`false`	Let `Student` own it

❌ Pitfall — CascadeType.REMOVE on @ManyToMany

Using CascadeType.REMOVE (or ALL) on a plain @ManyToMany will delete the related entities themselves — not just the join row. Removing one Student will delete all their Course records from the courses table, affecting every other enrolled student.

9. Serialization — Avoiding Infinite Recursion

Bidirectional relationships create circular object graphs. When Jackson (or any JSON library) tries to serialize a Student that contains Courses, which contain Students, which contain Courses... it throws a StackOverflowError.

9.1 Jackson Annotations

// On the owning side (Student)
@JsonManagedReference
private Set<Course> courses;

// On the inverse side (Course)
@JsonBackReference
private Set<Student> students;  // this side is NOT serialized

9.2 Better: Use DTOs (Recommended)

Never serialize JPA entities directly to your API layer. Use dedicated DTO/response classes:

// DTO — safe, no cycles, no Hibernate proxies
public record CourseDTO(Long id, String title, int credits) {
    public static CourseDTO from(Course c) {
        return new CourseDTO(c.getId(), c.getTitle(), c.getCredits());
    }
}

public record StudentDTO(Long id, String name, Set<CourseDTO> courses) {
    public static StudentDTO from(Student s) {
        return new StudentDTO(
            s.getId(), s.getName(),
            s.getCourses().stream().map(CourseDTO::from).collect(Collectors.toSet())
        );
    }
}

10. Performance Best Practices

10.1 Projections and DTO Queries

For read-heavy endpoints, skip entity loading entirely and query directly into DTOs:

@Query("SELECT new com.example.dto.StudentCourseDTO(s.name, c.title) " +
       "FROM Student s JOIN s.courses c WHERE s.id = :studentId")
List<StudentCourseDTO> findCoursesByStudent(@Param("studentId") Long id);

10.2 Pagination — Never Paginate With JOIN FETCH

// ❌ Wrong — Hibernate loads ALL rows into memory, then paginates
@Query("SELECT DISTINCT s FROM Student s JOIN FETCH s.courses")
Page<Student> findAll(Pageable pageable);   // issues HHH90003004 warning

// ✅ Correct — paginate the root entity, load collection separately
@Query(value = "SELECT s FROM Student s",
       countQuery = "SELECT COUNT(s) FROM Student s")
Page<Student> findAll(Pageable pageable);
// Then use @BatchSize or a second query to load courses

10.3 Use @Transactional on Service, Not Repository

Keep your transactions at the service layer where the full unit of work is clear. Opening a transaction in a repository method gives you no control over lazy loading in the service.

11. Quick Reference — Best Practices vs Pitfalls

✅ Best Practice	❌ Pitfall to Avoid
Use `@ManyToMany` with intermediate entity for extra columns	Using plain `@JoinTable` when join table has extra data
Set `fetch = FetchType.LAZY` on both sides	Using `FetchType.EAGER` (causes N+1 queries)
Define owning side clearly with `mappedBy` on inverse	Bidirectional mapping without `mappedBy`
Use `Set<>` instead of `List<>` to avoid duplicates	Using `List<>` and getting `MultipleBagFetchException`
Use `orphanRemoval` + `CascadeType.ALL` on parent side only	Cascading `ALL` on both sides (infinite loops / dual deletes)
Implement `equals()`/`hashCode()` based on business key	Using default `Object` identity for `equals`/`hashCode`
Use `@BatchSize` or `JOIN FETCH` to load related data	Loading collections in a loop (classic N+1 problem)
Use DTOs and projections for read-heavy queries	Serializing full entity graphs to JSON (`StackOverflow` risk)

12. Conclusion

Many-to-many associations are powerful but require deliberate design. The key takeaways are:

Use Set<> — always. List<> in M:N leads to bags, duplicates, and MultipleBagFetchException.
Prefer intermediate entity — as soon as the join table has any extra column, model it explicitly.
Keep fetch=LAZY everywhere — solve loading problems with JOIN FETCH or @BatchSize, not EAGER.
Define equals()/hashCode() on a stable business key — never rely on the database-generated id.
Cascade carefully — REMOVE and orphanRemoval belong only on aggregate-root-owned children.
Use DTOs at the API layer — never serialize entity graphs directly to JSON.
Measure first — use Hibernate's statistics or a query logger (P6Spy/datasource-proxy) to confirm you have no N+1 queries before shipping.

JPA Mapping with Hibernate- One-to-Many and Many-to-One Relationship

AnkitDevCode — Sat, 14 Mar 2026 11:14:02 +0000

In the previous section, we discussed the One-to-One Relationship Now, let’s look at the one-to-many and many-to-one relationships

What Are These Relationships?
Setting Up a Bidirectional Relationship
- The Parent (One Side)
- The Child (Many Side)
Unidirectional @OneToMany — Avoid It
Best Practices
- 1. Always Use Lazy Fetching
- 2. Use List Instead of Set
- 3. Keep Both Sides in Sync
- 4. Use orphanRemoval for Parent-Owned Children
- 5. Never Cascade on @ManyToOne
- 6. Override equals and hashCode
Common Pitfalls
- The N+1 Query Problem
- LazyInitializationException
- Out-of-Sync Bidirectional State
- CascadeType.REMOVE + orphanRemoval Redundancy
Cascade Types Reference
Quick Reference Table
Summary

1. What Are These Relationships?

In JPA, One-to-Many and Many-to-One are two sides of the same coin. A Department can have many Employee records, and each Employee belongs to one Department. In the database, the foreign key (department_id) lives on the employees table — making Employee the owning side.

Key Terminology

Term	Meaning
Owning side	The entity that holds the foreign key column in the database — always the `@ManyToOne` side
Inverse side	The entity with `mappedBy` — does not control the FK, just navigates the relationship
`mappedBy`	Used on the inverse (non-owning) side to point back to the owning field
`CascadeType`	Which operations (`PERSIST`, `MERGE`, `REMOVE`, etc.) propagate from parent to child
`orphanRemoval`	Automatically deletes a child row when it is removed from the parent collection
`FetchType.LAZY`	Child data is loaded on demand when accessed — default for collections
`FetchType.EAGER`	Child data is always loaded with the parent — default for single associations

Database Representation

departments            employees
────────────────       ──────────────────────
dept_id  (PK)    ◀─    employee_id  (PK)
name                   name
                       department_id  (FK)  ← FK lives here (owning side)

2. Setting Up a Bidirectional Relationship

The recommended approach is a bidirectional mapping, where both entities know about each other.

The Parent (One Side)

@Entity
public class Department {

    @Id
    @GeneratedValue
    private Long id;

    private String name;

    @OneToMany(mappedBy = "department", cascade = CascadeType.ALL, orphanRemoval = true)
private List<Employee> employees = new ArrayList<>();

    // Always use helper methods to keep both sides in sync
    public void addEmployee(Employee emp) {
        employees.add(emp);
        emp.setDepartment(this);
    }

    public void removeEmployee(Employee emp) {
        employees.remove(emp);
        emp.setDepartment(null);
    }
}

The Child (Many Side)

@Entity
public class Employee {

    @Id
    @GeneratedValue
    private Long id;

    private String name;

    @ManyToOne(fetch = FetchType.LAZY)   // Always override the default!
    @JoinColumn(name = "department_id")
    private Department department;
}

Why mappedBy?
It tells JPA that Department is the inverse side — it does not own the FK column. Without it, Hibernate creates a join table, which is almost never what you want.

3. Unidirectional @OneToMany — Avoid It

// Looks clean but generates extra SQL
@OneToMany
@JoinColumn(name = "department_id")  // no mappedBy
private List<Employee> employees;

Here, Department knows about Employee, but Employee does not reference Department. When Hibernate cannot write the FK during the child INSERT (because it doesn't own the column), it issues extra UPDATE statements afterward. This produces unnecessary SQL and hurts performance.

Problems with unidirectional @OneToMany:

Generates extra UPDATE queries on every insert
Poor performance at scale
May silently create join tables if @JoinColumn is omitted
Harder to maintain relationship consistency
Limited query capability from the child side

✅ Best Practice: Always use @ManyToOne as the owning side and @OneToMany(mappedBy = "...") as the inverse side for bidirectional relationships.

4. Best Practices

1. Always Use Lazy Fetching

@ManyToOne defaults to EAGER — a hidden performance trap that loads the parent every time you load a child, even when you don't need it. Always override it explicitly.

@ManyToOne(fetch = FetchType.LAZY)   // override the EAGER default
@JoinColumn(name = "department_id")
private Department department;

@OneToMany is lazy by default, which is correct — leave it as-is.

2. Use `List` Instead of `Set`

If a JPA entity’s equals() and hashCode() are based on an auto-generated identifier, developers often use a constant hashCode() until the ID is assigned.

However, this hurts Set performance because all elements end up in the same hash bucket. As a result, every add() or contains() operation requires scanning all elements, degrading performance from O(1) to O(n).

In a Set, duplicate elements are not allowed because it relies on equals() and hashCode() to determine uniqueness. However, in Jakarta Persistence entities, equality typically corresponds to the identity of the associated database record. Since every child entity has a unique primary key (or a unique business key), entities retrieved from the database will already be distinct.
Because of this, a Set rarely provides any real benefit for a bidirectional @OneToMany association. Hibernate will not return duplicate rows for the same entity when loading the collection, so the collection naturally contains unique elements.

From a performance perspective, List implementations such as ArrayList are usually faster and simpler.

3. Keep Both Sides in Sync

In a bidirectional relationship, JPA uses the owning side to write to the DB. If you only update the inverse side (Department.employees), the FK won't be persisted. Always use helper methods:

// ✅ Good — updates both sides
department.addEmployee(employee);

// ❌ Bad — only updates the inverse side, FK not persisted
department.getEmployees().add(employee);

4. Use `orphanRemoval` for Parent-Owned Children

When the parent fully owns the lifecycle of its children, enable orphanRemoval:

@OneToMany(mappedBy = "department", cascade = CascadeType.ALL, orphanRemoval = true)
private Set<Employee> employees = new HashSet<>();

Removing a child from the collection now automatically deletes it from the database on the next flush — no need for an explicit em.remove() call.

5. Never Cascade on `@ManyToOne`

cascade = CascadeType.ALL belongs on the parent (@OneToMany) side. Adding it to @ManyToOne can cause catastrophic side effects — like deleting a Department when you delete one Employee.

// ❌ WRONG — could delete the entire department!
@ManyToOne(cascade = CascadeType.ALL)
private Department department;

// ✅ CORRECT — no cascade on the child side
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "department_id")
private Department department;

6. Override `equals` and `hashCode`

Use a natural business key (e.g., email for an employee), not the database ID. The ID is null before the entity is persisted, so ID-based equality breaks collections like HashSet.

@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof Employee)) return false;
    Employee other = (Employee) o;
    return email != null && email.equals(other.email);
}

@Override
public int hashCode() {
    return getClass().hashCode();  // stable across transient and persistent states
}

5. Common Pitfalls

The N+1 Query Problem

The most common JPA performance issue. Loading a list of departments, then accessing each one's employees, fires one query per department.

// ❌ Triggers 1 + N queries
List<Department> depts = repo.findAll();
depts.forEach(d -> d.getEmployees().size()); // N extra queries!

Fix 1 — JOIN FETCH in JPQL:

@Query("SELECT DISTINCT d FROM Department d LEFT JOIN FETCH d.employees")
List<Department> findAllWithEmployees();

Fix 2 — @EntityGraph (Spring Data):

@EntityGraph(attributePaths = {"employees"})
List<Department> findAll();

Fix 3 — @BatchSize (Hibernate):

@OneToMany(mappedBy = "department")
@BatchSize(size = 25)
private List<Employee> employees;

@BatchSize loads children in batches using an IN (...) clause rather than one query each — a low-friction option when you don't want to change your JPQL queries.

`LazyInitializationException`

Accessing a lazy collection outside of an active Hibernate session (e.g., after the transaction has closed) throws this exception.

// ❌ Fails if the session is already closed
department.getEmployees().size(); // LazyInitializationException!

Fix: Always access lazy relationships within a @Transactional context, or eagerly fetch what you need in the repository query.

// ✅ Safe — transaction is open for the duration of the method
@Transactional
public DepartmentDTO getDepartmentWithEmployees(Long id) {
    Department dept = repo.findById(id).orElseThrow();
    dept.getEmployees().size(); // safe here
    return DepartmentDTO.from(dept);
}

Out-of-Sync Bidirectional State

Setting the child's reference without updating the parent's collection (or vice versa) leaves the in-memory object graph inconsistent, even if the DB is correct after flush.

// ❌ Only sets one side — department.getEmployees() won't contain emp in memory
emp.setDepartment(department);

// ✅ Use the helper method to keep both sides consistent
department.addEmployee(emp);

`CascadeType.REMOVE` + `orphanRemoval` Redundancy

Both cause child deletion when the parent is removed. Using both together is redundant and signals a misunderstanding of their purpose.

CascadeType.REMOVE — deletes children when the parent entity is explicitly removed via em.remove().
orphanRemoval = true — deletes children when they are removed from the parent's collection or when the parent is deleted.

✅ Use orphanRemoval = true when the parent fully owns the child lifecycle — it covers the REMOVE case and also handles disassociation from the collection. You do not need both.

6. Cascade Types Reference

Cascade Type	Effect	Use When
`PERSIST`	When parent is saved for the first time, unsaved children are also saved	Always safe on parent side
`MERGE`	When parent is merged (updated), children are also merged	Almost always paired with `PERSIST`
`REMOVE`	When parent is deleted, all children are deleted	Only on owned children; use `orphanRemoval` instead
`REFRESH`	When parent is refreshed from DB, children are also refreshed	Rarely needed
`DETACH`	When parent is detached from context, children are also detached	Rarely needed
`ALL`	Shorthand for all of the above	Convenient but potentially dangerous — review carefully

7. Quick Reference Table

Attribute	Recommended Setting	Notes
`@OneToMany` fetch	`LAZY` (default)	Don't override unless necessary
`@ManyToOne` fetch	`LAZY` (explicit)	Default is `EAGER` — always override
`mappedBy`	On the `@OneToMany` side	Marks the inverse (non-owning) side
`cascade`	`CascadeType.ALL` on parent only	Never put cascade on `@ManyToOne`
`orphanRemoval`	`true` for fully owned children	Handles both removal and disassociation
Collection type	`Set<T>`	Safer than `List<T>` with multiple joins
N+1 prevention	`JOIN FETCH` or `@EntityGraph`	`@BatchSize` is a low-friction alternative
`equals`/`hashCode`	Based on business key	Never based on database ID
Unidirectional `@OneToMany`	Avoid	Extra `UPDATE` SQL, harder to maintain
Helper methods	Always define on parent	Keep both sides of bidirectional mapping in sync

8. Summary

The FK lives on the many side — that entity is the owning side.
Use mappedBy on @OneToMany to declare the inverse side and avoid a spurious join table.
Always set @ManyToOne(fetch = FetchType.LAZY) — the default EAGER is a performance trap.
Write bidirectional helper methods (addEmployee / removeEmployee) to keep both sides in sync.
Use Set<> over List<> to avoid Cartesian products when joining multiple collections.
Watch for the N+1 problem whenever you iterate over collections — fix with JOIN FETCH, @EntityGraph, or @BatchSize.
Never cascade from child to parent (@ManyToOne).
Prefer orphanRemoval = true over CascadeType.REMOVE — it handles more cases cleanly.
Base equals()/hashCode() on a stable business key, never on the auto-generated database ID.

Code

@Entity
@Getter
@Setter
public class Department {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @OneToMany(mappedBy = "department", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<Employee> employees = new ArrayList<>();

    // Always use helper methods to keep both sides in sync
    public void addEmployee(Employee emp) {
        employees.add(emp);
        emp.setDepartment(this);
    }

    public void removeEmployee(Employee emp) {
        employees.remove(emp);
        emp.setDepartment(null);
    }
}

@Entity
@Getter
@Setter
public class Employee {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    private String email;

    public Employee(String name, String email) {
        this.name = name;
        this.email = email;
    }

    @ManyToOne(fetch = FetchType.LAZY)   // Always override the default!
    @JoinColumn(name = "department_id")
    private Department department;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Employee)) return false;
        Employee other = (Employee) o;
        return email != null && email.equals(other.email);
    }

    @Override
    public int hashCode() {
        return getClass().hashCode();
    }
}

public interface DepartmentRepository extends JpaRepository<Department, Long> {
}

public interface EmployeeRepository extends JpaRepository<Employee, Long> {
}

@Component
public class DataLoader implements ApplicationRunner {

    private final DepartmentRepository departmentRepo;
    private final EmployeeRepository employeeRepo;

    public DataLoader(DepartmentRepository departmentRepo, EmployeeRepository employeeRepo) {
        this.departmentRepo = departmentRepo;
        this.employeeRepo = employeeRepo;
    }

    @Override
    @Transactional
    public void run(ApplicationArguments args) {

        /*
         * STEP 1: Create a Department entity
         * No DB query yet because the entity is only created in memory.
         */
        Department engineering = new Department();
        engineering.setName("Engineering");

        /*
         * STEP 2: Create Employee entities
         * These are also only in memory at this point.
         */
        Employee alice = new Employee("Alice", "alice@example.com");
        Employee bob   = new Employee("Bob",   "bob@example.com");

        /*
         * STEP 3: Link employees to department
         * The helper method usually:
         * 1. Adds employee to department.employees list
         * 2. Sets employee.department = this
         *
         * This ensures both sides of the bidirectional relationship stay consistent.
         */
        engineering.addEmployee(alice);
        engineering.addEmployee(bob);

        /*
         * STEP 4: Persist department
         *
         * Because the Department entity likely has:
         *
         * @OneToMany(mappedBy="department", cascade = CascadeType.ALL, orphanRemoval = true)
         *
         * Hibernate will cascade the persist operation to Employee entities.
         *
         * Expected SQL queries:
         *
         * INSERT INTO department (name)
         * INSERT INTO employee (name, email, department_id)
         * INSERT INTO employee (name, email, department_id)
         *
         * Total queries = 3
         */
        departmentRepo.save(engineering);

        /*
         * STEP 5: Read all departments
         *
         * Expected SQL:
         * SELECT * FROM department
         *
         * If employees collection is LAZY (recommended),
         * employees are NOT fetched until accessed.
         */
        departmentRepo.findAll().forEach(d ->
                System.out.println("Dept: " + d.getName())

        );

        /*
         * STEP 6: Find department by ID
         *
         * Expected SQL:
         * SELECT * FROM department WHERE id = ?
         */
        Optional<Department> dept = departmentRepo.findById(engineering.getId());
        dept.ifPresent(d -> System.out.println("Found: " + d.getName()));

        System.out.println("Department loaded");

      // employees should load only here
        dept.get().getEmployees().forEach(e ->
                System.out.println(e.getName()));


        /*
         * STEP 7: Update employee
         *
         * Changing Alice's name marks the entity as dirty.
         *
         * Expected SQL on flush/commit:
         * UPDATE employee SET name='Alice Smith' WHERE id=?
         */
        alice.setName("Alice Smith");
        employeeRepo.save(alice);

        /*
         * STEP 8: Remove employee from department
         *
         * Helper method typically:
         * 1. Removes Bob from department.employees list
         * 2. Sets bob.department = null
         *
         * Because orphanRemoval = true:
         * Hibernate will DELETE the employee record automatically.
         *
         * Expected SQL:
         * DELETE FROM employee WHERE id = ?
         */
        engineering.removeEmployee(bob);

        /*
         * Saving department ensures Hibernate detects the orphan removal.
         */
        departmentRepo.save(engineering);
    }
}

JPA Mapping with Hibernate-One-to-One Relationship

AnkitDevCode — Sat, 07 Mar 2026 12:46:24 +0000

What is JPA?
What is Hibernate?
JPA vs Hibernate — Key Differences
Relationship Mapping in JPA — Quick Reference
What is a One-to-One Relationship?
- Unidirectional vs Bidirectional
- How to Identify Owner, FK Side, and Child
- JPA Annotation Summary
Bidirectional One-to-One — Standard Mapping
- The Child Entity (Owning Side)
- The Parent Entity (Inverse Side)
The Lazy Loading Problem on the Inverse Side
- Why the Extra Query Fires
Solutions to the Inverse-Side Probe Query
- Option 1 — @LazyToOne Bytecode Instrumentation
- Option 2 — JOIN FETCH Query
- Option 3 — @NamedEntityGraph
- Option 4 — @MapsId Shared Primary Key (Best & Simplest)
Deep Dive — @MapsId
- Advantages of @MapsId
- Downsides of @MapsId
- When @MapsId Is Ideal
Comparison — @JoinColumn vs @MapsId
Quick Reference Table
Summary

1. What is JPA?

The Java Persistence API (JPA) is a Java specification that defines a standard way to manage relational data in Java applications using Object Relational Mapping (ORM).

It provides a set of interfaces and annotations that allow developers to map Java objects to database tables, perform CRUD operations, and manage persistence without writing large amounts of SQL.

Key points:

JPA is a specification, not an implementation
It standardizes how Java applications interact with relational databases
It uses annotations and configuration to map objects to tables
It simplifies database operations through entity management and persistence context

2. What is Hibernate?

Hibernate is a popular open-source ORM framework that provides a concrete implementation of the JPA specification.

It allows developers to interact with databases using Java objects instead of writing complex SQL queries, making application code loosely coupled with the underlying database.

Key points:

Hibernate is a JPA implementation
Provides powerful ORM capabilities beyond the JPA spec
Handles CRUD operations automatically
Supports caching, lazy loading, and transaction management
Reduces boilerplate JDBC code

3. JPA vs Hibernate — Key Differences

	JPA	Hibernate
Type	Specification (standard API)	Implementation of JPA
Who defines it	Jakarta EE / Oracle	Red Hat / JBoss
Can run standalone?	No — needs an implementation	Yes
Extra features	Standard only	Caching, `@BatchSize`, `@NaturalId`, etc.
Code coupling	Low — portable across providers	Higher — Hibernate-specific annotations

In practice:

Developers write code using JPA annotations and interfaces
Hibernate executes the actual database operations behind the scenes

4. Relationship Mapping in JPA — Quick Reference

Annotation	Relationship	FK Location
`@OneToOne`	One entity ↔ one entity	Child / owning side
`@OneToMany`	One entity → many entities	Child table
`@ManyToOne`	Many entities → one entity	Owning entity (FK here)
`@ManyToMany`	Many entities ↔ many entities	Join / junction table

Key best practices across all relationship types:

Always use FetchType.LAZY on relationships — avoids N+1 query problems
mappedBy goes on the non-owning side (the side without the FK column)
Cascade carefully — only cascade from parent to child, never upward
@JoinColumn explicitly names your FK column for clarity
Use Set instead of List for @ManyToMany to avoid duplicate join queries

5. What is a One-to-One Relationship?

A One-to-One relationship occurs when one entity is associated with exactly one instance of another entity.

Real-world examples:

Person → Passport
User → UserProfile
Order → Invoice

Unidirectional vs Bidirectional

Unidirectional — Only one entity has a reference to the other. Navigation works in one direction only.

User  →  UserProfile      (User knows about UserProfile; UserProfile does NOT know about User)

Bidirectional — Both entities have a reference to each other. Navigation works in both directions.

User  ⇆  UserProfile      (both sides can navigate to the other)

How to Identify Owner, FK Side, and Child

Ask yourself these three questions:

Question	Answer
Who cannot exist without the other?	That's the child → holds the FK
Who exists independently?	That's the parent → has `mappedBy`
Who makes sense to delete first?	That's the child → cascade from parent

Rule of thumb: Child = cannot exist without parent = has @JoinColumn (FK).
Parent = exists independently = has mappedBy (no FK).

JPA Annotation Summary

Annotation	Side	FK
`@JoinColumn`	Owning / Child	FK lives here
`mappedBy`	Inverse / Parent	No FK
`@JoinTable`	`@ManyToMany` owner	Junction table
`cascade`	Parent → Child	Delete parent = delete child

6. Bidirectional One-to-One — Standard Mapping

In a User ↔ UserProfile relationship, UserProfile is the child because the foreign key (user_id) lives in the user_profile table. User is the parent (inverse side).

users                  user_profile
─────────────          ──────────────────────
id  (PK)        ◀──    id  (PK)
username               phone
password               address
enabled                user_id  (FK) ← FK lives here

The Child Entity (Owning Side)

@JoinColumn is used on the owning side — the child entity contains the foreign key pointing to the parent's primary key.

@Entity
@Table(name = "user_profile")
public class UserProfile {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String phone;

    @Column(nullable = false)
    private String address;

    @OneToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id", unique = true)   // FK column lives here
    private User user;
}

The Parent Entity (Inverse Side)

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true, length = 50)
    private String username;

    @Column(nullable = false)
    private String password;

    @Column(nullable = false)
    private boolean enabled = true;

    @OneToOne(mappedBy = "user", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
    private UserProfile profile;

    @ElementCollection(fetch = FetchType.EAGER)
    @CollectionTable(
        name = "user_roles",
        joinColumns = @JoinColumn(name = "user_id"),
        uniqueConstraints = @UniqueConstraint(columnNames = {"user_id", "role"})
    )
    @Enumerated(EnumType.STRING)
    @Column(name = "role", nullable = false)
    private Set<Role> roles = new HashSet<>();

    // Bidirectional sync helper — keeps both sides consistent
    public void setProfile(UserProfile profile) {
        this.profile = profile;
        if (profile != null) {
            profile.setUser(this);
        }
    }

    // Role helper methods
    public void addRole(Role role) {
        if (role != null) this.roles.add(role);
    }

    public void removeRole(Role role) {
        this.roles.remove(role);
    }

    public boolean hasRole(Role role) {
        return this.roles.contains(role);
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof User user)) return false;
        return username != null && username.equals(user.getUsername());
    }

    @Override
    public int hashCode() {
        return getClass().hashCode();
    }
}

Note on @ElementCollection: @ElementCollection stores simple values (like enum Role) in a separate table — it is not a full entity relationship, so there is no "other side" to sync.
Keeping FetchType.EAGER here is intentional when using Spring Security — UserDetails needs roles immediately on authentication.

7. The Lazy Loading Problem on the Inverse Side

Declaring fetch = FetchType.LAZY on the inverse side (mappedBy) of a @OneToOne does not actually make it lazy. Hibernate silently fires an extra query anyway.

Why the Extra Query Fires

On the owning side, the FK column is in the same row — Hibernate immediately knows if the association is null or not, and can safely create a proxy.

On the inverse side, there is no FK column. Hibernate must probe the database just to determine whether a UserProfile exists for a given User.

Query 1: SELECT * FROM users          ← your actual request
Query 2: SELECT * FROM user_profile   ← YOU DIDN'T ASK FOR THIS (Hibernate probe)
Query 3: SELECT * FROM user_roles     ← expected (EAGER @ElementCollection)

Query 2 is Hibernate asking: "does a profile exist for this user?" — because the inverse side has no FK column to check locally.

8. Solutions to the Inverse-Side Probe Query

Option 1 — @LazyToOne Bytecode Instrumentation

Forces truly lazy loading via Hibernate bytecode enhancement — Hibernate injects an interceptor into the bytecode so it never needs to probe the DB.

// User.java
@OneToOne(mappedBy = "user", fetch = FetchType.LAZY)
@LazyToOne(LazyToOneOption.NO_PROXY)   // forces true lazy via bytecode
private UserProfile profile;

Requires adding the Hibernate bytecode enhancer plugin to your build tool:

<!-- Maven -->
<plugin>
    <groupId>org.hibernate.orm.tooling</groupId>
    <artifactId>hibernate-enhance-maven-plugin</artifactId>
    <configuration>
        <enableLazyInitialization>true</enableLazyInitialization>
    </configuration>
</plugin>

Without Enhancement	With Enhancement
Hibernate probes DB to check if profile is null	Bytecode interceptor handles it — no probe needed
Extra query always fires	Truly lazy — query only fires on access

Option 2 — JOIN FETCH Query

Load both entities together in a single SQL query — profile is already in memory, no probe needed.

@Query("SELECT u FROM User u LEFT JOIN FETCH u.profile")
List<User> findAllWithProfile();

Hibernate generates:

SELECT
    u.id, u.enabled, u.password, u.username,
    p.id, p.address, p.phone
FROM users u
LEFT JOIN user_profile p ON u.id = p.user_id

Without JOIN FETCH	With JOIN FETCH
`SELECT FROM users` + `SELECT FROM user_profile` (2 queries)	`SELECT FROM users LEFT JOIN user_profile` (1 query)

Option 3 — @NamedEntityGraph

A @NamedEntityGraph defines a pre-declared fetch plan that can be reused across multiple repository methods, avoiding the need to write JOIN FETCH everywhere.

@NamedEntityGraph(
    name = "User.withDetails",
    attributeNodes = {
        @NamedAttributeNode("roles"),
        @NamedAttributeNode("profile")
    }
)
@Entity
@Table(name = "users")
public class User { ... }

Use it in the repository:

public interface UserRepository extends JpaRepository<User, Long> {

    @Query("SELECT u FROM User u LEFT JOIN FETCH u.profile")
    List<User> findAllWithProfile();

    @EntityGraph("User.withDetails")   // applies the named graph
    List<User> findAll();
}

Combining with @NamedSubgraph for nested associations:

When you need to fetch deeply nested associations (e.g., User → UserProfile → Address), use @NamedSubgraph:

@Entity
@NamedEntityGraph(
    name = "User.profile",
    attributeNodes = {
        @NamedAttributeNode(value = "profile", subgraph = "profile-subgraph")
    },
    subgraphs = {
        @NamedSubgraph(
            name = "profile-subgraph",
            attributeNodes = {
                @NamedAttributeNode("address")
            }
        )
    }
)
public class User { ... }

@Entity
public class UserProfile {
    @Id
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    private Address address;
}

@Repository
public interface UserRepository extends JpaRepository<User, Long> {

    @EntityGraph(value = "User.profile", type = EntityGraph.EntityGraphType.FETCH)
    Optional<User> findById(Long id);
}

With the entity graph, Hibernate generates a single query:

SELECT u.*, p.*, a.*
FROM users u
LEFT JOIN user_profile p ON p.user_id = u.id
LEFT JOIN address a       ON p.address_id = a.id
WHERE u.id = ?

When to use @EntityGraph:

You want dynamic fetch strategies per query
You want associations to be LAZY by default
You want to avoid scattering JOIN FETCH across all queries
Different repository methods need different fetch plans

Option 4 — @MapsId Shared Primary Key (Best & Simplest)

Since both entities share the same PK, Hibernate already knows the profile ID without probing. This is the cleanest solution for a strict @OneToOne relationship.

See Section 9 — Deep Dive: @MapsId for full details.

9. Deep Dive — @MapsId

The best way to map a @OneToOne relationship in Hibernate is using @MapsId, which allows the child entity to share the same primary key as the parent entity.

In this approach:

The child table uses the parent's PK as its own PK
This avoids creating an additional FK column
Hibernate already knows the child's ID — no probe query needed

users                  user_profile
─────────────          ──────────────────────
id  (PK)        ═══    id  (PK = FK) ← shared PK, no separate user_id column
username               phone
password               address

@Entity
@Table(name = "user_profile")
public class UserProfile {

    @Id                          // No @GeneratedValue — value is copied from User
    private Long id;

    @Column(nullable = false)
    private String phone;

    @Column(nullable = false)
    private String address;

    @OneToOne(fetch = FetchType.LAZY)
    @MapsId                      // this entity's PK = users.id
    @JoinColumn(name = "id")
    private User user;
}

The id column in user_profile serves as both PK and FK — its value is copied directly from User.id.

Key Differences Per Entity

	`User`	`UserProfile`
`@GeneratedValue`	✅ Yes — generates own PK	❌ No — copies from `User`
Owns the relationship	No — no `profile` field needed	Yes — has `@MapsId`
Probe query on fetch	Gone — no inverse field	—
Save strategy	`userRepository.save(user)`	`userProfileRepository.save(profile)`

Advantages of @MapsId

No extra FK column — cleaner schema, better normalization
No probe query — Hibernate already knows the child's ID
Efficient joins — PK = FK means the join is on the same column
No need for bidirectional association — User can be unidirectional
UserProfile can always be fetched directly using the User ID

Downsides of @MapsId

Tight coupling — UserProfile cannot exist without User (shares PK)
Insert order dependency — User must be persisted before UserProfile
Less flexibility — migrating from one-to-one → one-to-many requires schema redesign
Harder independent lifecycle management — deleting User invalidates UserProfile
Not suitable for optional relationships — if a User can exist without a UserProfile, this gets awkward
Harder for beginners — shared PK, @MapsId, and entity lifecycle can be confusing
Schema migration complexity — adding a separate PK to the child table later requires a full refactor

When @MapsId Is Ideal

Use @MapsId when:

The relationship is strictly one-to-one
The child cannot exist without the parent
The child is more like an extension of the parent (e.g., UserProfile is just extra columns for User)
You want zero extra queries and a cleaner schema

10. Comparison — @JoinColumn vs @MapsId

	`@JoinColumn` on child	`@MapsId`
Profile FK column	`user_profile.user_id`	`user_profile.id` = `users.id`
Hibernate knows child ID?	Must probe DB	Already has it
Extra query on `getUser()`?	Always fires (inverse side)	Only when accessed
DB schema	Extra `user_id` column	Shared PK — cleaner
Optional relationship?	✅ Yes	❌ Not ideal
Child exists independently?	✅ Can	❌ Cannot
Schema simplicity	Slightly more columns	Minimal columns

11. Quick Reference Table

Topic	Recommendation	Notes
Owning side	Entity holding the FK (`@JoinColumn`)	Always the child
Inverse side	Entity with `mappedBy`	No FK — navigation only
`@OneToOne` fetch (owning)	`FetchType.LAZY`	FK in same row — proxy safe
`@OneToOne` fetch (inverse)	`FetchType.LAZY` declared, but won't be	Hibernate probes regardless
Probe query fix	`@MapsId` or `JOIN FETCH`	`@MapsId` is cleanest for strict 1:1
N+1 prevention	`JOIN FETCH` or `@EntityGraph`	`@NamedSubgraph` for nested graphs
Cascade	`CascadeType.ALL` on parent only	Never cascade from child to parent
`orphanRemoval`	`true` for owned children	Handles disassociation too
`equals`/`hashCode`	Based on business key	Never based on database ID
Collection for roles	`Set<Role>`	Safer than `List` with multiple joins
Best overall mapping	`@MapsId` for strict 1:1	`@JoinColumn` for optional or flexible

12. Summary

In a @OneToOne relationship, the child holds the FK (@JoinColumn); the parent uses mappedBy.
Declaring FetchType.LAZY on the inverse side does not make it truly lazy — Hibernate fires a probe query anyway because there is no FK column to inspect locally.
Four ways to fix the probe query: bytecode instrumentation (@LazyToOne), JOIN FETCH, @NamedEntityGraph, or @MapsId.
@MapsId is the cleanest solution for strict one-to-one relationships — the child shares the parent's PK, eliminating the extra FK column and the probe query entirely.
Bidirectional = convenience (user.getProfile()) but costs a probe query. Unidirectional = no probe but you lose navigation from the User side.
For most applications — skip bytecode plugins, go unidirectional with @MapsId, and use JOIN FETCH when you need both entities at once.
Always use CascadeType.ALL on the parent side only — never cascade upward from child to parent.
Base equals()/hashCode() on a stable business key (e.g., username), never on the auto-generated database ID.

REST API Design: A Comprehensive Guide

AnkitDevCode — Sat, 07 Mar 2026 09:54:56 +0000

Understanding REST Fundamentals

REST works on top of the HTTP protocol, where each URI represents a resource. Because of this, endpoints should use nouns, not verbs. An RPC-style endpoint like /api/v1/getStudents becomes simply /api/v1/students in REST. The distinction between actions is handled by HTTP methods — GET, POST, PUT, PATCH, and DELETE — rather than the URL itself.

A REST endpoint is a unique URI that represents a resource. For example, https://demo.app/api/v1/students is a REST endpoint, where /api/v1/students is the path and students is the resource.

REST does not maintain server-side state — it only transfers state between server and client, which is the origin of the name REpresentational State Transfer. REST also leverages HTTP cache control, making responses cacheable because every representation is self-descriptive.

REST operates using three key components:

Resources and URIs — the nouns that identify what you're working with
HTTP methods — the verbs that define the action
HATEOAS — hypermedia links that guide clients dynamically

HTTP Methods

The five primary HTTP methods map to standard CRUD operations:

Method	Operation	Notes
`POST`	Create (or search)	Use for search when filter params exceed GET limits
`GET`	Read	Should be side-effect free
`PUT`	Full update / replace	Replaces the entire resource
`PATCH`	Partial update	Updates only the provided fields
`DELETE`	Delete	Should be idempotent

Some organisations also expose the HEAD method to retrieve only response headers without a body — useful for checking resource existence or metadata. For example:

curl --head https://api.github.com/users

Note: REST does not strictly mandate which method maps to which operation, but the conventions above are widely adopted across the industry.

POST

POST is normally used for create operations. There are two notable exceptions where POST is acceptable for reads:

Long filter criteria — GET query strings are limited to around 2,048 characters. When filter parameters exceed this, POST is a reasonable alternative.
Sensitive parameters — if input parameters contain private data, POST with HTTPS keeps them out of the URL and server logs.

A successful create operation should return 201 Created.

GET

GET is used for read operations. It should never modify server state. Successful responses return 200 OK when data is present, or 204 No Content when there is nothing to return.

PUT

PUT is used for full update or replace operations. It replaces the entire resource with the provided representation. Successful responses return 200 OK with data or 204 No Content without.

DELETE

DELETE removes a resource. For example, DELETE /licenses/agpl-3.0 deletes the resource identified by the agpl-3.0 key. A successful delete returns 204 No Content.

PATCH

PATCH is used for partial updates — only the supplied fields are changed. A successful response returns 200 OK. Unlike PUT, you do not need to send the full resource representation.

HTTP Status Codes

Status codes fall into five categories:

Range	Category
100–199	Informational
200–299	Success
300–399	Redirection
400–499	Client errors
500–599	Server errors

Commonly Used Codes

2xx — Success

200 OK — Request succeeded. Used for GET, PUT, and PATCH responses with a body.
201 Created — Resource was successfully created.
202 Accepted — Request received but processing is deferred (e.g., async or batch jobs).
204 No Content — Request succeeded with no response body.

3xx — Redirection

304 Not Modified — Resource hasn't changed; client should use its cached copy.

4xx — Client Errors

400 Bad Request — Missing, malformed, or invalid input parameters.
401 Unauthorized — Request is unauthenticated (despite the misleading name).
403 Forbidden — Authenticated but not authorised to perform the action.
404 Not Found — The requested resource does not exist.
405 Method Not Allowed — The HTTP method is not supported for this endpoint.
409 Conflict — Duplicate create or a state conflict (e.g., version mismatch).
429 Too Many Requests — Rate limit has been exceeded.

5xx — Server Errors

500 Internal Server Error — A generic, unexpected server-side failure.
502 Bad Gateway — An upstream dependency (e.g., a payment provider) returned an error.
503 Service Unavailable — The server is temporarily unable to handle requests (overload or maintenance).

HATEOAS

HATEOAS (Hypermedia as the Engine of Application State) means that a REST API dynamically provides links to related actions and resources within its responses — rather than requiring clients to construct URLs themselves.

A client starts from a single known URL and discovers everything else through the hypermedia links in each response. This has two key benefits:

Clients don't need hardcoded knowledge of the API's URL structure.
When endpoint paths change, clients pick up the new URLs automatically through the links.

Best Practices

1. Use Nouns for Resource Names

HTTP methods already supply the verb. Adding a verb to the URL is redundant and produces RPC-style paths:

# Wrong (RPC style)
GET /getLicenses
POST /createUser

# Correct (REST style)
GET /licenses
POST /users

2. Use Plural Names for Collections

/licenses   ✓
/license    ✗

A GET /licenses call returns a collection. Plural naming makes the intent clear and consistent regardless of whether you're fetching one or many.

3. Version Your APIs

APIs evolve over time, and existing clients may depend on older behaviour. Always include a version identifier so you can introduce breaking changes without affecting existing integrations.

Option A — Version in the path (most common):

https://demo.app/api/v1/students

Clients always know exactly which version they're calling.

Option B — Version in the Accept header (GitHub's approach):

Accept: application/vnd.github.v3+json

Allows a default version when no header is present, but requires clients to update the header when upgrading.

Either approach works — the important thing is to pick one and apply it consistently from day one.

4. Model Nested Resources

When a resource belongs to another, reflect that in the URL hierarchy:

GET    /customers/1/addresses       # all addresses for customer 1
GET    /customers/1/addresses/2     # address 2 of customer 1
POST   /customers/1/addresses       # add a new address
PUT    /customers/1/addresses/2     # replace address 2
PATCH  /customers/1/addresses/2     # partially update address 2
DELETE /customers/1/addresses/2     # delete address 2

For resources that exist independently (e.g., payments in a microservices architecture), a top-level endpoint is often cleaner:

GET /payments/1    # instead of /orders/1/payments/1

HATEOAS helps here — the order response can include a payment link rather than the client needing to know the URL structure upfront.

5. Secure Your APIs

Always use HTTPS — never expose REST APIs over plain HTTP.
Use JWT or OAuth 2.0 tokens for authentication. REST is stateless, so cookies and server-side sessions are not appropriate.
Regularly review OWASP's API Security Top 10 for current threats and mitigations.
Validate all inputs on the server side regardless of client-side validation.

6. Implement Caching

HTTP provides two standard mechanisms for cache validation:

ETag — the server returns a hash of the response body in the ETag header. The client sends it back as If-None-Match on subsequent requests. If the resource hasn't changed, the server returns 304 Not Modified and saves the bandwidth of resending the body.

Last-Modified — the server returns the resource's last modification timestamp. The client sends it back as If-Modified-Since. The server returns 304 if nothing has changed since that timestamp. This is less precise than ETag and should be used as a fallback.

7. Enforce Rate Limiting

Use 429 Too Many Requests when a client exceeds its allowed request quota. Communicate rate limit status via response headers so clients can adapt:

Header	Meaning	Example
`X-Ratelimit-Limit`	Requests allowed per period	`60`
`X-Ratelimit-Remaining`	Requests left in current period	`55`
`X-Ratelimit-Used`	Requests used in current period	`5`
`X-Ratelimit-Reset`	Seconds until the period resets	`1601299930`

8. Support Filtering, Sorting, and Pagination

For endpoints that return collections, always support query parameters to avoid returning unbounded result sets:

GET /products?category=electronics&sort=price       # filter + sort
GET /users?page=1&size=20                           # pagination
GET /orders?status=pending&sort=created_at&page=2  # combined

9. Maintain Documentation

Good documentation is part of your API contract. It should:

Stay in sync with the current implementation, including version history.
Include code samples and example request/response pairs.
Clearly document deprecated endpoints and provide migration paths.
Be generated from the code where possible (e.g., OpenAPI/Swagger) to reduce drift.

10. Return Consistent Error Responses

Error responses should follow a predictable structure so clients can handle them programmatically:

{
  "status": 400,
  "error": "Bad Request",
  "message": "The 'email' field is required.",
  "path": "/api/v1/users"
}

Consistency here dramatically reduces the integration effort for API consumers.

Quick Reference

Concern	Recommendation
URL naming	Nouns, plural, lowercase, hyphen-separated
HTTP methods	Match semantics: `GET` reads, `POST` creates, `PUT` replaces, `PATCH` partially updates, `DELETE` removes
Status codes	Use the most specific code; avoid overusing `200` for everything
Versioning	Include from day one (`/api/v1/`)
Auth	JWT or OAuth 2.0 — no cookies or sessions
Caching	Use `ETag` or `Last-Modified` headers
Rate limiting	Return `429` with `X-Ratelimit-*` headers
Pagination	`?page=&size=` query params on collection endpoints
Documentation	OpenAPI/Swagger, kept current, with examples
Error format	Consistent JSON structure across all endpoints

Reference:

AI tools such as ChatGpt and Claude
Modern API Development with Spring and Spring Boot | Web Development | Paperback

Design highly scalable and maintainable APIs with REST, gRPC, GraphQL, and the reactive paradigm. 12 customer reviews. Top rated Web Development products.

packtpub.com

Java Virtual Threads — Quick Guide

AnkitDevCode — Sun, 01 Feb 2026 12:12:55 +0000

Java Virtual Threads — Quick Guide

Java 21+ · Spring Boot 3.2+ · Project Loom

A concise, production-focused guide to Java Virtual Threads — what they are, how to enable them, when to use them, and the real-world pitfalls that can silently hurt performance.

01 · What Are Virtual Threads

Before Project Loom, there is only one type of threads in Java, which is called platform thread in Project Loom. Platform threads are typically mapped 1:1 to kernel threads scheduled by the operating system. In Project Loom, virtual threads are introduced as a new type of threads.

Virtual threads are typically user-mode threads scheduled by the Java runtime rather than the operating system. Virtual threads are mapped M:N to kernel threads.

Platform and virtual threads are both represented using java.lang.Thread

Extremely lightweight compared to platform (OS) threads.
Millions of virtual threads can be created safely.
Allow developers to write simple, blocking-style code while remaining highly scalable.

How to create virtual threads?

The first approach to create virtual threads is using the Thread.ofVirtual method.

In the code below, a new virtual thread is created and started. The return value is an instance of java.lang.Thread object.

var thread = Thread.ofVirtual().name("My virtual thread")
    .start(() -> System.out.println("I'm running"))

The second approach is using Thread.startVirtualThread(Runnable task) method. This is the same as calling Thread.ofVirtual().start(task).

The third approach is using ThreadFactory.

var factory = Thread.ofVirtual().factory();
var thread = factory.newThread(() -> System.out.println("Create in factory"));

How to check if a thread is virtual?

The new isVirtual() method in java.lang.Thread returns true is this thread is a virtual thread.

Can virtual threads be non-daemon threads?

No. Virtual threads are always daemon threads. So they cannot prevent JVM from terminating. Calling setDaemon(false) on a virtual thread will throw an IllegalArgumentException exception.

Should virtual threads be pooled?

No. Virtual threads are light-weight. There is no need to pool them.

Can virtual threads support thread-local variables?

Yes. Virtual threads support both thread-local variables (ThreadLocal) and inheritable thread-local variables (InheritableThreadLocal).

Can virtual threads support thread-local variables?

Yes. Virtual threads support both thread-local variables (ThreadLocal) and inheritable thread-local variables (InheritableThreadLocal).

Can ExecutorService use virtual threads?

An ExecutorService can start a virtual thread for each task. This kind of ExecutorServices can be created using Executors.newVirtualThreadPerTaskExecutor() or Executors.newThreadPerTaskExecutor(ThreadFactory threadFactory) methods. The number of virtual threads created by the Executor is unbounded.

In the code below, a new ExecutorService is created to use virtual threads. 10000 tasks are submitted to this ExecutorService.

try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
  IntStream.range(0, 10_00).forEach(i -> executor.submit(() -> {
    Thread.sleep(Duration.ofSeconds(1));
    return i;
  }));
}

Blocking comparison

OS Thread blocks

RestTemplate blocks an OS thread
Thread is idle during I/O
Under load → thread exhaustion

Virtual Thread blocks

JVM suspends the virtual thread
Carrier thread is released immediately
Scales safely under high concurrency

Why we need virtual threads?

Enable in Spring Boot

One property. No code changes.

# application.yml
server:
  servlet:
    threads:
      virtual-threads-enabled: true

Requirements

Java 21+ (final, not preview)
Spring Boot 3.2+

What changes

Each HTTP request runs on a fresh virtual thread
Controllers, services, RestTemplate → unchanged

What `virtual-threads-enabled: true` Actually Does in Spring

It replaces Tomcat’s entire servlet thread pool with a virtual-thread-per-request executor. Every incoming HTTP request is immediately assigned a new virtual thread. There is no fixed pool size — Tomcat doesn’t cap anything. The JVM manages it all.

This means your entire request lifecycle — from the moment the request hits the DispatcherServlet to the moment the response is written — runs on a virtual thread. Every blocking call inside that chain (RestTemplate, JDBC, Thread.sleep()) is automatically cheap because it’s already on a virtual thread.

The Manual Offload Approach

Tomcat’s default OS thread pool handles accept and dispatch, then the work is explicitly handed off to a virtual thread executor. For example, CompletableFuture.supplyAsync() offloads work to the virtual thread executor. The OS thread that accepted the request is released immediately.

Spring MVC knows how to handle a returned CompletableFuture:

It suspends servlet processing
It resumes when the future completes

The key point: Spring MVC does not block the servlet thread waiting for the future. It registers a callback internally and frees the thread immediately.

Service and Client Layers Remain Unchanged

The service and client layers stay completely unchanged in both approaches.

Virtual Threads Adoption Strategy in Spring Boot

Context

The existing Spring Boot microservice handles incoming HTTP requests using Spring MVC (Servlet stack) and communicates with multiple downstream services using blocking clients such as RestTemplate and JDBC.

Key constraints and characteristics:

The current implementation cannot be changed or rewritten.
The codebase contains:
- synchronized blocks and methods
- Heavy reliance on ThreadLocal (SecurityContext, MDC, request attributes)
The service performs I/O-heavy aggregation across multiple downstream services.
Scalability issues arise due to thread blocking under load.

The goal is to improve concurrency and scalability using Java Virtual Threads, without breaking existing behavior or introducing subtle runtime risks.

Two approaches are available in Spring Boot:

Property-based virtual threads (spring.threads.virtual.enabled=true)
Manual offloading to a virtual-thread executor using CompletableFuture

Option 1: Property-Based Virtual Threads (Global Enablement)

Description

Enabling:

(spring.threads.virtual.enabled=true)

replaces Tomcat's servlet thread pool with a virtual-thread-per-request executor.

Each HTTP request:

Is assigned a fresh virtual thread
Runs entirely on that virtual thread (filters → controllers → services → response)
Executes blocking calls cheaply (RestTemplate, JDBC, Thread.sleep)

Benefits

Zero code changes
Uniform behavior across the entire application
Automatic scalability for blocking I/O

Risks and Limitations

Pinning Risk

synchronized blocks pin carrier threads
Pinning is invisible and global
Concurrent access can exhaust the small carrier thread pool

[Virtual Thread]

↓

synchronized block  ← carrier pinned

↓

blocking I/O

If N concurrent requests enter pinned sections, N carrier threads are required. With only ~CPU-count carriers available, the application can stall.

ThreadLocal Assumptions Break

Virtual threads are short-lived
No thread reuse across requests
ThreadLocal data does not persist beyond a single request

This breaks assumptions made by existing code that was written for pooled OS threads.

ThreadLocal Abuse: If your project stores massive objects in ThreadLocal, you might run into memory issues because you could suddenly have 100,000 threads instead of 200.

Lack of Control

No isolation boundary
No way to selectively exclude endpoints or code paths
Fixing issues requires rewriting synchronized and ThreadLocal-dependent code

Option 2: Manual Offload to Virtual Threads (Selective Adoption)

Description

Tomcat continues to use its default OS-thread servlet pool
Existing code runs unchanged on OS threads
I/O-heavy logic is explicitly offloaded using:

CompletableFuture.supplyAsync(task, virtualThreadExecutor)

Spring MVC:

Natively supports CompletableFuture return types
Suspends request processing
Releases the servlet thread immediately
Resumes when the future completes

ThreadLocal Considerations

Offloading creates a hard thread boundary.

Context such as:

SecurityContext
MDC tracing data

is not propagated automatically and must be captured and restored manually.

This boundary is explicit and controlled.

Benefits

Preserves existing assumptions (synchronized, ThreadLocal)
Avoids carrier-thread pinning in legacy code
Allows targeted use of virtual threads only where beneficial
Enables incremental migration
Clear isolation between OS-thread and virtual-thread execution

Trade-offs

Slightly more boilerplate
Requires explicit context propagation
Virtual thread usage must be consciously applied

Consequences

Positive

Improved scalability for I/O-heavy endpoints
No need to refactor existing synchronized code
Predictable runtime behavior
Clear migration path

Negative

Additional boilerplate for context propagation
Requires discipline to maintain offload boundaries

Final Verdict

The property-based virtual thread approach is suitable only for codebases that are already virtual-thread-friendly.

For this system, manual offloading is the safest and most effective strategy, delivering the benefits of virtual threads while preserving correctness and operational stability.

Pitfalls (Read Before Production)

`synchronized` pins carrier threads

Problem

Virtual thread becomes glued to the carrier
9 concurrent requests + 8 carriers → deadlock

Fix: use ReentrantLock

// Pins carrier
public synchronized Product fetch(String id) {
    return restTemplate.getForObject("/p/{id}", Product.class, id);
}

// Safe
private final ReentrantLock lock = new ReentrantLock();

public Product fetch(String id) {
    lock.lock();
    try {
        return restTemplate.getForObject("/p/{id}", Product.class, id);
    } finally {
        lock.unlock();
    }
}

ThreadLocal context loss during manual offload

What breaks

MDC
SecurityContext
RequestAttributes

Fix: capture & restore context

Map<String, String> mdc = MDC.getCopyOfContextMap();
SecurityContext sec = SecurityContextHolder.getContext();

return CompletableFuture.supplyAsync(() -> {
    if (mdc != null) MDC.setContextMap(mdc);
    SecurityContextHolder.setContext(sec);
    try {
        return service.doWork();
    } finally {
        MDC.clear();
        SecurityContextHolder.clearContext();
    }
}, ioExecutor);

💡 This issue does not exist when using virtual-threads-enabled: true globally.

ThreadLocal leaks with pooled executors

Problem

Someone replaces the executor with a fixed pool
ThreadLocals leak across requests

Fix: enforce correct executor

@Bean
public Executor ioExecutor() {
    return Executors.newVirtualThreadPerTaskExecutor();
}

Native (JNI) calls pin silently

Examples

Some JDBC drivers
Crypto libraries

Contain the damage

private static final ExecutorService NATIVE_POOL =
    Executors.newFixedThreadPool(10);

public Future<Result> callNative(String input) {
    return NATIVE_POOL.submit(() -> nativeLib.process(input));
}

Enable pin logging (dev only):

-XX:+PrintVirtualThreadPinning

MVC + WebFlux together

If both starters are present, Spring chooses MVC
No warning is shown

Rule

Virtual Threads → keep spring-boot-starter-web
Remove starter-webflux

CPU-bound work on virtual threads

Anti-pattern

Heavy computation
Image processing
Crypto loops

Correct split

// I/O work
CompletableFuture.supplyAsync(
    () -> restTemplate.getForObject(...),
    Executors.newVirtualThreadPerTaskExecutor());

// CPU work
CompletableFuture.supplyAsync(
    () -> heavyComputation(data),
    ForkJoinPool.commonPool());

Final Takeaway

Virtual Threads are the best choice for blocking, I/O-heavy Spring Boot services you cannot rewrite.

They give you scalability, simplicity, and production safety — without reactive complexity.

Concurrency and Asynchronous Programming: Introduction

AnkitDevCode — Fri, 30 Jan 2026 17:24:29 +0000

What is Parallel Programming?

Tasks run at the same time.
Progress happens simultaneously at any given instant.
Requires sufficient hardware resources (e.g., multiple CPU cores).

Example

Walking and talking:
- Both actions occur at the same time.
- At every moment, both are progressing.

What is Concurrent Programming?

Tasks make progress over time, but not at the same instant.
The system switches between tasks.
Over a time interval, all tasks move forward.

Example

Talking and drinking:
- You alternate between the two.
- At any moment, you’re doing one or the other, not both.

What “Asynchronous” Really Means?

Tasks don’t block while waiting for something (I/O, timers, network).

Key idea:

Asynchrony is about waiting efficiently.

A task starts work
It pauses when waiting
Resumes later via callbacks, promises

Common Misconception

Asynchronous ≠ no waiting
Tasks still wait for data.

The Real Question

Does the thread block while waiting?

Blocking threads = poor scalability.

Free threads = better resource utilization.

The twist: they’re not opposites

You can have:

Concurrent + synchronous (multiple threads blocking)
Single-threaded + asynchronous (Node.js style)
Concurrent + asynchronous (modern web servers)
Parallel (true simultaneous execution on multiple cores)

Parallelism = literally running at the same time

Concurrency = dealing with multiple things

Asynchrony = not blocking while waiting

Real-world analogy

Concurrency: A chef cooking 3 dishes at once

Asynchronous: Putting something in the oven and doing other prep instead of staring at it

Parallel: Multiple chefs cooking at the same time

Why threads are expensive?

Threads are considered expensive because each thread consumes significant system resources, even when it’s idle.

Main reasons:

Memory usage (stack space)
- Each thread has its own stack
- Typical stack size:
  - ~1 MB per thread (common default on 64-bit systems)
  - Can range from 256 KB to several MB, depending on OS and JVM/runtime configuration
- 1,000 threads ≈ ~1 GB of memory just for stacks
Context switching overhead
- The CPU must save and restore thread state when switching
- Frequent context switches reduce CPU efficiency
- Becomes costly at high thread counts
Scheduling overhead
- The OS scheduler must manage runnable threads
- Large numbers of threads increase scheduling complexity and latency
Synchronization costs
- Threads often require locks, mutexes, or other coordination mechanisms
- Leads to contention, deadlocks, and performance bottlenecks

Why Blocking Threads Hurt Scalability

When threads block on I/O:

They sit idle.
More threads are created to compensate.
Threads are limited by:
- CPU cores.
- Memory.

This leads to:

More machines.
More architectural complexity.
Higher costs (and environmental impact).

Evolution of Java Multithreading

Java 5 – `ExecutorService`

Introduced thread pools.
Solved:
- Uncontrolled thread creation.
New problem:
- Thread-pool–induced deadlocks.

Java 7 – Fork/Join Framework

Introduced work stealing.
Reduced pool starvation issues.
Well-suited for CPU-bound parallelism.

Java 8 – Expressive Concurrency

Introduced:

Parallel Streams
CompletableFuture

Enabled:

More declarative parallelism.
Better asynchronous composition.

Java 20 / 21 – Virtual Threads

Another major step forward.
Makes blocking cheap and scalable.
Simplifies concurrency for many workloads.

What Are Virtual Threads?

Virtual threads are a lightweight threading model introduced with Project Loom in Java.
They are managed by the JVM, not the operating system.
Designed to support massive concurrency with minimal resource usage.

Key Characteristics

Extremely lightweight compared to platform (OS) threads.
Millions of virtual threads can be created safely.
Allow developers to write simple, blocking-style code while remaining highly scalable.

The Problem Virtual Threads Aim to Solve

Traditional Java Concurrency Issues

Thread-per-request model:
- Threads block during I/O (DB, network, file).
- Blocking threads consume memory and OS resources.
- Scalability is limited by thread count.
To scale:
- More threads → more memory.
- More machines → higher cost and complexity.

Rise of Reactive Programming

Reactive frameworks (Reactor, RxJava) emerged to:
- Avoid blocking OS threads.
- Handle high concurrency using non-blocking I/O.
Downsides:
- Complex APIs.
- Harder to read, debug, and reason about.

How Virtual Threads Work?

Virtual threads are scheduled by the JVM, not the OS.
When a virtual thread blocks on I/O:
- It is unmounted from its carrier (platform) thread.
- The carrier thread is reused for other work.
- The virtual thread is remounted once I/O completes.
Result:
- Blocking no longer wastes threads.
- High scalability with familiar programming models.

Virtual Threads vs Reactive Programming

Shared Goal

Both aim to:

Maximize concurrency.
Avoid wasting threads during I/O.
Improve scalability of server-side applications.

Key Differences

Virtual Threads	Reactive Programming
Blocking code is acceptable	Requires non-blocking code
Simple, imperative style	Functional, stream-based style
Easier to read and debug	Steeper learning curve
Works with existing APIs	Requires reactive-compatible APIs

Core Argument

Virtual threads make thread-per-task scalable again.
This reduces the need for reactive frameworks in many common cases.

Benefits of Virtual Threads

Simplicity

Write synchronous, blocking code.
No need to manage callbacks or reactive pipelines.

Scalability

Blocking no longer ties up OS threads.
Supports very high concurrency with low overhead.

Compatibility

Works with existing Java libraries and APIs.
No need to rewrite large codebases.

Does Virtual Threads Kill Reactive Programming?

Short Answer: No — But It Shrinks Its Use Cases

Reactive programming still matters when:

Fine-grained event streams are required.
Backpressure control is critical.
Complex data-flow transformations are needed.

Virtual threads:

Do not automatically provide:
- Backpressure.
- Stream composition.
- Reactive operators.

Takeaways

Why Reactive Programming Existed

To avoid blocking OS threads and improve scalability.

What Changed

Virtual threads make blocking cheap and scalable.
Structured concurrency brings better control and safety.

Practical Impact

Many server-side workloads can return to:
- Simple, imperative code.
- Thread-per-request style.
Reactive programming remains relevant for specialized scenarios, but is no longer mandatory for scalability.

DEV Community: AnkitDevCode

The Idempotency Pattern: Making Retries Safe in Distributed Systems

Introduction

The Problem Statement

The "At-Least-Once" Reality

Why "Just Don't Retry" Isn't an Option

Where This Bites in Practice

The Common Problem

The Idempotency Pattern — The Solution

Core Idea

Sequence Diagram: Idempotent Payment

The Idempotency Store

Handling the "In-Flight" Race

Different Layers Where Idempotency Applies

How This Achieves Loose Coupling

How This Achieves Scaling

Trade-offs to Be Aware Of

Idempotency + Outbox: Natural Partners

Summary

The Outbox Pattern: Solving the Dual-Write Problem in Distributed Systems

Introduction

The Problem Statement

The Dual-Write Problem

Failure Scenarios

Where This Bites in Practice

The Outbox Pattern — The Solution

Core Idea

The Outbox Table

Sequence Diagram: End-to-End Flow

Two Ways to Implement the Relay

How This Achieves Loose Coupling

How This Achieves Scaling

Trade-offs to Be Aware Of

Summary

Java Thread Coordination

1. Basic Thread Coordination

Thread.start()

Thread.join()

Thread.sleep()

Thread.interrupt()

2. Memory Visibility: volatile

3. Monitor-Based Coordination (Intrinsic Locks)

synchronized

Object.wait() / notify() / notifyAll()

wait() vs sleep()

4. Explicit Lock Coordination (java.util.concurrent.locks)

ReentrantLock

When ReentrantLock is preferable

Condition — await() / signal() / signalAll()

ReadWriteLock / ReentrantReadWriteLock

StampedLock (Java 8+)

5. Atomic Variables & Compare-And-Swap (java.util.concurrent.atomic)

CAS mental model

6. Synchronization Utilities (java.util.concurrent)

CountDownLatch

Latch vs Barrier vs Phaser

CyclicBarrier

Phaser

Semaphore

7. Producer/Consumer: BlockingQueue

8. Task Coordination

ExecutorService

Executor lifecycle

Future

CompletionService

ScheduledExecutorService

CompletableFuture

CompletableFuture

9. Fork/Join Framework (java.util.concurrent)

10. Low-Level Coordination: LockSupport

11. Specialized: Exchanger

12. Thread-Confinement Tools

ThreadLocal

ScopedValue (finalized in Java 25, JEP 506)

13. Virtual Threads

13. Structured Concurrency: StructuredTaskScope

14. Supporting Concurrent Collections

15. VarHandle (Java 9+)

14. Happens-Before: The Memory Visibility Layer

Atomicity vs visibility

`Thread.start()`

`Thread.join()`

`Thread.sleep()`

`Thread.interrupt()`

2. Memory Visibility: `volatile`

`synchronized`

`Object.wait()` / `notify()` / `notifyAll()`

`wait()` vs `sleep()`

4. Explicit Lock Coordination (`java.util.concurrent.locks`)

`ReentrantLock`

When `ReentrantLock` is preferable

`Condition` — `await()` / `signal()` / `signalAll()`

`ReadWriteLock` / `ReentrantReadWriteLock`

`StampedLock` (Java 8+)

5. Atomic Variables & Compare-And-Swap (`java.util.concurrent.atomic`)

6. Synchronization Utilities (`java.util.concurrent`)

`CountDownLatch`

`CyclicBarrier`

`Phaser`

`Semaphore`

7. Producer/Consumer: `BlockingQueue`

`ExecutorService`

`Future`

`CompletionService`

`ScheduledExecutorService`

`CompletableFuture`

`CompletableFuture`

9. Fork/Join Framework (`java.util.concurrent`)

10. Low-Level Coordination: `LockSupport`

11. Specialized: `Exchanger`

`ThreadLocal`

`ScopedValue` (finalized in Java 25, JEP 506)

13. Structured Concurrency: `StructuredTaskScope`

15. `VarHandle` (Java 9+)

1. Using `sleep()` as synchronization

2. Using `if` instead of `while` around `wait()`

3. Forgetting `unlock()` on exceptional paths

4. Assuming `volatile` makes compound operations atomic

1. Shared Mutable Objects — `synchronized` / Locks

2. `volatile` Fields

7. Thread Confinement / `ThreadLocal`

Important: `volatile` is not atomic

`volatile`

`synchronized`

Java 5 — Executors and `java.util.concurrent`