Skip to content

Add structured public DataProvider exceptions#10

Open
remdui wants to merge 63 commits into
mainfrom
structured-exceptions
Open

Add structured public DataProvider exceptions#10
remdui wants to merge 63 commits into
mainfrom
structured-exceptions

Conversation

@remdui

@remdui remdui commented Jul 21, 2026

Copy link
Copy Markdown
Member

What changed

  • adds a public unchecked DataProviderException hierarchy with stable error codes
  • exposes backend type, logical connection identifier, operation name, retry advice, execution outcome, immutable diagnostics and a validated correlation ID
  • adds structured failures for configuration, registration, unavailable/disabled backends, authentication, generic operation failure, timeout, queue/subscription saturation, serialization, conflict, transactions and closed providers
  • adds strict registerDatabaseOrThrow(...) and requireRegisteredDatabase(...) methods to default and scoped APIs
  • maps MySQL, MongoDB, Redis, messaging and execution-runtime failures at public async boundaries
  • preserves transaction phase, uncertain commit outcomes and suppressed rollback/cleanup failures
  • redacts public backend causes and diagnostic data

Compatibility

  • existing nullable and optional registration methods keep their current return behavior
  • existing legacy lifecycle methods retain their previous IllegalStateException behavior after closure
  • new strict methods report closure through ProviderClosedException
  • normal caller validation failures remain standard validation exceptions rather than being mislabeled as backend outages
  • public API method signatures remain source-compatible

Final engineering review

  • unknown SQL/driver failures now use DataProviderOperationException instead of incorrectly reporting backend unavailability
  • general exception unwrapping is limited to actual async wrappers; registration-only lifecycle wrappers are handled separately
  • read timeouts are SAFE with NOT_APPLIED; write timeouts remain CONDITIONAL with MAY_HAVE_APPLIED
  • transaction setup always closes an acquired connection when initialization fails
  • transaction cleanup is explicit rather than relying on try-with-resources suppression
  • public rollback, restore and close failures remain structured and redacted
  • post-commit restore/close failures use phase CLEANUP, outcome MAY_HAVE_APPLIED, and are non-retryable
  • JVM-fatal errors remain primary and are never converted into ordinary DataProvider failures
  • validates diagnostic correlation identifiers and diagnostic metadata
  • improves CI failure diagnostics by printing and uploading Surefire and Failsafe reports without masking the original result
  • documents strict/legacy behavior, generic failures, retry safety, commit uncertainty, cleanup semantics and redaction guarantees

Validation

  • CI Lint: passed
  • complete JDK 25 unit test suite: passed
  • MySQL Testcontainers integration tests: passed
  • MongoDB Testcontainers integration tests: passed
  • Redis Testcontainers integration tests: passed
  • final validated head: 2627abb43f27e0281358d207728707a2afe2b62c

remdui added 30 commits July 21, 2026 23:12
@remdui
remdui marked this pull request as ready for review July 22, 2026 09:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant