Vidocq Documentation

mansart-persistence est l’implémentation cible Jakarta Persistence 3.2 de Mansart : EntityManager, JPQL, Criteria API, listeners, métamodèle JPA standard. Statut : M7 en attente. Conception détaillée différée jusqu’à la fin du jalon M4 de mansart-jakarta-data (stabilisation de la SPI dialecte et du métamodèle).

Pour les besoins courants dans Vidocq (CRUD, queries typées, pagination, @Transactional), mansart-jakarta-data (livré) suffit largement. L’exemple vidocq-runtime-mansart-h2-example montre une intégration complète sans mansart-persistence.

Pourquoi un module séparé

Jakarta Data 1.0 et Jakarta Persistence 3.2 ne servent pas le même usage :

  • Jakarta Data — repositories déclaratifs typés, stateless, pas de cache L1, mapping ResultSet direct. Couvre 80 % des besoins applicatifs courants. Livré.

  • Jakarta Persistence — EntityManager impératif, persistence context (managed/detached), cache L1, listeners (@PrePersist, @PostLoad), JPQL riche, Criteria API. Nécessaire pour : graphes d’entités complexes, transactions longues avec lots de modifications, applications portées depuis Hibernate qui exploitent le persistence context.

Les deux modules partageront la même SPI dialecte (mansart-data-dialect-spi) et le même métamodèle statique. Pas de duplication SQL.

Statut

⏳ M7 en attente — voir lien:https://codeberg.org/Vidocq/mansart/src/branch/main/mansart-persistence/PLAN.md[mansart-persistence/PLAN.md] (esquisse) et lien:https://codeberg.org/Vidocq/mansart/src/branch/main/mansart-jakarta-data/PLAN.md[mansart-jakarta-data/PLAN.md] (jalon M7 « Pont mansart-persistence »).

Périmètre cible (à raffiner) :

  • EntityManagerFactory, EntityManager, Query, TypedQuery, EntityTransaction.

  • Persistence context : managed/detached, cascade, orphan removal.

  • JPQL — surensemble de JDQL : joins explicites, sous-requêtes, agrégats.

  • Criteria API.

  • Listeners cycle de vie : @PrePersist, @PostPersist, @PreUpdate, @PostUpdate, @PreRemove, @PostRemove, @PostLoad.

  • Métamodèle JPA standard (Book_.title) — déjà généré par APT, partagé avec mansart-jakarta-data.

  • Schema generation — externe (Flyway/Liquibase recommandé).

  • TCK Jakarta Persistence 3.2 (date à définir).

Principes (déjà fixés)

  • Zéro réflexion — EntityManager interne consomme le métamodèle statique et les MethodHandle produits par APT. Pas d'`EntityManagerProxy` runtime.

  • Pas de bytecode runtime — pas d’enhancement Hibernate-style. Lazy loading via getter intercepté généré APT (à concevoir en M7).

  • Virtual threads natifs — toute exécution JDBC sous Loom. Pas de synchronized englobant un I/O bloquant.

  • JPMS strict — module io.vidocq.mansart.persistence, exports minimaux.

À planifier en détail plus tard

  • Stratégie de cache L1 (HashMap par EM ? compatible virtual threads ?).

  • Gestion du persistence context à travers suspend/resume de transaction.

  • Cascade PERSIST / MERGE / REMOVE sur graphes d’entités.

  • Lazy loading sans bytecode enhancement.

  • Compatibilité mansart-jakarta-data ↔ mansart-persistence dans la même application (un même Book consommé par les deux).

En attendant

Pour les besoins JPA dans Vidocq aujourd’hui :

  • Si CRUD + queries typées suffisent → mansart-jakarta-data (livré, TCK 73/73).

  • Si besoin de JPQL avancé non couvert par JDQL → SQL natif via @Query("…​") ou Connection.prepareStatement(…​).

  • Si besoin de listeners JPA → contournement applicatif (intercepteurs CDI, @Transactional + appel explicite avant/après save).

  • Si besoin de persistence context → migration différée jusqu’à livraison M7.

Voir aussi