Vidocq Documentation

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 Java class annotated @jakarta.persistence.Entity (or its zero-dep Mansart equivalent @io.vidocq.mansart.data.Entity). It represents a row in a SQL table. Mansart reads its annotations at compile time through APT and generates a static metamodel (Book or Book); no classpath scan at startup.

Recognized attributes: @Id, @GeneratedValue, @Column, @Table, @Version, @Enumerated, @Embedded/@Embeddable, @ManyToOne, @OneToOne, @JoinColumn, @Transient. Collections (@OneToMany, @ManyToMany) and inheritance are deferred to mansart-persistence (M7).

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, delete, findById, findAll, count, existsById).

  • CrudRepository<T, K> — extends BasicRepository with batch variants.

  • 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. Out of scope for mansart-jakarta-data; will be provided by mansart-persistence (M7 pending — 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 by a ScopedValue<TransactionContext> — transparent propagation across virtual threads created via StructuredTaskScope.

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:

  • Deque<PooledConnection> idle — lock-free stack of available connections.

  • Set<PooledConnection> inUse — currently borrowed connections.

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

  • ScopedValue<Connection> CURRENT — connection bound to the current transaction.

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

SQL dialect

MansartDialect — 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>. Interop for future 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 superset (explicit joins, subqueries, aggregates), handled by mansart-persistence (M7). For now, JPQL needs are covered by JDQL or by native SQL.

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 73/73)

⏳ M7 pending