Concepts · Vidocq

Champollion exposes two distinct Jakarta APIs: JSON-P (Processing) which manipulates raw JSON as an event stream or value tree, and JSON-B (Binding) which automatically maps between JSON and POJOs. This page lays out the vocabulary of each.

JSON-P 2.1 — JSON Processing

Low-level API, JSON-structure oriented. Covers spec https://jakarta.ee/specifications/jsonp/2.1/.

Parser and Generator (streaming)

JsonParser

Pull event-based reader: hasNext() / next() return a JsonParser.Event (START_OBJECT, KEY_NAME, VALUE_STRING, END_ARRAY…). No tree allocation, ideal for large documents or skipping.

JsonGenerator

Push fluent writer: writeStartObject().write("k", v).writeEnd(). Pushes to a Writer or OutputStream (UTF-8). Optional pretty-printing.

JsonParserFactory / JsonGeneratorFactory

Pre-configured factories (buffer pool, pretty-printing, encoding). Reusable, thread-safe.

Object model (DOM)

JsonValue

Sealed interface — root of the hierarchy. Subtypes: JsonString, JsonNumber, JsonObject, JsonArray, plus the constants JsonValue.TRUE, FALSE, NULL.

JsonObject

Immutable Map<String, JsonValue>, insertion order preserved.

JsonArray

Immutable List<JsonValue>.

JsonObjectBuilder / JsonArrayBuilder

Mutable builders; build() returns an immutable value.

JsonReader / JsonWriter

Whole-document read / write of a JsonValue (vs the event-based streaming).

Patch / Pointer / Merge Patch

JsonPointer (RFC 6901)

Addresses a value inside a document: /users/0/name. getValue, add, replace, remove.

JsonPatch (RFC 6902)

Sequence of atomic operations (add, remove, replace, move, copy, test). apply() returns the modified document.

JsonMergePatch (RFC 7396)

Tree-merge differential patch. null means deletion.

JSON-B 3.0 — JSON Binding

High-level API, Java-object oriented. Covers spec https://jakarta.ee/specifications/jsonb/3.0/.

Jsonb

Main entry point. toJson(obj) / fromJson(s, Class<T>). Thread-safe, created once per application.

JsonbBuilder

Fluent. JsonbBuilder.newBuilder().withConfig(…).build().

JsonbConfig

Standard property bag: formatting, null-values, locale, date-format, property-naming-strategy, binary-data-strategy, etc.

JsonbAdapter<Original, Adapted>

Bidirectional conversion between a Java type and a native JSON type (typically String or JsonObject). Simplest customization case.

JsonbSerializer<T> / JsonbDeserializer<T>

Low-level customization: you drive JsonGenerator / JsonParser directly. Required for conditional polymorphism or dynamic-key structures.

BindingPlan (Champollion-internal)

Plan resolved once per class: ordered list of PropertyWriter / PropertyReader. Lock-free ClassValue<BindingPlan> cache.

JsonbBinding<T> (Champollion-internal)

Contract of an APT-generated static binding. Implemented by <Type>$$Binding. Discovered via ServiceLoader.

Essential difference: JSON-P vs JSON-B

Criterion JSON-P JSON-B

Criterion	JSON-P	JSON-B
Level	Low — handles events or a JSON DOM	High — handles Java objects
Typical use	Streaming, large documents, patch / merge	REST DTOs, configuration, CRUD payloads
Allocation	Minimal in streaming (zero DOM)	A full object graph per call
Customization	None — pure structure	Annotations (`@JsonbProperty`…), adapters, serializers
Performance target	Parsson / Jackson streaming	Yasson / Jackson databind

Level

Low — handles events or a JSON DOM

High — handles Java objects

Typical use

Streaming, large documents, patch / merge

REST DTOs, configuration, CRUD payloads

Allocation

Minimal in streaming (zero DOM)

A full object graph per call

Customization

None — pure structure

Annotations (@JsonbProperty…), adapters, serializers

Performance target

Parsson / Jackson streaming

Yasson / Jackson databind

JSON-B builds on JSON-P: Jsonb.toJson(obj) ultimately pushes into a JsonGenerator. The binding layer composes on top of the processing layer — never the other way round.

Champollion-specific vocabulary

Runtime mode

JSON-B binding by MethodHandles introspection on first encounter, ClassValue cache. Cost amortized after warmup. Requires a JPMS --add-opens if the target module does not opens its package to the binding.

Static mode (or "codegen")

JSON-B binding generated at compile time by champollion-codegen-apt. <Type>$$Binding: zero reflection, no MethodHandles.privateLookupIn needed. AOT-friendly (GraalVM, Leyden).

Differential testing

Automated suite: for each tested type, verify runtime.toJson(o).equals(static.toJson(o)) and the symmetric for reads. Guardrail against codegen regressions.

@JsonbStatic

Champollion-specific annotation marking a type for binding generation. Optional — the APT also scans types annotated with standard annotations (@JsonbProperty, @JsonbTypeAdapter, etc.).

BindingFactoryProvider

ServiceLoader SPI exposing a generated static binding. The runtime queries this SPI first, then falls back to introspection if absent.