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>6.1.1</version>
    <extensions>true</extensions>
    <configuration>
        <basePackage>com.acme.shop</basePackage>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>io.hexaglue.plugins</groupId>
            <artifactId>hexaglue-plugin-jpa</artifactId>
            <version>3.1.1</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.

Les projets utilisant Lombok sont pris en charge nativement depuis HexaGlue 6.0.0 : le delombok est injecté automatiquement avant l'analyse, aucune configuration spéciale n'est nécessaire côté plugin.

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

Paramètres Maven

La configuration de la génération se fait via les paramètres <configuration> du plugin Maven dans le pom.xml.
Ces paramètres contrôlent le package analysé, le répertoire de sortie et le comportement en cas de types non classifiés.
Le paramètre skip peut aussi être passé en ligne de commande via -Dhexaglue.skip=true.

Option	Défaut	Description
`basePackage`	(requis)	Package racine à analyser. Les artefacts JPA sont générés à partir des types de domaine de ce package.
`failOnUnclassified`	`false`	Fait échouer le build si des types du domaine ne peuvent pas être classifiés
`outputDirectory`	`/generated-sources/hexaglue`	Répertoire où les entités JPA, repositories et mappers sont écrits
`skip`	`false`	Désactive complètement l'exécution de HexaGlue (configurable via `-Dhexaglue.skip=true`)
`skipValidation`	`false`	Ignore la validation des classifications avant la génération JPA
`tolerantResolution`	`false`	Active la résolution tolérante des types non résolus. Utile pour les projets utilisant des annotation processors (MapStruct, Immutables) dont le code généré n'est pas encore sur le classpath (configurable via `-Dhexaglue.tolerantResolution=true`)

Configuration

Options YAML

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
`idStrategy`	string	`ASSIGNED`	Stratégie `@GeneratedValue` ajoutée au champ `@Id` des entités JPA générées. Contrôle comment la base de données attribue les identifiants.
`targetModule`	string	`null`	Multi-module : identifiant du module cible pour le routage des artefacts générés
`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
`outputDirectory`	string	(défaut global)	Répertoire de sortie spécifique au plugin. Utilisez `src/main/java` pour écrire les artefacts JPA directement dans votre arbre source au lieu de `target/`. Les fichiers existants sont écrasés à chaque build (voir note ci-dessous).

Le paramètre idStrategy contrôle l'annotation @GeneratedValue ajoutée au champ @Id des entités JPA générées. Le domaine reste pur : aucune annotation JPA n'y est nécessaire.

ASSIGNED (défaut) : pas de @GeneratedValue, l'application fournit l'identifiant (adapté aux identifiants métier ou UUID générés dans le domaine)
IDENTITY : auto-incrément géré par la base (MySQL, SQL Server, PostgreSQL)
SEQUENCE : séquence de base de données (PostgreSQL, Oracle)
UUID : génération d'UUID déléguée au provider JPA
AUTO : le provider JPA choisit la stratégie selon la base
TABLE : table dédiée simulant une séquence (portable, moins performant)

Les fichiers générés sont systématiquement écrasés à chaque build. Si vous redirigez la sortie vers src/main/java via outputDirectory, toute modification manuelle des fichiers générés sera perdue au prochain mvn compile.
Un avertissement est émis dans les logs Maven lorsqu'un fichier existant est écrasé.

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

    # Stratégie @GeneratedValue sur le champ @Id généré
    idStrategy: "ASSIGNED"

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

Besoin d'une génération sur mesure ?

Ce plugin couvre les patterns de persistance les plus courants, mais chaque entreprise a ses propres conventions et exigences techniques. L'architecture ouverte d'HexaGlue vous permet de créer des plugins adaptés à votre stack.

Plugins sur mesure Services Nous contacter

Concentrez-vous sur le métier.
Générez la persistance en quelques lignes.

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

Voir la génération en action Se faire accompagner

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