Vidocq Documentation

Cinq minutes pour ajouter Champollion à un projet Maven, parser un document JSON en streaming, puis sérialiser et désérialiser un POJO via JSON-B.

Prérequis

  • Java 25 (Temurin recommandé)

  • Maven 3.9.16 (un .sdkmanrc est fourni à la racine du repo : sdk env)

  • Aucune autre dépendance — Champollion ne tire rien d’autre que les specs Jakarta

Dépendances Maven

Pour la couche JSON-P seule (streaming + object model + Patch / Pointer) :

<dependency>
  <groupId>io.vidocq.champollion</groupId>
  <artifactId>champollion-jsonp</artifactId>
  <version>${champollion.version}</version>
</dependency>

Pour le binding JSON-B (entraîne champollion-jsonp transitivement) :

<dependency>
  <groupId>io.vidocq.champollion</groupId>
  <artifactId>champollion-jsonb</artifactId>
  <version>${champollion.version}</version>
</dependency>

Pour générer les bindings statiques à la compilation (recommandé en production), ajouter l’APT :

<dependency>
  <groupId>io.vidocq.champollion</groupId>
  <artifactId>champollion-codegen-apt</artifactId>
  <version>${champollion.version}</version>
  <scope>provided</scope>
</dependency>

Ou via le Mojo champollion-codegen-maven-plugin lié à generate-sources (voir Référence).

Lire du JSON en streaming (JSON-P, pull parser)

try (var reader = new StringReader("""
        {"name":"Champollion","year":1822}
        """);
     var parser = Json.createParser(reader)) {
    while (parser.hasNext()) {
        var event = parser.next();
        switch (event) {
            case KEY_NAME    -> System.out.println("key: " + parser.getString());
            case VALUE_STRING -> System.out.println("str: " + parser.getString());
            case VALUE_NUMBER -> System.out.println("num: " + parser.getInt());
            default -> { /* START/END_OBJECT, etc. */ }
        }
    }
}

Construire un object model (JSON-P, builder)

JsonObject obj = Json.createObjectBuilder()
        .add("name", "Champollion")
        .add("year", 1822)
        .add("tags", Json.createArrayBuilder().add("egyptology").add("rosetta"))
        .build();

try (var writer = Json.createWriter(System.out)) {
    writer.writeObject(obj);
}

Sérialiser un POJO (JSON-B, mode runtime par défaut)

public record Hieroglyph(String symbol, String meaning, int age) {}

Jsonb jsonb = JsonbBuilder.create();

String json = jsonb.toJson(new Hieroglyph("oeil", "eye", 5000));
// {"age":5000,"meaning":"eye","symbol":"oeil"}

Hieroglyph back = jsonb.fromJson(json, Hieroglyph.class);

JsonbBuilder.create() retourne un Jsonb thread-safe et virtual-thread-friendly — on le crée une fois pour toute l’application.

Activer les bindings statiques (mode codegen, sans réflexion)

Annoter le record :

@JsonbStatic
public record Hieroglyph(String symbol, String meaning, int age) {}

L’APT champollion-codegen-apt génère à la compilation Hieroglyph$$Binding.java (un JsonbBinding<Hieroglyph> sans réflexion) et l’enregistre via META-INF/services. Le runtime prend automatiquement le binding statique si présent — sinon il retombe sur l’introspection MethodHandles.

Vérifier l’installation

mvn -ntp -Dtest=ChampollionSmokeTest test

Voir Cas d’usage pour les recettes avancées (Patch / Pointer, adapters, formats date).