JFrame

Enterprise-grade utilities for Spring Boot and Quarkus applications

Features • Quick Start • Documentation • Building • License

---

Overview

JFrame provides structured exception handling, ECS-compliant logging, paginated search, and OpenTelemetry tracing for Spring Boot and Quarkus. A shared framework-agnostic core ensures consistent behaviour across both runtimes.

✨ Features

Feature	Spring Boot	Quarkus
Structured exception handling with error enrichers	✅	✅
ECS-compliant MDC logging (request/transaction ID, duration)	✅	✅
Request/response body logging with content-type filtering	✅	✅
Paginated search with type-safe specifications	✅	✅
Fluent validation with ValidatorBuilder	✅	✅
OpenTelemetry auto-tracing (@Service, @Traced)	✅ AOP	✅ CDI interceptor
Build-time @Traced injection for @ApplicationScoped beans	—	✅
Auto-instrumentation (JDBC, HTTP, Kafka, gRPC)	✅	✅
Outbound HTTP correlation (RestTemplate / WebClient / JAX-RS client)	✅	✅
SQL query logging via datasource-proxy	✅	✅
OpenAPI error response schemas (400/429/500)	—	✅
Jackson 3.x configuration	—	✅
Jackson 2.x configuration	✅	—

🚀 Quick Start

Prerequisites

• Java 21+ (Temurin recommended)
• Spring Boot 4.1.0-M1+ or Quarkus 3.20.3+
• Gradle 9.x

Installation

Spring Boot — Gradle (Kotlin DSL)

dependencies {
    implementation("io.github.jframeoss:jframe-spring-core:0.10.0-SNAPSHOT")
    implementation("io.github.jframeoss:jframe-spring-jpa:0.10.0-SNAPSHOT")   // optional
    implementation("io.github.jframeoss:jframe-spring-otlp:0.10.0-SNAPSHOT")  // optional
}

Quarkus — Gradle (Kotlin DSL)

dependencies {
    implementation("io.github.jframeoss:jframe-quarkus-core:0.10.0-SNAPSHOT")
    implementation("io.github.jframeoss:jframe-quarkus-jpa:0.10.0-SNAPSHOT")   // optional
    implementation("io.github.jframeoss:jframe-quarkus-otlp:0.10.0-SNAPSHOT")  // optional
}

Maven coordinates

<!-- Spring Boot -->
<dependency>
    <groupId>io.github.jframeoss</groupId>
    <artifactId>jframe-spring-core</artifactId>
    <version>0.10.0-SNAPSHOT</version>
</dependency>

<!-- Quarkus -->
<dependency>
    <groupId>io.github.jframeoss</groupId>
    <artifactId>jframe-quarkus-core</artifactId>
    <version>0.10.0-SNAPSHOT</version>
</dependency>

Replace core with jpa or otlp as needed.

Minimal Configuration

Spring Boot (application.yml)

jframe:
  application:
    name: my-service
    group: com.example
    version: 1.0.0
    environment: dev

Quarkus (application.properties)

jframe.application.name=my-service
jframe.application.group=com.example
jframe.application.version=1.0.0
jframe.application.environment=dev

All four properties are required. See the Configuration Reference for the full property list.

📚 Documentation

Document	Description
Getting Started	Installation, configuration, feature matrix
Configuration Reference	All jframe.* properties, filter toggles, OTEL mapping, MDC fields
Core API	Exceptions, validation, search framework, ECS logging

Spring Boot

Module	Documentation
jframe-spring-core — Filters, exception handling, logging, caching	📖 Docs
jframe-spring-jpa — Search specifications, pagination, SQL logging	📖 Docs
jframe-spring-otlp — Tracing, auto-instrumentation, HTTP client	📖 Docs

Quarkus

Module	Documentation
jframe-quarkus-core — Exception mappers, JAX-RS filters, outbound correlation	📖 Docs
jframe-quarkus-jpa — Panache search, repository, page mapping	📖 Docs
jframe-quarkus-otlp — CDI tracing, build-time @Traced, auto-instrumentation	📖 Docs

Migration Guides

• Spring Boot 1.0.0 Migration — jframe-starter-* → jframe-spring-*
• ECS Naming Convention Migration — KibanaLogField* → EcsField*

🏗️ Project Structure

jframe/
├── jframe-core/                  # Framework-agnostic: exceptions, validation, search, ECS logging, tracing utils
├── jframe-spring/
│   ├── core/                     # Auto-configuration, servlet filters, exception handler, logging
│   ├── jpa/                      # JPA search specifications, pagination, datasource-proxy
│   └── otlp/                     # AOP tracing, span management, HTTP client tracing
├── jframe-quarkus/
│   ├── core/                     # CDI producers, JAX-RS filters, exception mappers, OpenAPI
│   ├── jpa/                      # Panache search repository, page mapping, datasource-proxy
│   ├── otlp/                     # CDI tracing interceptor, auth utilities
│   └── otlp-deployment/          # Build-time @Traced annotation processor
└── src/
    ├── docs/                     # Documentation wiki
    ├── quality/                  # Spotless, SpotBugs, PMD, Checkstyle configs
    └── dist/                     # LICENSE, CHANGELOG

🛠️ Building from Source

git clone https://github.com/JFrameOSS/JFrame.git
cd JFrame

./gradlew clean build                          # Build + test all modules
./gradlew spotlessApply checkQualityMain       # Code style + quality checks
./gradlew publishToMavenLocal                  # Install to local Maven repo

🤝 Contributing

Contributions welcome — open an issue or pull request on GitHub.

• Java 21+ with Temurin
• Code style: Spotless (./gradlew spotlessApply)
• Commits: Conventional Commits

📄 License

Apache License 2.0 — see LICENSE.

---

⭐ Star this repository if you find it useful!