Vidocq Documentation

Champollion expose deux APIs Jakarta distinctes : JSON-P (Processing) qui manipule du JSON brut comme un flux d’événements ou un arbre de valeurs, et JSON-B (Binding) qui mappe automatiquement entre JSON et POJO. Cette page pose le vocabulaire de chacune.

JSON-P 2.1 — JSON Processing

API bas niveau, orientée structure JSON. Couvre la spec https://jakarta.ee/specifications/jsonp/2.1/.

Parser et Generator (streaming)

JsonParser

Lecteur pull orienté événements : hasNext() / next() retournent un JsonParser.Event (START_OBJECT, KEY_NAME, VALUE_STRING, END_ARRAY…​). Pas d’allocation d’arbre, idéal pour gros documents ou skipping.

JsonGenerator

Écrivain push, fluide : writeStartObject().write("k", v).writeEnd(). Pousse vers un Writer ou OutputStream (UTF-8). Pretty-printing optionnel.

JsonParserFactory / JsonGeneratorFactory

Fabriques configurées (buffer pool, pretty-printing, encoding). Réutilisables, thread-safe.

Object model (DOM)

JsonValue

Interface scellée — racine de la hiérarchie. Sous-types : JsonString, JsonNumber, JsonObject, JsonArray, et les valeurs constantes JsonValue.TRUE, FALSE, NULL.

JsonObject

Map<String, JsonValue> immuable, ordre d’insertion préservé.

JsonArray

List<JsonValue> immuable.

JsonObjectBuilder / JsonArrayBuilder

Constructeurs mutables ; build() rend immuable.

JsonReader / JsonWriter

Lecture / écriture complète d’un JsonValue (par opposition au streaming événementiel).

Patch / Pointer / Merge Patch

JsonPointer (RFC 6901)

Adresse une valeur dans un document : /users/0/name. getValue, add, replace, remove.

JsonPatch (RFC 6902)

Séquence d’opérations atomiques (add, remove, replace, move, copy, test). apply() retourne le document modifié.

JsonMergePatch (RFC 7396)

Patch « différentiel » par fusion arborescente. null signifie suppression.

JSON-B 3.0 — JSON Binding

API haut niveau, orientée objet Java. Couvre la spec https://jakarta.ee/specifications/jsonb/3.0/.

Jsonb

Point d’entrée principal. toJson(obj) / fromJson(s, Class<T>). Thread-safe, créé une fois par application.

JsonbBuilder

Fluide. JsonbBuilder.newBuilder().withConfig(…​).build().

JsonbConfig

Bag de propriétés standard : formatting, null-values, locale, date-format, property-naming-strategy, binary-data-strategy, etc.

JsonbAdapter<Original, Adapted>

Conversion bidirectionnelle entre un type Java et un type JSON natif (typiquement String ou JsonObject). Cas le plus simple de customization.

JsonbSerializer<T> / JsonbDeserializer<T>

Customization bas niveau : on pilote directement JsonGenerator / JsonParser. Indispensable pour le polymorphisme conditionnel ou les structures à clé dynamique.

BindingPlan (interne Champollion)

Plan résolu une fois par classe : liste ordonnée de PropertyWriter / PropertyReader. Cache ClassValue<BindingPlan> lock-free.

JsonbBinding<T> (interne Champollion)

Contrat d’un binding statique généré par APT. Implémenté par <Type>$$Binding. Découvert via ServiceLoader.

Différence essentielle : JSON-P vs JSON-B

Critère JSON-P JSON-B

Niveau

Bas — manipule des événements ou un DOM JSON

Haut — manipule des objets Java

Cas typique

Streaming, gros documents, patch / merge

DTO REST, configuration, échanges CRUD

Allocation

Minimale en streaming (zéro DOM)

Un object graph complet à chaque appel

Customization

Aucune — c’est juste de la structure

Annotations (@JsonbProperty…​), adapters, sérialiseurs

Performance

Cible Parsson / Jackson streaming

Cible Yasson / Jackson databind

JSON-B repose sur JSON-P : Jsonb.toJson(obj) finit toujours par pousser dans un JsonGenerator. La couche binding sait composer sur la couche processing — pas l’inverse.

Vocabulaire Champollion-spécifique

Mode runtime

Binding JSON-B par introspection MethodHandles à la première rencontre, cache ClassValue. Coût amorti après warmup. Nécessite --add-opens JPMS si le module cible n'`opens` pas le package au binding.

Mode statique (ou « codegen »)

Binding JSON-B généré à la compilation par champollion-codegen-apt. <Type>$$Binding : zéro réflexion, MethodHandles.privateLookupIn non requis. Compatible AOT (GraalVM, Leyden).

Differential testing

Suite automatisée : pour chaque type testé, vérifier runtime.toJson(o).equals(static.toJson(o)) et symétrique en lecture. Garde-fou contre les régressions du codegen.

@JsonbStatic

Annotation Champollion-spécifique qui marque un type pour la génération de binding. Par défaut l’APT scanne aussi les annotations standard (@JsonbProperty, @JsonbTypeAdapter, etc.) pour découvrir les types.

BindingFactoryProvider

SPI ServiceLoader qui expose un binding statique généré. Le runtime consulte d’abord ce SPI, puis retombe sur l’introspection si absent.