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>
;,但 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 组件的基础。构建此项目时,它将在 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 存储库中。