Maven 插件 API – PluginDescriptor

插件描述符

插件描述符，存储在 META-INF/maven/plugin.xml插件的 jar 工件中。此描述符通常使用 maven-plugin-plugin从插件源生成。

注意：本文档是从 Modello 模型生成的，但执行的代码不是从这个描述符生成的。如果您发现任何错误，请报告。

<plugin>
  <name/>
  <description/>
  <groupId/>
  <artifactId/>
  <version/>
  <goalPrefix/>
  <isolatedRealm/>
  <inheritedByDefault/>

  <mojos>
    <mojo>
      <goal/>
      <description/>
      <implementation/>
      <language/>
      <phase/>
      <executePhase/>
      <executeGoal/>
      <executeLifecycle/>
      <requiresDependencyResolution/>
      <requiresDependencyCollection/>
      <requiresDirectInvocation/>
      <requiresProject/>
      <requiresReports/>
      <requiresOnline/>
      <aggregator/>
      <inheritedByDefault/>
      <threadSafe/>
      <instantiationStrategy/>
      <executionStrategy/>
      <since/>
      <deprecated/>
      <configurator/>
      <composer/>

      <parameters>
        <parameter>
          <name/>
          <alias/>
          <type/>
          <required/>
          <editable/>
          <implementation/>
          <description/>
          <since/>
          <deprecated/>
        </parameter>
      </parameters>
      <configuration>
        <paramName implementation=.. default-value=.. />
      </configuration>

      <requirements>
        <requirement>
          <role/>
          <role-hint/>
          <field-name/>
        </requirement>
      </requirements>
    </mojo>
  </mojos>

  <dependencies>
    <dependency>
      <groupId/>
      <artifactId/>
      <version/>
      <type/>
    </dependency>
  </dependencies>
</plugin>

插入

文件的根元素 plugin.xml。

元素	类型	描述
`name`	`String`	插件的名称。
`description`	`String`	插件说明。
`groupId`	`String`	插件的组 ID。
`artifactId`	`String`	插件的工件 ID。
`version`	`String`	插件的版本。
`goalPrefix`	`String`
`isolatedRealm`	`boolean`	默认值为：`false`。
`inheritedByDefault`	`boolean`	默认值为：`true`。
`mojos/mojo*`	`List<MojoDescriptor>`	（许多）插件提供的每个 Mojo 的描述。
`dependencies/dependency*`	`List<Dependency>`	（许多）插件运行所需的一组依赖项。这使插件能够独立于其 POM 运行（或至少声明它需要运行的库）。

魔力

Mojo 描述。

