Comment créer un plugin Maven

1. Introduction

Maven propose une grande variété de plugins pour nous aider dans la construction de notre projet. Cependant, nous pouvons trouver des cas où ces plugins ne sont pas suffisants et nous devons développer les nôtres.

Heureusement, Maven fournit des outils utiles pour nous aider dans ce processus.

Dans ce tutoriel, nous serons très pratiques et montrerons étape par étape comment créer un plugin Maven à partir de zéro.

Nous montrerons également comment l'utiliser dans nos projets et comment créer de la documentation pour cela.

2. Création d'un plugin

Au cours de ce tutoriel, nous développerons un plugin appelé counter-maven-plugin qui comptera le nombre de dépendances qu'un projet contient. Il est très important de suivre la convention de dénomination du plugin que Maven recommande lorsque nous choisissons le nom de notre plugin.

Maintenant que nous savons ce que nous allons développer, la prochaine chose que nous devons faire est de créer un projet Maven. Dans le pom.xml, nous définirons le groupId , artifactId et la version de notre plugin:

 4.0.0 com.baeldung counter-maven-plugin maven-plugin 0.0.1-SNAPSHOT counter-maven-plugin Maven Mojo //maven.apache.org  1.8 1.8  

Notez que nous avons défini le packaging sur maven-plugin .

Dans ce cas, nous avons créé le projet manuellement mais nous pourrions également le faire en utilisant le maven-archetype-mojo :

mvn archetype:generate -DgroupId=com.baeldung -DartifactId=counter-maven-plugin -Dversion=0.0.1-SNAPSHOT -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-mojo

Ce faisant, nous devons mettre à jour les versions par défaut des dépendances pour utiliser les dernières.

3. Créer un Mojo

Il est maintenant temps de créer notre premier mojo. Mojo est une classe Java qui représente un objectif que notre plugin exécutera . Un plugin contient un ou plusieurs mojos.

Notre mojo se chargera de compter le nombre de dépendances d'un projet.

3.1. Ajouter des dépendances

Avant de créer le mojo, nous devons ajouter des dépendances à notre pom.xml :

  org.apache.maven maven-plugin-api 3.6.3   org.apache.maven.plugin-tools maven-plugin-annotations 3.6.0 provided   org.apache.maven maven-project 2.2.1  

La dépendance maven-plugin-api est requise et contient les classes et interfaces nécessaires pour créer notre mojo . La dépendance maven-plugin-annotations est pratique pour utiliser les annotations dans nos classes. La dépendance maven-project nous permet d'accéder aux informations sur le projet dans lequel nous incluons le plugin.

3.2. Création de la classe Mojo

Nous sommes maintenant prêts à créer notre mojo!

Un mojo doit implémenter l' interface Mojo . Dans notre cas, nous allons étendre de AbstractMojo donc nous n'aurons qu'à implémenter la méthode execute :

