maven开发java插件【译】

介绍

This guide is intended to assist users in developing Java plugins for Maven 2.0.

本指南旨在帮助用户在 Maven 2.0 开发 Java 插件。

Important Notice: Plugin Naming Convention and Apache Maven Trademark

You will typically name your plugin <yourplugin>-maven-plugin.

通常这样命名你的插件  <yourplugin>-maven-plugin.

Calling it maven-<yourplugin>-plugin (note "Maven" is at the beginning of the plugin name) is strongly discouraged since it's a reserved naming pattern for official Apache Maven plugins maintained by the Apache Maven team with groupId org.apache.maven.plugins. Using this naming pattern is an infringement of the Apache Maven Trademark.

命名为 maven-<yourplugin>-plugin (注意“Maven”是插件名称的开头)是强烈反对的，因为它是由Apache Maven团队与groupld org.apache.maven.plugins保持的官方的Apache Maven Plugin保留的命名模式。使用这个命名模式Apache Maven商标的侵权。

你的第一个插件

In this section we will build a simple plugin which takes no parameters and simply displays a message on the screen when run. Along the way, we will cover the basics of setting up a project to create a plugin, the minimal contents of a Java mojo, and a couple ways to execute the mojo.

在本节中，我们将在本节中，我们将构建一个简单的插件，它不带任何参数，只是在运行时在屏幕上显示一条消息。接下来，我们将讨论建立一个项目，创建一个插件，内容最少的Java mojo和如何执行。

你的第一个Mojo

At its simplest, a Java mojo consists simply of a single class. There is no requirement for multiple classes like EJBs, although a plugin which contains a number of similar mojos is likely to use an abstract superclass for the mojos to consolidate code common to all mojos.

简单来说，Java mojo只是个独立的类。尽管插件包含大量类似的mojos，可使用抽象的超类mojos来定义共用的mojos代码。

When processing the source tree to find mojos, plugin-tools looks for classes with either @Mojo Java 5 annotation or "goal" javadoc annotation. Any class with this annotation are included in the plugin configuration file.

通过源码树去找到mojos，插件工具查找类的方式有2种，”@Mojo” Java 5的注解或”@goal“ javadoc的注解，任何有这个注解的类都包含在插件配置文件中。

简单的Mojo

Listed below is a simple mojo class which has no parameters. This is about as simple as a mojo can be. After the listing is a description of the various parts of the source.

下面是一个无参的简单Mojo类。只需要一个mojo即可。在这个之后是别的功能的介绍。

package sample.plugin;

import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugins.annotations.Mojo;

/
  Says "Hi" to the user.
 
 */
@Mojo( name = "sayhi")
public class GreetingMojo extends AbstractMojo
{
    public void execute() throws MojoExecutionException
    {
        getLog().info( "Hello, world." );
    }
}

<project>
  <modelVersion>4.0.0</modelVersion>

  <groupId>sample.plugin</groupId>
  <artifactId>hello-maven-plugin</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>maven-plugin</packaging>

  <name>Sample Parameter-less Maven Plugin</name>

  <dependencies>
    <dependency>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-plugin-api</artifactId>
      <version>3.0</version>
    </dependency>

    <!-- dependencies to annotations -->
    <dependency>
      <groupId>org.apache.maven.plugin-tools</groupId>
      <artifactId>maven-plugin-annotations</artifactId>
      <version>3.4</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>
</project>

<build>
    <plugins>
      <plugin>
        <groupId>sample.plugin</groupId>
        <artifactId>hello-maven-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
      </plugin>
    </plugins>
  </build>

mvn groupId:artifactId:version:goal

<pluginGroups>
  <pluginGroup>sample.plugin</pluginGroup>
</pluginGroups>

 <build>
    <plugins>
      <plugin>
        <groupId>sample.plugin</groupId>
        <artifactId>hello-maven-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
        <executions>
          <execution>
            <phase>compile</phase>
            <goals>
              <goal>sayhi</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

mvn archetype:generate \
  -DgroupId=sample.plugin \
  -DartifactId=hello-maven-plugin \
  -DarchetypeGroupId=org.apache.maven.archetypes \
  -DarchetypeArtifactId=maven-archetype-plugin

    /
      The greeting to display.
     /
    @Parameter( property = "sayhi.greeting", defaultValue = "Hello World!" )
    private String greeting;

The portion before the annotations is the description of the parameter. The parameter annotation identifies the variable as a mojo parameter. The defaultValue parameter of the annotation defines the default value for the variable. This value can include expressions which reference the project, such as "${project.version}" (more can be found in the "Parameter Expressions" document). The property parameter can be used to allow configuration of the mojo parameter from the command line by referencing a system property that the user sets via the -D option.

注解之前的部分是参数的描述，注解标识这个变量作为mojo的参数。注解的默认参数值定义为变量的默认值，该值可包含引用该项目的表达式，如”${project.version}”（更多可以在“参数表达式”文档中找到）。该属性参数允许通过命令行来引用配置系统属性，通过-D。

项目中的参数配置

<plugin>
  <groupId>sample.plugin</groupId>
  <artifactId>hello-maven-plugin</artifactId>
  <version>1.0-SNAPSHOT</version>
  <configuration>
    <greeting>Welcome</greeting>
  </configuration>