元素	类型	描述
`goal`	`String`	Mojo 的目标名称，用户将从命令行引用该名称以直接执行 Mojo，或在 POM 中引用该名称以提供特定于 Mojo 的配置。
`description`	`String`	此 Mojo 功能的描述。
`implementation`	`String`	Mojo 的完全限定类名（或非 Java Mojos 的脚本路径）。
`language`	`String`	这个 Mojo 的实现语言（java、beanshell 等）。默认值为：`java`。
`phase`	`String`	如果用户未在 POM 中显式设置阶段，则定义将 mojo 执行绑定到的默认阶段。注意：当插件声明添加到 POM 时，这不会自动运行 mojo。它仅使用户能够 `<phase>`从周围元素中省略该`<execution>`元素。
`executePhase`	`String`	参考 Mojo 的调用阶段。
`executeGoal`	`String`	引用 Mojo 的调用目标。
`executeLifecycle`	`String`
`requiresDependencyResolution`	`String`	将此 Mojo 标记为需要在执行之前解析指定类路径中的依赖项： `compile`, `runtime`, `test`, `compile+runtime`(从 Maven 3.0 开始) 或 `runtime+system`(从 Maven 3.0 开始) 默认值为: `runtime`。
`requiresDependencyCollection`	`String`	将此 mojo 标记为需要有关构成指定类路径的依赖项的信息。顾名思义，这类似于 requiresDependencyResolution 并支持相同的值。重要的区别是这不会解析依赖项的文件，即与 Maven 项目关联的工件可能缺少文件。因此，此注释适用于只想分析传递依赖项集的 mojo，特别是在早期生命周期阶段，由于尚未构建的项目，完全依赖项解析可能会失败。
`requiresDirectInvocation`	`boolean`	将此 Mojo 标记为仅直接调用。默认值为：`false`。
`requiresProject`	`boolean`	将此 Mojo 标记为需要在项目内部运行。默认值为：`true`。
`requiresReports`	`boolean`	将此 Mojo 标记为需要在报告上下文中运行。自 Maven 3.0 起不受支持。默认值为：`false`。
`requiresOnline`	`boolean`	将此 Mojo 标记为需要在线模式才能运行。默认值为：`false`。
`aggregator`	`boolean`	标记此 Mojo 以以多模块方式运行它，即将构建与列为模块的项目集聚合。默认值为：`false`。
`inheritedByDefault`	`boolean`	指定 Mojo 是继承的。默认值为：`true`。
`threadSafe`	`boolean`	将此 mojo 标记为线程安全的，即 mojo 在并行构建期间安全地支持并发执行。在并行构建会话期间使用没有此注释的 Mojos 将使 Maven 输出警告。从 Maven 3.0. 默认值为：`false`。
`instantiationStrategy`	`String`	指定实例化策略。默认值为：`per-lookup`。
`executionStrategy`	`String`	指定执行策略： `once-per-session`, `always`. 默认值为：`once-per-session`。
`since`	`String`	指定将 Mojo 添加到 API 时的版本。此后类似于 Javadoc。
`deprecated`	`String`	指定 API 弃用 Mojo 时的版本。类似于已弃用的 Javadoc。当用户尝试配置标记为已弃用的参数时，这将触发警告。
`configurator`	`String`	将参数值注入此 Mojo 时使用的配置器类型。该值通常是从 Mojo 的实现语言推导出来的，但可以指定以允许使用自定义 ComponentConfigurator 实现。
`composer`	`String`
`parameters/parameter*`	`List<Parameter>`	（许多）
`configuration/paramName*`	`List<Configuration>`	（许多）
`requirements/requirement*`	`List<Requirement>`	（许多）

范围

相位映射定义。

元素	类型	描述
`name`	`String`	参数的名称，在从 Mojo 声明的默认值或 POM 配置此参数时使用。
`alias`	`String`	指定可用于从 POM 配置此参数的别名。这主要用于提高用户友好性，其中 Mojo 字段名称对用户来说不直观，或者不利于通过 POM 进行配置。
`type`	`String`	此参数的 Java 类型。这用于验证用于计算应为该参数注入 Mojo 的值的任何表达式的结果。
`required`	`boolean`	Mojo 运行是否需要此参数。这用于在注入之前验证 Mojo 的配置，以及在从某个半状态执行 Mojo 之前。默认值为：`false`。
`editable`	`boolean`	指定此参数可以由用户直接配置（如 POM 指定配置的情况）。当您想要强制用户使用通用 POM 元素而不是插件配置时，这很有用，例如您想要使用工件的最终名称作为参数的情况。在这种情况下，您希望用户修改 `<build><finalName/></build>`而不是直接在插件配置部分中指定 finalName 的值。确保 - 例如 - 需要 Artifact 类型的项目的 List 类型的参数不会得到一个满是字符串的 List 也是有用的。默认值为：`true`。
`implementation`	`String`
`description`	`String`	该参数在 Mojo 中的使用说明。
`since`	`String`	指定将参数添加到 API 时的版本。此后类似于 Javadoc。
`deprecated`	`String`	指定 API 弃用参数时的版本。类似于已弃用的 Javadoc。当用户尝试配置标记为已弃用的参数时，这将触发警告。

参数名称

一个参数配置。

元素内容：参数表达式，让用户使用系统属性、pom 属性或设置属性覆盖默认值。

属性	类型	描述
`implementation`	`String`
`default-value`	`String`	默认值，作为将在注入或运行时评估的表达式。

要求

描述组件需求。

元素	类型	描述
`role`	`String`
`role-hint`	`String`
`field-name`	`String`	有此要求的字段名称。

依赖

插件在运行时需要的依赖项的定义。

元素	类型	描述
`groupId`	`String`	依赖项的组 ID。
`artifactId`	`String`	依赖项的工件 ID。
`version`	`String`	依赖项的版本。
`type`	`String`	依赖的类型。默认值为：`jar`。