Vidocq Documentation

This page shows how to lay the first stone: an entity, a Jakarta Data repository, a Mansart DataSource, and a transaction. Targets H2 in-memory for speed; switching to PostgreSQL only changes the configuration.

Prerequisites

  • Java 25 (Temurin) + Maven 3.9.16.

  • JDBC driver provided by the application (com.h2database:h2 or org.postgresql:postgresql).

  • cd mansart && sdk env (or equivalent .sdkmanrc) to pin the JVM and Maven.

Maven dependencies

<dependencies>
  <dependency>
    <groupId>io.vidocq.mansart</groupId>
    <artifactId>mansart-data-api</artifactId>
    <version>${mansart.version}</version>
  </dependency>
  <dependency>
    <groupId>io.vidocq.mansart</groupId>
    <artifactId>mansart-data-core</artifactId>
    <version>${mansart.version}</version>
  </dependency>
  <dependency>
    <groupId>io.vidocq.mansart</groupId>
    <artifactId>mansart-data-dialect-h2</artifactId>
    <version>${mansart.version}</version>
  </dependency>
  <dependency>
    <groupId>io.vidocq.mansart</groupId>
    <artifactId>mansart-pool</artifactId>
    <version>${mansart.version}</version>
  </dependency>
  <dependency>
    <groupId>io.vidocq.mansart</groupId>
    <artifactId>mansart-transactions</artifactId>
    <version>${mansart.version}</version>
  </dependency>
  <dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <artifactId>maven-compiler-plugin</artifactId>
      <configuration>
        <annotationProcessorPaths>
          <path>
            <groupId>io.vidocq.mansart</groupId>
            <artifactId>mansart-data-processor</artifactId>
            <version>${mansart.version}</version>
          </path>
        </annotationProcessorPaths>
      </configuration>
    </plugin>
  </plugins>
</build>

The mansart-data-processor APT generates, at compile time, the metamodel (_Author) and the AuthorRepositoryImpl implementation. No runtime generation.

An entity

package shop;

import jakarta.persistence.*;

@Entity
@Table(name = "authors")
public class Author {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String name;

    // getters / setters / no-arg constructor
}

Mansart also accepts its zero-dep annotation set io.vidocq.mansart.data.@Entity when you want to avoid jakarta.persistence-api at the business module’s compile time. See Reference.

A repository

package shop;

import jakarta.data.repository.BasicRepository;
import jakarta.data.repository.Repository;

import java.util.List;
import java.util.Optional;

@Repository
public interface AuthorRepository extends BasicRepository<Author, Long> {

    long count();
    boolean existsById(Long id);

    List<Author> findByName(String name);
    Optional<Author> findOneByName(String name);
    long deleteByName(String name);
}

The APT generates shop.AuthorRepositoryImpl next to it, plus an entry in META-INF/mansart-repositories.list.

Standalone bootstrap

import io.vidocq.mansart.pool.MansartDataSource;
import io.vidocq.mansart.pool.PoolConfig;
import io.vidocq.mansart.data.MansartData;

var dataSource = MansartDataSource.create(PoolConfig.builder()
    .jdbcUrl("jdbc:h2:mem:shop;DB_CLOSE_DELAY=-1")
    .username("sa").password("")
    .minSize(2).maxSize(10)
    .build());

var authors = MansartData.repository(AuthorRepository.class, dataSource);

authors.save(new Author("Sylvie Germain"));
authors.findByName("Sylvie Germain").forEach(System.out::println);

CDI bootstrap (Vauban)

@Inject AuthorRepository authors;

@Transactional
public Author register(String name) {
    return authors.save(new Author(name));
}

The mansart-data-cdi BCE reads META-INF/mansart-repositories.list and declares an @ApplicationScoped bean for each @Repository interface detected. The mansart-transactions interceptor materializes @Transactional. See Vauban for the CDI container details.

Full example in Vidocq Runtime

The vidocq-runtime-mansart-h2-example example (in the Vidocq Runtime repo) shows end-to-end wiring: MansartDataSource + mansart-jakarta-data + @Transactional + Cassini REST endpoint. It is the reference sandbox to validate an integration.

Next step

  • Usage: pagination, JDQL, nested transactions.

  • Concepts: Repository, EntityManager, Transaction, Pool.