45.2. 如何使用框架

概述

使用 API 框架实施组件的过程涉及混合使用 API 框架自动化代码生成、实施 Java 代码以及通过编辑 Maven POM 文件自定义构建的过程。下图提供了此开发流程的概述。

图 45.1. 使用 API 组件框架

Java API

API 组件的起点始终是 Java API。通常，在 Camel 上下文中，这通常是指连接到远程服务器端点的 Java 客户端 API。第一个问题是，Java API 来自哪里？以下是几个可能：

自行实施 Java API （尽管通常涉及到很多工作，且通常不是首选方法）。
使用第三方 Java API。例如，Apache Camel Box 组件基于第三方 Box Java SDK 库。
从中立接口生成 Java API。

javadoc元数据

您可以选择以 Javadoc 的形式为 Java API 提供元数据（在 API 组件框架中生成代码需要它）。如果您使用 Maven 存储库中的第三方 Java API，您通常会发现 Javadoc 已在 Maven 工件中提供。但即使在 不提供 Javadoc 时，您也可以使用 maven-javadoc-plugin Maven 插件轻松生成它。

注意

目前，处理 Javadoc 元数据有一个限制，因此不支持通用嵌套。例如，支持 java.util.List<String&gt;，但 java.util.List<java.util.List<String&gt; 不受支持。解决办法是在签名文件中将嵌套通用类型指定为 java.util.List<java.util.List >。

签名文件元数据

如果出于某种原因，最好以 Javadoc 的形式提供 Java API 元数据，您可以选择以签名文件的形式提供元数据。签名文件包含方法签名列表（每行一个方法签名）。这些文件可以手动创建，且只在构建时需要。

请注意以下有关签名文件的以下几点：

您必须为每个代理类创建一个签名文件(Java API 类)。
方法签名不应抛出异常。运行时提升的所有异常都嵌套到 RuntimeCamelException 中并从端点返回。
指定参数类型的类名称必须是完全限定的类名称（但 java.lang.\* 类型除外）。导入软件包名称没有机制。
目前，签名解析器中有一个限制，因此不支持通用嵌套。例如，支持 java.util.List<String&gt;，而 java.util.List<java.util.List<String&gt; 则不行。解决办法是将嵌套通用类型指定为 java.util.List<java.util.List>。

下面显示了签名文件内容的简单示例：

public String sayHi();
public String greetMe(String name);
public String greetUs(String name1, String name2);

使用 Maven archetype 生成代码

开始开发 API 组件的最简单方法是使用 camel-archetype-api-component Maven archetype Maven archetype 生成初始 Maven 项目。有关如何运行 archetype 的详情，请参考第 46.1 节 “使用 Maven Archetype 生成代码”。

运行 Maven archetype 后，您将在生成的 ProjectName 目录下找到两个子项目：

ProjectName-api: 此项目包含 Java API，它形成 API 组件的基础。构建此项目时，它会将 Java API 打包在 Maven 捆绑包中，并生成必要的 Javadoc。如果 Java API 和 Javadoc 已通过第三方提供，但您不需要这个子项目。
ProjectName-component: 此项目包含 API 组件的框架代码。

编辑组件类

您可以编辑 ProjectName-component 中的框架代码来开发您自己的组件实施。以下生成的类组成 skeleton 实现的核心：

ComponentNameComponent
ComponentNameEndpoint
ComponentNameConsumer
ComponentNameProducer
ComponentNameConfiguration

自定义 POM 文件

您还需要编辑 Maven POM 文件来自定义构建，并配置 camel-api-component-maven-plugin Maven 插件。

配置 camel-api-component-maven-plugin

配置 POM 文件最重要的一点是配置 camel-api-component-maven-plugin Maven 插件。此插件负责生成 API 方法和端点 URI 之间的映射，通过编辑插件配置，您可以自定义映射。

例如，在 ProjectName-component/pom.xml 文件中，以下 camel-api-component-maven-plugin 插件配置显示了名为 ExampleJavadocHello 的 API 类的最小配置。

<configuration>
  <apis>
    <api>
      <apiName>hello-javadoc</apiName>
      <proxyClass>org.jboss.fuse.example.api.ExampleJavadocHello</proxyClass>
      <fromJavadoc/>
    </api>
  </apis>
</configuration>

在本例中，hello-javadoc API 名称映射到 ExampleJavadocHello 类，这意味着您可以使用格式为 ://hello-javadoc/endpoint的 URI 从此类调用方法。fromJavadoc 元素的存在性表示 ExampleJavadocHello 类从 Javadoc 获取其元数据。

OSGi 捆绑包配置

组件子项目的 POM 示例 ProjectName-component/pom.xml 被配置为将组件打包为 OSGi 捆绑包。组件 POM 包含 maven-bundle-plugin 的示例配置。您应该自定义 maven-bundle-plugin 插件的配置，以确保 Maven 为您的组件生成正确配置的 OSGi 捆绑包。

构建组件

使用 Maven 构建组件（例如，使用 mvn clean package）时，ell-api-component-maven-plugin 插件会自动生成 API 映射类（定义 Java API 和端点 URI 语法之间的映射），将它们放入 target/classes 项目子目录中。当您处理大量复杂 Java API 时，生成的代码实际上构成了大量组件源代码。

当 Maven 构建完成时，编译的代码和资源被打包为 OSGi 捆绑包，并将其存储在本地 Maven 存储库中作为 Maven 工件。