45.2. 如何使用框架

概述

使用 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（在 API 组件框架中生成代码）的形式为 Java API 提供元数据。如果您从 Maven 存储库使用第三方 Java API，则通常会发现 Maven 工件中已提供 Javadoc。但即使在 未提供 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 的详情，请参考第 46.1 节 “使用 Maven Archetype 生成代码”。

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

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

编辑组件类

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

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 类，这意味着您可以使用表单的 URI 从这个类调用方法，方案://hello-javadoc/端点。存在 fromJavadoc 元素表示 ExampleJavadocHello 类从 Javadoc 获取其元数据。

OSGi 捆绑包配置

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

构建组件

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

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