17.3. 插件描述符

Maven插件包含了一个告诉Maven各种Mojo和插件配置的路线图。这就是插件描述符,它位于JAR文件中的META-INF/maven/plugin.xml。当Maven载入一个插件的时候,它读取该XML文件,初始化并配置插件对象,使Mojo被包含在插件中,供Maven使用。

当你编写自定义Maven插件的时候,你几乎不需要编写插件描述符。在Chapter 10, 构建生命周期中,绑定到maven-plugin打包类型的生命周期目标显示,plugin:descriptor目标被绑定到了generate-resources生命周期阶段。该目标根据插件源码中的注解生成一个插件描述符。本章后面,你会看到如何注解Mojo,并且你会了解这些注解最终如何成为META-INF/maven/plugin.xml文件的内容。

Example 17.1, “插件描述符”展示了Maven Zip插件的描述符。该插件简单的对输出目录进行zip压缩并归档。一般来说,你不需要编写自定义插件从Maven创建归档,你可以使用Maven Assembly插件,该插件能够以多种格式帮助生成分发归档。仔细阅读下面的插件描述符以了解其包含的内容:

Example 17.1. 插件描述符

<plugin>
  <description></description>
  <groupId>com.training.plugins</groupId>
  <artifactId>maven-zip-plugin</artifactId>
  <version>1-SNAPSHOT</version>
  <goalPrefix>zip</goalPrefix>
  <isolatedRealm>false</isolatedRealm>
  <inheritedByDefault>true</inheritedByDefault>
  <mojos>
    <mojo>
      <goal>zip</goal>
      <description>Zips up the output directory.</description>
      <requiresDirectInvocation>false</requiresDirectInvocation>
      <requiresProject>true</requiresProject>
      <requiresReports>false</requiresReports>
      <aggregator>false</aggregator>
      <requiresOnline>false</requiresOnline>
      <inheritedByDefault>true</inheritedByDefault>
      <phase>package</phase>
      <implementation>com.training.plugins.ZipMojo</implementation>
      <language>java</language>
      <instantiationStrategy>per-lookup</instantiationStrategy>
      <executionStrategy>once-per-session</executionStrategy>
      <parameters>
        <parameter>
          <name>baseDirectory</name>
          <type>java.io.File</type>
          <required>false</required>
          <editable>true</editable>
          <description>Base directory of the project.</description>
        </parameter>
        <parameter>
          <name>buildDirectory</name>
          <type>java.io.File</type>
          <required>false</required>
          <editable>true</editable>
          <description>Directory containing the build files.</description>
        </parameter>
      </parameters>
      <configuration>
        <buildDirectory implementation="java.io.File">/data/hudson-temporal-data/hudson-orchestrator-home/workspace/Book-To-Production/content-zh/target</buildDirectory>
        <baseDirectory implementation="java.io.File">/data/hudson-temporal-data/hudson-orchestrator-home/workspace/Book-To-Production/content-zh</baseDirectory>
      </configuration>
      <requirements>
        <requirement>
          <role>org.codehaus.plexus.archiver.Archiver</role>
          <role-hint>zip</role-hint>
          <field-name>zipArchiver</field-name>
        </requirement>
      </requirements>
    </mojo>
  </mojos>
  <dependencies>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-io</artifactId>
    <version>1.3.2</version>
  </dependencies>
</plugin>

该插件描述符有三个部分:插件的顶层配置,包含如groupIdartifactId之类的元素;mojo声明;以及依赖声明。让我们仔细解释一下每一部分。

17.3.1. 顶层插件描述符元素

plugin元素中顶层的配置元素有:

description

该元素包含了插件的简短描述。在Zip插件的情况中,该描述为空。

groupId, artifactId, version

就像Maven中的任何其它构件一样,插件也需要唯一的坐标。groupId, artifactId,和version用来在Maven仓库中定位插件。

goalPrefix

该元素(目标前缀)用来设置某个特定插件用来引用目标的前缀。如果你看一下Compiler插件的描述符,你会看到goalPrefix的值为compile,如果你看一下Jar插件的描述符,你会看到goalPrefixjar。为自定义插件选择一个独一无二的前缀非常重要。

isolatedRealm (不赞成使用)

该遗留属性不再被Maven使用。它的存在是为了给旧的插件提供向后兼容性。早期版本的Maven使用它提供一种在单独ClassLoader中载入插件依赖的机制。Maven扩展使用了Codehaus社区中一个名为ClassWorlds的项目,创建由ClassRealm对象建模的ClassLoader对象层次结构。尽管忽略该属性,永远将其设置成false

inheritedByDefault

如果inheritedByDefault(缺省继承)被设置成true,所有在父项目配置的该插件的mojo会在子项目中生效。如果你配置一个mojo在父项目中特定的阶段执行,并且该插件inheritedByDefault属性的值为true,这段执行会被子项目继承。如果inheritedByDefault没有被设置成true,那么定义在父项目中的目标执行不会被子项目继承。