89 lines
8.8 KiB
Markdown
89 lines
8.8 KiB
Markdown
---
|
|
title: "Spring Integration LockRegistry / JdbcLockRegistry 공식 레퍼런스"
|
|
source_type: official-doc
|
|
url: https://docs.spring.io/spring-integration/reference/distributed-locks.html
|
|
archive_url:
|
|
related_branches: [feature-distributed-lock-contract]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
tags: [official-doc, ca-distributed-lock, spring-integration, lock-registry, jdbc, distributed-lock]
|
|
created: 2026-06-12
|
|
---
|
|
|
|
# Spring Integration LockRegistry / JdbcLockRegistry 공식 레퍼런스
|
|
|
|
> Layer: `raw/` — 외부 자료(공식 문서)의 **원문 발췌·출처 기록**.
|
|
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 별도 작성. 원본은 raw에 영구 보관.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-distributed-lock-contract]] | ca-tmpl `distributedLockPort` 추상화의 reference 구현 후보로서 Spring Integration `LockRegistry`/`JdbcLockRegistry` 평가 — `java.util.concurrent.locks.Lock` 호환 추상화 + JDBC/Redis/Zookeeper provider 교체 가능성이 "port 추상화 + provider 교체" 결정의 근거. |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.spring.io/spring-integration/reference/distributed-locks.html
|
|
- 보조 URL (JDBC 상세): https://docs.spring.io/spring-integration/reference/jdbc/lock-registry.html
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: Spring Team (VMware / Broadcom)
|
|
- 발행일: Spring Integration 7.1.0 기준
|
|
- 마지막 확인일: 2026-06-12
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
ca-tmpl 의 `distributedLockPort` 추상화를 설계할 때, `java.util.concurrent.locks.Lock` 을 반환하는 `LockRegistry.obtain(key)` 가 표준 Java concurrency 인터페이스와 호환됨을 확인하고, JDBC / Redis / Zookeeper / DynamoDB 네 가지 provider 를 동일 추상화로 교체할 수 있음을 공식 문서로 뒷받침하기 위해 보관.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim, 5문장)
|
|
|
|
> [§Distributed Locks — Core Concept] "The `obtain(Object)` method returns a `java.util.concurrent.locks.Lock` instance, enabling standard Java concurrency patterns."
|
|
|
|
> [§Distributed Locks — LockRegistry Implementations] "Spring Integration provides `LockRegistry` implementations for: 1. **JDBC** - `JdbcLockRegistry` 2. **Redis** - `RedisLockRegistry` 3. **Zookeeper** - Zookeeper-based registry 4. **Spring Cloud AWS** - `DynamoDbLockRegistry`"
|
|
|
|
> [§JDBC Lock Registry — Overview] "The **JDBC Lock Registry** (`JdbcLockRegistry`) provides distributed locking across multiple application instances using a database backend. Introduced in version 4.3, it enables components like aggregators and resequencers to coordinate access to message groups across a cluster."
|
|
|
|
> [§JDBC Lock Registry — Advanced Features — Lock Renewal] "**Important:** Lock renewal can only be performed if the current thread holds the lock."
|
|
|
|
> [§JDBC Lock Registry — Advanced Features — Lock Release & Ownership (v6.4+)] "`JdbcLockRegistry.JdbcLock.unlock()` - Throws `ConcurrentModificationException` if lock ownership has expired"
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| SI-LOCK-C1 | `LockRegistry.obtain(key)` 는 표준 `java.util.concurrent.locks.Lock` 인스턴스를 반환한다 — Java 표준 concurrency 패턴 직접 사용 가능 | [§Core Concept] "The `obtain(Object)` method returns a `java.util.concurrent.locks.Lock` instance, enabling standard Java concurrency patterns." | `official-vendor-doc` | Spring Integration `LockRegistry` 추상화를 사용하는 모든 provider(JDBC/Redis/Zookeeper/DynamoDB) | provider 별 Lock 구현 내부 동작(재진입 여부, 공정성 등)이 동일함을 의미하지 않음 |
|
|
| SI-LOCK-C2 | Spring Integration 은 JDBC, Redis, Zookeeper, DynamoDB 네 가지 `LockRegistry` 구현체를 공식 제공한다 | [§LockRegistry Implementations] "Spring Integration provides `LockRegistry` implementations for: 1. JDBC - `JdbcLockRegistry` 2. Redis - `RedisLockRegistry` 3. Zookeeper - Zookeeper-based registry 4. Spring Cloud AWS - `DynamoDbLockRegistry`" | `official-vendor-doc` | Spring Integration 7.1.0 기준 | 모든 구현체가 동일한 TTL·재진입·갱신 시맨틱을 지원함을 의미하지 않음 |
|
|
| SI-LOCK-C3 | `JdbcLockRegistry` 는 v4.3 에 도입된 DB 기반 분산 락 구현이며, `aggregator`·`resequencer` 같은 메시지 그룹 컴포넌트가 클러스터에서 단 하나의 인스턴스만 조작하도록 보장한다 | [§JDBC Lock Registry — Overview] "The JDBC Lock Registry (`JdbcLockRegistry`) provides distributed locking across multiple application instances using a database backend. Introduced in version 4.3, it enables components like aggregators and resequencers to coordinate access to message groups across a cluster." | `official-vendor-doc` | Spring Integration + JDBC 기반 분산 환경 | ca-tmpl 의 특정 도메인 usecase 에 동일하게 적합함을 의미하지 않음 — 도메인 적합성은 별도 검증 필요 |
|
|
| SI-LOCK-C4 | lock renewal 은 **현재 스레드가 해당 lock 을 보유하고 있을 때만** 수행할 수 있다 | [§Lock Renewal] "Lock renewal can only be performed if the current thread holds the lock." | `official-vendor-doc` | `RenewableLockRegistry.renewLock()` 사용 시 | 재진입(reentrancy)이 지원되는지 여부 — 재진입 보장은 본 인용으로 도출되지 않음 |
|
|
| SI-LOCK-C5 | lock 소유권이 만료된 상태에서 `JdbcLockRegistry.JdbcLock.unlock()` 을 호출하면 `ConcurrentModificationException` 이 발생한다 | [§Lock Release & Ownership] "`JdbcLockRegistry.JdbcLock.unlock()` - Throws `ConcurrentModificationException` if lock ownership has expired" | `official-vendor-doc` | `JdbcLockRegistry` 를 TTL 과 함께 사용하는 시나리오 (v6.4+) | Redis / Zookeeper provider 에서 동일한 예외가 발생함을 보장하지 않음 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `SI-LOCK-C1`: `LockRegistry` 추상화가 `java.util.concurrent.locks.Lock` 을 반환하므로, port 인터페이스에서 `Lock` 을 그대로 노출하거나 래핑할 수 있음
|
|
- `SI-LOCK-C2`: JDBC/Redis/Zookeeper/DynamoDB 네 가지 공식 provider 가 존재하므로, `LockRegistry` 인터페이스를 port 로 추상화하면 provider 교체가 가능함
|
|
- `SI-LOCK-C3`: `JdbcLockRegistry` 가 클러스터 환경에서의 배타적 접근을 보장함을 공식 문서가 명시
|
|
- `SI-LOCK-C4`: TTL 초과 가능성이 있는 장시간 locked 작업에는 반드시 `renewLock()` 을 호출해야 하며, 반드시 동일 스레드에서 호출해야 함
|
|
- `SI-LOCK-C5`: TTL 만료 후 unlock 시 예외가 발생하므로, ca-tmpl port 구현에서 이 예외를 도메인 예외로 변환하는 처리가 필요함
|
|
|
|
- 이 자료가 증명하지 않는 것:
|
|
- `JdbcLockRegistry` 가 ca-tmpl 의 특정 도메인 lock 요구사항(예: 특정 entity ID 기반 lock key 전략)에 적합한지
|
|
- provider 간 (JDBC vs Redis) 성능·가용성 트레이드오프
|
|
- `JdbcLockRegistry` 가 재진입(reentrant) 락을 지원하는지 여부 — 본 문서에 명시 없음
|
|
- Spring Boot auto-configuration 없이 수동으로 `DefaultLockRepository`·`JdbcLockRegistry` bean 을 구성하는 방법의 세부 사항
|
|
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- ca-tmpl `distributedLockPort` 인터페이스가 `Lock` 을 직접 반환할지, 아니면 `executeLocked()` 패턴만 노출할지 — port 설계는 이 문서에서 도출 불가
|
|
- `INT_LOCK` 테이블 DDL 을 ca-tmpl 의 Flyway/Liquibase 마이그레이션에 포함하는 방법
|
|
- TTL 기본값(`DefaultLockRepository.timeToLive`)의 적정 설정값 — ca-tmpl 도메인 SLA 기반 결정 필요
|
|
|
|
## 메모 / Notes
|
|
|
|
- `executeLocked()` API (v6.2+): `LockRegistry.executeLocked("key", () -> ...)` 형태로 lock 획득 → 작업 → 해제를 한 번에 처리. port 구현에서 이 패턴을 채택하면 lock/unlock 분리 오용을 방지할 수 있음 — 단, 미검증 설계 의견이므로 branch-note 결정에서 별도 평가 필요.
|
|
- `DefaultLockRepository.idleBetweenTries` 기본값 100ms (v5.1.8+): lock 경쟁 시 재시도 대기 시간. 고빈도 lock 경쟁 환경에서는 조정 필요.
|
|
- v7.0+ 부터 `DistributedLock` 인터페이스가 별도로 존재하며, `lock(Duration ttl)` / `tryLock(long, TimeUnit, Duration ttl)` 처럼 per-acquire TTL 지정 가능 — `JdbcLock` 과 `RedisLock` 이 구현.
|
|
- 추가로 봐야 할 동일 출처 페이지: `https://docs.spring.io/spring-integration/reference/redis.html` (RedisLockRegistry 상세)
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc: [[raw/official-docs/cache-redisson-rlock-vs-setnx]] (Redis 기반 분산 락 비교)
|
|
- 이 자료를 인용한 wiki 요약: (생성 전)
|