Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

12 KiB

Raw Permalink Blame History

title, source_type, status, confidence, url, archive_url, tags, related_branches, related_projects, created, last_reviewed

title

source_type

status

confidence

url

archive_url

Spring DataAccessException hierarchy & exception translation

Layer: raw/official-docs/ — Spring Framework Reference + DataAccessException Javadoc 발췌. ca-tmpl persistence failure 분류의 공식 backbone.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-persistence-failure-baseline	ca-tmpl SQLState 9-row matrix 가 임의 분류가 아니라 Spring 의 `DataAccessException` hierarchy 위에 SQLState 를 입힌 형태라는 사실 근거
raw/branch-notes/feature-operational-error-observability-foundation	error code → retryable / non-retryable / recoverable 의 3-way classifier 가 Spring 공식 hierarchy 와 정합한다는 근거

특정 branch 없이 foundational 조사로 수집한 경우:

raw/project-notes/ca-skeleton-operational-contract — ca-tmpl persistence failure baseline + error observability 의 초기 조사

컨텍스트 / 왜 저장했는지

ca-tmpl persistence failure 분류의 공식 기준. SQLState 9-row matrix 가 임의 분류가 아니라 Spring 이 이미 채택한 hierarchy (DataAccessException 하위) 를 따른다는 근거.

출처 / Source

원본 URL: https://docs.spring.io/spring-framework/reference/data-access/dao.html
보조 URL: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/dao/DataAccessException.html (Javadoc — Direct Known Subclasses 확정)
아카이브 URL: (미수집)
저자 / 조직: Spring Team (VMware/Broadcom)
발행일: rolling (Spring Framework current)
마지막 확인일: 2026-05-27 (WebFetch 검증: dao.html landing 의 high-level translation quote + Javadoc 의 Direct Known Subclasses 확보. sql-error-codes.xml 및 상세 subclass 그룹 quote 는 본 세션 verbatim 미확보 — Javadoc 으로 보강)
보조 자료: SQLExceptionTranslator, SQLErrorCodeSQLExceptionTranslator Javadoc (별도 raw 미수집)

핵심 인용 / Key quotes (verbatim)

[Spring Framework Reference §Consistent Exception Hierarchy] "Spring provides a convenient translation from technology-specific exceptions, such as SQLException to its own exception class hierarchy, which has DataAccessException as the root exception. These exceptions wrap the original exception so that there is never any risk that you might lose any information about what might have gone wrong."

[Spring Framework Reference §Consistent Exception Hierarchy] "In addition to JDBC exceptions, Spring can also wrap JPA- and Hibernate-specific exceptions, converting them to a set of focused runtime exceptions."

[DataAccessException Javadoc — class description] "Root of the hierarchy of data access exceptions discussed in Expert One-On-One J2EE Design and Development. ... This exception hierarchy aims to let user code find and handle the kind of error encountered without knowing the details of the particular data access API in use (for example, JDBC). Thus, it is possible to react to an optimistic locking failure without knowing that JDBC is being used. As this class is a runtime exception, there is no need for user code to catch it or subclasses if any error is to be considered fatal (the usual case)."

