Vidocq Documentation

Référence consolidée des artifacts Maven, modules JPMS, annotations supportées, propriétés JsonbConfig, et points de configuration runtime de Champollion.

Artifacts Maven

groupId:artifactId Rôle

io.vidocq.champollion:champollion-api

Re-exposition pure des specs Jakarta (jakarta.json, jakarta.json.bind). Utile pour les modules consommateurs qui ne veulent pas dépendre d’une implémentation.

io.vidocq.champollion:champollion-jsonp

Implémentation JSON-P 2.1 (parser, generator, object model, Patch / Pointer / Merge Patch). JsonProvider ServiceLoader.

io.vidocq.champollion:champollion-jsonb

Implémentation JSON-B 3.0 (Jsonb, JsonbBuilder, JsonbConfig). Dépend de champollion-jsonp.

io.vidocq.champollion:champollion-codegen-apt

Annotation Processor (scope provided) qui génère les JsonbBinding<T> à la compilation.

io.vidocq.champollion:champollion-codegen-maven-plugin

Mojo champollion:generate lié à generate-sources ; scanne le classpath et invoque l’APT sur les types détectés mais non annotés.

io.vidocq.champollion:champollion-bench

JMH — comparatifs Parsson/Yasson/Jackson. Pas de scope runtime.

io.vidocq.champollion:champollion-examples

Exemples exécutables.

io.vidocq.champollion:champollion-tck (hors reactor)

Runners TCK officiels JSON-P 2.1 + JSON-B 3.0. Lancement via run-official-tck-*.sh uniquement.

Modules JPMS

Module Exports publics SPI / provides

io.vidocq.champollion.api

jakarta.json (transitive), jakarta.json.bind (transitive)

—

io.vidocq.champollion.jsonp

io.vidocq.champollion.jsonp.spi

provides jakarta.json.spi.JsonProvider with io.vidocq.champollion.jsonp.ChampollionJsonProvider

io.vidocq.champollion.jsonb

io.vidocq.champollion.jsonb.spi, io.vidocq.champollion.jsonb.annotation

provides jakarta.json.bind.spi.JsonbProvider with io.vidocq.champollion.jsonb.ChampollionJsonbProvider

io.vidocq.champollion.codegen.apt

—

provides javax.annotation.processing.Processor with io.vidocq.champollion.codegen.apt.JsonbStaticProcessor

Packages internes (internal.*) non exportés — ne pas dépendre dessus, ils peuvent casser entre versions.

Annotations JSON-B supportées

Annotations standard Jakarta JSON Binding 3.0 — toutes supportées :

Annotation Effet

@JsonbProperty("name")

Renomme la propriété JSON. Sur paramètre de constructeur : utilisé pour la résolution.

@JsonbTransient

Exclut la propriété (lecture et écriture).

@JsonbDateFormat("yyyy-MM-dd")

Format date / time. S’applique à java.time.*, java.util.Date, Calendar.

@JsonbNumberFormat(",#0.00")

Format numérique (cf. DecimalFormat).

@JsonbTypeAdapter(MyAdapter.class)

Adapter sur la propriété ou la classe.

@JsonbTypeSerializer(MySer.class) / @JsonbTypeDeserializer(…​)

Sérialiseur / désérialiseur custom.

@JsonbVisibility(MyStrategy.class)

Stratégie de visibilité (champs vs accesseurs).

@JsonbCreator

Constructeur ou factory à utiliser pour la désérialisation. Records natifs supportés sans annotation.

@JsonbNillable

Force l’écriture des null pour cette propriété (ou classe).

@JsonbPropertyOrder({"a", "b", "c"})

Ordre d’écriture des propriétés.

@JsonbTypeInfo + @JsonbSubtype

Polymorphisme avec discriminant (nouveau en JSON-B 3.0).

Annotations Champollion-spécifiques :

@JsonbStatic

Marque un type pour la génération de binding par champollion-codegen-apt. Optionnel — l’APT scanne aussi les types annotés @JsonbProperty etc.

Propriétés JsonbConfig

Toutes les propriétés standard de jakarta.json.bind.JsonbConfig sont supportées (cf. https://jakarta.ee/specifications/jsonb/3.0/) :

Propriété Description

JSONB_FORMATTING (withFormatting)

Pretty-print avec indentation.

JSONB_NULL_VALUES (withNullValues)

Inclure les propriétés à null dans la sortie.

JSONB_LOCALE (withLocale)

Locale pour les formats date / nombre.

JSONB_DATE_FORMAT (withDateFormat)

Format date / time global.

JSONB_PROPERTY_NAMING_STRATEGY

IDENTITY, LOWER_CASE_WITH_DASHES, LOWER_CASE_WITH_UNDERSCORES, UPPER_CAMEL_CASE, CASE_INSENSITIVE…​

JSONB_PROPERTY_ORDER_STRATEGY

LEXICOGRAPHICAL, ANY, REVERSE.

JSONB_BINARY_DATA_STRATEGY

BYTE, BASE_64, BASE_64_URL.

JSONB_ENCODING

UTF-8 par défaut.

withAdapters(…​), withSerializers(…​), withDeserializers(…​)

Enregistrement global.

Propriétés Champollion-spécifiques (préfixe champollion.) :

champollion.jsonb.warn-on-fallback

Si true, log WARN quand le runtime tombe en fallback réflexif (binding statique non trouvé). Utile en audit production. Défaut false.

champollion.jsonp.buffer-pool-size

Taille du pool de buffers du parser. Défaut : 8.

JsonProvider & JsonbProvider

Découverts automatiquement via ServiceLoader :

  • META-INF/services/jakarta.json.spi.JsonProvider → io.vidocq.champollion.jsonp.ChampollionJsonProvider

  • META-INF/services/jakarta.json.bind.spi.JsonbProvider → io.vidocq.champollion.jsonb.ChampollionJsonbProvider

Pour forcer l’implémentation (cas multi-impl sur le classpath) :

-Djakarta.json.provider=io.vidocq.champollion.jsonp.ChampollionJsonProvider
-Djakarta.json.bind.provider=io.vidocq.champollion.jsonb.ChampollionJsonbProvider

Plugin Maven champollion-codegen-maven-plugin

<plugin>
  <groupId>io.vidocq.champollion</groupId>
  <artifactId>champollion-codegen-maven-plugin</artifactId>
  <version>${champollion.version}</version>
  <executions>
    <execution>
      <goals><goal>generate</goal></goals>
    </execution>
  </executions>
  <configuration>
    <targets>
      <target>com.acme.dto.*</target>
    </targets>
    <excludes>
      <exclude>com.acme.dto.internal.*</exclude>
    </excludes>
  </configuration>
</plugin>

Lié à generate-sources. Délègue 100 % à champollion-codegen-apt — pas de duplication.

Compatibilité

Ressources

  • lien:https://codeberg.org/Vidocq/champollion/src/branch/main/BENCH.md[BENCH.md] — benchmarks JMH vs Parsson / Yasson / Jackson

  • lien:https://codeberg.org/Vidocq/champollion/src/branch/main/TCK.md[TCK.md] — détail TCK

  • lien:https://codeberg.org/Vidocq/champollion/src/branch/main/ROADMAP.md[ROADMAP.md] — phases M0..M7