第 47 章 配置 API 组件 Maven 插件
摘要
本章提供了 API 组件 Maven 插件中所有可用配置选项的引用。
47.1. 插件配置概述
概述
API 组件 Maven 插件的主要用途是 camel-api-component-maven-plugin,用于生成 API 映射类,该类实施端点 URI 和 API 方法调用之间的映射。通过编辑 API 组件 Maven 插件的配置,您可以自定义 API 映射的各个方面。
生成的代码的位置
默认情况下,API 组件 Maven 插件生成的 API 映射类放在以下位置:
ProjectName-component/target/generated-sources/camel-component先决条件
API 组件 Maven 插件的主要输入是 Java API 类和 Javadoc 元数据。这些插件适用于插件,方法是将其声明为常规 Maven 依赖项(其中 Javadoc Maven 依赖项应当声明为 提供 的范围)。
设置插件
设置 API 组件 Maven 插件的建议方法是使用 API 组件 archetype 生成起点代码。这会在 ProjectName-component/pom.xml 文件中生成默认插件配置,然后您可以为项目自定义。插件集的主要方面包括:
- 必须针对 requisite Java API 和 Javadoc 元数据声明 Maven 依赖项。
-
插件的基本配置在
pluginManagement范围内声明(也定义了要使用的插件的版本)。 - 插件实例本身的声明和配置。
-
build-helper-maven插件配置为从target/generated-sources/camel-component目录中获取生成的源,并将它们包含在 Maven 构建中。
基本配置示例
以下 POM 文件提取显示 API 组件 Maven 插件的基本配置,如使用 API 组件 archetype 生成的代码时 Maven 插件 所定义:
<?xml version="1.0" encoding="UTF-8"?>
<project ...>
...
<build>
...
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.camel</groupId>
<artifactId>camel-api-component-maven-plugin</artifactId>
<version>2.23.2.fuse-790054-redhat-00001</version>
<configuration>
<scheme>${schemeName}</scheme>
<componentName>${componentName}</componentName>
<componentPackage>${componentPackage}</componentPackage>
<outPackage>${outPackage}</outPackage>
</configuration>
</plugin>
</plugins>
</pluginManagement>
...
</build>
...
</project
插件管理 范围中指定的配置提供插件的默认设置。它实际上不创建插件实例,但其默认设置将由任何 API 组件插件实例使用。
基本配置
除了指定插件版本(在 version 元素中),前面的基本配置还指定以下配置属性:
scheme- 此 API 组件的 URI 方案。
componentName- 此 API 组件的名称(它也用作生成的类名称的前缀)。
componentPackage-
指定包含 API 组件 Maven archetype 生成的类的 Java 软件包。这个软件包也由默认的
maven-bundle-plugin配置导出。因此,如果您希望一个类是公开的,您应该将其放置在 Java 软件包中。 outPackage-
指定放置生成的 API 映射类的 Java 软件包(在 API 组件 Maven 插件生成时)。默认情况下,这具有
componentName属性的值,其添加了.internal后缀。这个软件包由默认的maven-bundle-plugin配置声明为私有。因此,如果您希望一个类是私有的,您应该将其放置在这个 Java 软件包中。
实例配置示例
以下 POM 文件提取显示 API 组件 Maven 插件的示例实例,该插件被配置为在 Maven 构建期间生成 API 映射:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
...
<build>
<defaultGoal>install</defaultGoal>
<plugins>
...
<!-- generate Component source and test source -->
<plugin>
<groupId>org.apache.camel</groupId>
<artifactId>camel-api-component-maven-plugin</artifactId>
<executions>
<execution>
<id>generate-test-component-classes</id>
<goals>
<goal>fromApis</goal>
</goals>
<configuration>
<apis>
<api>
<apiName>hello-file</apiName>
<proxyClass>org.jboss.fuse.example.api.ExampleFileHello</proxyClass>
<fromSignatureFile>signatures/file-sig-api.txt</fromSignatureFile>
</api>
<api>
<apiName>hello-javadoc</apiName>
<proxyClass>org.jboss.fuse.example.api.ExampleJavadocHello</proxyClass>
<fromJavadoc/>
</api>
</apis>
</configuration>
</execution>
</executions>
</plugin>
...
</plugins>
...
</build>
...
</project>基本映射配置
该插件由 configuration 元素配置,它包含单个 apis 子元素来配置 Java API 的类。每个 API 类由 api 元素配置,如下所示:
apiNameAPI 名称是 API 类的简短名称,用作
端点 URI 的端点前缀部分。注意如果 API 仅包含一个 Java 类,您可以将
apiName元素留空,以便端点前缀变为冗余,然后使用 “单个 API 类的 URI 格式”一节 中显示的格式指定端点 URI。proxyClass- 此元素指定 API 类的完全限定名称。
fromJavadoc-
如果 API 类附带 Javadoc 元数据,您必须通过包含
fromJavadoc元素和 Javadoc 本身等内容来指示这一点,作为提供的依赖项。 fromSignatureFile如果 API 类与签名文件元数据相配,您必须通过包含
fromSignatureFile元素来指示这一点,其中此元素的内容指定了签名文件的位置。注意签名文件 不会 包含在 Maven 构建的最终软件包中,因为仅构建时不需要这些文件,所以在运行时不需要这些文件。
自定义 API 映射
通过配置插件可以自定义 API 映射的以下方面:
-
方法别名 modprobe-you 您可以使用别名配置元素为 API 方法定义附加名称(
别名)。详情请查看 第 47.3 节 “方法别名”。 -
nullable 选项 TOKEN-you 可以使用
nullableOptions配置元素来声明默认为null的方法参数。详情请查看 第 47.4 节 “nullable 选项”。 -
在实施 API 映射时,参数名替换 只有 WWN-affinity,特定 API 类中的所有方法的参数都属于 同一命名空间。如果将具有相同名称的两个参数声明为不同的类型,这会导致一个清楚的。为避免这种名称冲突,您可以使用
替换配置元素来重命名方法参数(因为它们将显示在 URI 中)。详情请查看 第 47.5 节 “参数 Name Substitution”。 -
在将 Java 参数与 URI 选项映射时,除了将参数 TOKEN 排除在映射中时,有时您可能想从映射中排除某些参数。您可以通过指定
excludeConfigNames元素或excludeConfigTypes元素来过滤不需要的参数。详情请查看 第 47.6 节 “排除参数”。 -
您可能想定义多组选项(而不是 Java API 的一部分) 的额外选项 。您可以使用
extraOptions配置元素进行此操作。
配置 Javadoc 元数据
可以过滤 Javadoc 元数据来忽略或明确包含某些内容。有关如何进行此操作的详情,请参考 第 47.2 节 “javadoc选项”。
配置签名文件元数据
如果没有 Javadoc 可用,您可以利用签名文件来提供所需的映射元数据。fromSignatureFile 用于指定相应签名文件的位置。它没有特殊选项。