</plugin>

配置部分里，元素(“greeting”)是参数名，元素的内容的值是(“Welcome”)。

Note: More details can be found in the Guide to Configuring Plugins.

注意:点击查看更多配置插件细节。

Listed below are the various types of simple variables which can be used as parameters in your mojos, along with any rules on how the values in the POM are interpreted.

下面是不同类型的参数变量的例子。

Boolean

This includes variables typed boolean and Boolean. When reading the configuration, the text "true" causes the parameter to be set to true and all other text causes the parameter to be set to false. Example:

/
      My boolean.
     /
    @Parameter
    private boolean myBoolean;

<myBoolean>true</myBoolean>

 /
      My Integer.
     /
    @Parameter
    private Integer myInteger;

<myInteger>10</myInteger>

Floating-Point Numbers

This includes variables typed double, Double, float, and Float. When reading the configuration, the text in the XML file is converted to binary form using the valueOf() method for the appropriate class. This means that the strings can take on any format specified in section 3.10.2 of the Java Language Specification. Some samples of valid values are 1.0 and 6.02E+23.

    /
      My Double.
     /
    @Parameter
    private Double myDouble;

<myDouble>1.0</myDouble>

  /
      My Date.
     /
    @Parameter
    private Date myDate;

<myDate>2005-10-06 2:22:55.1 PM</myDate>

Files and Directories

This includes variables typed File. When reading the configuration, the text in the XML file is used as the path to the desired file or directory. If the path is relative (does not start with / or a drive letter like C:), the path is relative to the directory containing the POM. Example:

 /
      My File.
     /
    @Parameter
    private File myFile;

<myFile>c:\temp</myFile>

/
      My URL.
     /
    @Parameter
    private URL myURL;

<myURL>https://maven.apache.org</myURL&gt;

public enum Color {
      GREEN,
      RED,
      BLUE
    }

    /
      My Enum
     /
    @Parameter
    private Color myColor;

<myColor>GREEN</myColor>

 public enum Color {
      GREEN,
      RED,
      BLUE
    }

    /
      My Enum
     /
    @Parameter(defaultValue = "GREEN")
    private Color myColor;

Parameter Types With Multiple Values

Listed below are the various types of composite objects which can be used as parameters in your mojos, along with any rules on how the values in the POM are interpreted. In general, the class of the object created to hold the parameter value (as well as the class for each element within the parameter value) is determined as follows (the first step which yields a valid class is used):

1. 
   If the XML element contains an implementation hint attribute, that is used
   


2. 
   If the XML tag contains a ., try that as a fully qualified class name
   


3. 
   Try the XML tag (with capitalized first letter) as a class in the same package as the mojo/object being configured
   


4. 
   For arrays, use the component type of the array (for example, use String for a String[] parameter); for collections and maps, use the class specified in the mojo configuration for the collection or map; use String for entries in a collection and values in a map
   

Once the type for the element is defined, the text in the XML file is converted to the appropriate type of object

/
      My Array.
     /
    @Parameter
    private String[] myArray;

<myArray>
  <param>value1</param>
  <param>value2</param>
</myArray>

      /
      My List.
     /
    @Parameter
    private List myList;

<myList>
  <param>value1</param>
  <param>value2</param>
</myList>

/
      My Map.
     /
    @Parameter
    private Map myMap;

<myMap>
  <key1>value1</key1>
  <key2>value2</key2>
</myMap>

 /
      My Properties.
     /
    @Parameter
    private Properties myProperties;

<myProperties>
  <property>
    <name>propertyName1</name>
    <value>propertyValue1</value>
  <property>
  <property>
    <name>propertyName2</name>
    <value>propertyValue2</value>
  <property>
</myProperties>

Other Object Classes

This category covers any class which does not implement java.util.Map, java.util.Collection, or java.util.Dictionary. Example:

  /*
      My Object.
     */
    @Parameter
    private MyObject myObject;

<myObject>
  <myField>test</myField>
</myObject>

Using Setters

You are not restricted to using private field mapping which is good if you are trying to make you Mojos resuable outside the context of Maven. Using the example above we could name our private fields using the underscore convention and provide setters that the configuration mapping mechanism can use. So our Mojo would look like the following:

public class MyQueryMojo
    extends AbstractMojo
{
    @Parameter(property="url")
    private String _url;

    @Parameter(property="timeout")
    private int _timeout;

    @Parameter(property="options")
    private String[] _options;

    public void setUrl( String url )
    {
        _url = url;
    }

    public void setTimeout( int timeout )
    {
        _timeout = timeout;
    }

    public void setOptions( String[] options )
    {
        _options = options;
    }

    public void execute()
        throws MojoExecutionException
    {
        ...
    }

资源

1. 
   Mojo文档: Mojo API, Mojo注解
   


2. 
   Maven插件测试工具: 对你Mojos的测试架构.
   


3. 
   Plexus: 使用 Maven 的 IoC 容器.
   


4. 
   Plexus常见实用工具: Mojo开发实用工具类集.
   


5. 
   Commons IO:一整套file/path处理的实用工具类。.
   


6. 
   常见的Bug和误区: 总结编码模式的问题.