@Mojo(name = "dependency-counter", defaultPhase = LifecyclePhase.COMPILE) public class DependencyCounterMojo extends AbstractMojo { // ... }

Comme nous pouvons le voir, dependency-counter est le nom de l'objectif. D'autre part, nous l'avons attaché à la phase de compilation par défaut, nous n'aurons donc pas nécessairement à spécifier une phase lors de l'utilisation de cet objectif.

Pour avoir accès aux informations du projet, nous devons ajouter un MavenProject comme paramètre:

@Parameter(defaultValue = "${project}", required = true, readonly = true) MavenProject project;

Cet objet sera injecté par Maven lors de la création du contexte.

À ce stade, nous pouvons implémenter la méthode execute et compter le nombre de dépendances du projet:

public void execute() throws MojoExecutionException, MojoFailureException { List dependencies = project.getDependencies(); long numDependencies = dependencies.stream().count(); getLog().info("Number of dependencies: " + numDependencies); }

La méthode getLog () permet d'accéder au journal Maven. Le AbstractMojo gère déjà son cycle de vie.

3.3. Ajout de paramètres

Le paramètre que nous avons ajouté auparavant est en lecture seule et ne peut pas être configuré par l'utilisateur. De plus, il est injecté par Maven pour que nous puissions dire que c'est un peu spécial.

Dans cette section, nous allons ajouter un paramètre où les utilisateurs peuvent spécifier la portée des dépendances que nous voulons compter.

Par conséquent, créons un paramètre de portée dans notre mojo:

@Parameter(property = "scope") String scope;

Nous avons uniquement défini l' attribut de propriété . Cela nous permet de définir cette propriété via la ligne de commande ou une propriété pom . Pour le reste des attributs, nous acceptons les valeurs par défaut.

Nous allons maintenant modifier notre méthode d' exécution pour utiliser ce paramètre et filtrer les dépendances lors du comptage:

public void execute() throws MojoExecutionException, MojoFailureException  List dependencies = project.getDependencies(); long numDependencies = dependencies.stream() .filter(d -> (scope == null 

Des types de paramètres plus avancés sont expliqués dans la documentation officielle.

4. Test du plugin

Nous avons terminé le développement du plugin. Testons-le pour voir si cela fonctionne!

Tout d'abord, nous devons installer le plugin dans notre référentiel local:

mvn clean install

Dans les sections suivantes, nous verrons d'abord comment exécuter notre plugin à partir de la ligne de commande. Ensuite, nous verrons également comment l'utiliser dans un projet Maven.

4.1. Exécuter notre plugin

Nous pouvons exécuter l'objectif d'un plugin dans la ligne de commande en spécifiant son nom complet:

mvn groupId:artifactId:version:goal

Dans notre cas, cela ressemble à ceci:

mvn com.baeldung:counter-maven-plugin:0.0.1-SNAPSHOT:dependency-counter

Cependant, si nous avons suivi la convention de dénomination des plugins que nous avons mentionnée au début de ce tutoriel, Maven résoudra le préfixe de notre plugin et nous pourrons raccourcir la commande:

mvn counter:dependency-counter

Notice that this command is using the latest version of the plugin. Also, keep in mind that we have to add our groupId to the pluginGroups of our settings.xml so Maven also searches in this group:

 com.baeldung 

If we check the output of the command, we can see that the plugin counted the number of dependencies in the pom.xml of our plugin:

[INFO] Scanning for projects... [INFO] [INFO] ----------------------------------- [INFO] Building counter-maven-plugin Maven Mojo 0.0.1-SNAPSHOT [INFO] ----------------------------[ maven-plugin ]---------------------------- [INFO] [INFO] --- counter-maven-plugin:0.0.1-SNAPSHOT:dependency-counter (default-cli) @ counter-maven-plugin --- [INFO] Number of dependencies: 3 [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 0.529 s [INFO] Finished at: 2019-11-30T20:43:41+01:00 [INFO] ------------------------------------------------------------------------

We can also set the scope parameter via command line properties:

mvn counter:dependency-counter -Dscope=test

Notice that the scope name is the one that we defined in the property attribute of our parameter in the mojo.

4.2. Using Our Plugin in a Project

Let's test now our plugin by using it in a project!

We're going to create a very simple Maven project with some dependencies that our plugin will count:

 4.0.0 com.baeldung example pom 0.0.1-SNAPSHOT   org.apache.commons commons-lang3 3.9   junit junit 4.12 test   

The last thing is to add our plugin to the build. We have to explicitly set that we want to run the dependency-counter goal:

   com.baeldung counter-maven-plugin 0.0.1-SNAPSHOT    dependency-counter     test    

Notice that we've specified the scope parameter in the configuration node. Also, we haven't specified any phase because our mojo is attached to the compile phase by default.

Now, we just need to run the compile phase to execute our plugin:

mvn clean compile

And our plugin will print the number of test dependencies:

[INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------ [INFO] Building example 0.0.1-SNAPSHOT [INFO] --------------------------------[ pom ]--------------------------------- [INFO] [INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ example --- [INFO] [INFO] --- counter-maven-plugin:0.0.1-SNAPSHOT:dependency-counter (default) @ example --- [INFO] Number of dependencies: 1 [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 0.627 s [INFO] Finished at: 2019-11-25T18:57:22+01:00 [INFO] ------------------------------------------------------------------------

In this tutorial, we're not covering how to write unit or integration tests for our plugin but Maven provides some mechanisms to do it.

5. Adding Documentation

When we create a Maven plugin, it's important to generate documentation to make it easy for other people to use it.

We'll briefly cover how to generate this documentation with maven-plugin-plugin.

maven-plugin-plugin is already included in the project, but we're gonna update it to use the latest version.

Also, we'll do the same for maven-site-plugin:

    org.apache.maven.plugins maven-plugin-plugin 3.6.0   org.apache.maven.plugins maven-site-plugin 3.8.2    

Then, we have to make sure that we've added javadoc to our Mojo and also add some metadata in the pom.xml of the plugin:

 Baeldung //www.baeldung.com/ 

After that, we need to add a reporting section in our pom.xml:

   org.apache.maven.plugins maven-plugin-plugin    report      

Finally, we'll generate the documentation with the maven site command:

mvn site

Inside the target folder, we can find a site directory with all the HTML files generated. The plugin-info.html is the one containing the plugin documentation:

More options to add to our documentation can be found on the Maven plugin documentation guide.

6. Conclusion

In this tutorial, we've shown how to create a Maven plugin. We first implemented a simple plugin, which helped us see a typical Maven plugin project structure. Then, we covered some of the tools that Maven provides to help us develop plugins.

We've kept it simple to make things clearer, but at the same time, we've provided some useful links with the necessary information on how to create a more powerful plugin.

Comme toujours, le code source complet des exemples est disponible à l'adresse over sur GitHub.