afghaleek/problem-mapper-spring-boot-starter

Purpose and Integration

This repository is a Java 17 / Spring Boot 3.x starter that converts application exceptions into RFC-style Spring ProblemDetail HTTP responses. It is a library, not a standalone application: Spring Boot discovers and activates it through src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports.

The consumer-facing entry point is the @ResponseError annotation at src/main/java/io/github/daoud/problemapper/annotation/ResponseError.java, applied to exception classes.

Auto-Configuration Boundary

src/main/java/io/github/daoud/problemapper/autoconfigure/ProblemMapperAutoConfiguration.java is the composition root. It registers the starter’s runtime beans when present on a consuming Spring Boot application's classpath and binds configurable behavior through src/main/java/io/github/daoud/problemapper/properties/ProblemMapperProperties.java.

This is the principal boundary between consumer application code and the starter: applications supply exceptions, configuration properties, and HTTP requests; the starter supplies exception translation.

Exception Metadata Stage

src/main/java/io/github/daoud/problemapper/annotation/ResponseError.java declares static response metadata on exception types: HTTP status, application error code, and default message.

At runtime, the mapper inspects the thrown exception’s class for this annotation. The exception instance message can provide dynamic detail, while the annotation provides a stable API-level error classification.

Global HTTP Exception Interception

src/main/java/io/github/daoud/problemapper/handler/ResponseErrorExceptionHandler.java is the global Spring MVC exception-handling layer. It receives exceptions escaping REST controller execution, determines whether they carry @ResponseError, and delegates response construction.

It also provides the fallback path for unannotated or otherwise unmapped exceptions, preventing callers from needing their own repetitive @ControllerAdvice mappings.

ProblemDetail Construction

src/main/java/io/github/daoud/problemapper/factory/ProblemDetailFactory.java centralizes creation of Spring’s ProblemDetail response body. It combines exception metadata, request context, and configured options into a consistent payload.

Expected output includes standard ProblemDetail fields such as status, title/detail, and instance/path, plus an application-specific code extension. This factory is the main response-shape boundary and should remain the sole owner of field-selection rules.

Configuration and Fallback Policy

src/main/java/io/github/daoud/problemapper/properties/ProblemMapperProperties.java represents the problem-mapper.* configuration surface. It controls enablement, inclusion of path, timestamp, and exception-class information, plus fallback code and message behavior.

The fallback policy is significant: annotated exceptions produce intentional client-facing errors; all others become a configured internal-error response rather than leaking implementation details by default.

Runtime, Packaging, and External Dependencies

The artifact is Maven-built via pom.xml and packaged as a Spring Boot starter JAR. Its material runtime dependency is Spring Boot/Spring MVC, especially Spring’s ProblemDetail API and auto-configuration mechanism. There are no databases, queues, remote APIs, or standalone infrastructure components in the repository.

The build output target/problem-mapper-spring-boot-starter-0.0.1-SNAPSHOT.jar confirms this is distributable library packaging; JitPack is the documented external distribution channel.