45.2. 如何使用框架

概述

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

图 45.1. 使用 API 组件框架

图显示 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 存储库中。