Documentation

Plugin JPA
Suffixes, artefacts, options et routage multi-module.

Référence complète du plugin JPA HexaGlue : suffixes de nommage, artefacts générés, options d'auditing JPA et configuration multi-module.

Installation

Ajouter le plugin JPA

<plugin>
    <groupId>io.hexaglue</groupId>
    <artifactId>hexaglue-maven-plugin</artifactId>
    <version>5.0.0</version>
    <extensions>true</extensions>
    <configuration>
        <basePackage>com.acme.shop</basePackage>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>io.hexaglue.plugins</groupId>
            <artifactId>hexaglue-plugin-jpa</artifactId>
            <version>2.0.0</version>
        </dependency>
    </dependencies>
</plugin>

La génération s'exécute automatiquement lors de la phase generate-sources (mvn compile). Les artefacts sont générés dans target/generated-sources/hexaglue/.

Trois éléments clés dans cette configuration :

<extensions>true</extensions> : active le binding automatique aux phases Maven. Les goals HexaGlue se déclenchent sans configuration supplémentaire lors de mvn compile.
<basePackage> : package racine à analyser. Seules les classes de ce package et de ses sous-packages sont classifiées par HexaGlue.
Le plugin JPA est déclaré comme <dependency> du plugin Maven, pas du projet. HexaGlue découvre automatiquement les plugins via le mécanisme Java ServiceLoader : il suffit de les ajouter ici pour qu'ils soient actifs.

Le plugin génère du code qui utilise Spring Data JPA et MapStruct. Ajoutez ces dépendances à votre pom.xml :

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>1.6.3</version>
    </dependency>
</dependencies>

Configuration

Toutes les options

Le fichier hexaglue.yaml, placé à la racine du projet (à côté du pom.xml), centralise la configuration de HexaGlue et de tous ses plugins.
Les options ci-dessous se configurent dans la section plugins.io.hexaglue.plugin.jpa: du fichier YAML.
Les paramètres Maven (<configuration>) sont prioritaires sur les valeurs YAML.

Option	Type	Défaut	Description
`entitySuffix`	string	`"Entity"`	Suffixe ajouté aux noms de classes pour les entités JPA générées
`embeddableSuffix`	string	`"Embeddable"`	Suffixe pour les classes `@Embeddable` (value objects persistés)
`repositorySuffix`	string	`"JpaRepository"`	Suffixe pour les interfaces Spring Data Repository
`adapterSuffix`	string	`"Adapter"`	Suffixe pour les implémentations d'adapter de port
`mapperSuffix`	string	`"Mapper"`	Suffixe pour les interfaces MapStruct
`tablePrefix`	string	`""` (vide)	Préfixe ajouté à tous les noms de tables en base
`enableAuditing`	boolean	`false`	Génère les champs `@CreatedDate` et `@LastModifiedDate`
`enableOptimisticLocking`	boolean	`false`	Génère un champ `@Version` pour le verrouillage optimiste
`generateRepositories`	boolean	`true`	Génère les interfaces Spring Data JPA Repository
`generateMappers`	boolean	`true`	Génère les mappers MapStruct bidirectionnels
`generateAdapters`	boolean	`true`	Génère les implémentations d'adapter de port
`generateEmbeddables`	boolean	`true`	Génère les classes `@Embeddable` pour les value objects
`infrastructurePackage`	string	`"{basePackage}.infrastructure.persistence"`	Package cible pour les artefacts JPA générés
`targetModule`	string	`null`	Multi-module : identifiant du module cible pour le routage des artefacts générés

Génération

Ce qui est généré pour chaque agrégat

Pour chaque agrégat détecté dans le domaine, le plugin produit jusqu'à 5 types d'artefacts. La génération de chaque type est contrôlable individuellement.

Artefact	Exemple (`Order`)	Annotations	Option
Entité JPA	`OrderEntity`	`@Entity`, `@Table`, `@Id`, `@Column`	Toujours généré
Embeddable	`MoneyEmbeddable`	`@Embeddable`	`generateEmbeddables`
Repository	`OrderJpaRepository`	`extends JpaRepository<T, ID>`	`generateRepositories`
Mapper	`OrderMapper`	`@Mapper(componentModel = "spring")`	`generateMappers`
Adapter	`OrderAdapter`	`@Component`, `@Transactional`	`generateAdapters`

Les value objects simples (records à un seul champ comme record Quantity(int value)) ne génèrent pas d'embeddable. Ils sont automatiquement dépliés vers leur type primitif dans les entités JPA.

Tous les artefacts sont générés dans le package {basePackage}.infrastructure.persistence par défaut. Ce package est configurable via l'option infrastructurePackage.

Fonctionnalités JPA

Auditing et verrouillage optimiste

Ces deux options ajoutent des champs techniques aux entités JPA générées. Elles sont désactivées par défaut et s'activent dans hexaglue.yaml.

Quand `enableAuditing: true`

Chaque entité JPA générée inclut deux champs supplémentaires :

@CreatedDate
@Column(updatable = false)
private Instant createdAt;

@LastModifiedDate
private Instant updatedAt;

Quand `enableOptimisticLocking: true`

Chaque entité JPA générée inclut un champ version :

@Version
private Long version;

Multi-module

Routage des artefacts en multi-module

En multi-module, les artefacts JPA doivent être générés dans le module d'infrastructure, pas dans le module de domaine. Le plugin résout le module cible selon cette priorité :

1
Configuration explicite : targetModule: "banking-persistence" dans hexaglue.yaml
2
Auto-routage par convention : si un seul module a le rôle INFRASTRUCTURE, les artefacts y sont routés automatiquement
3
Défaut : si ni configuration ni convention ne s'appliquent, les artefacts sont écrits dans le répertoire de sortie par défaut

Si plusieurs modules ont le rôle INFRASTRUCTURE et qu'aucun targetModule n'est configuré, le plugin émet un avertissement et utilise le répertoire de sortie par défaut. Préférez la configuration explicite dans ce cas.

modules:
  banking-core:
    role: DOMAIN
  banking-persistence:
    role: INFRASTRUCTURE
  banking-service:
    role: APPLICATION

plugins:
  io.hexaglue.plugin.jpa:
    targetModule: "banking-persistence"
    generateRepositories: true
    generateAdapters: true

Exemple

Configuration complète

Cet exemple regroupe toutes les options du plugin JPA dans un seul fichier hexaglue.yaml. En pratique, seules les options dont vous souhaitez modifier la valeur par défaut sont nécessaires.

plugins:
  io.hexaglue.plugin.jpa:
    # Suffixes de nommage
    entitySuffix: "JpaEntity"
    embeddableSuffix: "Embeddable"
    repositorySuffix: "JpaRepository"
    adapterSuffix: "RepositoryAdapter"
    mapperSuffix: "Mapper"

    # Nommage des tables
    tablePrefix: "app_"

    # Package cible
    infrastructurePackage: "com.acme.shop.infrastructure.persistence"

    # Fonctionnalités JPA
    enableAuditing: true
    enableOptimisticLocking: true

    # Contrôle de la génération
    generateRepositories: true
    generateMappers: true
    generateAdapters: true
    generateEmbeddables: true

    # Multi-module (optionnel)
    # targetModule: "banking-persistence"

Votre domaine mérite mieux que des annotations JPA.
Configurez la génération en quelques lignes.

Voyez la génération en action sur un projet réel ou explorez toutes les options du plugin.

Comprendre la génération JPA Voir la génération en action

Plugin JPASuffixes, artefacts, options et routage multi-module.