Distributed Locking

RFC-44 compliant distributed locking patterns for Java services.

When to use this skill

• Implementing distributed locking for scheduled jobs

• Migrating from legacy locking mechanisms

• Choosing between PostgreSQL and Redis locking

• Migrating from Fabric8 leader election

• Migrating from incubated in-repo libraries

• When asked to "migrate locks to be RFC-44 compliant"

Skill Contents

Sections

• When to use this skill

• Quick Start

• Implementation Options

• Common Patterns

• References

• Related Rules

• Related Skills

Available Resources

📚 references/ - Detailed documentation

• lock patterns

• migration workflow

• redis integration

• troubleshooting

Quick Start

1. Add Dependencies (PostgreSQL)

gradle/libs.versions.toml

[versions] distributed-locking-api = "2.0.0" distributed-locking-postgres-jooq = "2.0.0"

[libraries] distributed-locking-api = { module = "com.bitso.commons:distributed-locking-api", version.ref = "distributed-locking-api" } distributed-locking-postgres-jooq = { module = "com.bitso.commons:distributed-locking-postgres-jooq", version.ref = "distributed-locking-postgres-jooq" }

2. Create Configuration Bean

@Configuration public class DistributedLockConfiguration { @Bean DistributedLockManager<Long> distributedLockManager( @Qualifier("write-dslcontext") DSLContext dslContext) { return new JooqPostgresSessionDistributedLockManager(dslContext); } }

3. Use in Scheduled Jobs

@Scheduled(cron = "${job.cron:-}", zone = "UTC") public void scheduledJob() { try (var lock = distributedLockManager.tryLock("job-lock")) { if (!lock.acquired()) { log.info("Job already running on another instance"); return; } doWork(); } }

Implementation Options

RFC-44 supports two valid locking implementations:

Implementation When to Use

PostgreSQL Advisory Locks (Default) Services with PostgreSQL available

Redis Locking (Allowed) Services without PostgreSQL, or with justified Redis use case

Important: Redis-based locking is NOT deprecated. It is explicitly supported per RFC-44.

Common Patterns

Try-with-resources Pattern

try (var lock = distributedLockManager.tryLock("lock-key")) { if (!lock.acquired()) { return; } executeTask(); }

Vavr Pattern

Try.withResources(() -> distributedLockManager.tryLock("lock-key")) .of(lock -> Option.of(lock) .filter(DistributedLock::acquired) .onEmpty(() -> log.info("Lock not acquired")) .peek(l -> doWork()));

References

Reference Description

references/migration-workflow.md Step-by-step migration guide

references/lock-patterns.md RFC-44 lock patterns

references/redis-integration.md Redis-based locking setup

references/troubleshooting.md Common issues and solutions

Related Rules

• .cursor/rules/java-distributed-locking-rfc44.mdc
• Full RFC-44 reference

Related Skills

Skill Purpose

gradle-standards Dependency configuration

java-testing Testing lock mechanisms