45.2. 如何使用框架
概述
使用 API 框架实施组件的过程涉及混合了自动化代码生成、实施 Java 代码以及通过编辑 Maven POM 文件来自定义构建。下图提供了此开发过程的概述。
图 45.1. 使用 API 组件框架
![图显示 API 组件实施的部分](https://access.redhat.com/webassets/avalon/d/Red_Hat_Fuse-7.11-Apache_Camel_Development_Guide-zh-CN/images/2c28b539baf78f1e6c1219d88fe8ef7e/framework_intro_01.gif)
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>
;,但 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>
;,而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 存储库中。