Vidocq Documentation

Cette page montre comment poser la première pierre : une entité, un repository Jakarta Data, un DataSource Mansart et une transaction. Cible H2 in-memory pour aller vite ; le passage à PostgreSQL ne change que la config.

Prérequis

  • Java 25 (Temurin) + Maven 3.9.16.

  • Driver JDBC fourni par l’application (com.h2database:h2 ou org.postgresql:postgresql).

  • cd mansart && sdk env (ou .sdkmanrc équivalent) pour caler la JVM et Maven.

Dépendances Maven

<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>

L’APT mansart-data-processor génère, à compile, le métamodèle (_Author) et l’implémentation AuthorRepositoryImpl. Aucune génération à l’exécution.

Une entité

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 / constructeur sans-arg
}

Mansart accepte aussi son set d’annotations zéro-dep io.vidocq.mansart.data.@Entity quand on veut éviter jakarta.persistence-api au compile-time du module métier. Voir Référence.

Un 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);
}

L’APT génère shop.AuthorRepositoryImpl à côté, plus une entrée dans META-INF/mansart-repositories.list.

Bootstrap standalone

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);

Bootstrap CDI (Vauban)

@Inject AuthorRepository authors;

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

La BCE mansart-data-cdi lit META-INF/mansart-repositories.list et déclare un bean @ApplicationScoped par interface @Repository détectée. L’intercepteur mansart-transactions matérialise @Transactional. Voir Vauban pour le détail du conteneur CDI.

Exemple complet dans Vidocq Runtime

L’exemple vidocq-runtime-mansart-h2-example (dans le repo Vidocq Runtime) montre le wiring de bout en bout : MansartDataSource + mansart-jakarta-data + @Transactional + endpoint REST Cassini. C’est le bac à sable de référence pour valider une intégration.

Étape suivante

  • Cas d’usage : pagination, JDQL, transactions imbriquées.

  • Concepts : Repository, EntityManager, Transaction, Pool.