45.2. 如何使用框架

概述

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

图 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 捆绑包配置

组件子项目的 POM 示例 ProjectName-component/pom.xml 配置为将组件打包为 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 存储库中。