[DataAccessException Javadoc — Direct Known Subclasses] "NonTransientDataAccessException, RecoverableDataAccessException, ScriptException (org.springframework.jdbc.datasource.init), ScriptException (org.springframework.r2dbc.connection.init), TransientDataAccessException"

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SDA-EX-C1	Spring 은 `SQLException` 같은 technology-specific exception 을 `DataAccessException` 을 root 로 하는 자체 hierarchy 로 변환하며, 원본 exception 정보를 wrap 으로 보존	[Reference §Consistent Exception Hierarchy] "Spring provides a convenient translation from technology-specific exceptions, such as `SQLException` to its own exception class hierarchy, which has `DataAccessException` as the root exception. These exceptions wrap the original exception so that there is never any risk that you might lose any information about what might have gone wrong."	`official-vendor-doc`	Spring JDBC / Spring Data JPA / Spring Data R2DBC 사용 환경	"모든 vendor exception 이 100% 손실 없이 매핑된다" 는 강한 주장은 아님 — wrap 으로 보존되지만 변환 표는 `sql-error-codes.xml` 의 한계 안에서 동작
SDA-EX-C2	`DataAccessException` 은 unchecked runtime exception 이며, user code 가 catch 할 필요가 없음 (fatal 처리 default 가정)	[Javadoc] "As this class is a runtime exception, there is no need for user code to catch it or subclasses if any error is to be considered fatal (the usual case)."	`official-reference`	DAO 호출 측 코드 일반	"절대 catch 하지 말라" 는 뜻 아님 — retry 가능한 transient 류는 의도적으로 catch 하는 것이 ca-tmpl 의 retry 정책과 정합
SDA-EX-C3	`DataAccessException` 의 Direct Known Subclasses 는 `NonTransientDataAccessException`, `RecoverableDataAccessException`, `TransientDataAccessException` (그리고 init 패키지의 `ScriptException` 2종). 즉 top-level 3-way 분류: transient / non-transient / recoverable	[Javadoc — Direct Known Subclasses] "NonTransientDataAccessException, RecoverableDataAccessException, ScriptException (org.springframework.jdbc.datasource.init), ScriptException (org.springframework.r2dbc.connection.init), TransientDataAccessException"	`official-reference`	Spring DAO hierarchy 분류 일반	각 sub-tree (`QueryTimeoutException`, `ConcurrencyFailureException` 등) 의 정확한 부모는 별도 Javadoc 확인 필요 (본 인용은 Direct Known Subclasses 만 보장)
SDA-EX-C4	Spring 은 JDBC exception 외에도 JPA / Hibernate 의 vendor-specific exception 을 별도 runtime exception 집합으로 변환	[Reference §Consistent Exception Hierarchy] "In addition to JDBC exceptions, Spring can also wrap JPA- and Hibernate-specific exceptions, converting them to a set of focused runtime exceptions."	`official-vendor-doc`	Spring Data JPA + Hibernate 사용 환경	"어떤 Hibernate exception 이 어떤 Spring exception 으로 매핑되는지" 의 정확한 표는 본 인용 범위 밖 — `HibernateJpaDialect` 별도
SDA-EX-C5	hierarchy 의 의도: user code 가 vendor (JDBC 등) 디테일을 모르고도 error kind 별로 핸들링 가능 (예: optimistic locking failure 를 JDBC 사용 여부 무관하게 처리)	[Javadoc] "This exception hierarchy aims to let user code find and handle the kind of error encountered without knowing the details of the particular data access API in use (for example, JDBC). Thus, it is possible to react to an optimistic locking failure without knowing that JDBC is being used."	`official-reference`	DAO portability / handler 분리	"모든 사용자 코드가 vendor-agnostic 해야 한다" 는 prescriptive 주장 아님 — 가능성을 의도한다는 뜻
SDA-EX-C6	`sql-error-codes.xml` 의 error code mapping 을 통해 vendor-specific SQL error 가 Spring DAO hierarchy 로 매핑된다는 메커니즘	(원본 frontmatter 발췌 — 본 세션 WebFetch 로 verbatim 직접 재확인 미완료. dao.html landing 에는 등장하지 않음, javadoc 별도 확인 필요)	`needs-confirmation`	`SQLErrorCodeSQLExceptionTranslator` 사용 환경	본 세션 verbatim 미확보 — 후속 라운드에 `SQLErrorCodeSQLExceptionTranslator` Javadoc 또는 Reference 의 JDBC 섹션에서 verbatim 재확인 필요
SDA-EX-C7	SQLState 8* (connection 계열) / 40001 (serialization) / 40P01 (deadlock) / 23* (integrity) / 23505 (unique violation) 와 Spring exception class 간의 구체적 매핑 (`DataAccessResourceFailureException`, `ConcurrencyFailureException` 계열, `DataIntegrityViolationException`, `DuplicateKeyException`)	(원본 frontmatter 발췌 — 본 세션 dao.html landing 에 등장하지 않음. `sql-error-codes.xml` source 또는 vendor-specific Javadoc 별도 확인 필요)	`needs-confirmation`	PostgreSQL / vendor 환경에서의 ca-tmpl SQLState matrix 정당성	본 세션 verbatim 미확보 — ca-tmpl 9-row matrix 의 SQLState ↔ Spring class 매핑은 후속 라운드에 vendor 별 `sql-error-codes.xml` 로 직접 검증 필요

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- SDA-EX-C1 ~ C5: Spring 의 DataAccessException hierarchy 가 존재하며 vendor exception 을 변환한다는 사실, hierarchy 가 unchecked 이며 portability 를 의도한다는 사실, top-level 3-way 분류 (Transient / NonTransient / Recoverable) 의 존재
이 자료가 증명하지 않는 것:
- sql-error-codes.xml 의 정확한 매핑 표 (SDA-EX-C6 — needs-confirmation)
- 특정 SQLState (8*, 23*, 40001, 23505 등) 가 어떤 Spring exception 으로 매핑되는지의 vendor-별 표 (SDA-EX-C7 — needs-confirmation). ca-tmpl 9-row matrix 의 vendor 정당성은 별도 검증 필요
- 각 sub-tree (QueryTimeoutException, OptimisticLockingFailureException 등) 의 직접 부모가 TransientDataAccessException 인지 RecoverableDataAccessException 인지의 정확한 위계 — Javadoc 별도 확인 필요
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 9-row matrix 의 SQLState → ca-tmpl code 매핑이 Spring 공식 sql-error-codes.xml 의 PostgreSQL/MySQL section 과 일치하는지 코드 검증
- DB_UNIQUE_VIOLATION 을 별도 code 로 가져가는 결정이 DuplicateKeyException 의 위계 (구체 부모는 DataIntegrityViolationException) 와 정합한지 javadoc 확인
- JPA / Hibernate exception 매핑이 ca-tmpl 의 retryable 분류와 충돌하지 않는지 별도 검증

