Dynamic Business Error Handling Framework¶
Target Platform: Spring Boot 4.1.2 | Java 25 | Jakarta EE 11 | Oracle Database 23ai
Package: com.dw.ngms.cis.framework.error
Git Branch: feat/error-framework
Author: Prateek Goel
1. Executive Summary & Design Goals¶
The CIS Error Handling Framework is an enterprise-grade, database-driven error resolution and translation engine for the Cadastral Information System. It replaces legacy ad-hoc runtime exceptions and hardcoded Java enums with a 100% dynamic, multi-channel architecture.
Key Capabilities¶
- 100% Dynamic Catalog (Zero Hardcoded Enums): Error codes are semantic uppercase strings (
RESERVATION_EXPIRED,LODGEMENT_DOCUMENT_MISSING,SUBDIVISION_EXCEEDS_EXTENT). No code recompilation or redeployment is required when adding or modifying error definitions. - Dual-Channel Delivery (
uivsapi): The engine inspectsX-Client-Channel. Web clients receive actionable, user-friendly toast messages; automated consumers and API integrations receive detailed technical diagnostics. - High Performance In-Memory Caching: Preloads all error definitions on startup into concurrent memory structures. Lookups execute in \(O(1)\) time with zero database queries during request execution.
- Zero-Downtime Hot Reloading: Administrators can trigger
POST /api/v1/system/errors/refreshto re-synchronize memory structures immediately from Oracle without server restart. - Deep Recursive Redaction: Automatically sanitizes sensitive keys (
password,token,secret,authorization,pin,ssn) and regex patterns in messages and nested payloads. - Spring Boot 4 Native: Standardized on RFC 9457
ProblemDetailwith correlationtraceIdand nativeNoResourceFoundExceptionrouting.
2. Dedicated Architectural Diagrams¶
2.1 Component & Boundary Diagram (Clean / Hexagonal Architecture)¶
flowchart TD
subgraph Clients [Client Layer]
ANGULAR["Angular Frontend (cis-internal)"]
EXTERNAL["BFF & External Microservices"]
end
subgraph SpringBoot4_Infrastructure [Spring Boot 4.1.2 MVC & Security Core]
DISPATCH["Spring DispatcherServlet"]
ROUTING["MvcRoutingExceptionAdvice (Order -1)\n[404 Route Not Found, 405 Method Not Allowed, 415 Media Mismatch]"]
SEC["Spring Security Filter Chain\n[401 AuthenticationEntryPoint, 403 AccessDeniedHandler]"]
end
subgraph Business_Domain [CIS Business Domain Services]
LODGE["LodgementService"]
RES["ReservationService"]
MAINT["MaintenanceService"]
EXAM["ExaminationService"]
ARCH["ArchiveService"]
INFO["InfoRequestService"]
end
subgraph Self_Contained_Framework [Module Root: com.dw.ngms.cis.framework.error]
direction TB
subgraph Boundary_Adapter [Public Boundary & API Adapter]
EXC["BusinessException\n(errorKey, args, details)"]
ADVICE["ExceptionHandlerAdvice\n(@RestControllerAdvice)"]
CTRL["ErrorCodeController\n(/api/v1/system/errors & /refresh)"]
end
subgraph Core_Engine [Domain Resolution Engine]
REG["ErrorCodeRegistry\n(In-Memory O(1) Concurrent Cache)"]
SVC["ErrorMessageService\n(Multi-Channel Resolver)"]
GRP["GroupResolutionService\n(Regex Pattern Exception Hierarchy)"]
RENDER["TemplateRenderer\n(Mustache & Positional {0} Engine)"]
REDACT["RedactionService\n(PII & Secret Sanitizer)"]
end
subgraph Data_Access [Persistence Layer]
E_CODE["ErrorCode Entity"]
E_MSG["ErrorMessage Entity"]
E_GRP["ErrorGroup Entity"]
E_MAP["ErrorGroupMapping Entity"]
E_HIST["ErrorMessageHistory Entity"]
REPOS["Spring Data JPA Repositories"]
end
end
subgraph Oracle_DB [Oracle Database: SGUSER Schema]
T_CODES[("ERROR_CODES\n(Catalog)")]
T_MSGS[("ERROR_MESSAGES\n(Templates)")]
T_GROUPS[("ERROR_GROUPS\n(Regex Patterns)")]
T_MAPS[("ERROR_GROUP_MAPPINGS\n(Channel Mappings)")]
T_HIST[("ERROR_MESSAGE_HISTORY\n(Audit Trail)")]
end
%% Wiring
ANGULAR & EXTERNAL --> DISPATCH
DISPATCH --> ROUTING
DISPATCH --> SEC
DISPATCH --> Business_Domain
Business_Domain -->|throws| EXC
EXC --> ADVICE
DISPATCH -->|Spring MVC & Unhandled Exceptions| ADVICE
CTRL --> REG
ADVICE --> SVC
SVC --> REG
SVC --> GRP
SVC --> RENDER
SVC --> REDACT
REG --> REPOS
GRP --> REPOS
REPOS --> E_CODE & E_MSG & E_GRP & E_MAP & E_HIST
E_CODE & E_MSG & E_GRP & E_MAP & E_HIST --> Oracle_DB
ADVICE -->|HTTP 400, 402, 404, 409, 422, 500| ANGULAR & EXTERNAL
2.2 Database Schema Relation ER Diagram (ERD)¶
erDiagram
ERROR_CODES ||--o{ ERROR_MESSAGES : "has templates"
ERROR_CODES ||--o{ ERROR_GROUP_MAPPINGS : "referenced by code"
ERROR_GROUPS ||--|{ ERROR_GROUP_MAPPINGS : "contains mappings"
ERROR_MESSAGES ||--o{ ERROR_MESSAGE_HISTORY : "tracks revisions"
ERROR_CODES {
VARCHAR2(50) CODE PK "Semantic error key (e.g. RESERVATION_EXPIRED)"
VARCHAR2(20) SEVERITY "INFO, WARN, ERROR, CRITICAL"
NUMBER DEFAULT_HTTP_STATUS "400, 402, 404, 409, 422, 500"
VARCHAR2(1000) DEFAULT_MESSAGE "Fallback message template"
CHAR(1) ACTIVE "'Y' or 'N'"
VARCHAR2(1000) DESCRIPTION "Technical failure condition"
VARCHAR2(100) CATEGORY "Functional domain module"
VARCHAR2(100) DOC_URL "Documentation wiki reference"
VARCHAR2(100) CREATED_BY "Author or system user"
TIMESTAMP CREATED_AT "Creation timestamp"
TIMESTAMP UPDATED_AT "Last modification timestamp"
}
ERROR_MESSAGES {
NUMBER ID PK "Synthetic primary key"
VARCHAR2(50) CODE FK "Foreign key to ERROR_CODES(CODE)"
VARCHAR2(10) LOCALE "Language code: 'en', 'af', etc."
VARCHAR2(50) CHANNEL "Delivery target: 'ui' or 'api'"
VARCHAR2(512) EXCEPTION_CLASS "Optional explicit class binding"
VARCHAR2(1000) EXCEPTION_PATTERN "Optional regex match on exception message"
VARCHAR2(2000) MESSAGE_TEMPLATE "Parameterized template: 'Reservation #{0} expired on {1}.'"
NUMBER HTTP_STATUS_OVERRIDE "Optional HTTP status override"
NUMBER PRIORITY "Evaluation priority (lowest number first)"
CHAR(1) ACTIVE "'Y' or 'N'"
NUMBER EXPOSE_STACK_TRACE "0 = suppressed, 1 = exposed"
TIMESTAMP EFFECTIVE_FROM "Optional scheduling start"
TIMESTAMP EFFECTIVE_TO "Optional scheduling expiry"
}
ERROR_GROUPS {
NUMBER ID PK "Synthetic primary key"
VARCHAR2(100) NAME UK "Unique group name (e.g. DataAccessGroup)"
VARCHAR2(1000) PATTERN "Regex match on class name (e.g. .*DataAccessException)"
VARCHAR2(500) DESCRIPTION "Group description"
NUMBER ACTIVE "1 = active, 0 = inactive"
}
ERROR_GROUP_MAPPINGS {
NUMBER ID PK "Synthetic primary key"
NUMBER GROUP_ID FK "Foreign key to ERROR_GROUPS(ID)"
VARCHAR2(50) CODE "Target error code"
VARCHAR2(10) LOCALE "Target language"
VARCHAR2(50) CHANNEL "Channel: 'ui' or 'api'"
VARCHAR2(1000) MESSAGE_TEMPLATE "Channel-specific template"
NUMBER PRIORITY "Evaluation order"
NUMBER ACTIVE "1 = active, 0 = inactive"
NUMBER EXPOSE_STACKTRACE "0 = suppressed, 1 = exposed"
}
ERROR_MESSAGE_HISTORY {
NUMBER HISTORY_ID PK "Audit record primary key"
NUMBER MESSAGE_ID "Reference to modified ERROR_MESSAGES(ID)"
VARCHAR2(50) CODE "Error code"
VARCHAR2(20) ACTION "'INSERT', 'UPDATE', 'DELETE'"
CLOB PAYLOAD "JSON snapshot of previous state"
VARCHAR2(100) PERFORMED_BY "User who executed mutation"
TIMESTAMP PERFORMED_AT "Audit timestamp"
}
2.3 Runtime Exception Resolution Sequence Diagram¶
sequenceDiagram
autonumber
actor User as Angular Client
participant Controller as REST Resource
participant Service as Business Service
participant Advice as ExceptionHandlerAdvice
participant MsgSvc as ErrorMessageService
participant Registry as ErrorCodeRegistry
participant GroupSvc as GroupResolutionService
participant Renderer as TemplateRenderer
participant Redact as RedactionService
User->>Controller: POST /api/v1/lodgement/draft/submit
Controller->>Service: submitLodgement(draftId)
Note over Service: Domain Rule Violation: Mandatory document missing
Service-->>Advice: throw new BusinessException("LODGEMENT_DOCUMENT_MISSING", "General Plan", "1049")
Advice->>MsgSvc: resolveErrorByCode("LODGEMENT_DOCUMENT_MISSING", locale="en", channel="ui", args)
MsgSvc->>Registry: findCode("LODGEMENT_DOCUMENT_MISSING")
Registry-->>MsgSvc: ErrorCode (HTTP 400, Severity WARN, Category LODGEMENT)
MsgSvc->>Registry: findMessage("LODGEMENT_DOCUMENT_MISSING", locale="en", channel="ui")
Registry-->>MsgSvc: ErrorMessage (template="Mandatory document '{0}' is missing for lodgement #{1}.")
MsgSvc->>Renderer: render(template, args=["General Plan", "1049"])
Renderer-->>MsgSvc: "Mandatory document 'General Plan' is missing for lodgement #1049."
MsgSvc->>Redact: sanitize(renderedMessage, contextDetails)
Redact-->>MsgSvc: Sanitized message and metadata
MsgSvc-->>Advice: ResolvedError(code="LODGEMENT_DOCUMENT_MISSING", httpStatus=400, message=...)
Advice-->>User: HTTP 400 Bad Request + ResponseResult JSON
2.4 Dual-Channel Message & Payload Flow Diagram¶
flowchart LR
EXC["Exception Occurs<br/>(e.g. DataAccessException during SQL timeout)"] --> ROUTE{"Channel Header<br/>X-Client-Channel"}
ROUTE -->|"Channel UI: Browser Toast"| UI_PATH["Match Group: DataAccessGroup<br/>Template: DB_ERROR_UI"]
ROUTE -->|"Channel API: Server Integration"| API_PATH["Match Group: DataAccessGroup<br/>Template: DB_ERROR"]
UI_PATH --> UI_RES["HTTP 500<br/>Code: DB_ERROR_UI<br/>Message: Something went wrong with database<br/>TraceId: a1b2-c3d4"]
API_PATH --> API_RES["HTTP 500<br/>Code: DB_ERROR<br/>Message: Database query error ORA-01013<br/>TraceId: a1b2-c3d4<br/>Exception: QueryTimeoutException"]
UI_RES --> ANGULAR["Angular App (cis-internal)<br/>Displays Toast Notification"]
API_RES --> LOGS["Splunk / CloudWatch / BFF<br/>Full Technical Diagnostics"]
2.5 Class Hierarchy & Component Structural Diagram¶
classDiagram
direction TB
class RuntimeException {
<<Java Core>>
}
class BusinessException {
-String errorCode
-Object[] args
-Map~String, Object~ details
-Integer explicitStatus
+getErrorCode() String
+getArgs() Object[]
+getDetails() Map
+getExplicitStatus() Integer
}
class ConsistencyCheckException {
<<Domain Specific>>
}
class ErrorCode {
<<JPA Entity>>
-String code
-String severity
-Integer defaultHttpStatus
-String defaultMessage
-String active
-String category
-String docUrl
}
class ErrorMessage {
<<JPA Entity>>
-Long id
-String code
-String locale
-String channel
-String exceptionClass
-String exceptionPattern
-String messageTemplate
-Integer httpStatusOverride
-Integer priority
-Integer exposeStackTrace
}
class ErrorGroup {
<<JPA Entity>>
-Long id
-String name
-String pattern
-String description
-Integer active
}
class ErrorGroupMapping {
<<JPA Entity>>
-Long id
-ErrorGroup group
-String code
-String locale
-String channel
-String messageTemplate
-Integer priority
-Integer active
-Integer exposeStackTrace
}
class ErrorCodeRegistry {
<<In-Memory Cache>>
-Map~String, ErrorCode~ codesByCode
-List~ErrorMessage~ cachedMessages
-List~ErrorGroup~ cachedGroups
-List~ErrorGroupMapping~ cachedMappings
+refresh() void
+findCode(code) Optional~ErrorCode~
+isValid(code) boolean
+getDefaultStatus(code) Integer
+resolveDocUrl(code) String
}
class ErrorMessageService {
<<Resolution Engine>>
-ErrorCodeRegistry registry
-GroupResolutionService groupService
-RedactionService redactionService
+resolveErrorByCode(code, locale, channel, args) ResolvedError
+resolveError(exceptionClass, locale, channel, throwable, extraContext) ResolvedError
}
class GroupResolutionService {
<<Rule Engine>>
-ErrorCodeRegistry registry
-RedactionService redactionService
+resolveByGroup(exceptionClass, locale, channel, t, extraContext) Optional~ResolvedErrorWithMapping~
}
class TemplateRenderer {
<<Renderer Utility>>
+render(template, ctx, args) String
}
class RedactionService {
<<Sanitizer Utility>>
+redact(context) Map
+redactString(input) String
}
RuntimeException <|-- BusinessException
BusinessException <|-- ConsistencyCheckException
ErrorMessageService --> ErrorCodeRegistry : queries cache
ErrorMessageService --> GroupResolutionService : delegates unmapped
ErrorMessageService --> TemplateRenderer : formats templates
ErrorMessageService --> RedactionService : sanitizes PII
GroupResolutionService --> ErrorCodeRegistry : queries groups/mappings
GroupResolutionService --> TemplateRenderer : renders group templates
GroupResolutionService --> RedactionService : sanitizes group context
ErrorCodeRegistry --> ErrorCode : holds
ErrorCodeRegistry --> ErrorMessage : holds
ErrorCodeRegistry --> ErrorGroup : holds
ErrorCodeRegistry --> ErrorGroupMapping : holds
3. Developer Guide & Usage Standards¶
Throwing Business Errors in Domain Services¶
// 1. Simple error with positional arguments:
throw new BusinessException("RESERVATION_EXPIRED", reservationId, expiryDate);
// 2. Error with custom contextual details map:
throw new BusinessException("SUBDIVISION_EXCEEDS_EXTENT",
Map.of("baseline", 5.0, "current", 8.2),
baseline, totalArea);
// 3. Backward compatible legacy integer codes:
throw new GenericException(80001);
Channel Selection via HTTP Headers¶
Clients can explicitly request UI-optimized or API-optimized errors by including the following header:
X-Client-Channel: ui # Returns end-user actionable message (Default)
X-Client-Channel: api # Returns technical diagnostics for integration consumers
4. Operational API Endpoints¶
The framework exposes management endpoints under /api/v1/system/errors:
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
GET |
/api/v1/system/errors |
Returns full active catalog of error codes, messages, and documentation URLs | Yes |
POST |
/api/v1/system/errors/refresh |
Triggers atomic reload of in-memory cache from Oracle database | Admin / System |
GET |
/api/v1/system/errors/export |
Exports formatted error catalog documentation for frontend/wiki consumers | Yes |
5. Seeded Module Error Codes Catalog (104 Codes)¶
| Module Category | Sample Codes | Default Status | Default Message Sample |
|---|---|---|---|
INFORMATION_REQUEST |
INFO_REQUEST_NOT_FOUNDINFO_QUOTATION_EXPIREDINFO_UNAUTHORIZED_ACCESS |
404 422 403 |
Information request #{0} not found. Fee quotation for request #{0} expired on {1}. |
RESERVATION |
RESERVATION_EXPIREDRESERVATION_DUPLICATE_PARCELRESERVATION_QUOTA_EXCEEDED |
422 409 422 |
Reservation #{0} expired on {1} and cannot be processed. Parcel {0} in province {1} is already reserved. |
LODGEMENT |
LODGEMENT_DOCUMENT_MISSINGLODGEMENT_PAYMENT_MISMATCHLODGEMENT_PQ_DISCREPANCY |
400 422 422 |
Mandatory document '{0}' is missing for lodgement #{1}. Discrepancy in PQ sheet section {0}: expected {1}, calculated {2}. |
EXAMINATION |
EXAM_CONSISTENCY_FAILEDEXAM_CLOSURE_EXCEEDEDEXAM_CAVEAT_EXISTS |
422 422 409 |
Consistency check failed for parcel {0}: {1}. Mathematical closure tolerance exceeded for {0}. Cannot proceed: active caveat exists on parcel {0}. |
MAINTENANCE |
MAINT_SUBDIVISION_EXCEEDS_EXTENTMAINT_STREET_RENAME_CONFLICTMAINT_CANNOT_WITHDRAW_REGISTERED |
422 409 409 |
Subdivision deduction exceeds extent for {0}. Baseline={1}ha, Current={2}ha. Street name '{0}' already exists in municipality {1}. |
ARCHIVE |
ARCHIVE_PACKET_NOT_FOUNDARCHIVE_SCAN_RESOLUTION_LOWARCHIVE_METADATA_INVALID |
404 422 422 |
Archive packet #{0} not found. Scanned document '{0}' resolution ({1} DPI) is below minimum (300 DPI). |
USER & WORKFLOW |
USER_LOCKEDWORKFLOW_INVALID_TRANSITIONPAYMENT_VERIFICATION_FAILED |
423 422 402 |
Account is locked. Invalid workflow process transition requested. |