Implementing Distributed Locking with Java Spring Boot and Redis for Data Integrity

Introduction

In a single-JVM application, synchronized or a ReentrantLock is enough. Run two replicas behind a load balancer and those locks protect nothing — each JVM has its own. Distributed locking coordinates mutual exclusion across processes, machines and regions.

The most common implementation: Redis + Redisson.

What distributed locking solves

• Race conditions — two replicas processing the same message simultaneously.
• Duplicate processing — a retried webhook charging the customer twice.
• Resource contention — only one node should run the nightly export.
• Idempotency — guarantee an operation runs at most once per key.

A concrete race condition

@PostMapping("/orders/{id}/refund")
public void refund(@PathVariable String id) {
  Order o = orders.findById(id);
  if (o.getStatus() == REFUNDED) return;
  paymentGateway.refund(o);          // ← if two requests get here simultaneously
  o.setStatus(REFUNDED);              //   the customer is refunded twice
  orders.save(o);
}

The "check then act" between line 3 and line 4 is the race.

Step 1 — Add Redisson

<dependency>
  <groupId>org.redisson</groupId>
  <artifactId>redisson-spring-boot-starter</artifactId>
  <version>3.32.0</version>
</dependency>

spring:
  redis:
    host: redis
    port: 6379
redisson:
  single-server-config:
    address: redis://redis:6379

Step 2 — Lock the critical section

```java
@Service
public class RefundService {
  private final RedissonClient redisson;
  private final OrderRepository orders;
  private final PaymentGateway gateway;

public RefundService(RedissonClient r, OrderRepository o, PaymentGateway g) { this.redisson = r; this.orders = o; this.gateway = g; }

public void refund(String orderId) { RLock lock = redisson.getLock("order:" + orderId + ":refund"); boolean acquired = false; try { // wait up to 2s, hold for at most 10s acquired = lock.tryLock(2, 10, TimeUnit.SECONDS); if (!acquired) throw new ConcurrentOperationException("refund already in progress");

Order o = orders.findById(orderId).orElseThrow(); if (o.getStatus() == OrderStatus.REFUNDED) return; gateway.refund(o); o.setStatus(OrderStatus.REFUNDED); orders.save(o); } catch (InterruptedException e) { Thread.currentThread().interrupt(); throw new RuntimeException(e); } finally { if (acquired && lock.isHeldByCurrentThread()) lock.unlock(); } } } ```

Three things are non-negotiable:

1. Bounded wait time — never call lock() without a timeout, or you'll exhaust threads. 2. Lease time — Redis auto-expires the lock if the JVM crashes mid-section. 3. Release in finally + check ownership — never release a lock you don't own.

Step 3 — How Redis distributed locks actually work

Redisson's lock is a Lua script around SET key value NX PX <ttl>:

SET order:42:refund <uuid> NX PX 10000

• NX — only set if not exists (atomic acquisition).
• PX 10000 — auto-expire after 10s (dead-holder safety).
• value = client UUID — release script checks ownership before deleting.

The watchdog thread renews the TTL while the JVM is alive, so a healthy holder never loses the lock.

Step 4 — Sequence diagram

client A ──► refund(42) ──► SET NX (OK)        ──► gateway.refund ──► UNLOCK
client B ──► refund(42) ──► SET NX (FAIL, wait)
                                  └─► retry ──► SET NX (FAIL, status=REFUNDED) ──► return

Step 5 — Idempotency keys (a better default for HTTP)

For external-facing endpoints, prefer idempotency keys stored as a Redis SETNX with TTL:

String key = "idemp:" + request.getHeader("Idempotency-Key");
Boolean first = redis.opsForValue().setIfAbsent(key, "in-progress", Duration.ofHours(24));
if (Boolean.FALSE.equals(first)) return cachedResponse(key);

Stripe and most payment APIs work this way. Combine with a distributed lock when the *processing* of the key needs mutual exclusion.

Step 6 — Docker Compose for local Redis

services:
  redis:
    image: redis:7
    ports: ["6379:6379"]
    command: ["redis-server","--appendonly","yes"]
  app:
    build: .
    environment: [SPRING_REDIS_HOST=redis]
    depends_on: [redis]

Real-world examples

• Payments — preventing duplicate captures or refunds.
• Banking transfers — locking both accounts in a deterministic order to avoid deadlock.
• Inventory — decrementing stock for a hot product during a flash sale.
• Scheduled jobs — only one replica should run the 02:00 export.
• Cache regeneration — single-flight rebuilds of an expensive cache key.

Production best practices

• Always set a lease time. A lock without TTL is a future outage.
• Keep critical sections short. Network calls inside a lock multiply contention; pre-compute, then lock only the mutation.
• Use logical, stable keys — order:<id>:refund, not random UUIDs.
• Monitor lock wait/hold times. Surface them as Micrometer metrics.
• Use Redisson's RedLock across multiple independent Redis nodes only if you need correctness against full-node failure — it's stricter and slower than the single-node lock.

Common pitfalls and anti-patterns

• Holding a lock across HTTP calls to a slow external API — one slow call can block every replica.
• Using SETNX without TTL — JVM crash leaves a permanent lock.
• Locking with @Transactional that commits *after* unlock — another node sees stale data. Acquire → load → mutate → commit → unlock, in that order.
• Assuming Redis fail-over preserves locks — async replication can lose the lock during a failover window. Combine with idempotency for safety.

Related tutorials

• Multi-Region Load Balancing with Ribbon and Eureka
• Spring Boot Microservices Architecture Explained
• Scaling Java Microservices on AWS EKS