메모 / Notes (내 프로젝트 해석 — 검증 전 추론)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

핵심 의미 (해석):
- TransientDataAccessException = retry 로 회복 가능 → ca-tmpl retryable=true 후보
- NonTransientDataAccessException = retry 무의미 → ca-tmpl retryable=false 후보
- RecoverableDataAccessException = 환경 정상화 후 재시도 가능 (커넥션 재획득 등)
SQLState 매핑 (해석 — SDA-EX-C7 의 needs-confirmation 영역):
- SQLState 8* 는 connection 계열 → DataAccessResourceFailureException 으로 매핑된다는 통설. ca-tmpl DB_UNAVAILABLE 매핑과 일치한다는 가정
- SQLState 40001(serialization), 40P01(deadlock) → ConcurrencyFailureException 계열. ca-tmpl DB_SERIALIZATION_FAILURE, DB_DEADLOCK 와 일치한다는 가정
- SQLState 23* → DataIntegrityViolationException. ca-tmpl DATA_INTEGRITY family 가정
- 23505 unique violation 은 DuplicateKeyException 으로 더 specific 함 → ca-tmpl 이 별도 code DB_UNIQUE_VIOLATION 로 가져가는 근거
시사점: ca-tmpl 9-row matrix 는 자의적 분류가 아니라 Spring DAO hierarchy 의 3-way 분류 (SDA-EX-C3) 에 SQLState 를 입힌 형태. canonical 로 승급 시 인용 가능 — 단 vendor 매핑은 sql-error-codes.xml 로 보강 필요.

같은 주제 다른 official-doc / company-tech-blog:
- raw/official-docs/persistence-r2dbc-reactive-spring (R2DBC 도 동일 DataAccessException hierarchy 재사용)
- raw/official-docs/persistence-osiv-antipattern-hibernate-vladmihalcea (JPA / Hibernate exception 변환 컨텍스트)
인용하는 branch:
- raw/branch-notes/feature-persistence-failure-baseline
- raw/branch-notes/feature-operational-error-observability-foundation
인용하는 wiki: (미작성)
대안 그룹 (ca-tmpl 결정 컨텍스트): Group G-C — Persistence failure (대안: Spring DAO hierarchy [ca-tmpl 채택] / R2DBC reactive / JOOQ SQL-first / 직접 JDBC + 자체 classifier / DB-specific vendor classification)

12 KiB Raw Permalink Blame History