Problem4J Core

This library provides a minimal, framework-agnostic Java model of the RFC 7807 "Problem Details" object, with an immutable Problem class and a fluent ProblemBuilder for convenient construction.

It is intended to be used as a foundation for other libraries or applications that add framework-specific behavior (e.g. Jackson, Spring).

Table of Contents

• Features
• Example
• Usage
• Problem4J Links
• Building from source

Features

• ✅ Immutable Problem data model.
• ✅ Dedicated unchecked ProblemException to be used in error handling.
• ✅ Builder pattern for fluent construction.
• ✅ Annotation @ProblemMapping and ProblemMapper to allow declarative approach in converting exception instances into Problem objects.
• ✅ Builder pattern for fluent construction.
• ✅ Serializable and easy to log or format.
• ✅ HTTP-agnostic (no external dependencies).
• ✅ Follows RFC 7807 semantics:
  • type (URI),
  • title (short summary),
  • status (numeric code),
  • detail (detailed description),
  • instance (URI to the specific occurrence),
  • custom field extensions.

Example

import io.github.problem4j.core.Problem;
import io.github.problem4j.core.ProblemException;

Problem problem =
    Problem.builder()
        .type("https://example.com/errors/invalid-request")
        .title("Invalid Request")
        .status(400)
        .detail("not a valid json")
        .instance("https://example.com/instances/1234")
        .build();
throw new ProblemException(problem);

import io.github.problem4j.core.ProblemMapping;
import io.github.problem4j.core.ProblemMapper;

@ProblemMapping(
        type = "https://example.org/probs/tests",
        title = "Test problem",
        status = 400,
        detail = "failed: {message}",
        extensions = {"subject"})
public class MessageException extends RuntimeException {
    
    private final String subject;

    public MessageException(String subject, String message) {
        super(message);
        this.subject = subject;
    }
}

MessageException ex = new MessageException("sub", "boom");

ProblemMapper mapper = ProblemMapper.create();
Problem problem = mapper.toProblemBuilder(ex).build();

Usage

Add library as dependency to Maven or Gradle. See the actual versions on Maven Central. Java 8 or higher is required to use this library.

1. Maven:

   <dependencies>
       <dependency>
           <groupId>io.github.problem4j</groupId>
           <artifactId>problem4j-core</artifactId>
           <version>1.3.0-RC1</version>
       </dependency>
   </dependencies>

2. Gradle (Groovy or Kotlin DSL):

   dependencies {
       implementation("io.github.problem4j:problem4j-core:1.3.0-RC1")
   }

Problem4J Links

• problem4j-core - Core library defining Problem model and ProblemException.
• problem4j-jackson - Jackson module for serializing and deserializing Problem objects.
• problem4j-spring - Spring modules extending ResponseEntityExceptionHandler for handling exceptions and returning Problem responses.

Building from source

Expand...

Gradle 9.x+ requires Java 17+ to run, but higher Java versions can also be used. All modules of this project are compiled using a Java 8 toolchain, so the produced artifacts are compatible with Java 8, regardless of the Java version Gradle runs on.

./gradlew build

To execute tests use test task.

./gradlew test

To format the code according to the style defined in build.gradle.kts rules use spotlessApply task. Note that building will fail if code is not properly formatted.

./gradlew spotlessApply

To publish the built artifacts to local Maven repository, run following command, replacing XXXX with the desired version. By default, the version is derived from git commit hash.

./gradlew -Pversion=XXXX publishToMavenLocal