https://github.com/t1/jsonbap

An implementations of Jakarta JSON Binding (JSON-B) using an annotation processor at compile-time instead of reflection at runtime
https://github.com/t1/jsonbap

Last synced: 3 months ago
JSON representation

An implementations of Jakarta JSON Binding (JSON-B) using an annotation processor at compile-time instead of reflection at runtime

• Host: GitHub
• URL: https://github.com/t1/jsonbap
• Owner: t1
• Created: 2024-10-27T09:57:50.000Z (over 1 year ago)
• Default Branch: trunk
• Last Pushed: 2026-04-22T03:08:39.000Z (3 months ago)
• Last Synced: 2026-04-22T05:17:19.709Z (3 months ago)
• Language: Java
• Size: 259 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 11
• Metadata Files:
  • Readme: README.adoc

Awesome Lists containing this project

README

          
= A _fast_ implementation of Jakarta JSON Binding (JSON-B)

[note]

====

This project is in a very early stage and still far from ready for production use.

Currently, only 21% of the JSON-B TCK tests pass.

The `jsonb-tck` module is intentionally not a submodule of the parent POM, as most TCK tests still fail and would break the build.

Build it separately: `cd jsonb-tck && mvn test`.

====

`jsonbap` = JSON-B Annotation Processor

An implementations of https://jakarta.ee/specifications/jsonb/3.0/jakarta-jsonb-spec-3.0[Jakarta JSON Binding] (JSON-B) using an annotation processor at compile-time instead of reflection at runtime, making it much faster, esp. when comparing to the reference implementation of JSON-B, https://github.com/eclipse-ee4j/yasson[Yasson].

Nice side effect: If you should need to debug your JSON-B mappings, you can simply set a breakpoint in your IDE and inspect the generated, nicely readable and simple Java code.

== Background

https://jakarta.ee/specifications/jsonb/3.0/jakarta-jsonb-spec-3.0[JSON-B] is a standard API for converting Java objects to and from JSON documents.

It's part of the Jakarta EE platform and is used by many other libraries and frameworks.

The reference implementation of JSON-B is https://github.com/eclipse-ee4j/yasson[Yasson], which was never designed to be fast, not even being production ready was a real design goal. https://github.com/FasterXML/jackson[Jackson], for example, is much faster and was in use for years before JSON-B, but it's not a standard API.

Sadly, people conclude that JSON-B is slow and use Jackson instead.

In principle, this works very similar to https://github.com/ngs-doo/dsl-json[DSL-Json] or https://github.com/quarkusio/qson[QSON], but with focus and proper support for JSON-B (when it's finally done), and it works as an annotation processor.

== Benchmark

I tried to do some benchmarks, but the results are obviously completely wrong.

// |===

// |Benchmark |Score |Error

//

// |Jackson

// |117.626

// |±  1.286

//

// |Johnzon

// |209.336

// |±  9.924

//

// |JsonP

// |1775.570

// |± 18.056

//

// |Jsonbap

// |146.648

// |±  1.126

//

// |StringWriter

// |142.689

// |±  3.918

//

// |Yasson

// |360.094

// |± 26.499

// |===

== Limitations

This is an annotation processor generating source code.

This makes things fast, but brings things to look out for:

* All classes that need to be (de)serialized have to be annotated as `@Bindable`, or (if it's not your own source) be listed in the `value` of some `@Bindable` annotation.

* Some configurations in the JSON-B API assume to be evaluated at runtime.

When generating the source code, this has not yet been specified, so we need different solutions:

** `jsonb.property-naming-strategy`: you can set the `propertyNamingStrategy` in the `@Bindable` annotation.

** `jsonb.property-visibility-strategy`: this is not yet supported, as it heavily relies on reflection; and we would need code everywhere just to allow for the potential.

Also, the `@JsonbVisibility` annotation relies on reflection, but at least, the annotation is an opt-in at compile time.

== Lombok

If you use Lombok to generate getters, you must make sure that the Lombok runs before the `jsonbap`.

To do so, specify the processor classes, e.g. for Maven in the `maven-compiler-plugin`:

[source,xml]

----

    org.apache.maven.plugins

    maven-compiler-plugin

    3.13.0

    

        

            lombok.launch.AnnotationProcessorHider$AnnotationProcessor

            

            lombok.launch.AnnotationProcessorHider$ClaimingProcessor

            

            com.github.t1.jsonbap.impl.JsonbAnnotationProcessor

        

    

----

== Logging/Debugging

JSONB-AP generates compiler notifications: e.g. errors, if you did something wrong, or warnings, if you did something suspicious.

It also generates notes for the most important things it does, e.g. which files it generates.

If you need to see more details, it's generally sufficient to look at the generated source files:

All the relevant information should be there.

Some things as plain Java code that you can even debug.

And some things as comments, e.g. the source of annotations it has picked up to generate the code.

To see what the `jsonbap` is doing in detail, you can add a *`compile`* scope dependency (normally you'd do this only `runtime` scoped) on an implementation of https://www.slf4j.org[slf4j] and set the log level to `DEBUG`.

E.g. https://logback.qos.ch[logback] logs at debug by default.