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 组件基于第三方 Java SDK 库。
从语言中立的接口生成 Java API。

javadoc 元数据

您可以选择以 Javadoc 的形式为 Java API 提供元数据（需要在 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 组件的基础。构建此项目时，它将在 Maven 捆绑包中打包 Java API，并生成必需的 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 捆绑包配置

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

构建组件

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

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