Vidocq Documentation

Lexique technique de Mansart. Pose les définitions communes aux quatre sous-modules pour éviter l’ambiguïté quand on lit internals.adoc ou reference.adoc.

Entity

Classe Java annotée @jakarta.persistence.Entity (ou son équivalent Mansart @io.vidocq.mansart.data.Entity zéro-dep). Elle représente une ligne d’une table SQL. Mansart lit ses annotations à la compilation via APT et génère un métamodèle statique (Book ou Book), pas de scan classpath au démarrage.

Attributs reconnus : @Id, @GeneratedValue, @Column, @Table, @Version, @Enumerated, @Embedded/@Embeddable, @ManyToOne, @OneToOne, @JoinColumn, @Transient. Les collections (@OneToMany, @ManyToMany) et l’héritage sont reportés à mansart-persistence (M7).

Repository

Interface annotée @jakarta.data.repository.Repository. Spécifie ce que l’application veut faire de l’entité, sans préjuger du SQL exact. Mansart matérialise l’interface en classe XxxRepositoryImpl à la compilation (APT). Aucune réflexion à l’exécution, aucun proxy dynamique.

Trois racines standards :

  • BasicRepository<T, K> — CRUD minimal (save, delete, findById, findAll, count, existsById).

  • CrudRepository<T, K> — étend BasicRepository avec variantes batch.

  • DataRepository<T, K> — repository « libre » à composer entièrement par méthodes nommées et @Query.

EntityManager

Concept Jakarta Persistence 3.2 — gestionnaire de cycle de vie des entités (managed/detached), file de modifications, propagation flush/commit. Hors périmètre de mansart-jakarta-data ; sera fourni par mansart-persistence (M7 en attente — voir mansart-persistence).

Dans Vidocq, le besoin courant (CRUD + queries typées) est déjà couvert par les repositories Jakarta Data, qui contournent l'`EntityManager` au profit d’un mapping ResultSet direct via MethodHandle.

Transaction

Démarcation atomique d’un ensemble d’opérations sur une ou plusieurs ressources. Mansart implémente Jakarta Transactions 2.0 :

  • TransactionManager — API SPI, gérée par le conteneur. begin/commit/rollback, suspend/resume, enlistResource/delistResource.

  • UserTransaction — API utilisateur, programmatique.

  • @Transactional — intercepteur CDI déclaratif, supporte les six TxType standards.

  • TransactionScoped — scope CDI dont la durée de vie épouse la transaction.

Le contexte transactionnel est porté par un ScopedValue<TransactionContext> — propagation transparente à travers les virtual threads créés via StructuredTaskScope.

ConnectionPool

Cache borné de java.sql.Connection physiques. Évite le coût connect/disconnect à chaque requête. mansart-pool fournit MansartDataSource implements javax.sql.DataSource :

  • Deque<PooledConnection> idle — pile lock-free des connexions disponibles.

  • Set<PooledConnection> inUse — empruntées en cours.

  • Semaphore permits — taille = maxSize, bloque l’acquisition au-delà.

  • ScopedValue<Connection> CURRENT — connexion liée à la transaction courante.

  • Housekeeper virtual thread — eviction idleTimeout / maxLifetime, validation isValid.

Dialecte SQL

MansartDialect — SPI qui isole les différences SQL entre bases : pagination (LIMIT/OFFSET vs FETCH FIRST), upsert (ON CONFLICT vs MERGE), retour d’identifiant (RETURNING vs getGeneratedKeys), types (UUID, JSONB, BOOLEAN).

Découverte par ServiceLoader (provides DialectFactory with H2DialectFactory). Dialectes livrés : H2, PostgreSQL. D’autres au backlog (MariaDB, SQL Server).

Métamodèle statique

Classes générées par APT à côté des entités. Deux formats :

  • Format Mansart riche (_Book) — _Book.title est une TextAttribute<Book> avec columnName(), MethodHandle getter(), etc. Permet au dialecte de générer du SQL spécialisé sans instanceof en chaîne.

  • Format JPA standard (Book_) — Book_.title est une SingularAttribute<Book, String>. Interop pour Criteria API future.

Les MethodHandle sont obtenus une seule fois au <clinit> via MethodHandles.privateLookupIn(…​) — jamais de réflexion à l’usage.

JDQL vs JPQL

  • JDQL (Jakarta Data Query Language) — sous-ensemble simplifié défini par Jakarta Data 1.0. SELECT/UPDATE/DELETE sur entités, LIKE, BETWEEN, ORDER BY, paramètres nommés. Mansart le supporte via @Query dans mansart-jakarta-data.

  • JPQL (Jakarta Persistence Query Language) — surensemble plus riche (joins explicites, sous-requêtes, agrégats), traité par mansart-persistence (M7). Pour l’instant, les besoins JPQL sont couverts par JDQL ou par requête SQL native.

Différences Jakarta Data vs JPA

Aspect Jakarta Data 1.0 (mansart-jakarta-data) Jakarta Persistence 3.2 (mansart-persistence)

API

Repositories déclaratifs typés

EntityManager impératif

Cycle de vie entités

Stateless — pas de managed/detached

Persistence context (managed)

Cache L1

Aucun

Persistence context

Requêtes

Method names + JDQL + lifecycle annotations

JPQL + Criteria API

État Mansart

✅ Livré (TCK 73/73)

⏳ M7 en attente