Vidocq Documentation

mansart-persistence is Mansart’s target Jakarta Persistence 3.2 implementation: EntityManager, JPQL, Criteria API, listeners, JPA standard metamodel. Status: M7 pending. Detailed design deferred until the end of mansart-jakarta-data milestone M4 (stabilization of the dialect SPI and the metamodel).

For everyday needs in Vidocq (CRUD, typed queries, pagination, @Transactional), mansart-jakarta-data (delivered) is largely enough. The vidocq-runtime-mansart-h2-example example shows a full integration without mansart-persistence.

Why a separate module

Jakarta Data 1.0 and Jakarta Persistence 3.2 do not serve the same purpose:

  • Jakarta Data — typed declarative repositories, stateless, no L1 cache, direct ResultSet mapping. Covers 80% of common application needs. Delivered.

  • Jakarta Persistence — imperative EntityManager, persistence context (managed/detached), L1 cache, listeners (@PrePersist, @PostLoad), rich JPQL, Criteria API. Required for: complex entity graphs, long transactions with batches of modifications, applications ported from Hibernate that rely on the persistence context.

Both modules will share the same dialect SPI (mansart-data-dialect-spi) and the same static metamodel. No SQL duplication.

Status

⏳ M7 pending — see lien:https://codeberg.org/Vidocq/mansart/src/branch/main/mansart-persistence/PLAN.md[mansart-persistence/PLAN.md] (sketch) and lien:https://codeberg.org/Vidocq/mansart/src/branch/main/mansart-jakarta-data/PLAN.md[mansart-jakarta-data/PLAN.md] (M7 milestone "mansart-persistence bridge").

Target scope (to be refined):

  • EntityManagerFactory, EntityManager, Query, TypedQuery, EntityTransaction.

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

  • JPQL — superset of JDQL: explicit joins, subqueries, aggregates.

  • Criteria API.

  • Lifecycle listeners: @PrePersist, @PostPersist, @PreUpdate, @PostUpdate, @PreRemove, @PostRemove, @PostLoad.

  • JPA standard metamodel (Book_.title) — already generated by APT, shared with mansart-jakarta-data.

  • Schema generation — external (Flyway/Liquibase recommended).

  • Jakarta Persistence 3.2 TCK (date TBD).

Principles (already fixed)

  • Zero reflection — internal EntityManager consumes the static metamodel and the MethodHandle produced by APT. No runtime EntityManagerProxy.

  • No runtime bytecode — no Hibernate-style enhancement. Lazy loading via APT-generated intercepted getter (to be designed in M7).

  • Native virtual threads — every JDBC execution under Loom. No synchronized block wrapping a blocking I/O.

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

To plan in detail later

  • L1 cache strategy (HashMap per EM? virtual-thread-compatible?).

  • Persistence context handling across transaction suspend/resume.

  • Cascade PERSIST / MERGE / REMOVE on entity graphs.

  • Lazy loading without bytecode enhancement.

  • mansart-jakarta-data ↔ mansart-persistence co-existence in the same application (same Book consumed by both).

Meanwhile

For JPA needs in Vidocq today:

  • If CRUD + typed queries are enough → mansart-jakarta-data (delivered, TCK 73/73).

  • If advanced JPQL not covered by JDQL is needed → native SQL via @Query("…​") or Connection.prepareStatement(…​).

  • If JPA listeners are needed → application-level workaround (CDI interceptors, @Transactional + explicit before/after save).

  • If a persistence context is needed → migration deferred until M7 delivery.

See also