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
• ✅ 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.malczuuu.problem4j.core.Problem;
import io.github.malczuuu.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);

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.malczuuu.problem4j</groupId>
           <artifactId>problem4j-core</artifactId>
           <version>1.2.1</version>
       </dependency>
   </dependencies>

2. Gradle (Groovy or Kotlin DSL):

   dependencies {
       implementation("io.github.malczuuu.problem4j:problem4j-core:1.2.1")
   }

For using snapshot versions Snapshots chapter of RELEASING.md.

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 clean build

To format the code according to the style defined in build.gradle.kts rules use spotlessApply task.

./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 clean build publishToMavenLocal