Skip to content

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 (ui vs api): The engine inspects X-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/refresh to 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 ProblemDetail with correlation traceId and native NoResourceFoundException routing.

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_FOUND
INFO_QUOTATION_EXPIRED
INFO_UNAUTHORIZED_ACCESS
404
422
403
Information request #{0} not found.
Fee quotation for request #{0} expired on {1}.
RESERVATION RESERVATION_EXPIRED
RESERVATION_DUPLICATE_PARCEL
RESERVATION_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_MISSING
LODGEMENT_PAYMENT_MISMATCH
LODGEMENT_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_FAILED
EXAM_CLOSURE_EXCEEDED
EXAM_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_EXTENT
MAINT_STREET_RENAME_CONFLICT
MAINT_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_FOUND
ARCHIVE_SCAN_RESOLUTION_LOW
ARCHIVE_METADATA_INVALID
404
422
422
Archive packet #{0} not found.
Scanned document '{0}' resolution ({1} DPI) is below minimum (300 DPI).
USER & WORKFLOW USER_LOCKED
WORKFLOW_INVALID_TRANSITION
PAYMENT_VERIFICATION_FAILED
423
422
402
Account is locked.
Invalid workflow process transition requested.