Vidocq Documentation
Version

Mansart’s technical lexicon. Sets the common definitions across the four sub-modules to avoid ambiguity when reading internals.adoc or reference.adoc.

Entity

A managed Java class representing persistent state. Jakarta Data reads mapping annotations through APT; Persistence supports annotations and XML metadata, with a shared class-file model and generated entity accesses. Its recommended APT path keeps entity packages closed; bootstrap generation is also available for classes compiled without the processor.

Jakarta Data supports basic attributes, embeddables and to-one references. Persistence additionally implements collections, inheritance, converters and XML overrides within the boundaries documented in mansart-persistence.

Repository

An interface annotated @jakarta.data.repository.Repository. Specifies what the application wants to do with the entity, without prescribing the exact SQL. Mansart materializes the interface as a XxxRepositoryImpl class at compile time (APT). No runtime reflection, no dynamic proxy.

Three standard roots:

  • BasicRepository<T, K> — minimal CRUD (save, saveAll, findById, findAll, deleteById, delete, deleteAll).

  • CrudRepository<T, K> — extends BasicRepository with insert/insertAll/update/updateAll.

  • DataRepository<T, K> — fully free-form repository, composed from named methods and @Query.

EntityManager

A Jakarta Persistence 3.2 concept — entity lifecycle manager (managed/detached), modification queue, flush/commit propagation. Implemented by mansart-persistence, independently of Jakarta Data repositories; see mansart-persistence.

In Vidocq, the common need (CRUD + typed queries) is already covered by Jakarta Data repositories, which bypass the EntityManager in favor of direct ResultSet mapping via MethodHandle.

Transaction

Atomic boundary around a set of operations on one or more resources. Mansart implements Jakarta Transactions 2.0:

  • TransactionManager — SPI, container-managed. begin/commit/rollback, suspend/resume, enlistResource/delistResource.

  • UserTransaction — user-facing API, programmatic.

  • @Transactional — declarative CDI interceptor, supports the six standard TxTypes.

  • TransactionScoped — CDI scope whose lifetime matches the transaction.

The transactional context is carried in a ThreadLocal — a deliberate choice: the Jakarta Transactions API is imperative (begin() returns, commit() comes later from arbitrary call sites), which cannot fit ScopedValue’s enclosing-scope model; `ThreadLocal works on virtual threads exactly as on platform threads.

ConnectionPool

A bounded cache of physical java.sql.Connection. Avoids the connect/disconnect cost on every query. mansart-pool provides MansartDataSource implements javax.sql.DataSource:

  • ConcurrentLinkedDeque<PooledEntry> idle — lock-free stack of available connections.

  • Set<PooledEntry> inUse — currently borrowed connections (ConcurrentHashMap.newKeySet).

  • Semaphore permits — size = maxSize, blocks acquisition above it.

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

SQL dialect

Dialect (io.vidocq.mansart.data.dialect) — SPI that isolates SQL differences across databases: pagination (LIMIT/OFFSET vs FETCH FIRST), upsert (ON CONFLICT vs MERGE), identifier return (RETURNING vs getGeneratedKeys), types (UUID, JSONB, BOOLEAN).

Discovered via ServiceLoader (provides DialectFactory with H2DialectFactory). Shipped dialects: H2, PostgreSQL. Others on the backlog (MariaDB, SQL Server).

Static metamodel

Classes generated by APT next to the entities. Two formats:

  • Mansart rich format (_Book) — _Book.title is a TextAttribute<Book> with columnName(), MethodHandle getter(), etc. Lets the dialect produce specialized SQL without an instanceof chain.

  • JPA standard format (Book_) — Book_.title is a SingularAttribute<Book, String>, used by the implemented Criteria API.

MethodHandle instances are obtained once at <clinit> via MethodHandles.privateLookupIn(…​) — never any runtime reflection.

JDQL vs JPQL

  • JDQL (Jakarta Data Query Language) — simplified subset defined by Jakarta Data 1.0. SELECT/UPDATE/DELETE on entities, LIKE, BETWEEN, ORDER BY, named parameters. Mansart supports it via @Query in mansart-jakarta-data.

  • JPQL (Jakarta Persistence Query Language) — richer entity query language (explicit joins, subqueries, aggregates), implemented by mansart-persistence and sharing its execution path with Criteria.

Jakarta Data vs JPA differences

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

API

Typed declarative repositories

Imperative EntityManager

Entity lifecycle

Stateless — no managed/detached

Persistence context (managed)

L1 cache

None

Persistence context

Queries

Method names + JDQL + lifecycle annotations

JPQL + Criteria API

Mansart status

✅ Delivered (TCK 74/74)

✅ P0–P12 delivered within scope; local patched TCK, not certification