9. Maven plugins
9.1 Plugin Types
9.2 Archetype plugin
9.3 Maven release plugin
9.4 Custom Maven plugins
9.4.1 Writing plugins
9.4.2 Documenting plugins
9.4.3 Mojo
9.1 Plugin Types
Maven provides useful tools for software projects creation and management.
- easy project build
- customizes the project object model
- standard project life cycle
- dependency management system.
Maven is a plugin execution framework. A plugin can create a new packaging type. it can add new actions to the build process, customizing the lifecycle. Plugins are used especially for packaging, testing, project documentation and project reports.
The functionality of Maven can be extended for writing plugins. Maven itself is a collection of plugins.
Plugins are grouped according to a directory structure similar to Java package naming convention.
Some examples of Maven plugins:
Core plugins
- clean
- compiler
- deploy
Packaging types/tools
- ear
- jar
- war
- rar
Reporting plugins
- changelog
- changes
- checkstyle
- docck
- javadoc
Tools
- ant
- antrun
- enforcer
IDEs
- eclipse
The syntax for executing the goals of a plugin is:
mvn [plugin-name]:[goal-name]
For example:
mvndeploy:deploy-file
or:
mvnclean:clean
The following command will generate the deployment descriptor application.xml for the project.
9.2 Archetype plugin
Maven archetype plugins are project templates that can be used for creating new projects starting from some core files.
A simple project can be transformed into a template in 2 ways:
- select the necessary files and add them to the new future project
- run Maven archetype plugin on an existing project and configure it.
Some Maven archetypes are contained in the groupIdorg.apache.maven.archetypes. The most notable are:
maven-archetype-quickstart | Project with JAR packaging and JUnit dependency. Contain the class App with main() method. Contains also a JUnit test class named AppTest() and testApp() method. |
maven-archetype-webapp
| Project with WAR packaging and Junit dependency. The directory structure is specific to web applications containing ${basedir}/src/main/webapp directory with index.jsp page and web.xml file. |
maven-archetype-mojo
| Project with maven-plugin packaging and class MyMojo. The class contains touch goal bound to process-resource phase and creates the file touch.txt and target/directory when the new project is executed. The project contains a dependency on maven –plugin-api and JUnit. |
Other notable third-party archetypes are AppFuse (end to end tired-applications with Java, Spring, Hibernate), Confluence and Jira plugins (issue trackers with Apache Velocity, Spring, Postrgessql, Rest web services), Wicket (server-side management with Spring and Ruby on Rails).
In order to create a new archetype there are necessary some actions:
- archetype name
- command line to call the archetype
- check if the archetype can be used in the projects directory
- a tree view of the resulting files
- additional properties used by the plugin
The projects can be created from command line (see chapter 2) with the statement called from the root directory of the project:
mvnarchetype:generate\ -DgroupId=com.somecompany.app\ -DartifactId=somecompany-app \ -DarchetypeArtifactId=maven-archetype-quickstart \ -DinteractiveMode=false
See in chapter 2.3 Create new project with Maven the result in the console and POM.
9.3 Maven release plugin
This plugin is used to release a project with Maven. It works in combination with Jenkins plugin.
With Maven Release Plugin there can be done the following actions:
- prepare a release
- perform a release
- Rollback a release
- Clean a release
- Generate release POM
- Lock files during release
- Run additional goals before commit
- Create a branch
- Non-interactive release
- Update POM versions
For multi-module projects it is preferable to get the same version for all the modules as the parent POM so the option autoVersionSubmodules has to be set to true.
9.4 Custom Maven plugins
Maven provides extension capabilities for pluging-in custom plugins in the form of MOJOs.
With Maven we can create custom Maven plugins that can be executed in stand-alone mode as part of the Maven life-cycle.
9.4.1 Writing plugins
A plugin can be done by creating a new Java class that extends certain Maven class and then create POM for the project. The plugin should have the location in a separate project.
A plugin can have one or more goals that can be called from command line or integrated with project build phases.
mvnarchetype:create -DgroupId=com.mymavenplugin.app -DartifactId=mymavenplugin-app -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-mojo
The console output is:
[INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building Maven Stub Project (No POM) 1 [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- maven-archetype-plugin:2.2:create (default-cli) @ standalone-pom --- [WARNING] This goal is deprecated. Please use mvnarchetype:generate instead [INFO] Defaulting package to group ID: com.mymavenplugin.app …… [INFO] ---------------------------------------------------------------------------- [INFO] Using following parameters for creating project from Old (1.x) Archetype: maven-archetype-mojo:RELEASE [INFO] ---------------------------------------------------------------------------- [INFO] Parameter: groupId, Value: com.mymavenplugin.app [INFO] Parameter: packageName, Value: com.mymavenplugin.app [INFO] Parameter: package, Value: com.mymavenplugin.app [INFO] Parameter: artifactId, Value: mymavenplugin-app [INFO] Parameter: basedir, Value: C:\my maven mojo [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] project created from Old (1.x) Archetype in dir: C:\my maven mojo\mymavenplugin-app [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 12.983 s [INFO] Finished at: 2014-10-20T05:51:05+03:00 [INFO] Final Memory: 9M/23M [INFO] ------------------------------------------------------------------------
The POM of the Plugin Project:
<project...> <modelVersion>4.0.0</modelVersion> <groupId>com.mymavenplugin.app</groupId> <artifactId>mymavenplugin-app</artifactId> <packaging>maven-plugin</packaging> <version>1.0-SNAPSHOT</version> <name>mymavenplugin-app Maven Mojo</name> <url>http://maven.apache.org</url> <dependencies> <dependency> <groupId>org.apache.maven</groupId> <artifactId>maven-plugin-api</artifactId> <version>2.0</version> </dependency> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>3.8.1</version> <scope>test</scope> </dependency> </dependencies> </project>
The project is different from a regular java project because it is not a usual java artifact like JAR, WAR etc. The package type maven - plugin indicates that is a maven plugin project.
The project can be imported to Eclipse with the command line with the command :
mvneclipse:eclipse
In Eclipse select File menu>Import>Existitng project into workspace or Maven Project and specify the directory for the project.
This step will create the Eclipse .project and .classpath files.
9.4.2 Documenting plugins
Documentation can be automatically generated using the command
mvn site
C:\my maven plugin\mymavenplugin-app>mvn site [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building mymavenplugin-app 1.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ ……… [INFO] Rendering site with org.apache.maven.skins:maven-default-skin:jar:1.0 skin. [INFO] Generating "About" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Plugin Management" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Distribution Management" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Dependency Information" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Source Repository" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Mailing Lists" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Issue Tracking" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Continuous Integration" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Project Plugins" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Project License" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Project Team" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Project Summary" report --- maven-project-info-reports-plugin:2.7 [INFO] Generating "Dependencies" report --- maven-project-info-reports-plugin:2.7 [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 01:10 min [INFO] Finished at: 2014-10-19T23:55:15+03:00 [INFO] Final Memory: 13M/40M [INFO] ------------------------------------------------------------------------
In order to ensure a good documentation the project’s POM has to be completed. Optional elements referring to organization details, names, descriptions, URLs, mailing lists, issue/ bug trackers, source code repositories are correctly filled in.
Then it has to be checked if the documentation complies with the Maven community standards by running the command :
mvndock:check
Recommended reporting plugins for a Maven plugins are:
Maven Javadoc plugin
Maven JXR plugin
9.4.3 Mojo
Mojo is a single Java class which contains some annotations that command to Maven how to generate the Plugin descriptor.
Before to create Mojo classes it is necessary to create a Maven project from the groupIdmaven-archetype-mojo. See chapter 8.4.1 Writing plugins. After creating the project compile it with:
mvn clean install
command.
In javadoc annotations it has to be specified the goal or eventually the phase. See below:
packagecom.mymavenplugin.app;
importorg.apache.maven.plugin.AbstractMojo;
importorg.apache.maven.plugin.MojoExecutionException;
importorg.apache.maven.plugin.MojoFailureException;
/**
* @goal mymojo-info
*/
public class MyMojoInfo extends AbstractMojo{
public void execute() throws MojoExecutionException, MojoFailureException {
getLog().info("This is my first Mojo!");
}
}
In POM.xml of the new project that is using this mojo after the dependencies tag the following lines have to be added:
<build> <plugins> <plugin> <groupId>com.mymavenplugin.app</groupId> <artifactId>mymavenplugin-app</artifactId> <version>1.0-SNAPSHOT</version> <executions> <execution> <id>mymojo-info-compile</id> <phase>compile</phase> <goals> <goal>mymojo-info</goal> </goals> </execution> <execution> <id>mymojo-info-install</id> <phase>install</phase> <goals> <goal>mymojo-info</goal> </goals> </execution> </executions> </plugin> </plugins> </build>
Compile the project with
mvn clean install
The following output will be obtain:
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] myapp
[INFO] myapp-application
[INFO] myapp-web
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building myapp 0.0.1-SNAPSHOT
[INFO] ------------------------------------------------------------------------
….
[INFO]
[INFO] --- mymavenplugin-app:1.0-SNAPSHOT:mymojo-info (date-info-compile) @ myapp ---
[INFO] This is my first Mojo!
…….
[INFO]
[INFO] --- mymavenplugin-app:1.0-SNAPSHOT:mymojo-info (date-info-install) @ myapp-web ---
[INFO] This is my first Mojo!
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] myapp .............................................. SUCCESS [ 25.806 s]
[INFO] myapp-application .................................. SUCCESS [ 28.307 s]
[INFO] myapp-web .......................................... SUCCESS [ 2.882 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 57.222 s
[INFO] Finished at: 2014-10-20T07:16:46+03:00
[INFO] Final Memory: 11M/28M
[INFO] ------------------------------------------------------------------------