09 - Maven plugins

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

Like us on Facebook