Apache Camel 开发指南

Red Hat Fuse 7.11

使用 Apache Camel 开发应用程序

摘要

本指南介绍了如何使用 Apache Camel 开发 JBoss Fuse 应用程序。它涵盖了基本的构建块、企业级集成模式、用于路由表达式和谓词语言的基本语法、使用 Apache CXF 组件创建 Web 服务、使用 Apache Camel API 创建网络服务,以及如何创建包含任何 Java API 的 Camel 组件。

使开源包含更多

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始:master、slave、黑名单和白名单。由于此项工作十分艰巨,这些更改将在即将推出的几个发行版本中逐步实施。详情请查看我们的 CTO Chris Wright 信息

部分 I. 实施企业级集成模式

这部分论述了如何使用 Apache Camel 构建路由。它涵盖了基本构建块和 EIP 组件。

第 1 章 为路由定义构建块

摘要

Apache Camel 支持两个替代 域特定语言 (DSL)来定义路由:Java DSL 和 Spring XML DSL。定义路由的基本构建块是 端点处理器,其中处理器的行为通常由表达式或逻辑 predicates 修改。Apache Camel 可让您使用各种不同语言定义表达式和 predicates。

1.1. 实施 RouteBuilder 类

概述

要使用 域特定语言 (DSL),您可以扩展 RouteBuilder 类并覆盖其 configure() 方法(您定义路由规则)。

您可以根据需要定义多个 RouteBuilder 类。每个类都会实例化一次,并在 CamelContext 对象中注册。通常,每个 RouteBuilder 对象的生命周期由您在其中部署路由器的容器自动管理。

RouteBuilder 类

作为路由器开发人员,您的核心任务是实施一个或多个 RouteBuilder 类。您可以从继承两种替代 RouteBuilder 类:

  • org.apache.camel.builder.RouteBuilder 时间为适用于 部署到任何 容器类型的通用 RouteBuilder 基础类。它在 camel-core 工件中提供。
  • org.apache.camel.spring.SpringRouteBuilder abrt-abrt这个基础类特别适用于 Spring 容器。特别是,它提供对以下 Spring 特定功能的额外支持:在 Spring registry 中查找 BeanRef() Java DSL 命令,以及事务(请参阅 交易指南 )。它在 camel-spring 工件中提供。

RouteBuilder 类定义用于启动路由规则的方法(例如,来自()、拦截器 ()exception())。

实施 RouteBuilder

例 1.1 “RouteBuilder 类的实现” 显示最小的 RouteBuilder 实施。configure() 方法正文包含路由规则;每个规则都是单个 Java 语句。

例 1.1. RouteBuilder 类的实现

import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {

public void configure() {
  // Define routing rules here:
  from("file:src/data?noop=true").to("file:target/messages");

  // More rules can be included, in you like.
  // ...
}
}

来自URL1.to(URL2) 的规则形式指示路由器从目录 src/data 读取文件,并将它们发送到目录 目标/消息。选项 ?noop=true 指示路由器保留(而不是删除) src/data 目录中的源文件。

注意

当您将 contextScan 与 Spring 或 Blueprint 搭配使用以过滤 RouteBuilder 类时,默认情况下,Apache Camel 将查找 singleton Bean。但是,您可以打开旧行为,使其包含使用新选项 includeNonSingletons 的模型范围。

1.2. 基本 Java DSL 语法

什么是 DSL?

域特定语言(DSL)是专为特殊用途而设计的微型语言。DSL 不需要逻辑上完成,但需要足够的表达力来描述所选域中的问题。通常,DSL 不需要 专用的解析程序、解释器或编译器。DSL 可以在现有面向对象的主机语言之上 piggyback,提供 DSL 构造在主机语言 API 中彻底构造。

在假设 DSL 中请考虑以下命令序列:

command01;
command02;
command03;

您可以将这些命令映射到 Java 方法调用,如下所示:

command01().command02().command03()

您甚至可将块映射到 Java 方法调用。例如:

command01().startBlock().command02().command03().endBlock()

DSL 语法由主机语言 API 的数据类型隐式定义。例如,Java 方法的返回类型决定了您可以法律地调用哪些方法(与 DSL 中的下一个命令相同)。

路由器规则语法

Apache Camel 定义了一个 路由器 DSL,用于定义路由规则。您可以使用此 DSL 在 RouteBuilder.configure() 实施的正文中定义规则。图 1.1 “本地路由规则” 展示了定义本地路由规则的基本语法概述。

图 1.1. 本地路由规则

本地路由规则

本地规则始终以 ("EndpointURL") 方法开头,该方法指定路由规则的消息(使用者端点)来源。然后您可以在规则中添加任意较长的处理器链(如 filter())。您通常通过 to("EndpointURL") 方法关闭规则,它指定通过规则传递的消息的目标(制作端点)。但是,始终不需要以 to() 结束规则。在规则中指定消息目标的方法有其他方法。

注意

您还可以通过使用特殊处理器类型(如 intercept()、exception()errorHandler () )启动规则来定义全局路由规则。全局规则不在本指南的讨论范围内。

消费者和制作者

本地规则始终通过定义消费者端点(使用 ("EndpointURL") )开始,并且通常(但并不总是)通过定义制作者端点(使用 to("EndpointURL") )来结束。端点 URL EndpointURL 可以使用部署时配置的任何组件。例如,您可以使用文件端点、file:MyMessageDirectory、Apache CXF 端点、cxf:MyServiceName 或 Apache ActiveMQ 端点 activemq:queue:MyQName。有关组件类型的完整列表,请参阅 Apache Camel 组件参考

交换

Exchange 对象由元数据增强的消息组成。交换是 Apache Camel 中的集中重要性,因为交换是通过路由规则传播消息的标准表单。交换的主要特征是,如下所示:

  • message 这个过程中,使用交换封装的当前消息。在通过路由进行交换过程中,可能会修改此消息。因此,在路由开始时的 In 消息通常和路由末尾的 In 消息 不同org.apache.camel.Message 类型提供了消息的通用模型,包括以下部分:

    • 正文.
    • 标头.
    • 附件.

    务必要意识到这是消息 的通用 模型。Apache Camel 支持各种协议和端点类型。因此,无法 标准化邮件正文或邮件标题的格式。例如,JMS 消息正文与 HTTP 消息正文或 Web 服务消息的正文具有完全不同的格式。因此,正文和标头被声明为 对象类型。然后,正文和标头的原始内容由创建交换实例的端点决定(即,端点会出现在 from() 命令中)。

  • out messageourier- burdenis a temporary holding area for a reply message or a transformed message.某些处理节点(特别是 to() 命令)可以将 In 消息视为请求,将其发送到制作者端点,然后从该端点接收回复来修改当前消息。然后将回复消息插入到交换中的 Out message 插槽。

    通常,如果当前节点设置了 Out 消息,Apache Camel 会在将交换传递到路由中的下一个节点之前修改交换:旧的 In 消息被丢弃,并将 Out 消息移到 In message slot。因此,回复会成为新的当前消息。如需了解 Apache Camel 如何在路由中连接节点的详情,请参考 第 2.1 节 “Pipeline 处理”

    然而,有一个特殊情形: Out 消息的处理方式有所不同。如果路由开头的消费者端点预期回复消息,则路由末尾的 Out 消息将被视为消费者端点的回复消息(在这种情况下,最终节点 必须创建 Out 消息,或者消费者端点会挂起)。

  • 消息交换模式(MEP)admission-IFL-ffects 在路由中交换和端点之间的交互,如下所示:

    • 消费者端点 the consumer 端点创建原始交换,设置 MEP 的初始值。初始值表示消费者端点是否期望收到回复(例如,InOut MEP)是否不是(例如 InOnly MEP)。
    • 生产者端点 时间为 MEP 影响生产者端点,该端点会影响路由所遇到的生产者端点(例如,交换通过 to() 节点时)。例如,如果当前 MEP 是 InOnly,则 to() 节点不应该从端点接收回复。有时您需要更改当前的 MEP,以便自定义与制作者端点的交互。如需了解更多详细信息,请参阅 第 1.4 节 “Endpoints”
  • 交换当前消息元数据的命名属性列表。

消息交换模式

使用 Exchange 对象可轻松地将消息处理规范化为 不同的消息交换模式。例如,异步协议可以定义一个 MEP,它由一个消息组成,消息从消费者端点流到制作者端点( 仅适用 MEP)。另一方面,RPC 协议可能会定义由请求消息和回复消息(一个 InOut MEP)组成的 MEP。目前,Apache Camel 支持以下 MEPs:

  • InOnly
  • RobustInOnly
  • InOut
  • InoptionalOut
  • OutOnly
  • RobustOutOnly
  • OutIn
  • OutOptionalIn

其中,这些消息交换模式由枚举类型中的常数来表示,即 org.apache.camel.ExchangePattern

分组交换

有时,有一个封装多个交换实例的单一交换很有用。为了实现此目的,您可以使用一个 分组的交换。分组交换基本上是一个交换实例,其中包含存储在 Exchange.GROUPED_EXCHANGE 交换属性中的 java.util.List 的 Exchange 对象。有关如何使用分组交换的示例,请参阅 第 8.5 节 “聚合器”

处理器

处理器 是路由中的节点,可访问和修改通过路由进行的交换流。处理器可以使用 表达式或 predicate 参数,用于修改其行为。例如,图 1.1 “本地路由规则” 中显示的规则包含一个 filter() 处理器,该处理器使用 xpath() predicate 作为其参数。

表达式和 predicates

表达式(评估为字符串或其他数据类型)和 predicates(显示为 true 或 false)经常作为内置处理器类型的参数。例如,以下过滤器规则会传播 In 消息,只有在 foo 标头等于值 bar 时:

from("seda:a").filter(header("foo").isEqualTo("bar")).to("seda:b");

如果过滤器由 predicate、header("foo").isEqualTo("bar") 授权。要根据消息内容构建更加复杂的 predicates 和表达式,您可以使用以下一种表达式和谓词语言(请参阅 第 II 部分 “路由表达式和指定语言”)。

1.3. Spring XML 文件中的路由器架构

命名空间

路由器 schema>_<- the definition XML DSL-abrtbelongs 到以下 XML 模式命名空间:

http://camel.apache.org/schema/spring

指定 schema 位置

路由器模式的位置通常指定为 http://camel.apache.org/schema/spring/camel-spring.xsd,它引用 Apache Web 站点上 schema 的最新版本。例如,Apache Camel Spring 文件的 root Bean 元素通常配置为 例 1.2 “指定路由器架构位置”

例 1.2. 指定路由器架构位置

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:camel="http://camel.apache.org/schema/spring"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

  <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
    <!-- Define your routing rules here -->
  </camelContext>
</beans>

运行时模式位置

在运行时,Apache Camel 不会从 Spring 文件中指定的架构位置下载路由器模式。相反,Apache Camel 会自动从 camel-spring JAR 文件的根目录获取 schema 的副本。这样可确保用于解析 Spring 文件的 schema 版本始终与当前的运行时版本匹配。这很重要,因为 Apache 网站上发布的模式的最新版本可能与当前使用的运行时版本不匹配。

使用 XML 编辑器

通常,建议您使用全功能 XML 编辑器编辑 Spring 文件。借助 XML 编辑器的自动完成功能,编写符合路由器架构的 XML 更轻松,如果 XML 不正确,编辑器也会立即提醒您。

XML 编辑器 通常 依赖从您在 xsi:schemaLocation 属性中指定的位置下载 schema。为了确保您使用正确的 schema 版本,最好选择 camel-spring.xsd 文件的特定版本。例如,若要为 Apache Camel 的 2.3 版本编辑 Spring 文件,您可以修改 Bean 元素,如下所示:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:camel="http://camel.apache.org/schema/spring"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring-2.3.0.xsd">
...

编辑完成后,请更改默认值( camel-spring.xsd )。要查看当前可用于下载的模式版本,请导航至网页 http://camel.apache.org/schema/spring

1.4. Endpoints

概述

Apache Camel 端点是路由中消息的源和接收器。端点是一个非常一般的构建块:它必须满足的唯一要求是它充当消息来源(制作端点)或作为消息(消费者端点)的接收器(消费者端点)。因此,Apache Camel 中支持各种不同的端点类型,范围从协议支持端点(如 HTTP)到简单的计时器端点,如 Quartz,以固定间隔生成 dummy 消息。Apache Camel 的主要优势之一是,相对容易地添加实施新端点类型的自定义组件。

端点 URI

端点通过 端点 URI 标识,其通用表单如下:

scheme:contextPath[?queryOptions]

URI 方案 标识了协议,如 httpcontextPath 提供由协议解释的 URI 详情。另外,大多数方案都允许您定义查询选项,而 queryOptions 则采用以下格式指定:

?option01=value01&option02=value02&...

例如,以下 HTTP URI 可以用来连接到 Google 搜索引擎页面:

http://www.google.com

以下文件 URI 可用于读取在 C:\temp\src\data 目录下出现的所有文件:

file://C:/temp/src/data

不是每个 方案 都代表了一个协议。有时候,方案 只需提供对有用的实用程序(如计时器)的访问。例如,以下计时器端点 URI 每秒生成交换一次(=1000 毫秒)。您可以使用它来调度路由中的活动。

timer://tickTock?period=1000

使用长 Endpoint URI

有时,端点 URI 可能会因为提供的所有配置信息而变得非常长。在 JBoss Fuse 6.2 中,您可以采用两种方法使您使用冗长的 URI 更易于管理。

配置端点 9 月

您可以单独配置端点,从路由中使用简写 ID 引用端点。

<camelContext ...>

  <endpoint id="foo" uri="ftp://foo@myserver">
    <property name="password" value="secret"/>
    <property name="recursive" value="true"/>
    <property name="ftpClient.dataTimeout" value="30000"/>
    <property name="ftpClient.serverLanguageCode" value="fr"/>
  </endpoint>

  <route>
    <from uri="ref:foo"/>
    ...
  </route>
</camelContext>

您还可以在 URI 中配置一些选项,然后使用 property 属性指定附加选项(或覆盖 URI 中的选项)。

<endpoint id="foo" uri="ftp://foo@myserver?recursive=true">
  <property name="password" value="secret"/>
  <property name="ftpClient.dataTimeout" value="30000"/>
  <property name="ftpClient.serverLanguageCode" value="fr"/>
</endpoint>
跨新行的分割端点配置

您可以使用新行分割 URI 属性。

<route>
  <from uri="ftp://foo@myserver?password=secret&amp;
           recursive=true&amp;ftpClient.dataTimeout=30000&amp;
           ftpClientConfig.serverLanguageCode=fr"/>
  <to uri="bean:doSomething"/>
</route>
注意

您可以在每行中指定一个或多个选项,每个选项由 & 分隔。

在 URI 中指定时间段

许多 Apache Camel 组件都有选项,其值是时间段(例如,指定超时值等)。默认情况下,此类时间周期选项通常指定为纯数字,被解释为毫秒的时间段。但是,Apache Camel 还支持更易读的语法,它可让您用小时、分钟和秒来表达周期。正式,人类可读的时间段是一个符合以下语法的字符串:

[NHour(h|hour)][NMin(m|minute)][NSec(s|second)]

在方括号 [] 中,每个术语都是可选的,并且符号 (A|B) 表示 AB 是 alternatives。

例如,您可以使用 45 分钟的时间配置计时器 端点,如下所示:

from("timer:foo?period=45m")
  .to("log:foo");

您还可以使用小时、分钟和第二个单元的任意组合,如下所示:

from("timer:foo?period=1h15m")
  .to("log:foo");
from("timer:bar?period=2h30s")
  .to("log:bar");
from("timer:bar?period=3h45m58s")
  .to("log:bar");

在 URI 选项中指定原始值

默认情况下,您在 URI 中指定的选项值会自动进行 URI 编码。在某些情况下这是不需要的行为。例如,当设置 password 选项时,最好在 没有 URI 编码的情况下 传输原始字符字符串。

通过利用语法指定选项值,可以切换 URI 编码,即 RAW(RawValue)。例如,

from("SourceURI")
 .to("ftp:joe@myftpserver.com?password=RAW(se+re?t&23)&binary=true")

在本例中,密码值作为字面值传输,即 se+re?t&23

不区分大小写的 enum 选项

某些端点 URI 选项映射到 Java enum constants。例如,Log 组件的 level 选项可以采用 enumINFOWARNERROR 等等。这个类型转换不区分大小写,因此可以使用以下任意一种选项来设置日志制作者端点的日志记录级别:

<to uri="log:foo?level=info"/>
<to uri="log:foo?level=INfo"/>
<to uri="log:foo?level=InFo"/>

指定 URI 资源

从 Camel 2.17,基于资源组件(如 XSLT)可以使用 ref: 作为前缀从 Registry 加载资源文件。

例如,如果myvelocityscriptbeanmysimplescriptbean 是 registry 中的两个 Bean 的 ID,您可以按照如下所示使用这些 Bean 的内容:

Velocity endpoint:
------------------
from("velocity:ref:myvelocityscriptbean").<rest_of_route>.

Language endpoint (for invoking a scripting language):
-----------------------------------------------------
from("direct:start")
  .to("language:simple:ref:mysimplescriptbean")
 Where Camel implicitly converts the bean to a String.

Apache Camel 组件

每个 URI 方案 都映射到 Apache Camel 组件,其中 Apache Camel 组件基本上是一个端点工厂。换句话说,若要使用特定类型的端点,您必须在运行时容器中部署对应的 Apache Camel 组件。例如,若要使用 JMS 端点,您要在容器中部署 JMS 组件。

Apache Camel 提供了大量不同的组件,可让您将应用程序与各种传输协议和第三方产品集成。例如,一些常用的组件有: File、JMS、CXF(Web 服务)、HTTP、Jetty、Direct 和 Mock。有关支持组件的完整列表,请参阅 Apache Camel 组件文档

大多数 Apache Camel 组件都单独打包成 Camel 内核。如果您使用 Maven 构建应用程序,只需在相关组件构件上添加依赖项即可向应用程序中添加组件(及其第三方依赖项)。例如,要包含 HTTP 组件,您要将以下 Maven 依赖项添加到项目 POM 文件中:

<!-- Maven POM File -->
  <properties>
    <camel-version>{camelFullVersion}</camel-version>
    ...
  </properties>

  <dependencies>
    ...
    <dependency>
      <groupId>org.apache.camel</groupId>
      <artifactId>camel-http</artifactId>
      <version>${camel-version}</version>
    </dependency>
    ...
  </dependencies>

以下组件内置到 Camel 内核(在 camel 内核 工件中),因此始终可用:

  • bean
  • 浏览
  • dataset
  • direct
  • File
  • Log
  • 模拟
  • Properties
  • Ref
  • SEDA
  • timer
  • VM

消费者端点

消费者端点 是在路由 开始时 出现的端点(即,在 from() DSL 命令中)。换句话说,使用者端点负责在路由中发起处理:它创建一个新的交换实例(通常基于它收到或获取的一些消息),并提供线程来处理路由的其余部分中的交换。

例如,以下 JMS 使用者端点会拉取出 支付 队列的消息,并在路由中处理它们:

from("jms:queue:payments")
  .process(SomeProcessor)
  .to("TargetURI");

或者,在 Spring XML 中:

<camelContext id="CamelContextID"
              xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="jms:queue:payments"/>
    <process ref="someProcessorId"/>
    <to uri="TargetURI"/>
  </route>
</camelContext>

一些组件 只是消费者 ,它们只能被用来定义消费者端点。例如,Panartz 组件专门用于定义消费者端点。以下 Quartz 端点每秒钟生成一个事件(1000 毫秒):

from("quartz://secondTimer?trigger.repeatInterval=1000")
  .process(SomeProcessor)
  .to("TargetURI");

如果您愿意,可以使用 fromF() Java DSL 命令,将端点 URI 指定为格式的字符串。例如,要将用户名和密码替换为 FTP 端点的 URI,您可以使用 Java 编写路由,如下所示:

fromF("ftp:%s@fusesource.com?password=%s", username, password)
  .process(SomeProcessor)
  .to("TargetURI");

其中,第一个位置的 %s 替换为用户名字符串的值,第二次出现 %s 替换为密码 字符串。这个字符串格式化机制由 String.format() 实施,它类似于 C printf() 函数提供的格式。详情请查看 java.util.Formatter

producer 端点

制作者端点 是在 中间 或路由 末尾 出现的端点(例如,在 to() DSL 命令中)。换句话说,制作者端点接收现有的交换对象,并将交换内容发送到指定的端点。

例如,以下 JMS producer 端点将当前交换的内容推送到指定的 JMS 队列:

from("SourceURI")
  .process(SomeProcessor)
  .to("jms:queue:orderForms");

也可以在 Spring XML 中:

<camelContext id="CamelContextID" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="SourceURI"/>
    <process ref="someProcessorId"/>
    <to uri="jms:queue:orderForms"/>
  </route>
</camelContext>

某些组件 只是制作者 ,只能用来定义制作者端点。例如,HTTP 端点专门用于定义制作者端点。

from("SourceURI")
  .process(SomeProcessor)
  .to("http://www.google.com/search?hl=en&q=camel+router");

如果您愿意,可以使用 toF() Java DSL 命令,将端点 URI 指定为格式的字符串。例如,要将自定义 Google 查询替换为 HTTP URI,您可以使用 Java 编写路由,如下所示:

from("SourceURI")
  .process(SomeProcessor)
  .toF("http://www.google.com/search?hl=en&q=%s", myGoogleQuery);

如果出现 %s 被您的自定义查询字符串 myGoogleQuery 来替换。详情请查看 java.util.Formatter

1.5. 处理器

概述

要让路由器执行比简单地将消费者端点连接到制作者端点更有趣的事情,您可以将 处理器 添加到路由中。处理器是一个命令,您可以插入到路由规则中,以执行任何通过规则流的消息处理。Apache Camel 提供各种处理器,如 表 1.1 “Apache Camel Processors” 所示。

表 1.1. Apache Camel Processors

Java DSLXML DSL描述

aggregate()

aggregate

第 8.5 节 “聚合器”:创建一个聚合器,将多个传入的交换组合到一个交换中。

aop()

AOP

使用 Aspect Oriented 编程(AOP)在指定的子路由之前和之后工作。

bean(), beanRef()

bean

通过调用 Java 对象(或 bean)的方法来处理当前的交换。请参阅 第 2.4 节 “bean Integration”

choice()

choice

第 8.1 节 “基于内容的路由器”:使用 when 和 other 子句根据交换内容选择特定的子路由。

convertBodyTo()

convertBodyTo

In 消息正文转换为指定的类型。

delay()

delay

第 8.9 节 “Delayer”:将交换的传播延迟到路由后面的部分。

doTry()

doTry

创建用于处理异常的 try/catch 块,使用 doCatch最后执行、和 end 子句。

end()

N/A

结束当前命令块。

enrich(),enrichRef()

增强

第 10.1 节 “内容增强器”:将当前交换与指定 制作者 端点 URI 请求的数据相结合。

filter()

filter

第 8.2 节 “Message Filter”:使用 predicate 表达式来过滤传入的交换。

idempotentConsumer()

idempotentConsumer

第 11.8 节 “幂等的消费者”:实施策略以抑制重复的消息。

inheritErrorHandler()

@inheritErrorHandler

布尔选项可用于禁用特定路由节点上继承的错误处理程序(定义为 Java DSL 中的子词,以及 XML DSL 中的属性)。

inOnly()

仅限

将当前的交换的 MEP 设置为 InOnly (如果没有参数),或者将交换作为 InOnly 发送到指定的端点。

inOut()

inOut

将当前的交换的 MEP 设置为 InOut (如果没有参数),或者将交换作为 InOut 发送到指定的端点。

loadBalance()

loadBalance

第 8.10 节 “Load Balancer”:在一组端点上实施负载平衡。

log()

log

将消息记录到控制台。

loop()

loop

第 8.16 节 “loop”:重复将每个交换的后端到路由中的后方。

markRollbackOnly()

@markRollbackOnly

(事务) 只标记当前回滚的事务(不会引发异常)。在 XML DSL 中,此选项设置为 回滚 元素上的布尔值属性。请参阅 Apache Karaf 事务指南

markRollbackOnlyLast()

@markRollbackOnlyLast

(事务) 如果之前已与这个线程关联一个或多个事务,然后暂停,这个命令只标记回滚的最新事务(不会引发异常)。在 XML DSL 中,此选项设置为 回滚 元素上的布尔值属性。请参阅 Apache Karaf 事务指南

marshal()

marshal

使用指定数据格式转换为低级或二进制格式,以准备通过特定传输协议发送。

multicast()

multicast

第 8.13 节 “多播”:将当前交换多播到多个目的地,其中每个目标获得自己的交换副本。

onCompletion()

onCompletion

定义在主路由完成后执行的子路由(以 end() 结尾)。另请参阅 第 2.14 节 “OnCompletion”

onException()

onException

定义在 Java DSL 中以 end() 结尾的子路由(在发生指定异常时执行的子路由)。通常在其自己的行中定义(不在路由中)。

pipeline()

pipeline

第 5.4 节 “pipes 和 Filters”:将交换发送到一系列端点,其中一个端点的输出成为下一个端点的输入。另请参阅 第 2.1 节 “Pipeline 处理”

policy()

policy

将策略应用到当前路由(目前仅用于事务性策略>_<),请参阅 Apache Karaf 事务指南

pollEnrich(),pollEnrichRef()

pollEnrich

第 10.1 节 “内容增强器”:将当前交换与从指定 消费者 端点 URI 轮询的数据合并。

process(),processRef

process

在当前交换上执行自定义处理器。请参阅 “自定义处理器”一节第 III 部分 “高级 Camel 编程”

recipientList()

recipientList

第 8.3 节 “接收者列表”:将交换发送到在运行时计算的接收者列表(例如,基于标头的内容)。

removeHeader()

removeHeader

从交换的 In 消息中删除指定的标头。

removeHeaders()

removeHeaders

从交换的 In 消息中删除与指定模式匹配的标头。这个模式可以具有形式的 prefix\* 替代方案,在这种情况下,它匹配以前缀为为 prefix the- theotherwise 的每个名称,它被解释为正则表达式。

removeProperty()

删除Property

从交换中删除指定的交换属性。

removeProperties()

removeProperties

从交换中删除与指定模式匹配的属性。将以逗号分隔的 1 个或多个字符串列表作为参数。第一个字符串是 模式(请参阅上面的 removeHeaders() )。后续字符串指定例外 - 这些属性保留。

resequence()

重新排序

第 8.6 节 “Resequencer”: 按指定比较主操作对传入的交换进行重新排序。支持 批处理 模式和 流模式

rollback()

rollback

(事务) 只标记当前仅回滚的事务(默认情况下也增加一个异常)。请参阅 Apache Karaf 事务指南

routingSlip()

routingSlip

第 8.7 节 “路由 Slip”:根据从 slip 标头提取的端点 URI 列表,通过动态构建的 Pipeline 路由交换。

sample()

示例

创建一个抽样节流,允许您从路由上的流量中提取交换示例。

setBody()

setBody

设置交换的 消息正文

setExchangePattern()

setExchangePattern

将当前的交换的 MEP 设置为指定的值。请参阅 “消息交换模式”一节

setHeader()

setHeader

在交换的 In 消息中设置指定的标头。

setOutHeader()

setOutHeader

在 Exchange's Out 消息中设置指定的标头。

setProperty()

setProperty()

设置指定的交换属性。

sort()

排序

In 消息正文的内容进行排序(其中可以指定自定义比较器)。

split()

split

第 8.4 节 “Splitter”:将当前交换分成一系列交换,其中每个分割交换包含原始消息正文的片段。

stop()

stop

可停止路由当前交换,并将其标记为 completed。

threads()

threads

创建线程池,以并发处理路由中的后一部分。

throttle()

throttle

第 8.8 节 “Throttler”:将流率限制为指定级别(每秒更改)。

throwException()

throwException

引发指定的 Java 异常。

to()

将交换发送到一个或多个端点。请参阅 第 2.1 节 “Pipeline 处理”

toF()

N/A

使用字符串格式将交换发送到端点。也就是说,端点 URI 字符串可以在 C printf() 函数的样式中嵌入替换。

transacted()

Transacted

创建包含路由后者一部分的 Spring 事务范围。请参阅 Apache Karaf 事务指南

transform()

转换

第 5.6 节 “message Translator”:将 In 消息标头复制到 Out 消息标头,并将 Out 消息正文设置为指定的值。

unmarshal()

unmarshal

使用指定数据格式将 In 消息正文从低级或二进制格式转换为高级别格式。

validate()

validate

使用 predicate 表达式来测试当前消息是否有效。如果该 predicate 返回 false,则抛出一个 PredicateValidationException 异常。

wireTap()

wireTap

第 12.3 节 “wire Tap”:使用 ExchangePattern.InOnly MEP 将当前交换的副本发送到指定的线 tap URI。

一些示例处理器

要了解如何在路由中使用处理器,请查看以下示例:

Choice

choice() 处理器是一个条件语句,用于将传入的消息路由到替代制作者端点。每个替代制作者端点的前面为一个 when() 方法,该方法使用一个 predicate 参数。如果 predicate 为 true,则会选择以下目标,否则处理继续进行规则中的下一个 when() 方法。例如,以下 choice() 处理器将传入消息定向到 Target1、Target 2Target3,具体取决于 Predicate1Predicate2 的值:

from("SourceURL")
    .choice()
        .when(Predicate1).to("Target1")
        .when(Predicate2).to("Target2")
        .otherwise().to("Target3");

也可以在 Spring XML 中:

<camelContext id="buildSimpleRouteWithChoice" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="SourceURL"/>
    <choice>
      <when>
        <!-- First predicate -->
        <simple>header.foo = 'bar'</simple>
        <to uri="Target1"/>
      </when>
      <when>
        <!-- Second predicate -->
        <simple>header.foo = 'manchu'</simple>
        <to uri="Target2"/>
      </when>
      <otherwise>
        <to uri="Target3"/>
      </otherwise>
    </choice>
  </route>
</camelContext>

在 Java DSL 中,有一个特殊情形,您可能需要使用 endChoice() 命令。某些标准 Apache Camel 处理器允许您使用特殊子使用指定额外参数,从而有效地打开额外的嵌套级别,这通常由 end() 命令终止。例如,您可以将负载均衡器子指定为 loadBalance().round SDin().to("mock:foo").to(" mock:bar ").end(),它加载 balances 信息在 模拟:foo 和模拟:bar 端点之间进行负载平衡。但是,如果负载均衡器条款嵌入到所选条件中,需要使用 endChoice() 命令终止子句,如下所示:

from("direct:start")
    .choice()
        .when(bodyAs(String.class).contains("Camel"))
            .loadBalance().roundRobin().to("mock:foo").to("mock:bar").endChoice()
        .otherwise()
            .to("mock:result");

Filter

filter() 处理器可用于防止不间断消息到达制作者端点。它取一个 predicate 参数:如果 predicate 为 true,则允许消息交换给制作者;如果 predicate 为 false,则会阻止消息交换。例如,以下过滤器将阻止消息交换,除非传入消息包含标题为 foo,值设为 bar

from("SourceURL").filter(header("foo").isEqualTo("bar")).to("TargetURL");

也可以在 Spring XML 中:

<camelContext id="filterRoute" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="SourceURL"/>
    <filter>
      <simple>header.foo = 'bar'</simple>
      <to uri="TargetURL"/>
    </filter>
  </route>
</camelContext>

Throttler

throttle() 处理器确保制作者端点不会超载。throttler 通过限制每秒可传递的消息数量来实现。如果传入的消息超过指定率,则节流器会在缓冲区中累积过量消息,并将它们更慢地传输到制作者端点。例如,要将吞吐量率限制为每秒 100 个消息,您可以定义以下规则:

from("SourceURL").throttle(100).to("TargetURL");

也可以在 Spring XML 中:

<camelContext id="throttleRoute" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="SourceURL"/>
    <throttle maximumRequestsPerPeriod="100" timePeriodMillis="1000">
      <to uri="TargetURL"/>
    </throttle>
  </route>
</camelContext>

自定义处理器

如果此处描述的标准处理器都不提供您需要的功能,您可以始终定义自己的自定义处理器。要创建自定义处理器,请定义一个实施 org.apache.camel.Processor 接口的类,并覆盖 process() 方法。以下自定义处理器 MyProcessor 会从传入信息中删除名为 foo 的标头:

例 1.3. 实施自定义处理器类

public class MyProcessor implements org.apache.camel.Processor {
public void process(org.apache.camel.Exchange exchange) {
  inMessage = exchange.getIn();
  if (inMessage != null) {
      inMessage.removeHeader("foo");
  }
}
};

要将自定义处理器插入到路由器规则中,调用 process() 方法,它为将处理器插入到规则中提供了通用机制。例如,以下规则调用 例 1.3 “实施自定义处理器类” 中定义的处理器:

org.apache.camel.Processor myProc = new MyProcessor();

from("SourceURL").process(myProc).to("TargetURL");

第 2 章 Route 构建的基本原则

摘要

Apache Camel 提供了几个处理器和组件,您可以在路由中连接在一起。本章介绍了使用提供的构建块构建路由原则的基础。

2.1. Pipeline 处理

概述

在 Apache Camel 中,pipelining 是路由定义中连接节点的主要范式。管道概念可能对 UNIX 操作系统的用户最熟悉,其中用于加入操作系统命令。例如, ls | 更多 是一个命令示例,它将目录列表传送到 page-scrolling 实用程序,更多。管道的基本概念是,一个命令的输出 将进入下一个 输入 中。如果路由的情况是,从一个处理器的 Out 消息被复制到下一处理器的 In 消息,则类似情况。

处理器节点

路由中的每个节点(除初始端点外)都是一个 处理器,它的确是从 org.apache.camel.Processor 接口继承的意义。换句话说,处理器构成 DSL 路由的基本构建块。例如: DSL 命令,如 filter ()、delayer()、 setBody()、 setHeader()to() 所有代表的处理器。当考虑到处理器如何连接路由时,务必要区分两种不同的处理方法。

第一种方法是,处理器只需要修改交换的消息,如 图 2.1 “处理器修改信息” 所示。在这种情况下,交换的 Out 消息仍保持 null

图 2.1. 处理器修改信息

处理器修改消息

以下路由显示了一个 setHeader() 命令,它通过添加(或修改) BillingSystem 标题来修改当前的 In 消息:

from("activemq:orderQueue")
    .setHeader("BillingSystem", xpath("/order/billingSystem"))
    .to("activemq:billingQueue");

第二种方法是,处理器创建 Out 信息来表示处理的结果,如 图 2.2 “处理器创建 Out 消息” 所示。

图 2.2. 处理器创建 Out 消息

处理器创建消息

以下路由显示了一个 transform() 命令,该命令会 创建一个带有包含字符串 DummyBody 的消息正文:

from("activemq:orderQueue")
    .transform(constant("DummyBody"))
    .to("activemq:billingQueue");

其中 常量("DummyBody") 代表一个恒定表达式。您不能直接传递字符串 DummyBody,因为对 transform() 的参数必须是表达式类型。

用于 InOnly 交换的管道

图 2.3 “InOnly Exchanges 的 Pipeline 示例” 显示用于 InOnly 交换的处理器管道示例。处理器 A 通过修改 In 消息,而处理器 B 和 C 创建 Out 消息。路由构建器按照所示将处理器链接在一起。特别是,B 和 C 以 管道 的形式链接在一起:也就是说,处理器 B 的 Out 消息移到 In 消息,在向处理器 C 传输交换前,处理器 C 的 Out 消息移到 In 消息,然后再将处理器 C 的 Out 消息移到 In 消息中。因此,处理器的输出和输入被加入到持续管道中,如 图 2.3 “InOnly Exchanges 的 Pipeline 示例” 所示。

图 2.3. InOnly Exchanges 的 Pipeline 示例

InOnly 交换的管道示例

Apache Camel 默认使用管道模式,因此您无需使用任何特殊语法在路由中创建管道。例如,以下路由从 userdataQueue 队列拉取消息,通过 Velocity 模板管道消息(以便以文本格式生成客户地址),然后将生成的文本地址发送到队列,envelopeAddresses:

from("activemq:userdataQueue")
    .to(ExchangePattern.InOut, "velocity:file:AdressTemplate.vm")
    .to("activemq:envelopeAddresses");

在文件系统中,Velocit y:file:AddressTemplate.vm 指定 Velocity 模板文件的位置,file:AddressTemplate.vmto() 命令在将交换模式发送到 Velocity 端点之前,将交换模式更改为 InOut,然后将它改回到 InOnly 后。有关速率端点的详情,请参阅 Apache Camel 组件参考指南 中的 Velocity

InOut 交换的管道

图 2.4 “InOut Exchanges 的 Pipeline 示例” 演示了 InOut 交换的处理器管道示例,您通常会用来支持远程过程调用(RPC)语义。处理器 A、B 和 C 以管道的形式链接,以及每个处理器的输出进入下一版本的输入。制作者端点生成的最终 Out 消息将将所有方式发送到消费者端点,在其中提供原始请求的回复。

图 2.4. InOut Exchanges 的 Pipeline 示例

InOut 交换的管道示例

请注意,为了支持 InOut 交换模式,重要的是,路由中最后一个节点(无论是制作者端点还是其他类型的处理器)会创建一个 Out 消息。否则,连接到消费者端点的任何客户端都会挂起并无限期等待回复消息。您应该注意,并非所有制作者端点都会创建 Out 消息。

通过处理传入的 HTTP 请求来考虑以下处理支付请求的路由:

from("jetty:http://localhost:8080/foo")
    .to("cxf:bean:addAccountDetails")
    .to("cxf:bean:getCreditRating")
    .to("cxf:bean:processTransaction");

如果传入的支付请求通过通过 Web 服务管道、cxf:bean:addAccountDetailscxf:bean:bean:getCreditRatingcxf:bean:processTransaction 来处理。最后的 Web 服务 processTransaction 生成通过 JETTTY 端点发回的响应(Out 消息)。

当管道只由一系列端点组成时,也可以使用以下替代语法:

from("jetty:http://localhost:8080/foo")
    .pipeline("cxf:bean:addAccountDetails", "cxf:bean:getCreditRating", "cxf:bean:processTransaction");

In OptionalOut Exchanges 的管道

In OptionalOut Exchanges 的管道基本上与 图 2.4 “InOut Exchanges 的 Pipeline 示例” 中的管道相同。In Out InoptionalOut 之间的区别在于,可以使用" 可选Out 交换"模式交换作为答复。也就是说,当一个 In OptionalOut Exchange 交换时,一个 null Out 消息会被复制到管道中下一节点的 In 消息。相反,在 InOut 交换的情况下,丢弃 null Out 消息,来自当前节点的原始 In 消息将被复制到下一个节点的 In 消息。

2.2. 多个输入

概述

标准路由仅使用 Java DSL 中的 from(EndpointURL) 语法从单一端点中获取其输入。但是,如果您需要为路由定义多个输入,该怎么办?Apache Camel 提供了一些替代方法来指定多个到路由的输入。采取的方法取决于您是否希望相互独立处理交换,还是您希望以某种方式组合使用不同输入的交换(在这种情况下,您应该使用 “内容增强器模式”一节)。

多个独立输入

指定多个输入的最简单方法是使用 from() DSL 命令的多参数形式,例如:

from("URI1", "URI2", "URI3").to("DestinationUri");

或者您可以使用以下等效语法:

from("URI1").from("URI2").from("URI3").to("DestinationUri");

在这两个示例中,从每个输入端点、URI1、URI 2URI3 中交换交换,分别相互处理,并在单独的线程中处理。实际上,您可以认为前面的路由等同于以下三个独立的路由:

from("URI1").to("DestinationUri");
from("URI2").to("DestinationUri");
from("URI3").to("DestinationUri");

分段路由

例如,您可能希望合并来自两个不同的消息传递系统的传入信息,并使用同一路由处理它们。在大多数情况下,您可以通过将路由分成片段来处理多个输入,如 图 2.5 “使用分段路由处理多个输入” 所示。

图 2.5. 使用分段路由处理多个输入

使用分段路由处理多个输入

路由的初始片段从某些外部队列 3.10.0--XDP 中获取其输入,例如 activemq:Nyseactivemq:Nasdaq WWPN,并将传入的交换发送到内部端点 InternalUrl。第二个路由片段合并传入的交换,从内部端点中提取,并将它们发送到目标队列 activemq:USTxnInternalUrl 是端点的 URL,仅用于在路由器应用程序中使用。以下类型的端点适合内部使用:

这些端点的主要目的是您可以将路由的不同片段粘滞在一起。它们都提供了将多个输入合并到一个路由的有效方法。

直接端点

直接组件提供了将路由链接最简单的机制。直接组件的事件模型是 同步的,因此后续的路由片段在与第一网段相同的线程中运行。直接 URL 的一般格式是 direct:EndpointID,其中端点 ID 为 EndpointID,它只是标识端点实例的唯一字母数字字符串。

例如,如果要从两个消息队列中使用输入 located :Nyseactivemq:Nasdaq,并将它们合并到一个消息队列中 Foo:USTxn,您可以通过定义以下组路由来执行此操作:

from("activemq:Nyse").to("direct:mergeTxns");
from("activemq:Nasdaq").to("direct:mergeTxns");

from("direct:mergeTxns").to("activemq:USTxn");

其中前两个路由使用来自消息队列( NyseNasdaq )的输入,并将它们发送到端点,direct:mergeTxns。最后一个队列合并了前两个队列中的输入,并将组合消息流发送到 activemq:USTxn 队列。

直连端点的实施方式如下:每当交换到达制作者端点(例如,("direct:mergeTxns")时,直接将交换传递到具有相同端点 ID 的所有用户端点(例如,从direct:mergeTxns"))。直接端点只能用于在同一 Java 虚拟机(JVM)实例中属于同一 CamelContext 的路由之间进行通信。

SEDA 端点

SEDA 组件提供了将路由连接在一起的替代机制。您可以以类似直接组件的方式使用它,但它有不同的底层事件和线程模型,如下所示:

  • 对 SEDA 端点的处理 不会 同步。也就是说,当您将交换发送到 SEDA producer 端点时,控件会立即返回到路由中的上一处理器。
  • SEDA 端点包含一个队列缓冲区(包括 java.util.concurrent.BlockingQueue 类型),它将所有传入的交换存储在下一个路由网段处理之前的所有传入交换器。
  • 每个 SEDA 使用者端点都会创建一个线程池(默认大小为 5),以处理来自阻塞队列的交换对象。
  • SEDA 组件支持 竞争的使用者 模式,这样可保证每个传入的交换仅被处理一次,即使有多个用户附加到特定端点。

使用 SEDA 端点的一个主要优点是路由可以更快地响应,导致内置消费者线程池。库存交易示例可以重新编写为使用 SEDA 端点而不是直接端点,如下所示:

from("activemq:Nyse").to("seda:mergeTxns");
from("activemq:Nasdaq").to("seda:mergeTxns");

from("seda:mergeTxns").to("activemq:USTxn");

此示例和直接示例之间的主要区别在于,使用 SEDA 时,第二个路由片段(从 seda:mergeTxnsactivemq:USTxn)由五个线程池处理。

注意

SEDA 不仅仅是将多个路由段过去在一起。暂存事件驱动的架构(SEDA)包含了用于构建更易管理的多线程应用程序的设计理念。Apache Camel 中的 SEDA 组件的目的是使您能够将此设计理念应用到您的应用程序。有关 SEDA 的详情,请参考 http://www.eecs.harvard.edu/~mdw/proj/seda/

虚拟机端点

VM 组件与 SEDA 端点非常相似。唯一的不同之处在于,SEDA 组件只能将来自同一 CamelContext 中的路由片段链接在一起,VM 组件可让您将不同 Apache Camel 应用程序的路由链接在一起,只要它们在同一 Java 虚拟机中运行。

库存交易示例可以重新编写为使用 VM 端点而不是 SEDA 端点,如下所示:

from("activemq:Nyse").to("vm:mergeTxns");
from("activemq:Nasdaq").to("vm:mergeTxns");

在单独的路由器应用程序(在同一 Java 虚拟机中运行),您可以定义路由的第二个片段,如下所示:

from("vm:mergeTxns").to("activemq:USTxn");

内容增强器模式

内容增强器模式定义了处理对路由的多个输入的根本不同方式。当交换进入增强器处理器时,增强器联系一个外部资源以检索信息,然后添加到原始消息中。在此模式中,外部资源有效表示消息的第二个输入。

例如,假设您正在编写处理贡献请求的应用程序。在处理信贷请求之前,您需要用数据进行添加,从而向客户分配贡献度等级到客户,其中评分数据存储在 目录中的一个文件中,src/data/ratings。您可以使用 pollEnrich() 模式和 GroupedExchangeAggregationStrategy 聚合策略将传入的信请求与 ratings 文件中的数据合并,如下所示:

from("jms:queue:creditRequests")
    .pollEnrich("file:src/data/ratings?noop=true", new GroupedExchangeAggregationStrategy())
    .bean(new MergeCreditRequestAndRatings(), "merge")
    .to("jms:queue:reformattedRequests");

其中 GroupedExchangeAggregationStrategy 类是一个标准的聚合策略,来自 org.apache.camel.processor.aggregate 软件包,将每个新交换添加到 java.util.List 实例,并将结果列表存储在 Exchange.GROUPED_EXCHANGE 交换属性中。在本例中,列表中包含两个元素:原始交换(来自 creditRequests JMS 队列);以及增强器交换(来自文件端点)。

要访问分组的交换,您可以使用类似如下的代码:

public class MergeCreditRequestAndRatings {
    public void merge(Exchange ex) {
        // Obtain the grouped exchange
        List<Exchange> list = ex.getProperty(Exchange.GROUPED_EXCHANGE, List.class);

        // Get the exchanges from the grouped exchange
        Exchange originalEx = list.get(0);
        Exchange ratingsEx  = list.get(1);

        // Merge the exchanges
        ...
    }
}

此应用的另一种方法是将合并代码直接放入自定义聚合策略类的实施中。

有关内容丰富的模式的详情,请参考 第 10.1 节 “内容增强器”

2.3. 异常处理

摘要

Apache Camel 提供了几种不同的机制,您可以在不同的粒度级别处理异常:您可以使用 doTrydoCatch最后执行 来处理路由中的异常异常,也可以使用 Exception 来指定将这个规则应用到 RouteBuilder 中的所有路由。 或者,您可以指定 所有 异常类型要执行的操作,并使用 errorHandler 将这个规则应用到 RouteBuilder 中的所有路由。

有关异常处理的详情,请参考 第 6.3 节 “死信频道”

2.3.1. onException Clause

概述

onException 子句是一种在一个或多个路由中发生陷入异常的强大机制:它特定于类型,允许您定义处理不同异常类型的不同操作;它允许您定义使用相同(实际、稍扩展)语法作为路由作为路由的操作,您可以以处理异常的方式提供了相当的灵活性;它基于陷入模型,从而让出现异常情况的出现。

使用 onException 的 Trapping 例外

onException 子句 是用于捕获 异常的机制。即,当您定义 onException 子句后,它会在路由的任意时间点捕获异常。这与 Java try/catch 机制相反,只有在一个异常被发现时,才会在试块中 明确 包含特定的代码片段。

当您定义 onException 子句时实际上会出现什么情况,即 Apache Camel 运行时会隐式将每个路由节点包含在 try 块中。这就是为什么 onException 子句可以在路由中的任何点捕获异常。但是,这个嵌套式是自动进行的,它无法在路由定义中可见。

Java DSL 示例

在以下 Java DSL 示例中,在Exception 子句中,将应用到 RouteBuilder 类中定义的所有路由。如果在处理任何路由(从("seda:inputA")或 ("seda:inputB") )时发生 ValidationException 异常,而 onException 子句会捕获异常并将当前交换重定向到 验证Failed JMS 队列(作为死信队列)。

// Java
public class MyRouteBuilder extends RouteBuilder {

  public void configure() {
    onException(ValidationException.class)
      .to("activemq:validationFailed");

    from("seda:inputA")
      .to("validation:foo/bar.xsd", "activemq:someQueue");

    from("seda:inputB").to("direct:foo")
      .to("rnc:mySchema.rnc", "activemq:anotherQueue");
  }
}

XML DSL 示例

前面的示例也可以在 XML DSL 中表示,使用 onException 元素来定义 exception 子句,如下所示:

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:camel="http://camel.apache.org/schema/spring"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
    http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
    http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

    <camelContext xmlns="http://camel.apache.org/schema/spring">
        <onException>
            <exception>com.mycompany.ValidationException</exception>
            <to uri="activemq:validationFailed"/>
        </onException>
        <route>
            <from uri="seda:inputA"/>
            <to uri="validation:foo/bar.xsd"/>
            <to uri="activemq:someQueue"/>
        </route>
        <route>
            <from uri="seda:inputB"/>
            <to uri="rnc:mySchema.rnc"/>
            <to uri="activemq:anotherQueue"/>
        </route>
    </camelContext>

</beans>

Trapping 多例外

您可以在 Exception 子定义多个 来陷入 RouteBuilder 范围中的异常。这可让您使用不同的操作来响应不同的例外。例如,Java DSL 中定义的以下一系列 onException 子句为 ValidationExceptionIOExceptionException 定义不同的死字母目的地:

onException(ValidationException.class).to("activemq:validationFailed");
onException(java.io.IOException.class).to("activemq:ioExceptions");
onException(Exception.class).to("activemq:exceptions");

您可以在 XML DSL 中定义与 Exception 子句相同的系列,如下所示:

<onException>
    <exception>com.mycompany.ValidationException</exception>
    <to uri="activemq:validationFailed"/>
</onException>
<onException>
    <exception>java.io.IOException</exception>
    <to uri="activemq:ioExceptions"/>
</onException>
<onException>
    <exception>java.lang.Exception</exception>
    <to uri="activemq:exceptions"/>
</onException>

您也可以将多个例外分组到一起,以被同一 onException 子句捕获。在 Java DSL 中,您可以按以下方式对多个例外进行分组:

onException(ValidationException.class, BuesinessException.class)
  .to("activemq:validationFailed");

在 XML DSL 中,您可以通过在 onException 元素中定义多个 异常 元素来将多个异常元素分组在一起,如下所示:

<onException>
    <exception>com.mycompany.ValidationException</exception>
    <exception>com.mycompany.BuesinessException</exception>
    <to uri="activemq:validationFailed"/>
</onException>

陷入多个异常时,在 Exception 子句上 的顺序非常重要。Apache Camel 最初尝试匹配对 first 子句的引发异常。如果 first 子句无法匹配,则尝试 Exception 子句上的 下一个,直到找到匹配项为止。尝试的每个匹配都受到以下算法的约束:

  1. 如果抛出的异常是 链的异常 (即,一个异常已捕获并将其除以不同异常),则最嵌套的异常类型最初充当匹配的基础。这个例外被测试,如下所示:

    1. 如果 exception-to-test 具有 在Exception 子句(使用 实例测试)中指定的类型,则将触发匹配项。
    2. 如果 exception-to-test 是 onException 子句中指定的类型子类型,则会触发匹配项。
  2. 如果最嵌套的例外无法产生匹配项,则通过测试链中的下一个异常。测试会继续进行链,直到触发匹配项或链用尽为止。
注意

throwException EIP 可让您从简单语言表达式创建新异常实例。您可以根据当前交换中的可用信息,使其动态。例如,

<throwException exceptionType="java.lang.IllegalArgumentException" message="${body}"/>

Deadletter 频道

onException 使用的基本示例到目前为止都利用了 deadletter 频道 模式。也就是说,当 onException 子句捕获异常时,当前交换将路由到特殊的目的地( deadletter 频道)。deadletter 频道充当 尚未 处理的失败消息的保存区域。管理员可以稍后检查消息,并决定需要采取什么操作。

有关 deadletter 频道模式的详情,请参阅 第 6.3 节 “死信频道”

使用原始消息

在路由中引发异常的时间,交换中的消息可能会显著修改(而且可能被人类读取)。通常,如果死信队列中可见的消息是 原始消息,管理员更容易决定要采取的正确操作。useOriginalMessage 选项默认为 false,但如果它是在错误处理程序上配置,则会自动启用。

注意

在应用到将消息发送到多个端点的 Camel 路由时,useOriginalMessage 选项可能会导致意外行为。原始消息可能不会保留在多播、Splitter 或 RecipientList 路由中,中间处理步骤会修改原始消息。

在 Java DSL 中,您可以通过原始消息替换交换中的消息。将 setAllowUseOriginalMessage() 设置为 true,然后使用 useOriginalMessage() DSL 命令,如下所示:

onException(ValidationException.class)
  .useOriginalMessage()
  .to("activemq:validationFailed");

在 XML DSL 中,您可以通过设置 onException 元素上的 useOriginalMessage 属性来检索原始消息,如下所示:

<onException useOriginalMessage="true">
    <exception>com.mycompany.ValidationException</exception>
    <to uri="activemq:validationFailed"/>
</onException>
注意

如果将 setAllowUseOriginalMessage() 选项设定为 true,Camel 会在路由开始时制作原始消息的副本,这样可确保当您调用 useOriginalMessage() 时,它会保证原始消息可用。但是,如果 Camel 上下文上的 setAllowUseOriginalMessage() 选项被设置为 false (这是默认值),则不会 访问原始消息,您无法调用 useOriginalMessage()

利用默认行为的原因是在处理大型消息时优化性能。

在 2.18 之前的 Camel 版本中,allowUseOriginalMessage 的默认设置为 true。

重新传送策略

Apache Camel 允许您在出现异常时立即中断消息处理并立即放弃,Apache Camel 为您提供在发生异常情况时尝试 出消息的选项。在网络系统中,超时可能会出现并临时故障时,在原始异常出现后马上被处理失败的消息通常会被成功处理。

Apache Camel 重新传送支持在异常发生后对消息传输的各种策略。配置重新传送的一些最重要的选项如下:

maximumRedeliveries()
指定可尝试重新传送的次数上限(默认为 0)。负值意味着始终尝试重新传送(等同于无限值)。
retryWhile()

指定 predicate( Predicate 类型),它决定 Apache Camel ought 是否继续重整。如果该 predicate 在当前交换上评估为 true,则会尝试重新传送;否则,将停止重新发送,且不会进行进一步重新发送尝试。

此选项优先于 maximumRedeliveries() 选项。

在 Java DSL 中,使用 onException 子句中的 DSL 命令来指定重新传送策略选项。例如,您可以指定最大 6 个红色大小,然后该交换将发送到 验证Failed deadletter 队列,如下所示:

onException(ValidationException.class)
  .maximumRedeliveries(6)
  .retryAttemptedLogLevel(org.apache.camel.LogginLevel.WARN)
  .to("activemq:validationFailed");

在 XML DSL 中,通过在 redeliveryPolicy 元素上设置属性来指定重新传送策略选项。例如,前面的路由可以通过 XML DSL 表达,如下所示:

<onException useOriginalMessage="true">
    <exception>com.mycompany.ValidationException</exception>
    <redeliveryPolicy maximumRedeliveries="6"/>
    <to uri="activemq:validationFailed"/>
</onException>

在重新传送选项后,重新传送选项的后一部分在最后一次重新传送尝试失败后才会被处理。有关所有重新传送选项的详情,请参考 第 6.3 节 “死信频道”

另外,您还可以在 redeliveryPolicyProfile 实例中指定重新传送策略选项。然后,您可以使用 onException 元素的 redeliverPolicyRef 属性来引用 redeliveryPolicyProfile 实例。例如,前面的路由可以表达如下:

<redeliveryPolicyProfile id="redelivPolicy" maximumRedeliveries="6" retryAttemptedLogLevel="WARN"/>

<onException useOriginalMessage="true" redeliveryPolicyRef="redelivPolicy">
    <exception>com.mycompany.ValidationException</exception>
    <to uri="activemq:validationFailed"/>
</onException>
注意

如果您想在多个 onException 子句中重新使用同一个重新传送策略,使用 redeliveryPolicyProfile 的方法很有用。

条件捕获

通过指定 onWhen 选项,可以进行带有 onException 时出现异常捕获的问题。如果您在 onException 子句中指定 onWhen 选项,则仅在引发异常与 子句匹配时才会触发匹配项,并在 当前交换上评估为 true

例如,在以下 Java DSL 片段中,first onException 子句触发,只有在引发n 异常与 MyUserException 匹配时,用户 标头在当前交换中是非null:

// Java

// Here we define onException() to catch MyUserException when
// there is a header[user] on the exchange that is not null
onException(MyUserException.class)
    .onWhen(header("user").isNotNull())
    .maximumRedeliveries(2)
    .to(ERROR_USER_QUEUE);

// Here we define onException to catch MyUserException as a kind
// of fallback when the above did not match.
// Noitce: The order how we have defined these onException is
// important as Camel will resolve in the same order as they
// have been defined
onException(MyUserException.class)
    .maximumRedeliveries(2)
    .to(ERROR_QUEUE);

Exception 子句的前一个可以在 XML DSL 中表达,如下所示:

<redeliveryPolicyProfile id="twoRedeliveries" maximumRedeliveries="2"/>

<onException redeliveryPolicyRef="twoRedeliveries">
    <exception>com.mycompany.MyUserException</exception>
    <onWhen>
        <simple>${header.user} != null</simple>
    </onWhen>
    <to uri="activemq:error_user_queue"/>
</onException>

<onException redeliveryPolicyRef="twoRedeliveries">
    <exception>com.mycompany.MyUserException</exception>
    <to uri="activemq:error_queue"/>
</onException>

处理异常

默认情况下,当路由中引发异常时,当前交换的处理将中断,在路由开始时将引发异常回消费者端点。触发了 onException 子句时,其行为基本上相同,但 onException 子句在引发异常前执行一些处理。

但是这种 默认行为是 处理异常的唯一方法。onException 提供了各种选项来修改异常处理行为,如下所示:

  • 抑制异常 rethtion rethrow -abrtyou 在 onException 子句完成后可以阻止 rethrown 异常。换句话说,在这种情况下,异常 不会在 路由开始时传播到消费者端点。
  • 继续处理 时间为:包含从最初发生异常的点恢复正常处理交换的选择。隐式,这种方法也会阻止循环异常。
  • 在路由开头的消费者端点时发送一个响应 (即使用 InOut MEP),您可以更愿意构建自定义错误回复消息,而不是将异常请求回消费者端点。

抑制异常行

要防止当前例外被重新箭头并传播到消费者端点,您可以在 Java DSL 中将 handled() 选项设置为 true,如下所示:

onException(ValidationException.class)
  .handled(true)
  .to("activemq:validationFailed");

在 Java DSL 中,handled() 选项的参数可以是布尔值类型、Predicate 类型或 Expression 类型(其中任何非布尔值表达式)解释为 true,如果评估为非空值。

使用 处理 元素,可以将同一路由配置为阻止 XML DSL 中的放箭头异常,如下所示:

<onException>
    <exception>com.mycompany.ValidationException</exception>
    <handled>
        <constant>true</constant>
    </handled>
    <to uri="activemq:validationFailed"/>
</onException>

继续处理

要继续处理最初引发异常的路由中的当前消息,您可以在 Java DSL 中将持续选项设置为 true,如下所示:

onException(ValidationException.class)
  .continued(true);

在 Java DSL 中,continue() 选项的参数可以是布尔值类型、Predicate 类型或 Expression 类型(其中任何非布尔值的表达式)解释为 true

同一路由可以在 XML DSL 中使用 继续 元素配置,如下所示:

<onException>
    <exception>com.mycompany.ValidationException</exception>
    <continued>
        <constant>true</constant>
    </continued>
</onException>

发送响应

当启动路由的消费者端点需要回复时,您可能更愿意构建自定义错误回复消息,而不是直接让引发异常传播到消费者。在这种情况下,您需要执行两个重要步骤: 使用 处理 的选项禁止放减异常;然后,使用自定义错误消息填充交换的 Out 消息。

例如,以下 Java DSL 片段演示了如何在发生 MyFunctionalException 异常时发送包含文本字符串 Sorry 的回复消息:

// we catch MyFunctionalException and want to mark it as handled (= no failure returned to client)
// but we want to return a fixed text response, so we transform OUT body as Sorry.
onException(MyFunctionalException.class)
    .handled(true)
    .transform().constant("Sorry");

如果您要向客户端发送故障响应,您通常会希望将异常消息的文本包含在响应中。您可以使用 exceptionMessage() builder 方法访问当前异常消息的文本。例如,每当 MyFunctionalException 异常异常时,您可以发送包含异常消息文本的回复,如下所示:

// we catch MyFunctionalException and want to mark it as handled (= no failure returned to client)
// but we want to return a fixed text response, so we transform OUT body and return the exception message
onException(MyFunctionalException.class)
    .handled(true)
    .transform(exceptionMessage());

异常消息文本也可以通过 exception.message 变量从 Simple 语言访问。例如,您可以在回复信息中嵌入当前的异常文本,如下所示:

// we catch MyFunctionalException and want to mark it as handled (= no failure returned to client)
// but we want to return a fixed text response, so we transform OUT body and return a nice message
// using the simple language where we want insert the exception message
onException(MyFunctionalException.class)
    .handled(true)
    .transform().simple("Error reported: ${exception.message} - cannot process this message.");

Exception 子句的前一个 可以在 XML DSL 中表达,如下所示:

<onException>
    <exception>com.mycompany.MyFunctionalException</exception>
    <handled>
        <constant>true</constant>
    </handled>
    <transform>
        <simple>Error reported: ${exception.message} - cannot process this message.</simple>
    </transform>
</onException>

处理异常时引发异常

在处理现有异常时(换句话说,在处理 onException 子句)的过程中会抛出异常。)会以特殊方式处理。这种异常由特殊的回退异常处理程序处理,该处理程序处理异常,如下所示:

  • 所有现有的异常处理程序都会忽略,并立即处理失败。
  • 新异常被记录。
  • 在 exchange 对象上设置新的例外。

简单策略可避免复杂的故障场景,否则可能会以 a onException 子句结束,使锁定为死循环。

范围

onException 子句可在以下任何范围中有效:

  • RouteBuilder 范围 InventoryService- onException 子句定义为 RouteBuilder.configure() 方法内的单机语句,它们会影响该 RouteBuilder 实例中定义的所有路由。另一方面,这些 onException 子句 对任何其他 RouteBuilder 实例中定义的路由没有影响onException 子句 必须在 路由定义之前显示。

    所有最多的示例都是使用 RouteBuilder 范围来定义的。

  • 路由范围 InventoryService- onException 子句也可以直接嵌入路由内。这些 onException 子句 仅影响 定义它们的路由。

路由范围

您可以在路由定义内任何位置嵌入 onException 子句,但您必须使用 end() DSL 命令终止嵌入的Exception 子句。

例如,您可以在 Java DSL 中的 Exception 子句中定义嵌入,如下所示:

// Java
from("direct:start")
  .onException(OrderFailedException.class)
    .maximumRedeliveries(1)
    .handled(true)
    .beanRef("orderService", "orderFailed")
    .to("mock:error")
  .end()
  .beanRef("orderService", "handleOrder")
  .to("mock:result");

您可以在 XML DSL 中定义嵌入 Exception 子句,如下所示:

<route errorHandlerRef="deadLetter">
    <from uri="direct:start"/>
    <onException>
        <exception>com.mycompany.OrderFailedException</exception>
        <redeliveryPolicy maximumRedeliveries="1"/>
        <handled>
            <constant>true</constant>
        </handled>
        <bean ref="orderService" method="orderFailed"/>
        <to uri="mock:error"/>
    </onException>
    <bean ref="orderService" method="handleOrder"/>
    <to uri="mock:result"/>
</route>

2.3.2. 错误处理程序

概述

errorHandler() 子句提供类似于 onException 子句的功能,但这种机制无法区分不同的异常类型。errorHandler() 子句是 Apache Camel 提供的原始异常处理机制,在实施 onException 子句之前可用。

Java DSL 示例

errorHandler() 子句在 RouteBuilder 类中定义,并应用到该 RouteBuilder 类中的所有路由。每当在一个适用的路由中出现 任何种类的 异常时,它都会触发。例如,若要定义将所有失败交换路由到 ActiveMQ deadLetter 队列的错误处理程序,您可以按照如下所示定义 RouteBuilder

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        errorHandler(deadLetterChannel("activemq:deadLetter"));

        // The preceding error handler applies
        // to all of the following routes:
        from("activemq:orderQueue")
          .to("pop3://fulfillment@acme.com");
        from("file:src/data?noop=true")
          .to("file:target/messages");
        // ...
    }
}

然而,重定向到死信频道不会发生,直到重新发送都耗尽为止。

XML DSL 示例

在 XML DSL 中,您可以使用 errorHandler 元素在 camelContext 范围内定义一个错误处理程序。例如,若要定义将所有失败交换路由到 ActiveMQ deadLetter 队列的错误处理程序,您可以按照如下所示定义 errorHandler 元素:

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:camel="http://camel.apache.org/schema/spring"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
    http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
    http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

    <camelContext xmlns="http://camel.apache.org/schema/spring">
        <errorHandler type="DeadLetterChannel"
                      deadLetterUri="activemq:deadLetter"/>
        <route>
            <from uri="activemq:orderQueue"/>
            <to uri="pop3://fulfillment@acme.com"/>
        </route>
        <route>
            <from uri="file:src/data?noop=true"/>
            <to uri="file:target/messages"/>
        </route>
    </camelContext>

</beans>

错误处理器的类型

表 2.1 “错误处理程序类型” 概述您可以定义的不同类型的错误处理程序。

表 2.1. 错误处理程序类型

Java DSL BuilderXML DSL 类型属性描述

defaultErrorHandler()

DefaultErrorHandler

将例外传播到调用者并支持重新传送策略,但它不支持死信队列。

deadLetterChannel()

DeadLetterChannel

支持与默认错误处理程序相同的功能,并且支持死信队列。

loggingErrorChannel()

LoggingErrorChannel

每当发生异常时,记录异常文本。

noErrorHandler()

NoErrorHandler

虚拟处理器实施,可用于禁用错误处理程序。

 

TransactionErrorHandler

转换路由时出错处理程序。默认事务错误处理器实例会自动用于标记为转换的路由。

2.3.3. doTry、doCatch 和最后执行

概述

要在路由内处理异常,您可以使用 doTrydoCatchdo lastly 子句的组合,以类似 Java 的 尝试捕获最后 块处理异常。

doCatch 和 Java catch 之间的相似性

通常,路由定义中的 doCatch() 子句的行为与 Java 代码中的 catch() 语句类似。特别是,doCatch() 子句支持以下功能:

  • 多个 doCatch 子句 s IFL-时间可以在单个 doTry 块内拥有多个 doCatch 子句。doCatch 子句按显示的顺序进行测试,就像 Java catch() 语句一样。Apache Camel 执行与引发 异常匹配的第一个 doCatch 子句。

    注意

    这个算法与 onException 子句的匹配算法所使用的异常匹配算法不同,详情请参阅 第 2.3.1 节 “onException Clause”

  • 使用 结构(请参阅 “在 doCatch 中排放例外”一节)在 doCatch 子句中重新增加例外情况。

doCatch 的特殊特性

但是,doCatch() 子句的一些特殊功能在 Java catch() 语句中没有类似。以下功能特定于 doCatch()

示例

以下示例演示了如何在 Java DSL 中写入 doTry 块,执行 doCatch() 子句的位置,如果 IOException 异常或 IllegalStateException 异常进行引发,并且会 始终执行 doFinally() 子句,无论是否引发异常,是否引发异常。

from("direct:start")
    .doTry()
        .process(new ProcessorFail())
        .to("mock:result")
    .doCatch(IOException.class, IllegalStateException.class)
        .to("mock:catch")
    .doFinally()
        .to("mock:finally")
    .end();

或者,在 Spring XML 中:

<route>
    <from uri="direct:start"/>
    <!-- here the try starts. its a try .. catch .. finally just as regular java code -->
    <doTry>
        <process ref="processorFail"/>
        <to uri="mock:result"/>
        <doCatch>
            <!-- catch multiple exceptions -->
            <exception>java.io.IOException</exception>
            <exception>java.lang.IllegalStateException</exception>
            <to uri="mock:catch"/>
        </doCatch>
        <doFinally>
            <to uri="mock:finally"/>
        </doFinally>
    </doTry>
</route>

在 doCatch 中排放例外

可以使用构造在 doCatch () 子句中重新增加异常,如下所示:

from("direct:start")
    .doTry()
        .process(new ProcessorFail())
        .to("mock:result")
    .doCatch(IOException.class)
         .to("mock:io")
        // Rethrow the exception using a construct instead of handled(false) which is deprecated in a doTry/doCatch clause.
        .throwException(new IllegalArgumentException("Forced"))
    .doCatch(Exception.class)
        // Catch all other exceptions.
        .to("mock:error")
    .end();
注意

您还可以使用在 doTry/doCatch 子句中弃用的处理器 (false) 来重新增加异常:

.process(exchange -> {throw exchange.getProperty(Exchange.EXCEPTION_CAUGHT, Exception.class);})

在前面的示例中,如果 doCatch() 可以发现 IOException,则当前交换将发送到 模拟:io 端点,然后重新进行 IOException。这会在路由开始时(在 from() 命令中)为使用者端点提供处理异常的机会。

以下示例演示了如何在 Spring XML 中定义相同的路由:

<route>
    <from uri="direct:start"/>
    <doTry>
        <process ref="processorFail"/>
        <to uri="mock:result"/>
        <doCatch>
            <to uri="mock:io"/>
            <throwException message="Forced" exceptionType="java.lang.IllegalArgumentException"/>
        </doCatch>
        <doCatch>
            <!-- Catch all other exceptions. -->
            <exception>java.lang.Exception</exception>
            <to uri="mock:error"/>
        </doCatch>
    </doTry>
</route>

使用 When 捕获条件异常

Apache Camel doCatch() 子句的一个特殊功能是,您可以根据运行时评估的表达式来对异常的捕获进行条件化。换而言之,如果您使用表的条款捕获一个异常,则 doCatch(ExceptionList).doWhen(Expression).doWhen( Expression )只会被发现,如果 predicate 表达式、表达式、在运行时评估为 true

例如,以下 doTry 块将捕获异常、IOExceptionIllegalStateException,仅当异常消息包含单词时,Sever e:

from("direct:start")
    .doTry()
        .process(new ProcessorFail())
        .to("mock:result")
    .doCatch(IOException.class, IllegalStateException.class)
        .onWhen(exceptionMessage().contains("Severe"))
        .to("mock:catch")
    .doCatch(CamelExchangeException.class)
        .to("mock:catchCamel")
    .doFinally()
        .to("mock:finally")
    .end();

或者,在 Spring XML 中:

<route>
    <from uri="direct:start"/>
    <doTry>
        <process ref="processorFail"/>
        <to uri="mock:result"/>
        <doCatch>
            <exception>java.io.IOException</exception>
            <exception>java.lang.IllegalStateException</exception>
            <onWhen>
                <simple>${exception.message} contains 'Severe'</simple>
            </onWhen>
            <to uri="mock:catch"/>
        </doCatch>
        <doCatch>
            <exception>org.apache.camel.CamelExchangeException</exception>
            <to uri="mock:catchCamel"/>
        </doCatch>
        <doFinally>
            <to uri="mock:finally"/>
        </doFinally>
    </doTry>
</route>

嵌套条件

可以选择将 Camel 异常处理添加到 JavaDSL 路由。dotry() 创建尝试或捕获块来处理异常,对于特定于路由的错误处理非常有用。

如果要捕获 ChoiceDefinition 内的异常,您可以使用以下 doTry 块:

from("direct:wayne-get-token").setExchangePattern(ExchangePattern.InOut)
           .doTry()
              .to("https4://wayne-token-service")
              .choice()
                  .when().simple("${header.CamelHttpResponseCode} == '200'")
                     .convertBodyTo(String.class)
.setHeader("wayne-token").groovy("body.replaceAll('\"','')")
                     .log(">> Wayne Token : ${header.wayne-token}")
                .endChoice()

.doCatch(java.lang.Class (java.lang.Exception>)
              .log(">> Exception")
           .endDoTry();

from("direct:wayne-get-token").setExchangePattern(ExchangePattern.InOut)
           .doTry()
              .to("https4://wayne-token-service")
           .doCatch(Exception.class)
              .log(">> Exception")
           .endDoTry();

2.3.4. 传播 SOAP Exception

概述

Camel CXF 组件提供了与 Apache CXF 集成,可让您从 Apache Camel 端点发送和接收 SOAP 消息。您可以在 XML 中轻松定义 Apache Camel 端点,然后可使用端点的 bean ID 在路由中引用。如需了解更多详细信息,请参阅 Apache Camel 组件参考指南 中的 CXF

如何传播堆栈追踪信息

可以配置 CXF 端点,以便在服务器端抛出 Java 异常时,异常的堆栈追踪会被放入故障消息并返回到客户端。要启用这个 feaure,请将 dataFormat 设置为 PAYLOAD,并在 cxfEndpoint 元素中将 faultStackTraceEnabled 属性设置为 true,如下所示:

<cxf:cxfEndpoint id="router" address="http://localhost:9002/TestMessage"
    wsdlURL="ship.wsdl"
    endpointName="s:TestSoapEndpoint"
    serviceName="s:TestService"
    xmlns:s="http://test">
  <cxf:properties>
    <!-- enable sending the stack trace back to client; the default value is false-->
    <entry key="faultStackTraceEnabled" value="true" />
    <entry key="dataFormat" value="PAYLOAD" />
  </cxf:properties>
</cxf:cxfEndpoint>

出于安全考虑,堆栈追踪不包括造成异常(即 后面的堆栈跟踪部分)。如果要在堆栈追踪中包含造成异常,请在 cxfEndpoint 元素中将 exceptionMessageCauseEnabled 属性设置为 true,如下所示:

<cxf:cxfEndpoint id="router" address="http://localhost:9002/TestMessage"
    wsdlURL="ship.wsdl"
    endpointName="s:TestSoapEndpoint"
    serviceName="s:TestService"
    xmlns:s="http://test">
  <cxf:properties>
    <!-- enable to show the cause exception message and the default value is false -->
    <entry key="exceptionMessageCauseEnabled" value="true" />
    <!-- enable to send the stack trace back to client,  the default value is false-->
    <entry key="faultStackTraceEnabled" value="true" />
    <entry key="dataFormat" value="PAYLOAD" />
  </cxf:properties>
</cxf:cxfEndpoint>
警告

您应该只启用 exceptionMessageCauseEnabled 标记,用于测试和诊断。服务器通常会区分原始异常原因,从而使恶意用户更难以探测服务器。

2.4. bean Integration

概述

Bean 集成提供了一种通用机制,用于使用任意 Java 对象处理消息。通过将 bean 引用插入到路由中,您可以在 Java 对象上调用任意方法,然后访问和修改传入的交换。将交换内容映射到参数并返回 bean 方法值的机制称为 参数绑定。参数绑定可以使用以下任一方法组合来初始化方法的参数:

  • 传统的方法签名 >_<- the method 签名是否符合某些约定,则参数绑定可以使用 Java 反射来确定要通过哪些参数。
  • 注解和依赖项注入 GCM- the 以获得更灵活的绑定机制,使用 Java 注解指定要注入方法的参数。这种依赖项注入机制依赖于 Spring 2.5 组件扫描。通常,如果您将 Apache Camel 应用程序部署到 Spring 容器中,则依赖项注入机制将自动工作。
  • 在调用 bean 的点上,明确指定参数 InventoryService-latex,可显式指定 参数(可以是恒定常数或使用 Simple 语言)。

bean registry

Bean 是通过 bean registry 进行访问的,该服务可让您将类名称或 bean ID 用作密钥来查找 Bean。您在 bean registry 中创建条目的方式取决于底层的 framework>_<-abrt,如纯 Java、Spring、Spring、Gusice 或 Blueprint。registry 条目通常隐式创建(例如,当您在 Spring XML 文件中实例化 Spring bean 时)。

registry 插件策略

Apache Camel 为 bean 注册表实施插件策略,定义用于访问 Bean 的集成层,从而使底层 registry 的实施透明。因此,可以将 Apache Camel 应用程序与各种不同 Bean registry 集成,如 表 2.2 “registry 插件” 所示。

表 2.2. registry 插件

registry 的实现带有 Registry 插件的 Camel 组件

Spring bean registry

Camel-spring

Guice bean registry

camel-guice

蓝图 bean registry

Camel-blueprint

OSGi 服务 registry

OSGi 容器中部署

JNDI registry

 

通常,您不必担心配置 bean registry,因为会自动为您安装相关的 bean registry。例如,如果您使用 Spring 框架定义路由,则 Spring ApplicationContextRegistry 插件会在当前的 CamelContext 实例中自动安装。

在 OSGi 容器中部署是一个特殊情况。当将 Apache Camel 路由部署到 OSGi 容器时,CamelContext 会自动设置 registry 链以解析 Bean 实例:registry 链包括 OSGi 注册表,后面是 Blueprint(或 Spring) registry。

在 Java 中访问创建的 Bean

要使用 Java bean(一个普通旧的 Java 对象或 OVA)进程交换对象,请使用 bean() 处理器,将入站交换绑定到 Java 对象上的方法。例如,若要使用类 MyBeanProcessor 处理入站交换,请定义如下路由:

from("file:data/inbound")
    .bean(MyBeanProcessor.class, "processBody")
    .to("file:data/outbound");

其中 bean() 处理器创建 MyBeanProcessor 类型的实例,并调用 processBody() 方法来处理入站交换。如果您只想从一个路由访问 MyBeanProcessor 实例,则此方法就足够了。但是,如果您要从多个路由访问相同的 MyBeanProcessor 实例,请使用将对象类型用作其第一个参数的 bean() 变体。例如:

MyBeanProcessor myBean = new MyBeanProcessor();

from("file:data/inbound")
    .bean(myBean, "processBody")
    .to("file:data/outbound");
from("activemq:inboundData")
    .bean(myBean, "processBody")
    .to("activemq:outboundData");

访问过载的 bean 方法

如果 bean 定义了过载方法,您可以通过指定方法名称及其参数类型来选择调用的超载方法。例如,如果 MyBeanBrocessor 类有两个超载方法: processBody(String)processBody(String,String),您可以按照如下所示调用后面的超载方法:

from("file:data/inbound")
  .bean(MyBeanProcessor.class, "processBody(String,String)")
  .to("file:data/outbound");

或者,如果您想要使用的参数数量来识别方法,而不是明确指定每个参数的类型,您可以使用通配符字符 *。例如,要调用名为 processBody 的方法,它采用两个参数(irrespective of)参数,调用 bean() 处理器,如下所示:

from("file:data/inbound")
.bean(MyBeanProcessor.class, "processBody(*,*)")
.to("file:data/outbound");

在指定方法时,您可以使用简单的非限定类型 name- 例如,processBody(Exchange)- 或完全限定域名(如 processBody(org.apache.camel.Exchange)

注意

在当前实现中,指定的类型名称必须是与参数类型完全匹配。类型继承不会考虑。

明确指定参数

当调用 bean 方法时,可以明确指定参数值。可以传递以下简单类型值:

  • 布尔值: truefalse
  • 数字: 1237 等。
  • 字符串: 'In single quotes'"In double quotes"
  • null 对象: null.

以下示例演示了如何将显式参数值与同一方法调用的类型组合:

from("file:data/inbound")
  .bean(MyBeanProcessor.class, "processBody(String, 'Sample string value', true, 7)")
  .to("file:data/outbound");

在前面的示例中,第一个参数的值可能会假定由参数绑定注解决定(请参阅 “基本注解”一节)。

除了简单类型值外,您还可以使用 Simple 语言(第 30 章 简单语言)指定参数值。这意味着在指定 参数值时提供了 Simple 语言的完整功能。例如,将邮件正文和标题 标题 的值传递给 bean 方法:

from("file:data/inbound")
  .bean(MyBeanProcessor.class, "processBodyAndHeader(${body},${header.title})")
  .to("file:data/outbound");

您还可以将整个标头散列映射作为参数传递。例如,以下示例中必须声明第二个方法参数,才能作为 java.util.Map 类型:

from("file:data/inbound")
  .bean(MyBeanProcessor.class, "processBodyAndAllHeaders(${body},${header})")
  .to("file:data/outbound");
注意

从 Apache Camel 2.19 发行版本,从 bean 方法调用返回 null 现在始终确保消息正文已设置为 null 值。

基本方法签名

要将交换绑定到 bean 方法,您可以定义符合特定约定的方法签名。特别是,方法签名有两个基本惯例:

处理消息正文的方法签名

如果要实施访问或修改传入的消息正文的方法,您必须定义一个使用单个 字符串 参数的方法签名,并返回 String 值。例如:

// Java
package com.acme;

public class MyBeanProcessor {
    public String processBody(String body) {
        // Do whatever you like to 'body'...
        return newBody;
    }
}

处理交换的方法签名

为获得更大的灵活性,您可以实施访问传入交换的 bean 方法。这可让您访问或修改所有标头、正文和交换属性。对于处理交换,方法签名使用一个 org.apache.camel.Exchange 参数,并返回 void。例如:

// Java
package com.acme;

public class MyBeanProcessor {
    public void processExchange(Exchange exchange) {
        // Do whatever you like to 'exchange'...
        exchange.getIn().setBody("Here is a new message body!");
    }
}

从 Spring XML 访问 Springan

您可以使用 Spring XML 创建实例,而不必在 Java 中创建 bean 实例。实际上,如果您在 XML 中定义路由,这是唯一可行的方法。要在 XML 中定义 Bean,请使用标准的 Spring Bean 元素。以下示例演示了如何创建 MyBeanProcessor 的实例:

<beans ...>
    ...
    <bean id="myBeanId" class="com.acme.MyBeanProcessor"/>
</beans>

也可以使用 Spring 语法将数据传递到 bean 的构造器参数。有关如何使用 Spring bean 元素的完整详情,请参阅 Spring 参考指南 中的 IoC 容器

使用 bean 元素创建对象实例时,您可以使用 bean 的 ID(an 元素的 id 属性的值)来引用它。例如,如果将 ID 为等于 myBeanIdbean 元素,您可以使用 beanRef() 处理器来引用 Java DSL 路由中的an,如下所示:

from("file:data/inbound").beanRef("myBeanId", "processBody").to("file:data/outbound");

其中 beanRef() 处理器在指定的 bean 实例上调用 MyBeanProcessor.processBody() 方法。

您还可以使用 Camel 架构的 bean 元素从 Spring XML 路由内调用 bean。例如:

<camelContext id="CamelContextID" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="file:data/inbound"/>
    <bean ref="myBeanId" method="processBody"/>
    <to uri="file:data/outbound"/>
  </route>
</camelContext>

为了获得有效效率,您可以将 缓存 选项设置为 true,这样可避免在每次使用 bean 时查找 registry。例如,要启用缓存,您可以在 bean 元素上设置 cache 属性,如下所示:

<bean ref="myBeanId" method="processBody" cache="true"/>

从 Java 访问 Springan

使用 Spring bean 元素创建对象实例时,您可以使用 bean 的 ID( bean 元素的 id 属性的值)从 Java 引用它。例如,如果将 ID 为等于 myBeanIdbean 元素,您可以使用 beanRef() 处理器来引用 Java DSL 路由中的an,如下所示:

from("file:data/inbound").beanRef("myBeanId", "processBody").to("file:data/outbound");

另外,您可以使用 @BeanInject 注释(如下所示)来引用 Spring bean。

// Java
import org.apache.camel.@BeanInject;
...
public class MyRouteBuilder extends RouteBuilder {

   @BeanInject("myBeanId")
   com.acme.MyBeanProcessor bean;

   public void configure() throws Exception {
     ..
   }
}

如果省略 @BeanInject 注释中的 bean ID,Camel 会按照类型查找 registry,但只有在给定类型只有一个 bean 时才能发挥作用。例如,查找并注入 com.acme.MyBeanProcessor 类型的 Bean:

@BeanInject
com.acme.MyBeanProcessor bean;

Spring XML 中的 bean 关闭顺序

对于 Camel 上下文使用的 Bean,正确的关闭顺序通常是:

  1. 关闭 camelContext 实例,后接;
  2. 关闭使用的 Bean。

如果此关闭顺序被反向,那么 Camel 上下文会尝试访问已经被破坏的 Bean(导致直接出错);或者 Camel 上下文尝试在销毁时创建缺失的 bean,这也会导致错误。Spring XML 中的默认关闭顺序取决于 Bean 和 camelContext 中的顺序出现在 Spring XML 文件中。为了避免因为不正确的关闭顺序导致随机错误,因此 camelContext 配置为在 Spring XML 文件中的任何其他 Bean 之前 关闭。从 Apache Camel 2.13.0 开始,这是默认的行为。

如果您需要更改此行为(因此 Camel 上下文 不会在 其他 Bean 之前关闭),您可以将 camelContext 元素上的 shutdownEager 属性设为 false。在这种情况下,您可以使用 Spring dependent-on 属性对关机顺序进行更精细的控制。

参数绑定注解

“基本方法签名”一节 中描述的基本参数绑定可能并不总是方便使用。例如,如果您有一个执行一些数据操作的旧版 Java 类,您可能希望从入站交换中提取数据并将其映射到现有方法签名的参数。对于这种类型的参数绑定,Apache Camel 提供以下 Java 注解类型:

基本注解

表 2.3 “基本 Bean 标注” 显示 org.apache.camel Java 软件包中的注释,您可以使用它来将消息数据注入到 bean 方法的参数中。

表 2.3. 基本 Bean 标注

注解含义参数?

@Attachments

绑定到附加列表。

 

@Body

绑定到入站邮件正文。

 

@Header

绑定到入站邮件标题。

标头的字符串名称。

@Headers

绑定到入站邮件标头的 java.util.Map

 

@OutHeaders

绑定到出站邮件标头的 java.util.Map

 

@property

绑定到指定交换属性。

属性的字符串名称。

@properties

绑定到交换属性的 java.util.Map

 

例如,以下类显示如何使用基本注解将消息数据注入 processExchange() 方法参数。

// Java
import org.apache.camel.*;

public class MyBeanProcessor {
    public void processExchange(
        @Header(name="user") String user,
        @Body String body,
        Exchange exchange
    ) {
        // Do whatever you like to 'exchange'...
        exchange.getIn().setBody(body + "UserName = " + user);
    }
}

请注意,如何将注解与默认规则混合使用。除了注入注解的参数外,参数绑定也会自动将 exchange 对象注入到 org.apache.camel.Exchange 参数。

表达式语言注解

表达式语言注释提供了一种强大的机制,用于将消息数据注入 bean 方法的参数。通过使用这些注解,您可以调用任意脚本(使用您选择的脚本语言编写)从入站交换中提取数据,并将数据注入方法参数。表 2.4 “表达式语言注释” 显示 org.apache.camel.language 软件包(和子软件包)中的注释,供您用来将消息数据注入 bean 方法的参数中。

表 2.4. 表达式语言注释

注解描述

@Bean

注入 Bean 表达式。

@Constant

注入 Constant 表达式

@EL

注入 EL 表达式。

@Groovy

注入 Groovy 表达式。

@Header

注入标题表达式。

@JavaScript

注入 JavaScript 表达式。

@OGNL

注入 OGNL 表达式。

@PHP

注入 PHP 表达式。

@Python

注入 Python 表达式。

@Ruby

注入 Ruby 表达式。

@Simple

注入简单表达式。

@XPath

注入 XPath 表达式。

@XQuery

注入 XQuery 表达式。

例如,以下类显示如何使用 @XPath 注释从 XML 格式的传入消息正文中提取用户名和密码:

// Java
import org.apache.camel.language.*;

public class MyBeanProcessor {
    public void checkCredentials(
        @XPath("/credentials/username/text()") String user,
        @XPath("/credentials/password/text()") String pass
    ) {
        // Check the user/pass credentials...
        ...
    }
}

@Bean 注释是一个特殊情形,因为它可让您注入调用已注册 Bean 的结果。例如,要将关联 ID 注入方法参数,您可以使用 @Bean 注释来调用 ID 生成器类,如下所示:

// Java
import org.apache.camel.language.*;

public class MyBeanProcessor {
    public void processCorrelatedMsg(
        @Bean("myCorrIdGenerator") String corrId,
        @Body String body
    ) {
        // Check the user/pass credentials...
        ...
    }
}

其中字符串 myCorrIdGenerator 是 ID 生成器实例的 bean ID。ID 生成器类可以使用 spring bean 元素实例化,如下所示:

<beans ...>
    ...
    <bean id="myCorrIdGenerator" class="com.acme.MyIdGenerator"/>
</beans>

其中 MyIdGenerator 类可以定义如下:

// Java
package com.acme;

public class MyIdGenerator {

    private UserManager userManager;

    public String generate(
        @Header(name = "user") String user,
        @Body String payload
    ) throws Exception {
       User user = userManager.lookupUser(user);
       String userId = user.getPrimaryId();
       String id = userId + generateHashCodeForPayload(payload);
       return id;
   }
}

请注意,您也可以在 bean 类中使用注解 MyIdGeneratorgenerate() 方法签名的唯一限制是,它必须返回正确的类型来注入 @Bean 注释的参数。由于 @Bean 注释不要求您指定方法名称,因此注入机制只需在引用的 bean 中调用具有匹配返回类型的方法。

注意

某些语言注释在核心组件(@Bean@Constant@Simple@XPath)中可用。但是,对于非内核组件,您必须确定载入相关组件。例如,要使用 OGNL 脚本,您必须加载 camel-ognl 组件。

继承的注解

参数绑定注解可以从接口或从超级类继承。例如,如果您使用 标头 注释和 Body 注解定义 Java 接口,如下所示:

// Java
import org.apache.camel.*;

public interface MyBeanProcessorIntf {
    void processExchange(
        @Header(name="user") String user,
        @Body String body,
        Exchange exchange
    );
}

实现类 MyBeanProcessor 中定义的超载方法现在继承基础接口中定义的注解,如下所示:

// Java
import org.apache.camel.*;

public class MyBeanProcessor implements MyBeanProcessorIntf {
    public void processExchange(
        String user,  // Inherits Header annotation
        String body,  // Inherits Body annotation
        Exchange exchange
    ) {
        ...
    }
}

接口实现

实现 Java 接口的类通常 受保护的private 或在 仅软件包 范围内。如果您在以这种方式限制的实施类上调用方法,则 bean 绑定将返回到调用对应的接口方法,该方法可以公开访问。

例如,请考虑以下公共 BeanIntf 接口:

// Java
public interface BeanIntf {
    void processBodyAndHeader(String body, String title);
}

如果 BeanIntf 接口由以下受保护的 BeanIntfImpl 类实施:

// Java
protected class BeanIntfImpl implements BeanIntf {
    void processBodyAndHeader(String body, String title) {
        ...
    }
}

以下 bean 调用将回退到调用公共 BeanIntf.processBodyAndHeader 方法:

from("file:data/inbound")
  .bean(BeanIntfImpl.class, "processBodyAndHeader(${body}, ${header.title})")
  .to("file:data/outbound");

调用静态方法

Bean 集成具有调用静态方法的能力,无需创建关联类的实例。例如,请考虑以下用于定义静态方法的 Java 类,请更改Something()

// Java
...
public final class MyStaticClass {
    private MyStaticClass() {
    }

    public static String changeSomething(String s) {
        if ("Hello World".equals(s)) {
            return "Bye World";
        }
        return null;
    }

    public void doSomething() {
        // noop
    }
}

您可以使用 bean 集成来调用静态的 changeSomething 方法,如下所示:

from("direct:a")
  *.bean(MyStaticClass.class, "changeSomething")*
  .to("mock:a");

请注意,虽然这种语法与普通功能的调用相同,但同时也是集成漏洞的 Java 反映出方法,以识别静态方法并继续调用方法,而无需 实例化 MyStaticClass

调用 OSGi 服务

在特殊情况下,路由部署到红帽 Fuse 容器中,可以使用 bean 集成直接调用 OSGi 服务。例如,假设 OSGi 容器中的捆绑包已导出该服务,即 org.fusesource.example.HelloWorldOsgiService,您可以使用以下 bean 集成代码调用 sayHello 方法:

from("file:data/inbound")
  .bean(org.fusesource.example.HelloWorldOsgiService.class, "sayHello")
  .to("file:data/outbound");

您还可以使用 bean 组件从 Spring 或蓝图 XML 文件中调用 OSGi 服务,如下所示:

<to uri="bean:org.fusesource.example.HelloWorldOsgiService?method=sayHello"/>

这种方法的工作方式是,当 Apache Camel 在 OSGi 容器中部署时,会设置一个 registry 链。首先,它会在 OSGi 服务 registry 中查找指定的类名称 ; 如果这个查找失败,它将回退到本地 Spring DM 或蓝图 registry。

2.5. 创建交换实例

概述

使用 Java 代码处理消息时(例如,在 bean 类或在处理器类中),通常会需要创建新的交换实例。如果您需要创建 Exchange 对象,最简单的方法是调用 ExchangeBuilder 类的方法,如下所述。

ExchangeBuilder 类

ExchangeBuilder 类的完全限定名称如下:

org.apache.camel.builder.ExchangeBuilder

ExchangeBuilder 公开静态方法 aExchange,可用于开始构建交换对象。

示例

例如,以下代码会创建一个新的交换对象,其中包含消息正文字符串 Hello World!,以及包含用户名和密码凭证的标头:

// Java
import org.apache.camel.Exchange;
import org.apache.camel.builder.ExchangeBuilder;
...
Exchange exch = ExchangeBuilder.anExchange(camelCtx)
                    .withBody("Hello World!")
                    .withHeader("username", "jdoe")
                    .withHeader("password", "pass")
                    .build();

ExchangeBuilder 方法

ExchangeBuilder 类支持以下方法:

ExchangeBuilder aExchange(CamelContext context)
(静态方法)初始构建交换对象。
Exchange build()
构建交换.
ExchangeBuilder withBody(Object body)
在交换上设置消息正文(即,设置交换的 In 消息正文)。
ExchangeBuilder 带有Header(String key, Object value)
在交换上设置一个标头(即,在交换的 In 消息上设置一个标头)。
ExchangeBuilder withPattern(ExchangePattern pattern)
在交换模式上设置交换模式。
ExchangeBuilder withProperty(String key, Object value)
在交换上设置属性。

2.6. 转换消息内容

摘要

Apache Camel 支持多种方法来转换消息内容。除了用于修改消息内容的简单原生 API 外,Apache Camel 支持与几个不同的第三方库和转换标准集成。

2.6.1. 简单消息转换

概述

Java DSL 具有一个内置 API,允许您在传入和传出消息上执行简单的转换。例如,例 2.1 “引入消息的简单转换” 中显示的规则会将文本 World! 附加到传入消息正文的末尾。

例 2.1. 引入消息的简单转换

from("SourceURL").setBody(body().append(" World!")).to("TargetURL");

其中 setBody() 命令取代了传入邮件正文的内容。

用于简单转换的 API

您可以使用以下 API 类在路由器规则中执行消息内容的简单转换:

  • org.apache.camel.model.ProcessorDefinition
  • org.apache.camel.builder.Builder
  • org.apache.camel.builder.ValueBuilder

ProcessorDefinition class

org.apache.camel.model.ProcessorDefinition 类定义 DSL 命令,您可以在 例 2.1 “引入消息的简单转换” 中直接插入路由器 rule>_<-targetNamespaces 例如: 中的 setBody() 命令。表 2.5 “从处理器Definition 类转换方法” 显示与转换消息内容相关的 ProcessorDefinition 方法:

表 2.5. 从处理器Definition 类转换方法

方法描述

类型 convertBodyTo(Class type)

将 IN 消息正文转换为指定的类型。

类型 removeFaultHeader(字符串名称)

添加处理器,以删除 FAULT 消息上的标头。

type removeHeader(String name)

添加可移除 IN 消息上的标头的处理器。

键入 removeProperty(String name)

添加可移除交换属性的处理器。

ExpressionClause<ProcessorDefinition<Type>> setBody()

添加在 IN 消息上设置正文的处理器。

键入 setFaultBody(Expression expression)

添加在 FAULT 消息上设置正文的处理器。

type setFaultHeader(String name, Expression expression)

添加在 FAULT 消息上设置标头的处理器。

ExpressionClause<ProcessorDefinition<Type>> setHeader(String name)

添加在 IN 消息上设置标头的处理器。

type setHeader(String name, Expression expression)

添加在 IN 消息上设置标头的处理器。

ExpressionClause<ProcessorDefinition<Type>> setOutHeader(String name)

添加在 OUT 消息上设置标头的处理器。

type setOutHeader(String name, Expression expression)

添加在 OUT 消息上设置标头的处理器。

ExpressionClause<ProcessorDefinition<Type>> setProperty(String name)

添加可设置 Exchange 属性的处理器。

键入 setProperty(String name, Expression expression)

添加可设置 Exchange 属性的处理器。

ExpressionClause<ProcessorDefinition<Type>> transform()

添加在 OUT 消息上设置正文的处理器。

类型转换(Expression 表达式)

添加在 OUT 消息上设置正文的处理器。

builder 类

org.apache.camel.builder.Builder 类提供对预期表达式或 predicates 的上下文中的消息内容的访问。换句话说,在 DSL 命令的参数 中通常会调用 Builder 方法。例如,例 2.1 “引入消息的简单转换” 中的 body() 命令。表 2.6 “Builder 类中的方法” 总结 Builder 类中的静态方法。

表 2.6. Builder 类中的方法

方法描述

静态 <E 扩展 Exchange> ValueBuilder<E> body()

为交换上的入站正文返回 predicate 和 value builder。

静态 <E 扩展 Exchange,T> ValueBuilder<E> bodyAs(Class<T> type)

为入站邮件正文返回 predicate 和 value builder,作为特定类型的值。

静态 <E 扩展 Exchange> ValueBuilder<E> constant(Object value)

返回恒定表达式。

静态 <E 扩展 Exchange> ValueBuilder<E> faultBody()

为交换上的错误正文返回 predicate 和 value builder。

静态 <E 扩展 Exchange,T> ValueBuilder<E> faultBodyAs(Class<T> type)

为错误消息正文返回 predicate 和 value builder,作为特定类型的值。

静态 <E 扩展 Exchange> ValueBuilder<E> 标头(字符串名称)

为交换上的标头返回 predicate 和 value builder。

静态 <E 扩展 Exchange> ValueBuilder<E> outBody()

为交换上的出站正文返回 predicate 和 value builder。

静态 <E 扩展 Exchange> ValueBuilder<E> outBodyAs(Class<T> type)

为出站邮件正文返回 predicate 和 value builder,作为特定类型的特定类型。

static ValueBuilder 属性(字符串名称)

为交换的属性返回 predicate 和 value builder。

static ValueBuilder regexReplaceAll(Expression content, String regex, Expression replacement)

返回表达式将所有出现正则表达式的表达式替换为给定的替换。

static ValueBuilder regexReplaceAll(Expression content, String regex, String replacement)

返回表达式将所有出现正则表达式的表达式替换为给定的替换。

static ValueBuilder sendTo(String uri)

返回将交换发送到给定端点 uri 的表达式。

静态 <E 扩展 Exchange> ValueBuilder<E> systemProperty(String name)

返回给定系统属性的表达式。

静态 <E 扩展 Exchange> ValueBuilder<E> systemProperty(String name, String defaultValue)

返回给定系统属性的表达式。

ValueBuilder 类

org.apache.camel.builder.ValueBuilder 类允许您修改 Builder 方法返回的值。换句话说,ValueBuilder 中的方法提供了一个简单的修改消息内容的方法。表 2.7 “ValueBuilder 类的修饰符方法” 总结了 ValueBuilder 类中可用的方法。也就是说,该表只显示用于修改在其所调用的值的方法(查看完整详情,请参阅 API 参考文档 )。

表 2.7. ValueBuilder 类的修饰符方法

方法描述

ValueBuilder<E> append(Object value)

使用所给值附加此表达式的字符串评估。

predicate 包含(Object 值)

创建一个 predicate,使左手表达式包含右手表达式的值。

ValueBuilder<E> convertTo(Class type)

使用已注册类型转换器将当前值转换为给定类型。

ValueBuilder<E> convertToString()

使用注册的类型转换器转换当前值 String。

predicate 结束(Object value)

 

<T> T evaluate(Exchange exchange, Class<T> type)

 

predicate in(Object…​ values)

 

predicate in(Predicate…​ predicates)

 

predicate 是EqualTo(Object value)

返回 true,如果当前值等于给定 参数。

predicate 是GreaterThan(Object 值)

返回 true,如果当前值大于给定 参数。

predicate 是GreaterThanOrEqualTo(Object value)

返回 true,如果当前值大于或等于给定 参数。

predicate 是InstanceOf(Class type)

返回为 true,如果当前值是给定类型的实例。

predicate isLessThan(Object value)

返回为 true,如果当前值小于给定 参数。

predicate 是 LessThanOrEqualTo(Object value)

返回为 true,如果当前值小于或等于给定 参数。

predicate 是NotEqualTo(Object value)

返回 true,如果当前值不等于给定 参数。

predicate 是NotNull()

返回 true,如果当前值不是 null,则返回。

predicate isNull()

返回 true,如果当前值是 null

predicate matches(Expression 表达式)

 

predicate not(Predicate predicate)

导航 predicate 参数。

ValueBuilder prepend(Object value)

将这个表达式的字符串评估添加到所给值。

predicate regex(字符串 regex)

 

ValueBuilder<E> regexReplaceAll(String regex, Expression<E> 替换)

将正则表达式的所有发生情况替换为给定的替换。

ValueBuilder<E> regexReplaceAll(String regex, String replacement)

将正则表达式的所有发生情况替换为给定的替换。

ValueBuilder<E> regexTokenize(String regex)

使用给定的正则表达式对这个表达式的字符串转换进行令牌。

ValueBuilder sort(Comparator comparator)

使用给定比较器对当前值进行排序。

predicate 启动With(Object 值)

返回 true,如果当前值与 value 参数的字符串值匹配。

ValueBuilder<E> tokenize()

使用逗号令牌分隔符标记此表达式的字符串转换。

ValueBuilder<E> 令牌化(字符串令牌)

使用给定令牌分隔符对这个表达式的字符串转换进行令牌转换。

2.6.2. marshalling 和 Unmarshalling

Java DSL 命令

您可以使用以下命令在低级和高级别消息格式转换:

  • marshal() abrt-abrt 将高级别数据格式转换为低级数据格式。
  • unmarshal() jaxb-abrt 将低级数据格式转换为高级别数据格式。

数据格式

Apache Camel 支持以下数据格式的 marshalling 和 unmarshalling:

  • Java序列化
  • JAXB
  • XMLBeans
  • XStream

Java序列化

允许您将 Java 对象转换为二进制数据的 Blob。对于这个数据格式,取消marshall 会将二进制 blob 转换为 Java 对象,并将 Java 对象转换为二进制 blob。例如,若要从端点 SourceURL 读取序列化 Java 对象,并将其转换为 Java 对象,您可以使用类似如下的规则:

from("SourceURL").unmarshal().serialization()
.<FurtherProcessing>.to("TargetURL");

或者,在 Spring XML 中:

<camelContext id="serialization" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="SourceURL"/>
    <unmarshal>
      <serialization/>
    </unmarshal>
    <to uri="TargetURL"/>
  </route>
</camelContext>

JAXB

提供 XML 模式类型和 Java 类型之间的映射(请参阅 https://jaxb.dev.java.net/)。对于 JAXB,unmarshalling 会将 XML 数据类型转换为 Java 对象,并总结 Java 对象转换为 XML 数据类型。在可以使用 JAXB 数据格式之前,您必须使用 JAXB 编译器编译您的 XML 架构,以在架构中生成代表 XML 数据类型的 Java 类。这称为 绑定模式。绑定模式后,您可以使用类似如下的代码定义将 XML 数据解压缩到 Java 对象的规则:

org.apache.camel.spi.DataFormat jaxb = new org.apache.camel.converter.jaxb.JaxbDataFormat("GeneratedPackageName");

from("SourceURL").unmarshal(jaxb)
.<FurtherProcessing>.to("TargetURL");

其中 generateedPackagename 是 JAXB 编译器生成的 Java 软件包的名称,其中包含代表您的 XML 架构的 Java 类。

或者,在 Spring XML 中:

<camelContext id="jaxb" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="SourceURL"/>
    <unmarshal>
      <jaxb prettyPrint="true" contextPath="GeneratedPackageName"/>
    </unmarshal>
    <to uri="TargetURL"/>
  </route>
</camelContext>

XMLBeans

提供 XML 模式类型和 Java 类型之间的备选映射(请参阅 http://xmlbeans.apache.org/)。对于 XMLBeans,unmarshalling 会将 XML 数据类型转换为 Java 对象,并将 Java 对象转换为 XML 数据类型。例如,要使用 XMLBeans 将 XML 数据解压缩到 Java 对象,您可以使用类似如下的代码:

from("SourceURL").unmarshal().xmlBeans()
.<FurtherProcessing>.to("TargetURL");

或者,在 Spring XML 中:

<camelContext id="xmlBeans" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="SourceURL"/>
    <unmarshal>
      <xmlBeans prettyPrint="true"/>
    </unmarshal>
    <to uri="TargetURL"/>
  </route>
</camelContext>

XStream

提供 XML 类型和 Java 类型之间的另一个映射(请参阅 http://www.xml.com/pub/a/2004/08/18/xstream.html)。XStream 是一个序列化库(如 Java序列化),可让您将任何 Java 对象转换为 XML。对于 XStream,解压缩将 XML 数据类型转换为 Java 对象,并汇总 Java 对象,将 Java 对象转换为 XML 数据类型。

from("SourceURL").unmarshal().xstream()
.<FurtherProcessing>.to("TargetURL");
注意

Spring XML 目前不支持 XStream 数据格式。

2.6.3. 端点绑定

什么是绑定?

在 Apache Camel 中,绑定 是一种将端点嵌套在 contract contract-sHistoryLimit 例如,通过应用数据格式、内容增强器或验证步骤的方法。条件或转换应用于传入消息的消息,并应用于消息的补充条件或转换。

DataFormatBinding

对于您要定义 marshals 和 unmarshals 特定数据格式的绑定(请参阅 第 2.6.2 节 “marshalling 和 Unmarshalling”,请参阅 在这种情况下,您需要进行创建绑定的所有操作都是创建 DataFormatBinding 实例,在 constructor 中传递对相关数据格式的引用。

例如: 例 2.2 “JAXB Binding” 中的 XML DSL 片断会显示一个绑定(带有 ID、jaxb)的绑定(使用 ID, jaxb ),当它与 Apache Camel 端点关联时,能够放宽和取消汇总 JAXB 数据格式:

例 2.2. JAXB Binding

<beans ... >
    ...
    <bean id="jaxb" class="org.apache.camel.processor.binding.DataFormatBinding">
        <constructor-arg ref="jaxbformat"/>
    </bean>

    <bean id="jaxbformat" class="org.apache.camel.model.dataformat.JaxbDataFormat">
        <property name="prettyPrint" value="true"/>
        <property name="contextPath" value="org.apache.camel.example"/>
    </bean>

</beans>

将绑定与端点关联

以下的替代方法可用于将绑定与端点关联:

绑定 URI

要将绑定与端点关联,您可以将端点 URI 前缀为 binding:NameOfBinding,其中 NameOfBinding 是绑定的 bean ID(例如,在 Spring XML 中创建绑定 bean 的 ID)。

例如,以下示例演示了如何将 ActiveMQ 端点与 例 2.2 “JAXB Binding” 中定义的 JAXB 绑定关联。

<beans ...>
    ...
    <camelContext xmlns="http://camel.apache.org/schema/spring">
        <route>
            <from uri="binding:jaxb:activemq:orderQueue"/>
            <to uri="binding:jaxb:activemq:otherQueue"/>
        </route>
    </camelContext>
    ...
</beans>

BindingComponent

您可以做出隐式关联绑定而不是将绑定与端点关联,而不必在 URI 中显示绑定。对于没有隐式绑定的现有端点,实现此目的的最简单方法是使用 BindingComponent 类包装端点。

例如,要将 jaxb 绑定与 activemq 端点关联,您可以定义新的 BindingComponent 实例,如下所示:

<beans ... >
    ...
    <bean id="jaxbmq" class="org.apache.camel.component.binding.BindingComponent">
        <constructor-arg ref="jaxb"/>
        <constructor-arg value="activemq:foo."/>
    </bean>

    <bean id="jaxb" class="org.apache.camel.processor.binding.DataFormatBinding">
        <constructor-arg ref="jaxbformat"/>
    </bean>

    <bean id="jaxbformat" class="org.apache.camel.model.dataformat.JaxbDataFormat">
        <property name="prettyPrint" value="true"/>
        <property name="contextPath" value="org.apache.camel.example"/>
    </bean>

</beans>

其中(可选) jaxbmq 的第二个构造器参数定义了 URI 前缀。现在,您可以使用 jaxbmq ID 作为端点 URI 的方案。例如,您可以使用这个绑定组件定义以下路由:

<beans ...>
    ...
    <camelContext xmlns="http://camel.apache.org/schema/spring">
        <route>
            <from uri="jaxbmq:firstQueue"/>
            <to uri="jaxbmq:otherQueue"/>
        </route>
    </camelContext>
    ...
</beans>

前面的路由等同于以下路由,它使用绑定 URI 方法:

<beans ...>
    ...
    <camelContext xmlns="http://camel.apache.org/schema/spring">
        <route>
            <from uri="binding:jaxb:activemq:foo.firstQueue"/>
            <to uri="binding:jaxb:activemq:foo.otherQueue"/>
        </route>
    </camelContext>
    ...
</beans>
注意

对于实施自定义 Apache Camel 组件的开发人员,可以通过实施从 org.apache.camel.spi.HasBinding 接口继承的端点类来实现这一点。

BindingComponent constructors

BindingComponent 类支持以下 constructors:

public BindingComponent()
无参数形式。使用属性注入配置绑定组件实例。
public BindingComponent(Binding binding)
将此绑定组件与指定的 Binding 对象关联,并且 绑定
public BindingComponent(Binding binding, String uriPrefix)
将此绑定组件与指定的 Binding 对象、绑定和 URI 前缀关联,uriPrefix。这是最常用的构造器。
public BindingComponent(Binding binding, String uriPrefix, String uriPostfix)
此构造器支持额外的 URI post-fix, uri postfix , 参数,该参数会自动附加到使用此绑定组件定义的任何 URI。

实现自定义绑定

除了 DataFormatBinding 之外,可用于汇总和解包数据格式,您可以实施自己的自定义绑定。定义自定义绑定,如下所示:

  1. 实施 org.apache.camel.Processor 类,对传入到消费者端点的消息执行转换( 元素推断)。
  2. 实施补充 org.apache.camel.Processor 类,对从制作者端点(位于元素中)发出的消息执行反向转换。
  3. 实施 org.apache.camel.spi.Binding 接口,它充当处理器实例的工厂。

绑定接口

例 2.3 “org.apache.camel.spi.Binding 接口” 显示 org.apache.camel.spi.Binding 接口的定义,您必须实现它们来定义自定义绑定。

例 2.3. org.apache.camel.spi.Binding 接口

// Java
package org.apache.camel.spi;

import org.apache.camel.Processor;

/**
 * Represents a <a href="http://camel.apache.org/binding.html">Binding</a> or contract
 * which can be applied to an Endpoint; such as ensuring that a particular
 * <a href="http://camel.apache.org/data-format.html">Data Format</a> is used on messages in and out of an endpoint.
 */
public interface Binding {

    /**
     * Returns a new {@link Processor} which is used by a producer on an endpoint to implement
     * the producer side binding before the message is sent to the underlying endpoint.
     */
    Processor createProduceProcessor();

    /**
     * Returns a new {@link Processor} which is used by a consumer on an endpoint to process the
     * message with the binding before its passed to the endpoint consumer producer.
     */
    Processor createConsumeProcessor();
}

何时使用绑定

当您需要应用相同的转换到许多不同类型的端点时,绑定很有用。

2.7. attribute Placeholders

概述

属性占位符功能可用于将字符串替换为不同的上下文(如 XML DSL 元素中的端点 URI 和属性),其中占位符设置存储在 Java 属性文件中。如果您要在不同 Apache Camel 应用程序间共享设置,或者您想要集中特定的配置设置,则这个功能很有用。

例如,以下路由将请求发送到 Web 服务器(其主机和端口由占位符替换)、{{remote.host}}{{remote.port}}

from("direct:start").to("http://{{remote.host}}:{{remote.port}}");

占位符值在 Java 属性文件中定义,如下所示:

# Java properties file
remote.host=myserver.com
remote.port=8080
注意

属性 Placeholders 支持编码选项,可让您使用特定的字符集(如 UTF-8)读取 .properties 文件。但是,默认情况下,它会实施 ISO-8859-1 字符集。

使用 PropertyPlaceholders 的 Apache Camel 支持以下内容:

  • 将默认值与要查找的键一起指定。
  • 不需要定义 PropertiesComponent,如果所有占位符键都包含默认值,则会使用它们。
  • 使用第三方函数查找属性值。它可让您实施自己的逻辑。

    注意

    提供三个开箱即用功能,以从 OS 环境变量、JVM 系统属性或服务名称 idiom 查找值。

属性文件

属性设置存储在一个或多个 Java 属性文件中,且必须符合标准的 Java 属性文件格式。每个属性设置出现在其自己的行中,格式为 Key=Value。带有 #! 作为第一个非空字符的行被视为注释。

例如,属性文件可能含有内容,如 例 2.4 “Property 文件示例” 所示。

例 2.4. Property 文件示例

# Property placeholder settings
# (in Java properties file format)
cool.end=mock:result
cool.result=result
cool.concat=mock:{{cool.result}}
cool.start=direct:cool
cool.showid=true

cheese.end=mock:cheese
cheese.quote=Camel rocks
cheese.type=Gouda

bean.foo=foo
bean.bar=bar

解决属性

属性组件必须配置有一个或多个属性文件的位置,然后才能在路由定义中使用它。您必须使用以下解析器之一提供属性值:

classpath:PathName,PathName,…​
(默认) 指定类路径中的位置,其中 PathName 是使用正斜杠分隔的文件路径名。
file:PathName,PathName,…​
指定文件系统中的位置,其中 PathName 是以正斜杠分隔的文件路径名。
ref:BeanID
指定 registry 中的 java.util.Properties 对象的 ID。
蓝图:BeanID
指定 cm:property-placeholder bean 的 ID,该 ID 可用于访问 OSGi 配置管理服务中定义的属性。详情请查看 “与 OSGi 蓝图属性占位符集成”一节

例如,要指定 com/fusesource/cheese.properties 属性文件和 com/fusesource/bar.properties 属性文件,两者均位于 classpath 上,您需要使用以下位置字符串:

com/fusesource/cheese.properties,com/fusesource/bar.properties
注意

您可以省略本例中的 classpath: 前缀,因为默认情况下使用 classpath 解析器。

使用系统属性和环境变量指定位置

您可以在位置 PathName 中嵌入 Java 系统属性和 O/S 环境变量。

Java 系统属性可以使用语法 ${PropertyName} 嵌入在位置解析器中。例如,如果 Red Hat Fuse 的根目录存储在 Java 系统属性 karaf.home 中,您可以把该目录值嵌入到文件位置中,如下所示:

file:${karaf.home}/etc/foo.properties

O/S 环境变量可以使用语法( ${env:VarName} )嵌入到位置解析器中。例如,如果 JBoss Fuse 的根目录存储在环境变量 SMX_HOME 中,您可以将该目录的内容嵌入到文件位置,如下所示:

file:${env:SMX_HOME}/etc/foo.properties

配置属性组件

在开始使用属性占位符前,您必须配置属性组件,指定一个或多个属性文件的位置。

在 Java DSL 中,您可以使用属性文件位置配置属性组件,如下所示:

// Java
import org.apache.camel.component.properties.PropertiesComponent;
...
PropertiesComponent pc = new PropertiesComponent();
pc.setLocation("com/fusesource/cheese.properties,com/fusesource/bar.properties");
context.addComponent("properties", pc);

addComponent() 调用所示,属性组件的名称 必须设置为 属性

在 XML DSL 中,您可以使用专用 propertyPlacholder 元素配置属性组件,如下所示:

<camelContext ...>
   <propertyPlaceholder
      id="properties"
      location="com/fusesource/cheese.properties,com/fusesource/bar.properties"
   />
</camelContext>

如果您希望属性组件在初始化时忽略任何缺少的 .properties 文件,您可以将 ignoreMissingLocation 选项设置为 true (通常情况下,缺少 .properties 文件会导致错误引发)。

另外,如果您希望属性组件忽略使用 Java 系统属性或 O/S 环境变量指定的任何缺少的位置,您可以将 ignoreMissingLocation 选项设置为 true

占位符语法

配置后,属性组件会自动替换占位符(在适当的上下文中)。占位符语法取决于上下文,如下所示:

  • 在端点 URI 中,在 Spring XML 文件中 InventoryService-","the 占位符被指定为 { {Key}}
  • 当设置 XML DSL 属性时 ,使用以下语法设置 字符串 属性:

    AttributeName="{{Key}}"

    必须使用以下语法设置其他属性类型(例如 xs:intxs:boolean):

    prop:AttributeName="Key"

    其中 prophttp://camel.apache.org/schema/placeholder 命名空间关联。

  • 在设置 Java DSL EIP 选项 targetNamespaces 选项 InventoryService-jaxbto 时,在 Java DSL 中对企业级集成模式(EIP)命令设置选项时,请在流畅的 DSL 中添加类似于以下内容的 占位符() 子句:

    .placeholder("OptionName", "Key")
  • 在简单语言表达式中 ,placeholder指定为 ${properties:Key}

在端点 URI 中替换

只要端点 URI 字符串出现在路由中,解析端点 URI 的第一步是应用属性占位符解析器。占位符解析器自动替换双花括号之间出现的任何属性名称 {{ Key}}。例如,如果 例 2.4 “Property 文件示例” 中显示的属性设置,您可以定义路由,如下所示:

from("{{cool.start}}")
    .to("log:{{cool.start}}?showBodyType=false&showExchangeId={{cool.showid}}")
    .to("mock:{{cool.result}}");

默认情况下,占位符解析器查找 registry 中的 属性 bean ID 来查找属性组件。如果愿意,您可以在端点 URI 中明确指定方案。例如,通过为每个端点 URI 加上前缀 属性: 到每个端点 URI,您可以定义以下等同的路由:

from("properties:{{cool.start}}")
    .to("properties:log:{{cool.start}}?showBodyType=false&showExchangeId={{cool.showid}}")
    .to("properties:mock:{{cool.result}}");

在明确指定方案时,您还可以选择指定属性组件的选项。例如,要覆盖属性文件位置,您可以按照如下所示设置 location 选项:

from("direct:start").to("properties:{{bar.end}}?location=com/mycompany/bar.properties");

在 Spring XML 文件中替换

您还可以使用 XML DSL 中的属性占位符,设置 DSL 元素的各种属性。在此上下文中,拥有者语法也使用双花括号 {{ Key}}。例如,您可以使用属性占位符定义 jmxAgent 元素,如下所示:

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
    <propertyPlaceholder id="properties" location="org/apache/camel/spring/jmx.properties"/>

    <!-- we can use property placeholders when we define the JMX agent -->
    <jmxAgent id="agent" registryPort="{{myjmx.port}}"
              usePlatformMBeanServer="{{myjmx.usePlatform}}"
              createConnector="true"
              statisticsLevel="RoutesOnly"
            />

    <route>
        <from uri="seda:start"/>
        <to uri="mock:result"/>
    </route>
</camelContext>

替换 XML DSL 属性值

您可以使用常规占位符语法来指定 xs:string typegradle-sHistoryLimitfor example, < jmxAgent registryPort="{{myjmx.port}}" …​ >。但是,对于任何其他类型的属性(例如,xs:intxs:boolean),您必须使用特殊语法 prop:AttributeName="Key"

例如,如果某个属性文件定义了 stop.flag 属性的值为 true,您可以使用此属性来设置 stopOnException 布尔值属性,如下所示:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:prop="http://camel.apache.org/schema/placeholder"
       ... >

    <bean id="illegal" class="java.lang.IllegalArgumentException">
        <constructor-arg index="0" value="Good grief!"/>
    </bean>

    <camelContext xmlns="http://camel.apache.org/schema/spring">

        <propertyPlaceholder id="properties"
                             location="classpath:org/apache/camel/component/properties/myprop.properties"
                             xmlns="http://camel.apache.org/schema/spring"/>

        <route>
            <from uri="direct:start"/>
            <multicast prop:stopOnException="stop.flag">
                <to uri="mock:a"/>
                <throwException ref="damn"/>
                <to uri="mock:b"/>
            </multicast>
        </route>

    </camelContext>

</beans>
重要

必须明确分配给 Spring 文件中的 http://camel.apache.org/schema/placeholder 命名空间,如上例的 Bean 元素中所示。

替换 Java DSL EIP 选项

在 Java DSL 中调用 EIP 命令时,您可以通过添加表单、占位符(" options Name", "Key") 值,使用属性值来设置任何 EIP 选项。

例如,如果某个属性文件定义了 stop.flag 属性的值为 true,您可以使用此属性设置多播 EIP 的 stopOnException 选项,如下所示:

from("direct:start")
    .multicast().placeholder("stopOnException", "stop.flag")
        .to("mock:a").throwException(new IllegalAccessException("Damn")).to("mock:b");

使用简单语言表达式替换

您还可以使用简单语言表达式替换属性占位符,但在本例中,占位符语法为 ${properties:Key}。例如,您可以替换简单表达式内的 cheese.quote 占位符,如下所示:

from("direct:start")
    .transform().simple("Hi ${body} do you think ${properties:cheese.quote}?");

您可以使用语法 ${properties:Key:DefaultVal} 来指定属性的默认值。例如:

from("direct:start")
    .transform().simple("Hi ${body} do you think ${properties:cheese.quote:cheese is good}?");

也可以使用语法( ${properties-location:Location:Key} )覆盖属性文件的位置。例如,要使用 com/mycompany/bar.properties 属性中的设置替换 bar.quote 占位符,您可以按照如下所示定义简单表达式:

from("direct:start")
    .transform().simple("Hi ${body}. ${properties-location:com/mycompany/bar.properties:bar.quote}.");

在 XML DSL 中使用 Property Placeholders

在旧版中,xs:string 类型属性用于支持 XML DSL 中的占位符。例如,timeout 属性是一个 xs:int 类型。因此,您无法将字符串值设置为占位符键。

从 Apache Camel 2.7 开始,现在可以使用特殊的占位符命名空间来实现。以下示例演示了命名空间的 prop 前缀。它允许您使用 XML DSL 中属性中的 prop 前缀。

注意

在多播中,将选项 stopOnException 设置为带有键 stop 的占位符值。另外,在属性文件中,将值定义为

stop=true
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:prop="http://camel.apache.org/schema/placeholder"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
    ">

    <!-- Notice in the declaration above, we have defined the prop prefix as the Camel placeholder namespace -->

    <bean id="damn" class="java.lang.IllegalArgumentException">
        <constructor-arg index="0" value="Damn"/>
    </bean>

    <camelContext xmlns="http://camel.apache.org/schema/spring">

        <propertyPlaceholder id="properties"
                             location="classpath:org/apache/camel/component/properties/myprop.properties"
                             xmlns="http://camel.apache.org/schema/spring"/>

        <route>
            <from uri="direct:start"/>
            <!-- use prop namespace, to define a property placeholder, which maps to
                 option stopOnException={{stop}} -->
            <multicast prop:stopOnException="stop">
                <to uri="mock:a"/>
                <throwException ref="damn"/>
                <to uri="mock:b"/>
            </multicast>
        </route>

    </camelContext>

</beans>

与 OSGi 蓝图属性占位符集成

如果您将路由部署到红帽 Fuse OSGi 容器中,您可以将 Apache Camel 属性占位符机制与 JBoss Fuse 的蓝图属性占位符机制(事实上是启用集成)。设置集成的基本方法有两种,如下所示:

隐式蓝图集成

如果您在 OSGi 蓝图文件中定义了 camelContext 元素,Apache Camel 属性占位符机制会自动与蓝图属性占位符机制集成。也就是说,在 camelContext 范围内出现的占位符遵循 Apache Camel 语法(如 {{cool.end}})通过查找 蓝图属性占位符 机制来隐式解析。

例如,考虑在 OSGi 蓝图文件中定义以下路由,路由中最后一个端点由属性占位符定义,{{result}}

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"
           xsi:schemaLocation="
           http://www.osgi.org/xmlns/blueprint/v1.0.0 https://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">

    <!-- OSGI blueprint property placeholder -->
    <cm:property-placeholder id="myblueprint.placeholder" persistent-id="camel.blueprint">
        <!-- list some properties for this test -->
        <cm:default-properties>
            <cm:property name="result" value="mock:result"/>
        </cm:default-properties>
    </cm:property-placeholder>

    <camelContext xmlns="http://camel.apache.org/schema/blueprint">
        <!-- in the route we can use {{ }} placeholders which will look up in blueprint,
             as Camel will auto detect the OSGi blueprint property placeholder and use it -->
        <route>
            <from uri="direct:start"/>
            <to uri="mock:foo"/>
            <to uri="{{result}}"/>
        </route>
    </camelContext>

</blueprint>

蓝图属性占位符机制通过创建一个 cm:property-placeholder an 初始化。在前面的示例中,cm:property-placeholder bean 与 camel.blueprint 持久 ID 关联,持久 ID 是引用 OSGi 配置管理 服务中一组相关属性的标准方式。换句话说,cm:property-placeholder an 提供了对 camel.blueprint 持久 ID 中定义的所有属性的访问权限。也可以为某些属性指定默认值(使用嵌套的 cm:property 元素)。

在蓝图上下文中,Apache Camel 占位符机制搜索 bean registry 中的 cm:property-placeholder 实例。如果找到这样的实例,它会自动集成 Apache Camel 占位符机制,以便等占位符 {{result}} 可以通过在蓝图属性占位符机制中查找密钥(在这个示例中,通过 myblueprint.placeholder bean)来解决。

注意

默认蓝图占位符语法(直接访问蓝图属性)为 ${Key}。因此,在 camelContext 元素的范围 之外,您必须使用占位符语法为 ${Key}。但在 camelContext 元素的范围中,您必须使用占位符语法是 {{ Key}}

显式蓝图集成

如果您想要更多控制 Apache Camel 属性占位符机制在什么位置找到其属性,您可以定义一个 propertyPlaceholder 元素并明确指定解析器位置。

例如,请考虑以下与前面示例不同的蓝图配置,它会创建一个显式 propertyPlaceholder 实例:

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"
           xsi:schemaLocation="
           http://www.osgi.org/xmlns/blueprint/v1.0.0 ">https://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">

    <!-- OSGI blueprint property placeholder -->
    <cm:property-placeholder id="myblueprint.placeholder" persistent-id="camel.blueprint">
        <!-- list some properties for this test -->
        <cm:default-properties>
            <cm:property name="result" value="mock:result"/>
        </cm:default-properties>
    </cm:property-placeholder>

    <camelContext xmlns="http://camel.apache.org/schema/blueprint">

        <!-- using Camel properties component and refer to the blueprint property placeholder by its id -->
        <propertyPlaceholder id="properties" location="blueprint:myblueprint.placeholder"/>

        <!-- in the route we can use {{ }} placeholders which will lookup in blueprint -->
        <route>
            <from uri="direct:start"/>
            <to uri="mock:foo"/>
            <to uri="{{result}}"/>
        </route>

    </camelContext>

</blueprint>

在前面的示例中,propertyPlaceholder 元素指定通过将位置设置为 blueprint:myblueprint.placeholder 来指定使用哪个 cm:property-placeholder。该 蓝图: 解析器明确引用 cm:property-placeholder 的 ID、myblueprint.placeholder

这种配置方式很有用,如果蓝图文件中定义了多个 cm:property-placeholder an,并且您需要指定要使用的选项。它还可通过指定以逗号分隔的位置列表,从多个位置的源属性。例如,如果要从 cm:property-placeholder bean 和 properties 文件( myproperties.properties )在 classpath 上查找属性,您可以按照如下所示定义 propertyPlaceholder 元素:

<propertyPlaceholder id="properties"
  location="blueprint:myblueprint.placeholder,classpath:myproperties.properties"/>

与 Spring 属性占位符集成

如果您在 Spring XML 文件中使用 XML DSL 定义 Apache Camel 应用程序,您可以通过声明类型为 Spring 片段机制来将 Apache Camel 属性占位符机制集成,org.apache.camel.spring.spi.BridgePropertyPlaceholderConfigurer

定义 BridgePropertyPlaceholderConfigurer,它替代了 Spring XML 文件中 Apache Camel 的 propertyPlaceholder 元素和 Spring 的 ctx:property-placeholder 元素。然后,您可以使用 Spring ${PropName} 语法或 Apache Camel {{ PropName}} 语法来引用配置的属性。

例如,定义从 cheese.properties 文件中读取其属性设置的桥接属性占位符:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ctx="http://www.springframework.org/schema/context"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

  <!-- Bridge Spring property placeholder with Camel -->
  <!-- Do not use <ctx:property-placeholder ... > at the same time -->
  <bean id="bridgePropertyPlaceholder"
        class="org.apache.camel.spring.spi.BridgePropertyPlaceholderConfigurer">
    <property name="location"
              value="classpath:org/apache/camel/component/properties/cheese.properties"/>
  </bean>

  <!-- A bean that uses Spring property placeholder -->
  <!-- The ${hi} is a spring property placeholder -->
  <bean id="hello" class="org.apache.camel.component.properties.HelloBean">
    <property name="greeting" value="${hi}"/>
  </bean>

  <camelContext xmlns="http://camel.apache.org/schema/spring">
    <!-- Use Camel's property placeholder {{ }} style -->
    <route>
      <from uri="direct:{{cool.bar}}"/>
      <bean ref="hello"/>
      <to uri="{{cool.end}}"/>
    </route>
  </camelContext>

</beans>
注意

另外,您可以设置 BridgePropertyPlaceholderConfigurerlocation 属性,使其指向 Spring 属性文件。完全支持 Spring 属性文件语法。

2.8. 线程模型

Java 线程池 API

Apache Camel 线程模型基于强大的 Java 并发 API Package java.util.concurrent,最初在 Sun 的 JDK 1.5 中提供。此 API 中的关键接口是 ExecutorService 接口,它代表线程池。使用并发 API,您可以创建许多不同的线程池,涵盖了广泛的场景。

Apache Camel 线程池 API

Apache Camel 线程池 API 将基于 Java 并发 API 构建,为 Apache Camel 应用程序中的所有线程池提供中心工厂( org.apache.camel.spi.ExecutorServiceManager 类型)。以这种方式进行线程池的创建提供了几个优点,包括:

  • 使用实用程序类简化线程池的创建。
  • 将线程池与安全关闭集成.
  • 线程会自动提供信息名称,这对记录和管理有益。

组件线程模型

一些 Apache Camel 组件为 SEDA、JMS 和 Jettytty- inherent inherent多线程。这些组件已使用 Apache Camel 线程模型和线程池 API 实施。

如果您计划实施自己的 Apache Camel 组件,建议您将线程代码与 Apache Camel 线程模型集成。例如,如果您的组件需要线程池,建议您使用 CamelContext 的 ExecutorServiceManager 对象创建它。

处理器线程模型

Apache Camel 中的一些标准处理器默认创建自己的线程池。这些线程感知型处理器也与 Apache Camel 线程模型集成,它们提供各种选项,供您自定义它们使用的线程池。

表 2.8 “处理器线程选项” 显示了在内置到 Apache Camel 的线程处理器上控制和设置线程池的各种选项。

表 2.8. 处理器线程选项

处理器Java DSLXML DSL

aggregate

parallelProcessing()
executorService()
executorServiceRef()
@parallelProcessing
@executorServiceRef

multicast

parallelProcessing()
executorService()
executorServiceRef()
@parallelProcessing
@executorServiceRef

recipientList

parallelProcessing()
executorService()
executorServiceRef()
@parallelProcessing
@executorServiceRef

split

parallelProcessing()
executorService()
executorServiceRef()
@parallelProcessing
@executorServiceRef

threads

executorService()
executorServiceRef()
poolSize()
maxPoolSize()
keepAliveTime()
timeUnit()
maxQueueSize()
rejectedPolicy()
@executorServiceRef
@poolSize
@maxPoolSize
@keepAliveTime
@timeUnit
@maxQueueSize
@rejectedPolicy

wireTap

wireTap(String uri, ExecutorService executorService)
wireTap(String uri, String executorServiceRef)
@executorServiceRef

线程 DSL 选项

线程 处理器是一种通用的 DSL 命令,可用于将线程池引入到路由中。它支持以下选项自定义线程池:

poolSize()
池中的最小线程数量(以及初始池大小)。
maxPoolSize()
池中的最大线程数量。
keepAliveTime()
如果任何线程闲置的时间超过这个时间段(以秒为单位指定),则这些线程将被终止。
timeUnit()
使用 java.util.concurrent.TimeUnit 类型指定的时间单位。
maxQueueSize()
此线程池可以在其传入任务队列中存储的最大待处理任务数量。
rejectedPolicy()
指定在传入的任务队列已满时要执行的操作。请查看 表 2.10 “线程池构建器选项”
注意

前面的线程池选项与 executorServiceRef 选项 不兼容 (例如,您不能使用这些选项覆盖 executorServiceRef 选项引用的线程池中的设置)。Apache Camel 验证 DSL 来执行此操作。

创建默认线程池

要为一个线程感知处理器创建默认线程池,启用 parallelProcessing 选项,使用 parallelProcessing() 子使用、Java DSL 或 parallelProcessing 属性(在 XML DSL 中)。

例如,在 Java DSL 中,您可以使用默认线程池(使用线程池同时处理多播目的地)调用多播处理器:

from("direct:start")
  .multicast().parallelProcessing()
    .to("mock:first")
    .to("mock:second")
    .to("mock:third");

您可以在 XML DSL 中定义与以下方式相同的路由

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="direct:start"/>
        <multicast parallelProcessing="true">
            <to uri="mock:first"/>
            <to uri="mock:second"/>
            <to uri="mock:third"/>
        </multicast>
    </route>
</camelContext>

默认线程池配置集设置

默认线程池由线程工厂自动创建,它从 默认的线程池配置集 获取其设置。默认线程池配置集在 表 2.9 “默认线程池配置集设置” 中显示的设置(假设这些设置还没有由应用程序代码修改)。

表 2.9. 默认线程池配置集设置

线程选项默认值

maxQueueSize

1000

poolSize

10

maxPoolSize

20

keepAliveTime

60 (秒)

rejectedPolicy

CallerRuns

更改默认线程池配置集

可以更改默认的线程池配置集设置,以便所有后续的默认线程池都使用自定义设置来创建。您可以在 Java 或 Spring XML 中更改配置集。

例如,在 Java DSL 中,您可以自定义 poolSize 选项和默认线程池配置集中的 maxQueueSize 选项,如下所示:

// Java
import org.apache.camel.spi.ExecutorServiceManager;
import org.apache.camel.spi.ThreadPoolProfile;
...
ExecutorServiceManager manager = context.getExecutorServiceManager();
ThreadPoolProfile defaultProfile = manager.getDefaultThreadPoolProfile();

// Now, customize the profile settings.
defaultProfile.setPoolSize(3);
defaultProfile.setMaxQueueSize(100);
...

在 XML DSL 中,您可以自定义默认的线程池配置集,如下所示:

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
    <threadPoolProfile
        id="changedProfile"
        defaultProfile="true"
        poolSize="3"
        maxQueueSize="100"/>
    ...
</camelContext>

请注意,在前面的 XML DSL 示例中将 defaultProfile 属性设置为 true 非常重要,否则线程池配置集将被视为自定义线程池配置集(请参阅 “创建自定义线程池配置集”一节),而不是替换默认的线程池配置集。

自定义处理器的线程池

还可以使用 executorServiceexecutorServiceRef 选项(其中使用这些选项而不是 parallelProcessing 选项)指定线程池。您可以使用两种方法来自定义处理器的线程池,如下所示:

  • 指定自定义线程池 是否已创建 ExecutorService (线程池)实例,并将它传递到 executorService 选项。
  • 指定自定义线程池配置集 InventoryService- responsiblecreate 并注册自定义线程池工厂。当您使用 executorServiceRef 选项引用这个 factory 时,处理器会自动使用 factory 创建自定义线程池实例。

当您将 bean ID 传递给 executorServiceRef 选项时,线程识别处理器首先会尝试查找带有该 ID 在 registry 中的 ID 的自定义线程池。如果没有使用该 ID 注册了线程池,则处理器会尝试在 registry 中查找自定义线程池配置集,并使用自定义线程池配置集来实例化自定义线程池。

创建自定义线程池

自定义线程池可以是 java.util.concurrent.ExecutorService 类型的任何线程池。在 Apache Camel 中,建议使用以下创建线程池实例的方法:

  • 使用 org.apache.camel.builder.ThreadPoolBuilder 实用程序构建线程池类。
  • 使用来自当前 CamelContextorg.apache.camel.spi.ExecutorServiceManager 实例来创建线程池类。

最后,这两种方法之间没有区别,因为 ThreadPoolBuilder 实际使用 ExecutorServiceManager 实例定义。通常,最好使用 ThreadPoolBuilder,因为它提供了一个更简单的方法。但是,至少有一种线程( ScheduledExecutorService)只能通过直接访问 ExecutorServiceManager 实例来创建。

表 2.10 “线程池构建器选项” 显示 ThreadPoolBuilder 类支持的选项,您可以在定义新的自定义线程池时设置这些选项。

表 2.10. 线程池构建器选项

构建器选项描述

maxQueueSize()

设置此线程池可以存储在其传入任务队列中的最大待处理任务数量。值 -1 指定未绑定的队列。默认值从默认的线程池配置集中提取。

poolSize()

设置池中最小线程数量(这也是初始池大小)。默认值从默认的线程池配置集中提取。

maxPoolSize()

设置池中可以的最大线程数量。默认值从默认的线程池配置集中提取。

keepAliveTime()

如果任何线程闲置的时间超过这个时间段(以秒为单位指定),则这些线程将被终止。这样,当负载较正常时,线程池可以缩小。默认值从默认的线程池配置集中提取。

rejectedPolicy()

指定在传入的任务队列已满时要执行的操作。您可以指定 4 个可能值:

CallerRuns
(默认值) 获取调用器线程以运行最新的传入任务。这个问题的一个副作用是,此选项可防止调用者线程接收更多任务,直到完成最新的传入任务。
Abort
通过抛出异常以中止最新的传入任务。
discard
以静默方式丢弃最新的传入任务。
DiscardOldest
丢弃最旧的未处理的任务,然后尝试在任务队列中放入最新的传入的任务。

build()

完成构建自定义线程池,并将新线程池注册到 build() 的 ID 下。

在 Java DSL 中,您可以使用 ThreadPoolBuilder 定义自定义线程池,如下所示:

// Java
import org.apache.camel.builder.ThreadPoolBuilder;
import java.util.concurrent.ExecutorService;
...
ThreadPoolBuilder poolBuilder = new ThreadPoolBuilder(context);
ExecutorService customPool = poolBuilder.poolSize(5).maxPoolSize(5).maxQueueSize(100).build("customPool");
...

from("direct:start")
  .multicast().executorService(customPool)
    .to("mock:first")
    .to("mock:second")
    .to("mock:third");

您可以通过将 bean ID 传递给 executorServiceRef() 选项,而不必将对象引用 customPool 直接传递给 executorService() 选项,如下所示:

// Java
from("direct:start")
  .multicast().executorServiceRef("customPool")
    .to("mock:first")
    .to("mock:second")
    .to("mock:third");

在 XML DSL 中,您可以使用 threadPool 元素访问 ThreadPoolBuilder。然后,您可以使用 executorServiceRef 属性来引用自定义线程池,以便在 Spring registry 中根据 ID 查找线程池,如下所示:

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
    <threadPool id="customPool"
                poolSize="5"
                maxPoolSize="5"
                maxQueueSize="100" />

    <route>
        <from uri="direct:start"/>
        <multicast executorServiceRef="customPool">
            <to uri="mock:first"/>
            <to uri="mock:second"/>
            <to uri="mock:third"/>
        </multicast>
    </route>
</camelContext>

创建自定义线程池配置集

如果您有多个要创建的自定义线程池实例,您可能会发现它更加方便地定义自定义线程池配置集,该配置集充当线程池的工厂。每当您引用线程感知处理器的线程池配置集时,处理器会自动使用配置集来创建新的线程池实例。您可以在 Java DSL 或 XML DSL 中定义自定义线程池配置集。

例如,在 Java DSL 中,您可以使用 bean ID customProfile 并从路由中引用它,如下所示:

// Java
import org.apache.camel.spi.ThreadPoolProfile;
import org.apache.camel.impl.ThreadPoolProfileSupport;
...
// Create the custom thread pool profile
ThreadPoolProfile customProfile = new ThreadPoolProfileSupport("customProfile");
customProfile.setPoolSize(5);
customProfile.setMaxPoolSize(5);
customProfile.setMaxQueueSize(100);
context.getExecutorServiceManager().registerThreadPoolProfile(customProfile);
...
// Reference the custom thread pool profile in a route
from("direct:start")
  .multicast().executorServiceRef("customProfile")
    .to("mock:first")
    .to("mock:second")
    .to("mock:third");

在 XML DSL 中,使用 threadPoolProfile 元素创建自定义池配置集(其中,默认Profile 选项默认为 false,因为这 不是默认 的线程池配置集)。您可以使用 bean ID customProfile 创建自定义线程池配置集,并从路由中引用它,如下所示:

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
    <threadPoolProfile
                id="customProfile"
                poolSize="5"
                maxPoolSize="5"
                maxQueueSize="100" />

    <route>
        <from uri="direct:start"/>
        <multicast executorServiceRef="customProfile">
            <to uri="mock:first"/>
            <to uri="mock:second"/>
            <to uri="mock:third"/>
        </multicast>
    </route>
</camelContext>

在组件间共享线程池

某些标准基于轮询的组件(如 File 和 FTP1028-jaxballow)要指定要使用的线程池。这使得不同组件可以共享同一线程池,从而减少了 JVM 中的总线程数量。

例如,Apache Camel 组件参考指南 中的 see File2Apache Camel 组件参考指南 中的 Ftp2 均公开 scheduledExecutorService 属性,您可以使用它来指定组件的 ExecutorService 对象。

自定义线程名称

要使应用程序日志更易阅读,通常最好自定义线程名称(用于识别日志中的线程)。要自定义线程名称,您可以通过在 ExecutorServiceStrategy 类或 ExecutorServiceManager 类上调用 setThreadNamePattern 方法来配置线程名称 模式。另外,设置线程名称模式的更简单方法是在 CamelContext 对象中设置 threadNamePattern 属性。

以下占位符可以在线程名称模式中使用:

#camelId#
当前 CamelContext 的名称。
#counter#
唯一的线程标识符,作为递增计数器实施。
#name#
常规 Camel 线程名称。
#longName#
长线程名称 3.10.0-->_< 可以包含端点参数,以此类推。

以下是线程名称模式的典型示例:

Camel (#camelId#) thread #counter# - #name#

以下示例演示了如何使用 XML DSL 在 Camel 上下文上设置 threadNamePattern 属性:

<camelContext xmlns="http://camel.apache.org/schema/spring"
              threadNamePattern="Riding the thread #counter#" >
  <route>
    <from uri="seda:start"/>
    <to uri="log:result"/>
    <to uri="mock:result"/>
  </route>
</camelContext>

2.9. 控制路由启动和关闭

概述

默认情况下,当 Apache Camel 应用程序(由 CamelContext 实例表示)启动时自动启动路由,并在您的 Apache Camel 应用程序关闭时自动关闭路由。对于非关键部署,关闭序列的详情通常并不重要。但在生产环境中,现有任务在关闭期间应该运行非常关键,以避免数据丢失。您通常还希望控制路由关闭的顺序,这样依赖项就不会被违反(这样会导致现有任务无法运行完成)。

因此,Apache Camel 提供了一组功能来支持 安全关闭 应用程序。安全关闭可让您完全控制停止和启动路由,允许您控制路由的关闭顺序,并使当前任务能够运行完成。

设置路由 ID

最好为每个路由分配一个路由 ID。除了提高日志记录消息和管理功能外,使用路由 ID 可让您对停止和启动路由应用更多的控制。

例如,在 Java DSL 中,您可以通过调用 routeId() 命令来将路由 ID myCustomerRouteId 分配到路由,如下所示:

from("SourceURI").routeId("myCustomRouteId").process(...).to(TargetURI);

在 XML DSL 中,设置 route 元素的 id 属性,如下所示:

<camelContext id="CamelContextID" xmlns="http://camel.apache.org/schema/spring">
  <route id="myCustomRouteId" >
    <from uri="SourceURI"/>
    <process ref="someProcessorId"/>
    <to uri="TargetURI"/>
  </route>
</camelContext>

禁用自动启动路由

默认情况下,CamelContext 知道在启动时的所有路由都将自动启动。如果您想手动控制特定路由的启动启动,您可能需要为该路由禁用自动启动。

要控制 Java DSL 路由是否自动启动,可调用 autoStartup 命令,使用 布尔值 参数(truefalse)或 String 参数(truefalse)。例如,您可以在 Java DSL 中禁用路由的自动启动,如下所示:

from("SourceURI")
  .routeId("nonAuto")
  .autoStartup(false)
  .to(TargetURI);

您可以通过在路由元素上将 autoStartup 属性设置为 false 来禁用在 XML DSL 中自动启动 路由的 自动启动,如下所示:

<camelContext id="CamelContextID" xmlns="http://camel.apache.org/schema/spring">
  <route id="nonAuto" autoStartup="false">
    <from uri="SourceURI"/>
    <to uri="TargetURI"/>
  </route>
</camelContext>

手动启动和停止路由

您可以通过调用 CamelContext 实例的 startRoute()stopRoute() 方法,随时在 Java 中手动启动或停止路由。例如,要启动具有路由 ID nonAuto 的路由,在 CamelContext 实例( 上下文 )上调用 startRoute() 方法,如下所示:

// Java
context.startRoute("nonAuto");

要停止具有路由 ID nonAuto 的路由,调用 CamelContext 实例上的 stopRoute() 方法,上下文,如下所示:

// Java
context.stopRoute("nonAuto");

路由启动顺序

默认情况下,Apache Camel 以非确定的顺序启动路由。但是,在某些应用程序中,控制启动顺序非常重要。要在 Java DSL 中控制启动顺序,请使用 startupOrder() 命令,该命令使用正整数值作为其参数。具有最低整数值的路由首先启动,后接具有后续启动顺序值的路由。

例如,以下示例中的前两个路由通过 seda:buffer 端点链接在一起。您可以通过分配启动顺序(2 和 1)来保证在第二个路由片段 启动第一个路由片段,如下所示:

例 2.5. Java DSL 中的启动顺序

from("jetty:http://fooserver:8080")
    .routeId("first")
    .startupOrder(2)
    .to("seda:buffer");

from("seda:buffer")
    .routeId("second")
    .startupOrder(1)
    .to("mock:result");

// This route's startup order is unspecified
from("jms:queue:foo").to("jms:queue:bar");

在 Spring XML 中,您可以通过设置 route 元素的 startupOrder 属性来实现相同的效果,如下所示:

例 2.6. XML DSL 中的启动顺序

<route id="first" startupOrder="2">
    <from uri="jetty:http://fooserver:8080"/>
    <to uri="seda:buffer"/>
</route>

<route id="second" startupOrder="1">
    <from uri="seda:buffer"/>
    <to uri="mock:result"/>
</route>

<!-- This route's startup order is unspecified -->
<route>
    <from uri="jms:queue:foo"/>
    <to uri="jms:queue:bar"/>
</route>

必须为每个路由 分配一个唯一的 启动顺序值。您可以选择小于 1000 的正整数值。为 Apache Camel 保留 1000 和 over 的值,这会自动将这些值分配给路由,而不显示显式启动值。例如,上例中最后一个路由会自动分配启动值 1000(因此在前两个路由后启动)。

关闭序列

CamelContext 实例时,Apache Camel 使用可插入关闭 策略控制关闭 序列。默认关闭策略实施以下关闭序列:

  1. 路由以 相反的 启动顺序关闭。
  2. 通常,关闭策略会等待当前活动的交换发生。但是,运行任务的处理是可配置的。
  3. 总体而言,关闭序列由超时(默认为 300 秒)绑定。如果关闭序列超过此超时,则关闭策略将强制关闭,即使有些任务仍在运行。

路由关闭顺序

路由以相反的启动顺序关闭。也就是说,当使用 boot-rder () 命令(在 Java DSL 中)或 startupOrder 属性(在 XML DSL 中)定义启动顺序时,第一个关闭路由是第一个关闭的路由,由启动顺序分配 最高 的整数值。最后一个要关闭的路由是按照启动顺序分配 的最低 整数值的路由。

例如,在 例 2.5 “Java DSL 中的启动顺序” 中,需要关闭的第一个路由段是 ID、第一个 的路由,而要关闭的第二个路由段则是 ID 为 second 的路由。本例演示了一个常规规则,您应该在关闭路由时观察这些规则: 公开外部可访问消费者端点的路由应首先关闭,因为这有助于通过路由图的剩余部分来节流消息流。

注意

Apache Camel 还提供选项 shutdownRoute(Defer),它可让您指定路由必须位于关闭的最后一个路由中(覆盖了启动顺序值)。但是您很少需要此选项。这个选项主要是作为早期版本的 Apache Camel(prior 到 2.3)的一个临时解决方案,哪个路由会按照 与启动顺序相同的 顺序关闭。

关闭路由中正在运行的任务

如果关闭启动时路由仍在处理消息,关闭策略通常会等待当前活跃交换完成处理后再关闭路由。可以使用 shutdownRunningTask 选项在每个路由上配置此行为,该选项可采用以下值之一:

ShutdownRunningTask.CompleteCurrentTaskOnly
(默认) 通常,路由一次只在一条信息上运行,因此您可以在当前任务完成后安全地关闭路由。
ShutdownRunningTask.CompleteAllTasks
指定这个选项,以安全地关闭 批处理消费者。有些消费者端点(如 File、FTP、邮件、iBATIS 和 JPA)一次在批量消息上运行。对于这些端点,更适合等待当前批处理中的所有消息都已完成。

例如,要正常关闭文件消费者端点,您应该指定 CompleteAllTasks 选项,如以下 Java DSL 片段所示:

// Java
public void configure() throws Exception {
    from("file:target/pending")
        .routeId("first").startupOrder(2)
        .shutdownRunningTask(ShutdownRunningTask.CompleteAllTasks)
        .delay(1000).to("seda:foo");

    from("seda:foo")
        .routeId("second").startupOrder(1)
        .to("mock:bar");
}

同一路由可以在 XML DSL 中定义,如下所示:

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
    <!-- let this route complete all its pending messages when asked to shut down -->
    <route id="first"
           startupOrder="2"
           shutdownRunningTask="CompleteAllTasks">
        <from uri="file:target/pending"/>
        <delay><constant>1000</constant></delay>
        <to uri="seda:foo"/>
    </route>

    <route id="second" startupOrder="1">
        <from uri="seda:foo"/>
        <to uri="mock:bar"/>
    </route>
</camelContext>

关闭超时

关闭超时的默认值为 300 秒。您可以通过在 shutdown 策略上调用 setTimeout() 方法来更改超时值。例如,您可以将超时值更改为 600 秒,如下所示:

// Java
// context = CamelContext instance
context.getShutdownStrategy().setTimeout(600);

与自定义组件集成

如果您正在实施自定义 Apache Camel 组件(也会从 org.apache.camel.Service 接口继承),您可以确保自定义代码通过实施 org.apache.camel.spi.ShutdownPre ed 接口来接收关闭通知。这为组件提供了在准备关闭过程中执行自定义代码的机会。

2.9.1. RouteIdFactory

根据消费者端点,您可以添加 RouteIdFactory,以使用逻辑名称分配路由 ID。

例如,当将路由用于 seda 或 direct 组件作为路由输入时,您可能希望使用其名称作为路由 id,如:

  • direct:foo- foo
  • seda:bar- bar
  • JMS:orders- order

您可以使用 NodeIdFactory 为路由分配逻辑名称,而不是使用自动分配的名称。另外,您可以将上下文路由 URL 用作名称。例如,执行以下命令以使用 RouteIDFactory

context.setNodeIdFactory(new RouteIdFactory());
注意

可以从其他端点获取自定义路由 id。

2.10. 调度的路由策略

2.10.1. Scheduled Route 策略概述

概述

调度的路由策略可用于触发在运行时影响路由的事件。特别是,目前可用的实现可让您在策略指定的任意时间(或时间)启动、停止、挂起或恢复路由。

调度任务

调度的路由策略能够触发以下事件:

  • 在指定时间(或时间)时启动路由。如果路由当前处于已停止状态,则会等待激活,此事件才会生效。
  • 在指定的时间 (或时间)停止路由 InventoryService-操作会停止路由。只有路由当前处于活跃状态时,此事件才起作用。
  • 在路由开始时(如 from()中指定的) 挂起一个路由 时间(如 from))。其余的路由仍然活跃,但客户端将无法将新消息发送到路由。
  • 在路由开始时 恢复一个路由 gradle-gradlere-activate 消费者端点,将路由返回到完全活跃状态。

Quartz 组件

Quartz 组件是基于 Terracotta 的 Quartz 的计时器组件,它是作业调度程序的开源实施。Quartz 组件为简单调度的路由策略和 cron 计划路由策略提供了底层实施。

2.10.2. 简单调度的路由策略

概述

简单的调度路由策略是一个路由策略,可让您启动、停止、挂起和恢复路由,其中通过指定一定数量的后续 repititions 定义这些事件的时间和日期(可选)。要定义简单的调度路由策略,请创建以下类实例:

org.apache.camel.routepolicy.quartz.SimpleScheduledRoutePolicy

依赖项

简单调度的路由策略取决于 Quartz 组件 camel-quartz。例如,如果您使用 Maven 作为构建系统,则需要添加对 camel-quartz 工件的依赖项。

Java DSL 示例

例 2.7 “简单调度路由的 Java DSL 示例” 演示了如何调度路由以使用 Java DSL 启动。初始的开始时间 startTime 定义为当前时间之后的 3 秒。该策略也被配置为在初始开始时间后启动路由,3 秒(通过将 routeStartRepeatCount 设置为 1)并将 routeStartRepeatInterval 设置为 3000 毫秒。

在 Java DSL 中,您可以通过在路由中调用 routePolicy() DSL 命令将路由策略附加到路由。

例 2.7. 简单调度路由的 Java DSL 示例

// Java
SimpleScheduledRoutePolicy policy = new SimpleScheduledRoutePolicy();
long startTime = System.currentTimeMillis() + 3000L;
policy.setRouteStartDate(new Date(startTime));
policy.setRouteStartRepeatCount(1);
policy.setRouteStartRepeatInterval(3000);

from("direct:start")
   .routeId("test")
   .routePolicy(policy)
   .to("mock:success");
注意

您可以使用多个参数调用 routePolicy() 在路由上指定多个策略。

XML DSL 示例

例 2.8 “简单调度路由的 XML DSL 示例” 演示了如何调度路由以使用 XML DSL 启动。

在 XML DSL 中,您可以通过设置路由元素上的 routePolicyRef 属性将路由策略附加到 路由

例 2.8. 简单调度路由的 XML DSL 示例

<bean id="date" class="java.util.Data"/>

<bean id="startPolicy" class="org.apache.camel.routepolicy.quartz.SimpleScheduledRoutePolicy">
    <property name="routeStartDate" ref="date"/>
    <property name="routeStartRepeatCount" value="1"/>
    <property name="routeStartRepeatInterval" value="3000"/>
</bean>

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route id="myroute" routePolicyRef="startPolicy">
        <from uri="direct:start"/>
        <to uri="mock:success"/>
    </route>
</camelContext>
注意

您可以通过将 routePolicyRef 的值设置为以逗号分隔的 bean ID 列表,在路由上指定多个策略。

定义日期和时间

使用简单调度路由策略中使用的触发器的初始时间是使用 java.util.Date 类型指定的。定义 Date 实例的最灵活方法是通过 java.util.GregorianCalendar 类。使用 GregorianCalendar 类的方便构建者和方法来定义日期,然后通过调用 GregorianCalendar.getTime() 获取 日期

例如,要在 2011 年 1 月 1 日之前定义时间和日期,请致电 GregorianCalendar constructor,如下所示:

// Java
import java.util.GregorianCalendar;
import java.util.Calendar;
...
GregorianCalendar gc = new GregorianCalendar(
    2011,
    Calendar.JANUARY,
    1,
    12,  // hourOfDay
    0,   // minutes
    0    // seconds
);

java.util.Date triggerDate = gc.getTime();

GregorianCalendar 类还支持在不同时区中的时间定义。默认情况下,它使用您计算机上的本地时区。

正常关闭

当您将简单调度路由策略配置为停止路由时,路由停止算法会自动与安全关闭过程集成(请参阅 第 2.9 节 “控制路由启动和关闭”)。这意味着该任务会等待当前交换完成处理,然后再关闭路由。但是,您可以设置超时,它会强制路由在指定时间后停止,无论路由是否完成交换过程。

超时记录动态交换

如果安全关闭无法在给定的超时时间内完全关闭,那么 Apache Camel 将执行更积极的关机。它强制关闭路由、线程池等。

在超时后,Apache Camel 会记录有关当前动态交换的信息。它记录交换的源和当前交换路由。

例如,以下日志显示有一个动态的交换,来自 route1 的起源,目前在 delay1 节点上的同一 route1 上。

在安全关闭过程中,如果您在 org.apache.camel.impl.DefaultShutdownStrategy 上启用 DEBUG 日志记录级别,则会记录相同的动态交换信息。

2015-01-12 13:23:23,656 [- ShutdownTask] INFO DefaultShutdownStrategy - There are 1 inflight exchanges:
InflightExchange: [exchangeId=ID-davsclaus-air-62213-1421065401253-0-3, fromRouteId=route1, routeId=route1, nodeId=delay1, elapsed=2007, duration=2017]

如果您不想查看这些日志,可以通过将选项 logInflightExchangesOnTimeout 设置为 false 来关闭。

  context.getShutdownStrategegy().setLogInflightExchangesOnTimeout(false);

调度任务

您可以使用简单的调度路由策略来定义一个或多个以下调度任务:

启动路由

下表列出了调度一个或多个路由启动的参数。

参数类型默认值描述

routeStartDate

java.util.Date

指定首次启动路由时的日期和时间。

routeStartRepeatCount

int

0

当设置为非零值时,可指定路由应启动的次数。

routeStartRepeatInterval

long

0

指定启动之间的间隔,以毫秒为单位。

停止路由

下表列出了调度一个或多个路由的参数停止。

参数类型默认值描述

routeStopDate

java.util.Date

指定首次停止路由时的日期和时间。

routeStopRepeatCount

int

0

当设置为非零值时,可指定路由应该停止的次数。

routeStopRepeatInterval

long

0

指定停止之间的时间间隔,单位为毫秒。

routeStopGracePeriod

int

10000

指定在强制停止路由前等待当前交换完成(宽限期)的时长。在无限宽限期内设置为 0。

routeStopTimeUnit

long

TimeUnit.MILLISECONDS

指定宽限期的时间范围。

挂起路由

下表列出了用于调度路由启动或多次处理的参数。

参数类型默认值描述

routeSuspendDate

java.util.Date

指定首次暂停路由的时间和时间。

routeSuspendRepeatCount

int

0

当设置为非零值时,可指定路由应该暂停的次数。

routeSuspendRepeatInterval

long

0

指定挂起之间的时间间隔,单位为毫秒。

恢复路由

下表列出了用于调度一个或多个路由恢复的参数。

参数类型默认值描述

routeResumeDate

java.util.Date

指定首次恢复路由的时间和时间。

routeResumeRepeatCount

int

0

当设置为非零值时,指定应恢复路由的次数。

routeResumeRepeatInterval

long

0

指定恢复间隔,以毫秒为单位。

2.10.3. Cron Scheduled Route 策略

概述

cron 调度路由策略是一个路由策略,可让您启动、停止、挂起和恢复路由,其中使用 cron 表达式指定这些事件的时间。要定义 cron 计划路由策略,请创建以下类实例:

org.apache.camel.routepolicy.quartz.CronScheduledRoutePolicy

依赖项

简单调度的路由策略取决于 Quartz 组件 camel-quartz。例如,如果您使用 Maven 作为构建系统,则需要添加对 camel-quartz 工件的依赖项。

Java DSL 示例

例 2.9 “Cron Scheduled Route 的 Java DSL 示例” 演示了如何调度路由以使用 Java DSL 启动。策略使用 cron 表达式 \*/3 * * * ? ? 进行配置,这会每 3 秒触发一次启动事件。

在 Java DSL 中,您可以通过在路由中调用 routePolicy() DSL 命令将路由策略附加到路由。

例 2.9. Cron Scheduled Route 的 Java DSL 示例

// Java
CronScheduledRoutePolicy policy = new CronScheduledRoutePolicy();
policy.setRouteStartTime("*/3 * * * * ?");

from("direct:start")
    .routeId("test")
    .routePolicy(policy)
    .to("mock:success");;
注意

您可以使用多个参数调用 routePolicy() 在路由上指定多个策略。

XML DSL 示例

例 2.10 “Cron Scheduled 路由的 XML DSL 示例”演示了如何调度路由以使用 XML DSL 启动。

在 XML DSL 中,您可以通过设置路由元素上的 routePolicyRef 属性将路由策略附加到 路由

例 2.10. Cron Scheduled 路由的 XML DSL 示例

<bean id="date" class="org.apache.camel.routepolicy.quartz.SimpleDate"/>

<bean id="startPolicy" class="org.apache.camel.routepolicy.quartz.CronScheduledRoutePolicy">
    <property name="routeStartTime" value="*/3 * * * * ?"/>
</bean>

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route id="testRoute" routePolicyRef="startPolicy">
        <from uri="direct:start"/>
        <to uri="mock:success"/>
    </route>
</camelContext>
注意

您可以通过将 routePolicyRef 的值设置为以逗号分隔的 bean ID 列表,在路由上指定多个策略。

定义 cron 表达式

cron 表达式语法 在 UNIX cron 实用程序中包含其原始内容,可调度在 UNIX 系统上的后台运行的作业。cron 表达式有效了用于通配符日期和时间的语法,允许您指定单个事件或定期重复发生的多个事件。

cron 表达式按以下顺序由 6 个或 7 个字段组成:

Seconds Minutes Hours DayOfMonth Month DayOfWeek [Year]

Year 字段是可选的,通常省略,除非您要定义一次发生一次的事件。每个字段由字面和特殊字符的组合组成。例如,以下 cron 表达式指定每天每天触发一次事件:

0 0 24 * * ?

* 字符是一个通配符,与字段的每个值匹配。因此,前面的表达式与每月的每天匹配。? 字符是一个 dummy 占位符,这意味着 *ignore this field*。它始终出现在 DayOfMonth 字段中,或者在 DayOfWeek 字段中出现,因为它并不完全一致地指定这两个字段。例如,如果要调度一个每天触发一次的事件,但仅在周一到周五,请使用以下 cron 表达式:

0 0 24 ? * MON-FRI

其中连字符指定范围 MON-FRI。您还可以使用正斜杠字符 / 来指定增量。例如,要指定事件每 5 分钟触发一次,请使用以下 cron 表达式:

0 0/5 * * * ?

有关 cron 表达式语法的完整解释,请参阅 CRON 表达式 中的 Wikipedia。

调度任务

您可以使用 cron 计划路由策略定义以下一个或多个调度任务:

启动路由

下表列出了调度一个或多个路由启动的参数。

参数类型默认值描述

routeStartString

字符串

指定触发一个或多个路由启动事件的 cron 表达式。

停止路由

下表列出了调度一个或多个路由的参数停止。

参数类型默认值描述

routeStopTime

字符串

指定触发一个或多个路由停止事件的 cron 表达式。

routeStopGracePeriod

int

10000

指定在强制停止路由前等待当前交换完成(宽限期)的时长。在无限宽限期内设置为 0。

routeStopTimeUnit

long

TimeUnit.MILLISECONDS

指定宽限期的时间范围。

挂起路由

下表列出了用于调度路由启动或多次处理的参数。

参数类型默认值描述

routeSuspendTime

字符串

指定触发一个或多个路由暂停事件的 cron 表达式。

恢复路由

下表列出了用于调度一个或多个路由恢复的参数。

参数类型默认值描述

routeResumeTime

字符串

指定触发一个或多个路由恢复事件的 cron 表达式。

2.10.4. 路由策略因素

使用路由策略 onnectionFactoryy

Camel 2.14 已提供

如果要为每个路由使用路由策略,您可以使用 org.apache.camel.spi.RoutePolicy factory 作为每个路由创建 RoutePolicy 实例的工厂。当您想为每个路由使用相同路由策略时,可以使用它。然后,您只需要配置一次工厂,并且每个创建的路由都会分配策略。

CamelContext 上的 API 来添加工厂,如下所示:

context.addRoutePolicyFactory(new MyRoutePolicyFactory());

从 XML DSL 中,您只能使用 factory 定义 <bean >

<bean id="myRoutePolicyFactory" class="com.foo.MyRoutePolicyFactory"/>

factory 包含用于创建路由策略的 createRoutePolicy 方法。

/**
 * Creates a new {@link org.apache.camel.spi.RoutePolicy} which will be assigned to the given route.
 *
 * @param camelContext the camel context
 * @param routeId      the route id
 * @param route        the route definition
 * @return the created {@link org.apache.camel.spi.RoutePolicy}, or <tt>null</tt> to not use a policy for this route
 */
RoutePolicy createRoutePolicy(CamelContext camelContext, String routeId, RouteDefinition route);

请注意,您可以尽可能多地发生路由策略因素。只需要再次调用 addRoutePolicyFactory,或者把其他因素声明为 XML 中的 &lt ;bean& gt;。

2.11. 重新加载 Camel 路由

在 Apache Camel 2.19 发行版本中,您可以启用对 camel XML 路由的实时重新加载,该路由会在从编辑器保存 XML 文件时触发重新加载。在以下情况下使用此功能:

  • 带有 Camel 主类的 Camel 独立(Camel 主类)
  • Camel Spring Boot
  • 来自 camel:run maven 插件

但是,您还可以通过在 CamelContext 中设置 ReloadStrategy 并通过提供您自己的自定义策略来手动启用此功能。

2.12. Camel Maven 插件

Camel Maven 插件支持以下目标:

  • Camel:run - 来运行 Camel 应用程序
  • Camel:validate - 验证无效的 Camel 端点 URI 的源代码
  • Camel:route-coverage - 在单元测试后报告您的 Camel 路由覆盖情况

2.12.1. Camel:run

Camel Maven 插件的 camel:run 目标用于在从 Maven 派生的 JVM 中运行您的 Camel Spring 配置。您启动的好示例应用程序是 Spring 示例。

cd examples/camel-example-spring
mvn camel:run

这样,可以在无需编写 main(…​)方法的情况下轻松启动和测试您的路由规则;它还可让您创建多个 jar 来托管不同的路由规则,并轻松地独立测试它们。Camel Maven 插件编译了 maven 项目中的源代码,然后使用 META-INF/spring/*.xml 类路径上的 XML 配置文件引导 Spring ApplicationContext。如果要更快地引导 Camel 路由,您可以尝试 camel:embeeded

2.12.1.1. 选项

Camel Maven 插件 运行 目标支持以下选项,它们可从命令行配置(使用 -D 语法),或在 < configuration > 标签中的 pom.xml 文件中定义。

参数

默认值

描述

duration

-1

设置应用程序在终止前所运行的时间持续时间(秒)。系统会永久运行值 InventoryService 0。

durationIdle

-1

设置应用程序在终止前可以闲置的空闲时间(秒)持续时间。系统会永久运行值 InventoryService 0。

durationMaxMessages

-1

设置应用程序进程在终止前的最大消息的持续时间。

logClasspath

false

是否在启动时记录类路径

2.12.1.2. 运行 OSGi 蓝图

camel:run 插件还支持运行 Blueprint 应用程序,默认情况下,它会在 OSGI-INF/blueprint/*.xml 中扫描 OSGi 蓝图文件。您需要将 camel:run 插件配置为使用蓝图,方法是将 useBlueprint 设置为 true,如下所示:

<plugin>
  <groupId>org.jboss.redhat-fuse</groupId>
  <artifactId>camel-maven-plugin</artifactId>
  <configuration>
    <useBlueprint>true</useBlueprint>
  </configuration>
</plugin>

这可让您引导所有您想要的蓝图服务,无论它们是否与 Camel 相关,还是其它蓝图。camel:run 目标可自动检测 camel-blueprint 位于类路径中,或者项目中是否存在蓝图 XML 文件,因此您不必配置 useBlueprint 选项。

2.12.1.3. 使用有限的蓝图容器

我们使用 Felix Connector 项目作为蓝图容器。此项目不是完整的蓝图容器。为此,您可以使用 Apache Karaf 或 Apache ServiceMix。您可以使用 应用程序ContextUri 配置指定显式蓝图 XML 文件,例如:

<plugin>
  <groupId>org.jboss.redhat-fuse</groupId>
  <artifactId>camel-maven-plugin</artifactId>
  <configuration>
    <useBlueprint>true</useBlueprint>
    <applicationContextUri>myBlueprint.xml</applicationContextUri>
    <!-- ConfigAdmin options which have been added since Camel 2.12.0 -->
    <configAdminPid>test</configAdminPid>
    <configAdminFileName>/user/test/etc/test.cfg</configAdminFileName>
  </configuration>
</plugin>

应用程序ContextUri 从 classpath 加载文件,因此在 myBlueprint.xml 文件上方的示例中必须位于 classpath 的根目录中。configAdminPid 是 pid 名称,在加载持久性属性文件时将用作配置 admin 服务的 pid 名称。configAdminFileName 是用于加载配置 admin 服务属性文件的文件名。

2.12.1.4. 运行 CDI

camel:run 插件还支持运行 CDI 应用。这可让您引导所有您想要的 CDI 服务,无论它们是与 Camel 相关的,还是任何其他 CDI 启用的服务。您应该将您选择的 CDI 容器(如 Weld 或 OpenWebBeans)添加到 camel-maven-plugin 的依赖关系,如本例中所示。在 Camel 的源中,您可以运行 CDI 示例,如下所示:

cd examples/camel-example-cdi
mvn compile camel:run

2.12.1.5. 记录 classpath

您可以配置当 camel:run 执行时,是否应该记录 classpath。您可以使用以下方法在配置中启用此功能:

<plugin>
  <groupId>org.jboss.redhat-fuse</groupId>
  <artifactId>camel-maven-plugin</artifactId>
  <configuration>
    <logClasspath>true</logClasspath>
  </configuration>
</plugin>

2.12.1.6. 使用 XML 文件实时重新载入

您可以配置插件来扫描 XML 文件更改,并触发在这些 XML 文件中包含的 Camel 路由重新载入。

<plugin>
  <groupId>org.jboss.redhat-fuse</groupId>
  <artifactId>camel-maven-plugin</artifactId>
  <configuration>
    <fileWatcherDirectory>src/main/resources/META-INF/spring</fileWatcherDirectory>
  </configuration>
</plugin>

然后,插件会监视此目录。这可让您从编辑器编辑源代码并保存文件,并使正在运行的 Camel 应用程序使用这些更改。请注意,只有 Camel 路由的更改,如 < routes&gt; 或支持 & lt;route >。您无法更改 Spring 或 OSGi Blueprint < bean> 元素。

2.12.2. camel:validate

对于以下 Camel 功能的源代码验证:

  • 端点 URI
  • 简单表达式或 predicates
  • 重复的路由 ID

然后,您可以从命令行运行 camel:validate 目标,或者从 IDEA 或 Eclipse 等 Java 编辑器中运行。

mvn camel:validate

您还可以启用插件作为构建的一部分自动运行,以捕获这些错误。

<plugin>
  <groupId>org.jboss.redhat-fuse</groupId>
  <artifactId>camel-maven-plugin</artifactId>
  <executions>
    <execution>
      <phase>process-classes</phase>
      <goals>
        <goal>validate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

该阶段决定了插件何时运行。在上面的示例中,阶段是 进程类,它在主源代码的编译后运行。也可将 maven 插件配置为验证测试源代码,这意味着应相应地将阶段更改为 process-test-classes,如下所示:

<plugin>
  <groupId>org.jboss.redhat-fuse</groupId>
  <artifactId>camel-maven-plugin</artifactId>
  <executions>
    <execution>
      <configuration>
        <includeTest>true</includeTest>
      </configuration>
      <phase>process-test-classes</phase>
      <goals>
        <goal>validate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

2.12.2.1. 在任何 Maven 项目上运行目标

您还可以在任何 Maven 项目中运行验证目标,而无需将插件添加到 pom.xml 文件中。这样做需要使用其完全限定名称指定插件。例如,要在来自 Apache Camel 的 camel-example-cdi 上运行目标,您可以运行

$cd camel-example-cdi
$mvn org.apache.camel:camel-maven-plugin:2.20.0:validate

然后,运行和输出以下内容:

[INFO] ------------------------------------------------------------------------
[INFO] Building Camel :: Example :: CDI 2.20.0
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- camel-maven-plugin:2.20.0:validate (default-cli) @ camel-example-cdi ---
[INFO] Endpoint validation success: (4 = passed, 0 = invalid, 0 = incapable, 0 = unknown components)
[INFO] Simple validation success: (0 = passed, 0 = invalid)
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

通过验证验证,4 个端点已被验证。现在,假设我们在源代码中的一个 Camel 端点 URI 中有拼写错误,例如:

@Uri("timer:foo?period=5000")

被修改为在 period 选项中包含拼写错误

@Uri("timer:foo?perid=5000")

在运行验证目标时,会再次报告以下内容:

[INFO] ------------------------------------------------------------------------
[INFO] Building Camel :: Example :: CDI 2.20.0
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- camel-maven-plugin:2.20.0:validate (default-cli) @ camel-example-cdi ---
[WARNING] Endpoint validation error at: org.apache.camel.example.cdi.MyRoutes(MyRoutes.java:32)

	timer:foo?perid=5000

	                   perid    Unknown option. Did you mean: [period]


[WARNING] Endpoint validation error: (3 = passed, 1 = invalid, 0 = incapable, 0 = unknown components)
[INFO] Simple validation success: (0 = passed, 0 = invalid)
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

2.12.2.2. 选项

Camel Maven 插件 验证 目标支持以下选项,它们可从命令行配置(使用 -D 语法),或在 < configuration > 标签中的 pom.xml 文件中定义。

参数

默认值

描述

downloadVersion

true

是否允许从互联网下载 Camel 目录版本。项目默认使用不同于此插件的 Camel 版本,则需要此项。

failOnError

false

如果找到无效的 Camel 端点,是否失败。默认情况下,插件会在 WARN 级别上记录错误。

logUnparseable

false

是否记录不可解析的端点 URI,因此无法验证。

includeJava

true

是否包含用于无效的 Camel 端点验证的 Java 文件。

includeXml

true

是否要包含要针对无效 Camel 端点验证的 XML 文件。

includeTest

false

是否包括测试源代码。

includes

 

要过滤 java 和 xml 文件的名称,使其仅包含与任何给定模式列表匹配的文件(通配符和正则表达式)。可以使用逗号分隔多个值。

excludes

 

要过滤 java 和 xml 文件的名称,以排除与任何给定模式列表匹配的文件(通配符和正则表达式)。可以使用逗号分隔多个值。

ignoreUnknownComponent

true

是否忽略未知组件。

ignoreIncapable

true

是否忽略是否能够解析端点 URI 还是简单表达式。

ignoreLenientProperties

true

是否忽略使用 lenient 属性的组件。当此参数为 true 时,如果 URI 验证比较严格,但在 URI 中因为使用 lenient 属性而在 URI 中会失败。例如,使用 HTTP 组件在端点 URI 中提供查询参数。

ignoreDeprecated

true

Camel 2.23 是否忽略端点 URI 中使用的已弃用的选项。

duplicateRouteId

true

Camel 2.20 是否验证重复的路由 ID。路由 ID 应该是唯一的,如果有重复,Camel 将无法启动。

directOrSedaPairCheck

true

Camel 2.23 是否验证发送到非现有消费者的直接/横线端点。

showAll

false

是否显示所有端点和简单表达式(无效和有效)。

例如,要禁用在命令行中弃用的选项的使用,您可以运行:

$mvn camel:validate -Dcamel.ignoreDeprecated=false

请注意,您必须将 -D 命令参数前缀为 camel。,eg camel. ignore Deprecated 作为选项名称。

2.12.2.3. 使用验证端点包括测试

如果您有 Maven 项目,您可以运行插件来验证单元测试源代码中的端点。您可以使用 -D 风格传递选项,如下所示:

$cd myproject
$mvn org.apache.camel:camel-maven-plugin:2.20.0:validate -DincludeTest=true

2.12.3. camel:route-coverage

从单元测试开始生成 Camel 路由覆盖报告。您可以使用它来了解使用 Camel 路由哪些部分。

2.12.3.1. 启用路由覆盖范围

您可以通过以下方式在运行单元测试时启用路由覆盖范围:

  • 为所有测试类设置全局 JVM 系统属性
  • 如果使用 camel-test-spring 模块,在每个测试类使用 @EnableRouteCoverage 注解
  • 如果使用 camel-test 模块,覆盖为每个测试类的 DumpRouteCoverage 方法

2.12.3.2. 使用 JVM 系统属性启用路由覆盖范围

您可以开启 JVM 系统属性 CamelTestRouteCoverage,以启用所有测试案例的路由覆盖范围。这可以在 maven-surefire-plugin 配置中完成:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <configuration>
    <systemPropertyVariables>
      <CamelTestRouteCoverage>true</CamelTestRouteCoverage>
    </systemPropertyVariables>
  </configuration>
</plugin>

或者在运行测试时从命令行:

mvn clean test -DCamelTestRouteCoverage=true

2.12.3.3. 通过 @EnableRouteCoverage 注解启用

如果您使用 camel-test-spring 进行测试,您可以在测试类中添加 @EnableRouteCoverage 注解到测试类来启用路由覆盖:

@RunWith(CamelSpringBootRunner.class)
@SpringBootTest(classes = SampleCamelApplication.class)
@EnableRouteCoverage
public class FooApplicationTest {

2.12.3.4. 通过DumpRouteCoverage 方法启用

但是,如果您使用 camel-test,并且您的单元测试正在扩展 CamelTestSupport,那么您可以启用路由覆盖范围,如下所示:

@Override
public boolean isDumpRouteCoverage() {
    return true;
}

可在 RouteCoverage 方法中覆盖的路由必须具有一个唯一的 id,否则您不能使用匿名路由。您可以在 Java DSL 中使用 routeId 来完成此操作:

from("jms:queue:cheese").routeId("cheesy")
  .to("log:foo")
  ...

在 XML DSL 中,您刚刚通过 id 属性分配路由 id

<route id="cheesy">
  <from uri="jms:queue:cheese"/>
  <to uri="log:foo"/>
  ...
</route>

2.12.3.5. 生成路由覆盖报告

要生成路由覆盖范围报告,使用以下命令运行单元测试:

mvn test

然后,您可以运行该目标来报告路由覆盖范围,如下所示:

mvn camel:route-coverage

报告哪个路由缺少路由覆盖率,并提供精确的源代码行报告:

[INFO] --- camel-maven-plugin:2.21.0:route-coverage (default-cli) @ camel-example-spring-boot-xml ---
[INFO] Discovered 1 routes
[INFO] Route coverage summary:

File:	src/main/resources/my-camel.xml
RouteId:	hello

  Line #      Count   Route
  ------      -----   -----
      28          1   from
      29          1     transform
      32          1     filter
      34          0       to
      36          1     to

Coverage: 4 out of 5 (80.0%)

在这里,我们可以看到,使用 的第二代行在 count 栏中具有 0, 因此没有涵盖。我们还可以在源代码文件中看到,这是一行 34,它位于 my-camel.xml XML 文件中。

2.12.3.6. 选项

Camel Maven 插件 覆盖 目标支持以下选项,它们可从命令行配置(使用 -D 语法),或在 < configuration > 标签中的 pom.xml 文件中定义。

参数

默认值

描述

failOnError

false

如果任何路由没有 100% 覆盖,则是否失败。

includeTest

false

是否包括测试源代码。

includes

 

要过滤 java 和 xml 文件的名称,使其仅包含与任何给定模式列表匹配的文件(通配符和正则表达式)。可以使用逗号分隔多个值。

excludes

 

要过滤 java 和 xml 文件的名称,以排除与任何给定模式列表匹配的文件(通配符和正则表达式)。可以使用逗号分隔多个值。

anonymousRoutes

false

是否允许匿名路由(没有分配任何路由 id 的路由)。通过使用路由 ID,其安全器与路由源代码中的数据匹配。匿名路由不安全地使用路由覆盖范围,因为它更难以知道哪个路由被测试与源代码中哪个路由对应。

2.13. 运行 Apache Camel Standalone

当您作为独立应用程序运行 camel 时,它提供运行应用程序的主类,并保持其运行,直到 JVM 终止为止。您可以在 org.apache.camel.main Java 包中找到 MainListener 类。

以下是 Main 类的组件:

  • org.apache. camel.Main 类中的 Camel-core JAR
  • org.apache. camel.spring.Main 类中的 Camel- spring JAR

以下示例演示了如何从 Camel 中创建和使用 Main 类:

public class MainExample {

    private Main main;

    public static void main(String[] args) throws Exception {
        MainExample example = new MainExample();
        example.boot();
    }

    public void boot() throws Exception {
        // create a Main instance
        main = new Main();
        // bind MyBean into the registry
        main.bind("foo", new MyBean());
        // add routes
        main.addRouteBuilder(new MyRouteBuilder());
        // add event listener
        main.addMainListener(new Events());
        // set the properties from a file
        main.setPropertyPlaceholderLocations("example.properties");
        // run until you terminate the JVM
        System.out.println("Starting Camel. Use ctrl + c to terminate the JVM.\n");
        main.run();
    }

    private static class MyRouteBuilder extends RouteBuilder {
        @Override
        public void configure() throws Exception {
            from("timer:foo?delay={{millisecs}}")
                .process(new Processor() {
                    public void process(Exchange exchange) throws Exception {
                        System.out.println("Invoked timer at " + new Date());
                    }
                })
                .bean("foo");
        }
    }

    public static class MyBean {
        public void callMe() {
            System.out.println("MyBean.callMe method has been called");
        }
    }

    public static class Events extends MainListenerSupport {

        @Override
        public void afterStart(MainSupport main) {
            System.out.println("MainExample with Camel is now started!");
        }

        @Override
        public void beforeStop(MainSupport main) {
            System.out.println("MainExample with Camel is now being stopped!");
        }
    }
}

2.14. OnCompletion

概述

OnCompletion DSL 名称用于定义在完成 工作单元时要执行的操作工作单元是包含 整个交换的 Camel 概念。请参阅 第 34.1 节 “交换”onCompletion 命令有以下功能:

  • OnCompletion 命令的范围可以是全局或每个路由。路由范围会覆盖全局范围。
  • OnCompletion 可以配置为在成功时触发失败。
  • onWhen predicate 只能在某些情况下触发该 onCompletion
  • 您可以定义是否要使用线程池,但默认值为线程池。

在编译时只有路由范围

当在交换中指定Completion DSL 时,Camel 启动一个新的线程。这允许原始线程在不 与Completion 任务进行干预的情况下继续。路由只支持一个 在Completion 中。在以下示例中,无论交换成功完成是成功还是失败,会触发 Completion。这是默认的操作。

from("direct:start")
     .onCompletion()
         // This route is invoked when the original route is complete.
         // This is similar to a completion callback.
         .to("log:sync")
         .to("mock:sync")
     // Must use end to denote the end of the onCompletion route.
     .end()
     // here the original route contiues
     .process(new MyProcessor())
     .to("mock:result");

对于 XML,格式如下:

<route>
    <from uri="direct:start"/>
    <!-- This onCompletion block is executed when the exchange is done being routed. -->
    <!-- This callback is always triggered even if the exchange fails. -->
    <onCompletion>
        <!-- This is similar to an after completion callback. -->
        <to uri="log:sync"/>
        <to uri="mock:sync"/>
    </onCompletion>
    <process ref="myProcessor"/>
    <to uri="mock:result"/>
</route>

要在失败时触发 Completion,可以使用 onFailureOnly 参数。同样,若要成功触发 Completion,请使用 onCompleteOnly 参数。

from("direct:start")
     // Here onCompletion is qualified to invoke only when the exchange fails (exception or FAULT body).
     .onCompletion().onFailureOnly()
         .to("log:sync")
         .to("mock:sync")
     // Must use end to denote the end of the onCompletion route.
     .end()
     // here the original route continues
     .process(new MyProcessor())
     .to("mock:result");

对于 XML,在 Completion tag 中将 onFailureOnlyonCompleteOnly 来表示:

<route>
    <from uri="direct:start"/>
    <!-- this onCompletion block will only be executed when the exchange is done being routed -->
    <!-- this callback is only triggered when the exchange failed, as we have onFailure=true -->
    <onCompletion onFailureOnly="true">
        <to uri="log:sync"/>
        <to uri="mock:sync"/>
    </onCompletion>
    <process ref="myProcessor"/>
    <to uri="mock:result"/>
</route>

Completion 全局范围

为多个路由定义 Completion

// define a global on completion that is invoked when the exchange is complete
 onCompletion().to("log:global").to("mock:sync");

 from("direct:start")
     .process(new MyProcessor())
     .to("mock:result");

使用 OnWhen

要在某些情况下触发 Completion,请使用 onWhen predicate。当消息正文包含单词 Hello 时,以下示例会触发 onCompletion

/from("direct:start")
     .onCompletion().onWhen(body().contains("Hello"))
         // this route is only invoked when the original route is complete as a kind
         // of completion callback. And also only if the onWhen predicate is true
         .to("log:sync")
         .to("mock:sync")
     // must use end to denote the end of the onCompletion route
     .end()
     // here the original route contiues
     .to("log:original")
     .to("mock:result");

使用带有或没有线程池的处理

自 Camel 2.14 起,Completion 默认不使用线程池。要强制使用线程池,请将 executorService 设置为 true,或者将 parallelProcessing 设为 true。例如,在 Java DSL 中,使用以下格式:

onCompletion().parallelProcessing()
     .to("mock:before")
     .delay(1000)
     .setBody(simple("OnComplete:${body}"));

对于 XML,格式为:

<onCompletion parallelProcessing="true">
   <to uri="before"/>
   <delay><constant>1000</constant></delay>
   <setBody><simple>OnComplete:${body}<simple></setBody>
 </onCompletion>

使用 executorServiceRef 选项引用特定的线程池:

<onCompletion executorServiceRef="myThreadPool"
   <to uri="before"/>
   <delay><constant>1000</constant></delay>
   <setBody><simple>OnComplete:${body}</simple></setBody>
 </onCompletion>>

在 Consumer Sends Response 之前在Completion 上运行

在Completion 中有两种模式运行:

  • AfterConsumer - 在消费者完成后运行的默认模式
  • BeforeConsumer - 在消费者写出请求之前运行 给调用者。这可以在 编译时 修改 Exchange,如添加特殊标头,或将 Exchange 记录为响应日志记录器。

例如,要将标头 创建的 添加到响应中,请使用 modeBeforeConsumer(),如下所示:

.onCompletion().modeBeforeConsumer()
     .setHeader("createdBy", constant("Someone"))
 .end()

对于 XML,将 mode 属性设置为 BeforeConsumer

<onCompletion mode="BeforeConsumer">
   <setHeader headerName="createdBy">
     <constant>Someone</constant>
   </setHeader>
 </onCompletion>

2.15. 指标

概述

Camel 2.14 已提供

虽然 Camel 提供了很多现有指标集成,但为 Camel 路由添加了 Codahale 指标。这使得最终用户能够使用 Codahale 指标将 Camel 路由信息与所收集的现有数据连接在一起。

要使用 Codahale 指标,您需要:

  1. 添加 camel-metrics 组件
  2. 在 XML 或 Java 代码中启用路由指标

请注意,性能指标只在显示它们时可用 ; 任何类型的监控工具都可以与 JMX 集成,因为指标可以通过 JMX 获得。此外,实际数据是 100% Codehale JSON。

指标路由策略

可以根据各个路由定义 MetricsRoutePolicy,获取单个路由的 Codahale 指标。

从 Java 创建 MetricsRoutePolicy 实例,作为路由的策略分配。这如下所示:

from("file:src/data?noop=true").routePolicy(new MetricsRoutePolicy()).to("jms:incomingOrders");

从 XML DSL,您将定义一个 < bean&gt; 指定一个 <bean>,它指定为路由的策略;例如:

<bean id="policy" class="org.apache.camel.component.metrics.routepolicy.MetricsRoutePolicy"/>

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route routePolicyRef="policy">
    <from uri="file:src/data?noop=true"/>
[...]

指标路由策略 onnectionFactoryy

此工厂允许每个路由添加一个 RoutePolicy,该路由利用 Codahale 指标公开路由利用率统计信息。该工厂可以在 Java 和 XML 中使用,如下例所示。

从 Java 中,您刚刚将工厂添加到 CamelContext 中,如下所示:

context.addRoutePolicyFactory(new MetricsRoutePolicyFactory());

从 XML DSL 中,您可以按照如下所示定义 & lt;bean& gt;:

<!-- use camel-metrics route policy to gather metrics for all routes -->
<bean id="metricsRoutePolicyFactory" class="org.apache.camel.component.metrics.routepolicy.MetricsRoutePolicyFactory"/>

从 Java 代码中,您可以从 org.apache .camel.component.metrics.MetricsRegistry 获取 com.codahale.metrics.metrics.routepolicy.MetricsRegistryService,如下所示:

MetricRegistryService registryService = context.hasService(MetricsRegistryService.class);
if (registryService != null) {
  MetricsRegistry registry = registryService.getMetricsRegistry();
  ...
}

选项

MetricsRoutePolicyFactoryMetricsRoutePolicy 支持以下选项:

名称

default

描述

durationUnit

TimeUnit.MILLISECONDS

在指标报告器或转储统计 json 中用于持续时间的单元。

jmxDomain

org.apache.camel.metrics

JXM 域名。

metricsRegistry

 

allow 使用共享的 com.codahale.metrics.MetricRegistry。如果没有提供,则 Camel 将创建此 CamelContext 使用的共享实例。

prettyPrint

false

以 json 格式输出统计时是否使用完整的打印。

rateUnit

TimeUnit.SECONDS

指标报告器或转储统计为 json 的比率的单元。

useJmx

false

是否使用 com.codahale.metrics.JmxReporter 将精细统计报告为 JMX。

请注意,如果在 CamelContext 上启用了 JMX,那么在 JMX 树中的服务类型下列出了 MetricsRegistryService mbean。该 mbean 有单一操作,可使用 json 输出统计信息。只有在您希望每个统计类型进行精细 mbeans 时,才需要使用Jmx 设置为 true。

2.16. JMX 命名

概述

通过为它定义管理名称,Apache Camel 允许您自定义 CamelContext 的名称 (其出现在 JMX 中)。例如,您可以自定义 XML CamelContext 实例的名称模式,如下所示:

<camelContext id="myCamel" managementNamePattern="#name#">
    ...
</camelContext>

如果您没有明确为 CamelContext an 设置名称模式,Apache Camel 将恢复为默认的命名策略。

默认命名策略

默认情况下,在 OSGi 捆绑包中部署的 CamelContext 名称等于该捆绑包的 OSGi 符号链接名称。例如,如果 OSGi 符号链接名称为 MyCamelBundle,则 JMX 名称是 MyCamelBundle。如果捆绑包中有多个 CamelContext,则将计数器值添加为后缀,则 JMX 名称不会被混淆。例如,如果 MyCamelBundle 捆绑包中有多个 Camel 上下文,则对应的 JMX MBeans 命名如下:

MyCamelBundle-1
MyCamelBundle-2
MyCamelBundle-3
...

自定义 JMX 命名策略

默认命名策略的一个缺陷是,您不能保证给定 CamelContext an 在运行之间具有相同的 JMX 名称。如果您想在不同运行之间具有更高的一致性,您可以通过为 CamelContext 实例定义 JMX name 模式,以更精确地控制 JMX 名称。

在 Java 中指定名称模式

要在 Java 中为 CamelContext 指定名称模式,请调用 setNamePattern 方法,如下所示:

// Java
context.getManagementNameStrategy().setNamePattern("#name#");

在 XML 中指定名称模式

要在 XML 中为 CamelContext 指定名称模式,请在 camelContext 元素上设置 managementNamePattern 属性,如下所示:

<camelContext id="myCamel" managementNamePattern="#name#">

名称模式令牌

您可以通过将字面文本和以下令牌的任意令牌组合来构建 JMX 名称模式:

表 2.11. JMX Name Pattern Tokens

令牌描述

#camelId#

CamelContext Bean 的 id 属性的值。

#name#

#camelId#.

#counter#

递增计数器(从 1开始)。

#bundleId#

OSGi 部署捆绑包的 ID (仅限 OSGi)

#symbolicName#

OSGi 符号链接名称 (仅限 OSGi)

#version#

OSGi 捆绑版本 (仅限 OSGi)

例子

以下是您可以使用支持的令牌定义的 JMX 名称模式的一些示例:

<camelContext id="fooContext" managementNamePattern="FooApplication-#name#">
    ...
</camelContext>
<camelContext id="myCamel" managementNamePattern="#bundleID#-#symbolicName#-#name#">
    ...
</camelContext>

模糊名称

由于自定义命名模式会覆盖默认的命名策略,因此可以使用此方法定义模糊的 JMX MBean 名称。例如:

<camelContext id="foo" managementNamePattern="SameOldSameOld"> ... </camelContext>
...
<camelContext id="bar" managementNamePattern="SameOldSameOld"> ... </camelContext>

在这种情况下,Apache Camel 将在启动时失败,并报告 MBean 已经存在 异常。因此,您应该要格外小心,确保您没有定义模糊的名称模式。

2.17. 性能和优化

消息复制

allowUseOriginalMessage 选项默认设置为 false,以便在不需要时到达原始消息的副本。要启用 allowUseOriginalMessage 选项,请使用以下命令:

  • 对任何错误处理程序或 onException 元素设置 useOriginalMessage=true
  • 在 Java 应用代码中,设置 AllowUseOriginalMessage=true,然后使用 getOriginalMessage 方法。
注意

在 2.18 之前的 Camel 版本中,allowUseOriginalMessage 的默认设置为 true。

第 3 章 企业级集成模式简介

摘要

Apache Camel 的 企业集成模式通过 Gregor Hohpe 和 Bobby Woolf 编写的书写。这些作者描述的模式为开发企业集成项目提供了一个卓越的 toolbox。除了提供讨论集成架构的通用语言外,许多模式可直接使用 Apache Camel 的编程界面和 XML 配置来实施。

3.1. Patterns 概述

企业级集成模式书

Apache Camel 支持书本中的大多数模式,即 Gregor Hohpe 和 Bobby Woolf 的 Enterprise Integration Patterns

消息传递系统

表 3.1 “消息传递系统” 中显示的消息传递系统模式介绍了组成消息传递系统的基本概念和组件。

表 3.1. 消息传递系统

图标名称使用案例

Message icon

图 5.1 “消息模式”

邮件通道连接的两个应用程序如何交换信息?

Message channel icon

图 5.2 “Message Channel Pattern”

一个应用程序如何使用消息传递与另一个应用程序通信?

Message endpoint icon

图 5.3 “Message Endpoint Pattern”

应用程序如何连接到消息传递频道以发送和接收消息?

Pipes and filters icon

图 5.4 “pipes 和 Filters Pattern”

我们可以如何对消息执行复杂的处理,同时仍然保持独立性和灵活性?

Message router icons

图 5.7 “Message Router Pattern”

您可以如何分离单独的处理步骤,以便可以根据一组定义的条件将消息传递给不同的过滤器?

Message translator icon

图 5.8 “Message Translator Pattern”

如何使用不同数据格式的系统使用消息传递相互通信?

消息传递频道

消息传递频道是连接消息传递系统中的参与者的基本组件。表 3.2 “消息传递频道” 中的模式描述了可用的不同类型的消息频道。

表 3.2. 消息传递频道

图标名称使用案例

Point to point icon

图 6.1 “指向点频道模式”

调用者如何确保精确的一个接收器接收文档或执行调用?

Publish subscribe icon

图 6.2 “发布 Subscribe Channel Pattern”

发件人如何将事件广播到所有感兴趣的接收器?

Dead letter icon

图 6.3 “死的频道模式”

消息传递系统与无法发送的消息有什么作用?

Guaranteed delivery icon

图 6.4 “保证交付模式”

发件人如何确保要发送消息,即使消息传递系统失败也是如此?

Message bus icon

图 6.5 “消息总线模式”

哪个架构使分离应用程序可以协同工作,以便在不影响其他应用程序的情况下添加或删除一个或多个应用程序?

消息构建

消息构建模式(如 表 3.3 “消息构建” 所示)描述了通过系统传递的信息的各种形式和功能。

表 3.3. 消息构建

图标名称使用案例

Correlation identifier icon

“概述”一节

请求者如何识别生成接收回复的请求?

Return address icon

第 7.3 节 “返回地址”

replier 如何知道回复在哪里?

消息路由

消息路由模式(在 表 3.4 “消息路由” 所示)描述了将消息通道连接各种方法,包括可应用于消息流的各种算法(无需修改消息正文)。

表 3.4. 消息路由

图标名称使用案例

Content based router icon

第 8.1 节 “基于内容的路由器”

我们如何处理单一逻辑功能的实施(例如清单检查)到多个物理系统时?

Message filter icon

第 8.2 节 “Message Filter”

组件如何避免接收不必要的消息?

Recipient List icon

第 8.3 节 “接收者列表”

如何将消息路由到动态指定收件人列表?

Splitter icon

第 8.4 节 “Splitter”

如果消息包含多个元素,则我们可以处理一条消息,其中每个元素可能需要以不同的方式进行处理?

Aggregator icon

第 8.5 节 “聚合器”

我们如何组合单个结果,但相关消息以便可以作为一个整体进行处理?

Resequencer icon

第 8.6 节 “Resequencer”

我们可以如何把相关的消息流返回至正确的顺序?

distribution aggregate icon

第 8.14 节 “由消息处理器”

在处理由多个元素组成的消息时,您可以维护整个消息流,每个项可能需要不同的处理?

 

第 8.15 节 “scatter-Gather”

当您需要向多个接收者发送消息时,如何维护整个消息流,每个都可能会发送回复?

Routing slip icon

第 8.7 节 “路由 Slip”

在设计时不知道步骤时,我们如何连续通过一系列处理步骤来连续路由消息,每种消息可能会有所不同?

 

第 8.8 节 “Throttler”

如何节流消息以确保特定端点不会超载,或者我们没有超出一些外部服务的 SLA?

 

第 8.9 节 “Delayer”

如何延迟消息发送?

 

第 8.10 节 “Load Balancer”

如何在多个端点之间平衡负载?

 

第 8.11 节 “Hystrix”

在调用外部服务时,如何使用 Hystrix 断路器?Camel 2.18 中的新功能.

 

第 8.12 节 “service Call”

如何在 registry 中查找该服务在分布式系统中调用远程服务?Camel 2.18 中的新功能.

 

第 8.13 节 “多播”

如何同时将消息路由到多个端点?

 

第 8.16 节 “loop”

如何在循环中重复处理消息?

 

第 8.17 节 “sampling”

我该如何把给定时间段内的许多消息进行抽样,以避免超载下游路由?

消息转换

消息转换模式(如 表 3.5 “消息转换” 所示)描述了如何根据不同的目的修改信息内容。

表 3.5. 消息转换

图标名称使用案例

Content enricher icon

第 10.1 节 “内容增强器”

如果消息源器没有所有必需的数据项,我如何与另一个系统通信?

Content filter icon

第 10.2 节 “内容过滤器”

当您只对一些数据项目感兴趣时,您如何简化处理大量消息?

store in library icon

第 10.4 节 “声明检查 EIP”

如何在不牺牲信息内容的情况下减少系统发送的消息量?

Normalizer icon

第 10.3 节 “规范化程序”

您如何以其他格式格式处理语义等同的信息?

 

第 10.5 节 “排序”

如何对邮件的正文进行排序?

消息传递端点

消息传递端点表示消息传递频道和应用程序之间的联系点。消息端点模式(如 表 3.6 “消息传递端点” 所示)介绍了可以在端点上配置的各种功能和服务质量。

表 3.6. 消息传递端点

图标名称使用案例
 

第 11.1 节 “消息传递映射程序”

您如何在域对象和消息传递基础架构之间移动数据,同时保持相互独立的这两个数据?

Event driven icon

第 11.2 节 “event Driven Consumer”

应用程序如何在消息可用时自动消耗消息?

Polling consumer icon

第 11.3 节 “polling Consumer”

应用程序如何在应用程序就绪时消耗消息?

Competing consumers icon

第 11.4 节 “竞争消费者”

消息传递客户端如何同时处理多个消息?

Message dispatcher icon

第 11.5 节 “Message Dispatcher”

单个频道中的多个消费者如何协调其消息处理?

Selective consumer icon

第 11.6 节 “选择ive Consumer”

消息消费者如何选择希望接收的消息?

Durable subscriber icon

第 11.7 节 “durable Subscriber”

在订阅者没有侦听它们时,如何避免缺少消息?

 

第 11.8 节 “幂等的消费者”

邮件接收器如何处理重复的消息?

Transactional client icon

第 11.9 节 “事务客户端”

客户端如何通过消息传递系统控制其事务?

Messaging gateway icon

第 11.10 节 “消息传递网关”

您如何从应用的其余部分封装对消息传递系统的访问?

Service activator icon

第 11.11 节 “Service Activator”

应用程序如何设计要被各种消息传递技术以及非消息传递技术调用的服务?

系统管理

系统管理模式(如 表 3.7 “系统管理” 所示)介绍了如何监控、测试和管理消息传递系统。

表 3.7. 系统管理

图标名称使用案例

Wire tap icon

第 12 章 系统管理

如何检查出差点到点频道的消息?

第 4 章 定义 REST 服务

摘要

Apache Camel 支持多种方法来定义 REST 服务。特别是,Apache Camel 提供 REST DSL(Domain Specific Language),它是一种简单但强大的流畅 API,可以在任何 REST 组件上分层并提供与 OpenAPI 集成。

4.1. Camel 中的 REST 概述

概述

Apache Camel 提供了很多不同的方法和组件,用于在 Camel 应用程序中定义 REST 服务。本节概述了这些不同方法和组件,以便您可以决定哪些实施和 API 最适合您的要求。

什么是 REST?

Representational State Transfer (REST)是一个分布式应用程序的架构,它仅利用 HTTP 传输数据的中心,仅使用四个基本的 HTTP 动词: GETPOSTPUTDELETE

与 SOAP 等协议不同,它把 HTTP 视为 SOAP 消息的传输协议,REST 架构直接利用 HTTP。关键洞察是,HTTP 协议 本身 由几个简单惯例增强,它非常适合充当分布式应用程序的框架。

REST 调用示例

因为 REST 架构围绕标准 HTTP 动词构建,因此在很多情况下,您可以使用常规浏览器作为 REST 客户端。例如,若要调用在主机和端口 localhost:9091 上运行的简单 Hello World REST 服务,您可以在浏览器中导航到类似于以下 URL 的 URL:

http://localhost:9091/say/hello/Garp

Hello World REST 服务可能会返回响应字符串,例如:

Hello Garp

其显示在浏览器窗口中。您可以使用标准浏览器(或 curl 命令行实用程序)调用 REST 服务的简易性,是 REST 协议快速获得流行的原因之一。

REST 打包程序层

以下 REST 打包程序层提供了定义 REST 服务的简化语法,并可在不同 REST 实现之上分层:

REST DSL

REST DSL(在 camelcore中)是一个 facade 或 wrapper 层,它为定义 REST 服务提供了一个简化的构建器 API。REST DSL 本身不 提供 REST 实现:它必须与底层 REST 实现合并。例如,以下 Java 代码演示了如何使用 REST DSL 定义一个简单的 Hello World 服务:

rest("/say")
    .get("/hello/{name}").route().transform().simple("Hello ${header.name}");

如需了解更多详细信息,请参阅 第 4.2 节 “使用 REST DSL 定义服务”

REST 组件

Rest 组件(在 camel-core中)是一个打包程序层,可让您使用 URI 语法定义 REST 服务。与 REST DSL 一样,Rest( Rest)组件本身 不提供 REST 实现。它必须与底层 REST 实现相结合。

如果您没有显式配置 HTTP 传输组件,则 REST DSL 会自动发现通过检查类路径上的可用组件来使用的 HTTP 组件。REST DSL 查找任何 HTTP 组件的默认名称,并使用它找到的第一个名称。如果类路径中没有 HTTP 组件,并且您没有显式配置 HTTP 传输,则默认 HTTP 组件为 camel-http

注意

自动发现要使用哪些 HTTP 组件的功能是 Camel 2.18 中的新功能。Camel 2.17 中不提供它。

以下 Java 代码演示了如何使用 camel-rest 组件定义一个简单的 Hello World 服务:

from("rest:get:say:/hello/{name}").transform().simple("Hello ${header.name}");

REST 实现

Apache Camel 通过以下组件提供多个不同的 REST 实现:

spark-Rest 组件

Spark-Rest 组件(在 camel-spark-rest)是一个 REST 实现,可让您使用 URI 语法定义 REST 服务。Spark 框架本身是一个 Java API,它基于 Sinatra 框架(一个 Python API)。例如,以下 Java 代码演示了如何使用 Spark-Rest 组件定义一个简单的 Hello World 服务:

from("spark-rest:get:/say/hello/:name").transform().simple("Hello ${header.name}");

请注意,与 Rest 组件不同,URI 中的变量语法为 :name,而不是 {name}

注意

Spark-Rest 组件需要 Java 8。

Restlet 组件

Restlet 组件(在 camel-restlet)是一个 REST 实现,在原则上可以进行分层,但此组件仅针对 HTTP 协议进行测试。此组件还提供与 Restlet Framework 集成,它是 Java 中开发 REST 服务的一种商业框架。例如,以下 Java 代码演示了如何使用 Restlet 组件定义一个简单的 Hello World 服务:

from("restlet:http://0.0.0.0:9091/say/hello/{name}?restletMethod=get")
    .transform().simple("Hello ${header.name}");

如需了解更多详细信息,请参阅 Apache Camel 组件参考指南 中的 Restlet

servlet 组件

Servlet 组件(在 camel-servlet中)是一个组件,它将 Java servlet 绑定到 Camel 路由。换而言之,Servlet 组件可让您打包和部署 Camel 路由,就像它是标准的 Java servlet。因此,当您需要在 servlet 容器中部署 Camel 路由(例如,到 Apache Tomcat HTTP 服务器或 JBoss Enterprise Application Platform 容器中)中,Servlet 组件特别有用。

但是,它本身的 Servlet 组件不提供任何便捷的 REST API 来定义 REST 服务。因此,最简单的使用 Servlet 组件是将其与 REST DSL 合并,以便您可以用用户友好的 API 定义 REST 服务。

如需了解更多详细信息,请参阅 Apache Camel 组件参考指南 中的 Servlet

JAX-RS REST 实施

JAX-RS (RESTful Web 服务的 Java API)是一个将 REST 请求绑定到 Java 对象的框架,其中 Java 类必须使用 JAX-RS 注释进行解码,以定义绑定。JAX-RS 框架相对成熟,为开发 REST 服务提供了复杂的框架,但它在编程上也比较复杂。

JAX-RS 与 Apache Camel 集成由 CXFRS 组件实施,该组件通过 Apache CXF 进行分层。简而言之,CIBian-RS 使用以下注释将 REST 请求绑定到 Java 类(其中,这仅是许多可用注释的不完整示例):

@Path
标注可以映射至 Java 类的上下文路径,或者将子路径映射到特定的 Java 方法。
@GET, @POST, @PUT, @DELETE
将 HTTP 方法映射到 Java 方法的标注。
@PathParam
将 URI 参数映射到 Java 方法参数的注解,或者将 URI 参数注入到字段中。
@QueryParam
注释,可将查询参数映射到 Java 方法参数,或者将查询参数注入字段。

REST 请求或 REST 响应的正文通常应采用 JAXB(XML)数据格式。但 Apache CXF 还支持 JSON 格式转换为 JAXB 格式,以便也可以解析 JSON 消息。

如需了解更多详细信息,请参阅 Apache Camel 组件参考指南 和 Apache CXF 开发指南中的 CXFRS

注意

CXFRS 组件 没有与 REST DSL 集成。

4.2. 使用 REST DSL 定义服务

REST DSL 是一个常见问题解答

REST DSL 实际上是一个 facade,它提供了在 Java DSL 或 XML DSL(域特定语言)中定义 REST 服务的简化语法。REST DSL 并不实际提供 REST 实现,它只是一个围绕 现有 REST 实施(Apache Camel 中有几个)的打包程序。

REST DSL 的优点

REST DSL 打包程序层提供以下优点:

  • 现代易用的语法来定义 REST 服务。
  • 与多个不同的 Apache Camel 组件兼容。
  • OpenAPI 集成(通过 camel-openapi-java 组件)。

与 REST DSL 集成的组件

由于 REST DSL 不是实际的 REST 实现,所以您需要做的第一项一项是选择 Camel 组件以提供底层实施。以下 Camel 组件目前与 REST DSL 集成:

注意

Rest 组件( camelcore的一部分)并不是 REST 的实施。与 REST DSL 一样,Reest 组件是一个 facade,它提供了一个简化的语法来定义使用 URI 语法的 REST 服务。Rest 组件还需要底层 REST 的实施。

配置 REST DSL 以使用 REST 实现

要指定 REST 的实现,您可以使用 restConfiguration() 构建器(在 Java DSL 中)或 restConfiguration 元素(在 XML DSL 中)。例如,要将 REST DSL 配置为使用 Spark-Rest 组件,您可以在 Java DSL 中使用类似以下内容的构建器表达式:

restConfiguration().component("spark-rest").port(9091);

您会在 XML DSL 中使用类似如下的元素(作为 camelContext的子项):

<restConfiguration component="spark-rest" port="9091"/>

语法

定义 REST 服务的 Java DSL 语法如下:

rest("BasePath").Option().
    .Verb("Path").Option().[to() | route().CamelRoute.endRest()]
    .Verb("Path").Option().[to() | route().CamelRoute.endRest()]
    ...
    .Verb("Path").Option().[to() | route().CamelRoute];

其中 CamelRoute 是一个可选的嵌入式 Camel 路由(使用路由的标准 Java DSL 语法定义)。

REST 服务定义以 rest() 关键字开头,后跟处理特定 URL 路径片段的一个或多个 动词子。HTTP 动词可以是 get()、head() put()、 post()、 delete()、patch() verb() 之一。每个 verb 子句都可以使用以下语法之一:

  • 口头以 to() 关键字结尾的动词子。例如:

    get("...").Option()+.to("...")
  • 动词 子句以 route() 关键字结尾(用于嵌入 Camel 路由)。例如:

    get("...").Option()+.route("...").CamelRoute.endRest()

带有 Java 的 REST DSL

在 Java 中,若要使用 REST DSL 定义服务,请将 REST 定义放在 RouteBuilder.configure() 方法的正文中,就像常规的 Apache Camel 路由一样。例如,要使用带有 Spark-Rest 组件的 REST DSL 定义一个简单的 Hello World 服务,请定义以下 Java 代码:

restConfiguration().component("spark-rest").port(9091);

rest("/say")
    .get("/hello").to("direct:hello")
    .get("/bye").to("direct:bye");

from("direct:hello")
    .transform().constant("Hello World");
from("direct:bye")
    .transform().constant("Bye World");

前面的示例具有三种不同类型的构建器:

restConfiguration()
配置 REST DSL 以使用特定的 REST 实现(Spark-Rest)。
rest()
使用 REST DSL 定义服务。各个动词条款均通过 to() 关键字终止,该关键字可将传入的消息转发到 直接 端点( 直接 组件转换器,在同一应用程序内路由)。
from()
定义常规 Camel 路由。

使用 XML 的 REST DSL

在 XML 中,若要使用 XML DSL 定义服务,请将 rest 元素定义为 camelContext 元素的子级。例如,若要使用带有 Spark-Rest 组件的 REST DSL 定义一个简单的 Hello World 服务,请定义以下 XML 代码(在 Blueprint 中):

<camelContext xmlns="http://camel.apache.org/schema/blueprint">
  <restConfiguration component="spark-rest" port="9091"/>

  <rest path="/say">
    <get uri="/hello">
      <to uri="direct:hello"/>
    </get>
    <get uri="/bye">
      <to uri="direct:bye"/>
    </get>
  </rest>

  <route>
    <from uri="direct:hello"/>
    <transform>
      <constant>Hello World</constant>
    </transform>
  </route>
  <route>
    <from uri="direct:bye"/>
    <transform>
      <constant>Bye World</constant>
    </transform>
  </route>
</camelContext>

指定基本路径

rest() 关键字(Java DSL)或 rest 元素的 path 属性(XML DSL)允许您定义一个基本路径,然后是作为前缀放在所有 动词条款中的路径上。例如,给定以下 Java DSL 片段:

rest("/say")
    .get("/hello").to("direct:hello")
    .get("/bye").to("direct:bye");

或者给定以下 XML DSL 片段:

<rest path="/say">
  <get uri="/hello">
    <to uri="direct:hello"/>
  </get>
  <get uri="/bye" consumes="application/json">
    <to uri="direct:bye"/>
  </get>
</rest>

REST DSL 构建器为您提供了以下 URL 映射:

/say/hello
/say/bye

基本路径是可选的。如果您愿意,您可以在每个 动词条款中指定完整路径:

rest()
    .get("/say/hello").to("direct:hello")
    .get("/say/bye").to("direct:bye");

使用动态进行

REST DSL 支持使用 toD 动态参数。使用此参数指定 URI。

例如,在 JMS 中,可以通过以下方式定义动态端点 URI:

public void configure() throws Exception {
   rest("/say")
     .get("/hello/{language}").toD("jms:queue:hello-${header.language}");
}

在 XML DSL 中,同样的详情如下:

<rest uri="/say">
  <get uri="/hello//{language}">
    <toD uri="jms:queue:hello-${header.language}"/>
  </get>
<rest>

有关 toD 动态参数的更多信息,请参阅 “动态到”一节

URI 模板

在动词参数中,您可以指定一个 URI 模板,您可以在命名的属性中捕获特定路径片段(然后映射到 Camel 消息标头)。例如,如果您想要对 Hello World 应用进行个性化,以便它根据名称设置调用者,您可以定义一个 REST 服务,如下所示:

rest("/say")
    .get("/hello/{name}").to("direct:hello")
    .get("/bye/{name}").to("direct:bye");

from("direct:hello")
    .transform().simple("Hello ${header.name}");
from("direct:bye")
    .transform().simple("Bye ${header.name}");

URI 模板捕获 {name} 路径片段的文本,并将这个捕获的文本复制到 名称 消息标头中。如果您通过发送 URL 以 /say/hello/Joe 结尾的 GET HTTP 请求调用服务,则 HTTP 响应为 Hello Joe

嵌入式路由语法

您可以使用 to() 关键字(Java DSL)或 to 元素(XML DSL)来终止 verb 子句,而是可以选择直接使用 Apache Camel 路由到 REST DSL 中,使用 route() 关键字(Java DSL)或 路由 元素(XML DSL)。route() 关键字允许您将路由嵌入到 verb 子句中,语法如下:

RESTVerbClause.route("...").CamelRoute.endRest()

其中 endRest() 关键字(仅限 Java DSL)是一个必要的标点符号,可让您分隔操作动词子句(当 rest() 构建器中有多个动词子句时)。

例如,您可以重构 Hello World 示例以使用嵌入的 Camel 路由,如下为 Java DSL:

rest("/say")
    .get("/hello").route().transform().constant("Hello World").endRest()
    .get("/bye").route().transform().constant("Bye World");

如下在 XML DSL 中:

<camelContext xmlns="http://camel.apache.org/schema/blueprint">
  ...
  <rest path="/say">
    <get uri="/hello">
      <route>
        <transform>
          <constant>Hello World</constant>
        </transform>
      </route>
    </get>
    <get uri="/bye">
      <route>
        <transform>
          <constant>Bye World</constant>
        </transform>
      </route>
    </get>
  </rest>
</camelContext>
注意

如果您在当前 CamelContext 中定义任何异常子句(使用 Exception ())或拦截器(使用拦截器()),这些异常子句和拦截器在嵌入式路由中也处于活动状态。

REST DSL 和 HTTP 传输组件

如果您没有显式配置 HTTP 传输组件,则 REST DSL 会自动发现通过检查类路径上的可用组件来使用的 HTTP 组件。REST DSL 查找任何 HTTP 组件的默认名称,并使用它找到的第一个名称。如果类路径中没有 HTTP 组件,并且您没有显式配置 HTTP 传输,则默认 HTTP 组件为 camel-http

指定请求和响应的内容类型

您可以使用 consume () 过滤 HTTP 请求和响应 的内容类型,并在 Java 中生成s() 选项,或者在 XML 中生成属性。 例如,一些常见内容类型(官方称为 互联网介质类型)如下:

  • text/plain
  • text/html
  • text/xml
  • application/json
  • application/xml

内容类型在 REST DSL 中以 verb 子句的形式提供。例如,若要将 verb 子句限制为仅接受 text/plain HTTP 请求,并且仅发送 文本/html HTTP 响应,您需要使用类似如下的 Java 代码:

rest("/email")
    .post("/to/{recipient}").consumes("text/plain").produces("text/html").to("direct:foo");

在 XML 中,您可以设置 使用 并生成 属性,如下所示:

<camelContext xmlns="http://camel.apache.org/schema/blueprint">
  ...
  <rest path="/email">
    <post uri="/to/{recipient}" consumes="text/plain" produces="text/html">
      <to "direct:foo"/>
    </get>
  </rest>
</camelContext>

您还可以指定使用 ()的参数,或以逗号分隔列表的形式 生成。例如,使用 ("text/plain, application/json")

其他 HTTP 方法

一些 HTTP 服务器实施支持额外的 HTTP 方法,它们不是由 REST DSL 中标准动词集合提供的,即 get(), head() , put (), post (), delete (), patch().要访问其他 HTTP 方法,您可以在 XML DSL 中使用 generic 关键字 verb() 和通用元素 动词

例如,要在 Java 中实施 DIB HTTP 方法:

rest("/say")
    .verb("TRACE", "/hello").route().transform();

这里的 transform()IN 消息正文复制到 OUT 消息的正文,以回显 HTTP 请求。

在 XML 中实施 DIB HTTP 方法:

<camelContext xmlns="http://camel.apache.org/schema/blueprint">
  ...
  <rest path="/say">
    <verb uri="/hello" method="TRACE">
      <route>
        <transform/>
      </route>
    </get>
</camelContext>

定义自定义 HTTP 错误消息

如果您的 REST 服务需要发送错误消息作为其响应,您可以定义自定义 HTTP 错误消息,如下所示:

  1. 通过将 Exchange.HTTP_RESPONSE_CODE 标头密钥设置为错误代码值来指定 HTTP 错误代码(例如,400404 等)。此设置指示您要发送错误消息回复的 REST DSL,而不是定期响应。
  2. 将消息正文填充自定义错误消息。
  3. 如果需要,设置 Content-Type 标头。
  4. 如果您的 REST 服务被配置为为来自 Java 对象和从 Java 对象(启用 绑定Mode ),您应该确定启用了 skipBindingOnErrorCode 选项(默认为 )。这是为了确保 REST DSL 在发送响应时不会尝试解压缩消息正文。

    有关对象绑定的详情,请参阅 第 4.3 节 “摘要到 Java 对象以及”

以下 Java 示例演示了如何定义自定义错误消息:

// Java
// Configure the REST DSL, with JSON binding mode
restConfiguration().component("restlet").host("localhost").port(portNum).bindingMode(RestBindingMode.json);

// Define the service with REST DSL
rest("/users/")
    .post("lives").type(UserPojo.class).outType(CountryPojo.class)
        .route()
            .choice()
                .when().simple("${body.id} < 100")
                    .bean(new UserErrorService(), "idTooLowError")
                .otherwise()
                    .bean(new UserService(), "livesWhere");

在这个示例中,如果输入 ID 小于 100,则返回自定义错误消息,使用 UserErrorService bean,它实现:

// Java
public class UserErrorService {
    public void idTooLowError(Exchange exchange) {
        exchange.getIn().setBody("id value is too low");
        exchange.getIn().setHeader(Exchange.CONTENT_TYPE, "text/plain");
        exchange.getIn().setHeader(Exchange.HTTP_RESPONSE_CODE, 400);
    }
}

UserErrorService bean 中,我们定义自定义错误消息,并将 HTTP 错误代码设置为 400

参数默认值

可以为传入 Camel 消息的标头指定默认值。

您可以使用一个键单词(如 query 参数的 verbose )来指定默认值。例如,在下面的代码中,默认值为 false。这意味着,如果没有为带有 verbose 键的标头提供其他值,则会将 false 插入为默认值。

rest("/customers/")
    .get("/{id}").to("direct:customerDetail")
    .get("/{id}/orders")
      .param()
	.name("verbose")
	.type(RestParamType.query)
	.defaultValue("false")
	.description("Verbose order details")
      .endParam()
        .to("direct:customerOrders")
    .post("/neworder").to("direct:customerNewOrder");

将 JsonParserException 嵌套在自定义 HTTP 错误消息中

您可能希望返回自定义错误消息的一个常见情形是嵌套 JsonParserException 异常。例如,您可以方便地利用 Camel 异常处理机制来创建自定义 HTTP 错误消息,其 HTTP 错误代码 400,如下所示:

// Java
onException(JsonParseException.class)
    .handled(true)
    .setHeader(Exchange.HTTP_RESPONSE_CODE, constant(400))
    .setHeader(Exchange.CONTENT_TYPE, constant("text/plain"))
    .setBody().constant("Invalid json data");

REST DSL 选项

通常,可以直接将 REST DSL 选项应用到服务定义的基本部分(即,立即遵循 rest()),如下所示:

rest("/email").consumes("text/plain").produces("text/html")
    .post("/to/{recipient}").to("direct:foo")
    .get("/for/{username}").to("direct:bar");

在这种情形中,如果指定选项应用到所有从属动词子句。或者可将选项应用到每个单独的 verb 子句,如下所示:

rest("/email")
    .post("/to/{recipient}").consumes("text/plain").produces("text/html").to("direct:foo")
    .get("/for/{username}").consumes("text/plain").produces("text/html").to("direct:bar");

如果指定选项仅适用于相关的 动词子,则从基础部分覆盖任何设置。

表 4.1 “REST DSL 选项” 总结 REST DSL 支持的选项。

表 4.1. REST DSL 选项

Java DSLXML DSL描述

bindingMode()

@bindingMode

指定绑定模式,可用于将传入消息放入 Java 对象(以及可选的、unmarshal Java 对象到传出消息)。可以具有以下值: off (默认)、autojsonxmljson_xml

consumes()

@consumes

限制 verb 子句,以仅接受 HTTP 请求中的指定互联网介质类型(MIME 类型)。典型的值有: text/plain,text/http,text/xml,application/json,application/xml.

customId()

@customId

定义用于 JMX 管理的自定义 ID。

description()

description

记录 REST 服务或动词条款。对于 JMX 管理工具非常有用。

enableCORS()

@enableCORS

如果为 true,请在 HTTP 响应中启用 CORS(跨原始资源共享)标头。默认为 false

id()

@id

为 REST 服务定义唯一 ID,它可用于定义 JMX 管理和其他工具。

method()

@method

指定此动词子句处理的 HTTP 方法。通常与 generic verb() 关键字一起使用。

outType()

@outType

启用对象绑定(即启用 bindingMode 选项时),这个选项指定代表 HTTP 响应 消息的 Java 类型。

produces()

produces

限制 verb 子句,使其仅在 HTTP 响应中仅生成指定的互联网介质类型(MIME 类型)。典型的值有: text/plain,text/http,text/xml,application/json,application/xml.

type()

@type

启用对象绑定(即启用 bindingMode 选项时),这个选项指定代表 HTTP Request 消息的 Java 类型。

VerbURIArgument

@uri

指定路径片段或 URI 模板,作为动词的参数。例如,get(VerbURIArgument)

BasePathArgument

@path

指定 rest() 关键字(Java DSL)或 rest 元素(XML DSL)中的基本路径。

4.3. 摘要到 Java 对象以及

用于通过 HTTP 传输的 Java 对象

使用 REST 协议的最常见方式之一是传输消息正文中 Java Bean 的内容。为了实现此工作,您需要有一个机制来汇总 Java 对象,以及从适当的数据格式放入其中。REST DSL 支持下列数据格式适用于编码 Java 对象:

JSON

JSON (JavaScript 对象表示法)是一个轻量级数据格式,可轻松从 Java 对象映射。JSON 语法是紧凑、轻便键入的,方便人进行读和写。因此,JSON 已成为 REST 服务的消息格式。

例如,以下 JSON 代码可以代表用户 bean,具有两个属性字段,即 idname

{
    "id" : 1234,
    "name" : "Jane Doe"
}
JAXB

JAXB (XML Binding 的 Java 架构)是基于 XML 的数据格式,可轻松映射到 Java 对象或从 Java 对象映射。要将 XML 接合到 Java 对象,还必须注解您要使用的 Java 类。

例如,以下 JAXB 代码可以代表用户 bean,其中有两个属性字段: idname

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<User>
  <Id>1234</Id>
  <Name>Jane Doe</Name>
</User>
注意

从 Camel 2.17.0 中,CIB 数据格式和类型转换支持从 XML 转换到 POJO,这些类使用 ObjectFactory 而不是 XmlRootElement。此外,camel 上下文应包含 CamelJaxbObjectFactory 属性,其值为 true。但是,由于优化,默认值为 false。

JSON 和 JAXB 与 REST DSL 集成

当然,您可以编写所需的代码,以将邮件正文转换为 Java 对象,并自行从 Java 对象转换。但是 REST DSL 提供了自动进行这个转换的便利。特别是,JSON 和 JAXB 与 REST DSL 的集成提供了以下优点:

  • 自动对 Java 对象和从 Java 对象编入和执行(授予适当的配置)。
  • REST DSL 可以自动检测数据格式(JSON 或 JAXB),并执行适当的转换。
  • REST DSL 提供了一个抽象层,以便您编写的代码不特定于特定的 JSON 或 JAXB 实施。因此,您可以稍后切换实施,对应用程序代码产生最小影响。

支持的数据格式组件

Apache Camel 提供 JSON 和 JAXB 数据格式的多个不同实施。REST DSL 目前支持以下数据格式:

  • JSON

    • jackson 数据格式(camel-jackson) (默认)
    • GSon 数据格式(camel-gson)
    • XStream 数据格式(camel-xstream)
  • JAXB

    • JAXB 数据格式(camel-jaxb)

如何启用对象 marshalling

要在 REST DSL 中启用对象摘要,请观察以下几点:

  1. 启用绑定模式,通过设置 bindingMode 选项(有几个级别可设置绑定模式)。如需详情,请参阅 “配置绑定模式”一节
  2. 使用 type 选项(必需)以及带有 outType 选项(可选)的传出消息上指定要转换为的 Java 类型(或从中)。
  3. 如果要将 Java 对象转换为 JAXB 数据格式,您必须记得使用适当的 JAXB 注释给 Java 类添加注解。
  4. 指定底层数据格式实现(或实现),使用 jsonDataFormat 选项和/或 xmlDataFormat 选项(可以在 restConfiguration 构建器中指定)。
  5. 如果您的路由以 JAXB 格式提供返回值,则通常您希望将交换正文的 Out 消息设置为带有 JAXB 注释(a JAXB 元素)的类实例。如果您希望以 XML 格式直接提供 JAXB 返回值,但是,使用键 xml.out.mustBeJAXBElementdataFormatProperty 设置为 false (可以在 restConfiguration 构建器中指定)。例如,在 XML DSL 语法中:

    <restConfiguration ...>
      <dataFormatProperty key="xml.out.mustBeJAXBElement"
                          value="false"/>
      ...
    </restConfiguration>
  6. 将所需的依赖项添加到项目构建文件中。例如,如果您使用 Maven 构建系统,且您使用 Jackson 数据格式,您要将以下依赖项添加到 Maven POM 文件中:

    <?xml version="1.0" encoding="UTF-8"?>
    <project ...>
      ...
      <dependencies>
        ...
        <!-- use for json binding --> <dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-jackson</artifactId> </dependency>
        ...
      </dependencies>
    </project>
  7. 将应用程序部署到 OSGi 容器时,请记得为您的所选数据格式安装必要的功能。例如,如果您使用的是 Jackson 数据格式(默认),则通过输入以下命令来安装 camel-jackson 功能:

    JBossFuse:karaf@root> features:install camel-jackson

    或者,如果您部署到 Fabric 环境,您可以将该功能添加到 Fabric 配置集中。例如,如果您使用配置集 MyRestProfile,您可以通过输入以下命令来添加该功能:

    JBossFuse:karaf@root> fabric:profile-edit --features camel-jackson MyRestProfile

配置绑定模式

默认情况下,bindingMode 选项是 off,因此您必须明确配置它,以便能启用 Java 对象的 marshalling。TABLE 显示支持的绑定模式列表。

注意

仅当 content-type 标头包含 jsonxml 的绑定时,从 POJO 到 JSon/JAXB 的绑定才会进行 Camel 2.16.3。如果消息正文不应尝试使用绑定进行总结,这允许您指定自定义内容类型。例如,当消息正文是一个自定义二进制有效负载时,这很有用。

表 4.2. REST DSL BInding 模式

绑定模式描述

off

关闭绑定 (默认)

auto

为 JSON 和/或 XML 启用绑定。在这个模式中,Camel 会自动根据传入消息的格式自动选择 JSON 或 XML(JAXB)。您不需要 同时启用两种数据格式:JSON 实现、XML 实现,或两者都可以在类路径中提供。

json

仅为 JSON 启用了绑定。必须在 classpath 上提供 JSON 实施(默认为 Camel 尝试启用 camel-jackson 实施)。

xml

仅为 XML 启用绑定。必须在 classpath 上提供一个 XML 实现(默认为 Camel 尝试启用 camel-jaxb 实现)。

json_xml

为 JSON 和 XML 启用了绑定。在这个模式中,Camel 会自动根据传入消息的格式自动选择 JSON 或 XML(JAXB)。您需要在 classpath 上提供两种数据类型。

在 Java 中,这些绑定模式值表示为以下枚举类型的实例:

org.apache.camel.model.rest.RestBindingMode

您可以设置 bindingMode 的不同级别,如下所示:

REST DSL 配置

您可以在 restConfiguration 构建器中设置 bindingMode 选项,如下所示:

restConfiguration().component("servlet").port(8181).bindingMode(RestBindingMode.json);
服务定义基础部分

您可以在 rest() 关键字后设置 bindingMode 选项(在 verb 子句之前),如下所示:

rest("/user").bindingMode(RestBindingMode.json).get("/{id}").VerbClause
verb 子句

您可以在 verb 子句中设置 bindingMode 选项,如下所示:

rest("/user")
    .get("/{id}").bindingMode(RestBindingMode.json).to("...");

示例

如需完整的代码示例,显示如何使用 REST DSL 将 Servlet 组件用作 REST 实施,了解 Apache Camel camel-example-servlet-rest-blueprint 示例。您可以通过安装独立 Apache Camel 发行版 apache-camel-2.23.2 找到这个示例。fuse-7_10_0-00018-redhat-00001.zip,它包括在 Fuse 安装的额外s / 子目录中。

安装独立 Apache Camel 发行版后,您可以在以下目录中找到示例代码:

ApacheCamelInstallDir/examples/camel-example-servlet-rest-blueprint

将 Servlet 组件配置为 REST 实现

camel-example-servlet-rest-blueprint 示例中,REST DSL 的底层实施由 Servlet 组件提供。Servlet 组件在 Blueprint XML 文件中配置,如 例 4.1 “为 REST DSL 配置 Servlet 组件” 所示。

例 4.1. 为 REST DSL 配置 Servlet 组件

<?xml version="1.0" encoding="UTF-8"?>
<blueprint ...>

  <!-- to setup camel servlet with OSGi HttpService -->
  <reference id="httpService" interface="org.osgi.service.http.HttpService"/>

  <bean class="org.apache.camel.component.servlet.osgi.OsgiServletRegisterer"
        init-method="register"
        destroy-method="unregister">
    <property name="alias" value="/camel-example-servlet-rest-blueprint/rest"/>
    <property name="httpService" ref="httpService"/>
    <property name="servlet" ref="camelServlet"/>
  </bean>

  <bean id="camelServlet" class="org.apache.camel.component.servlet.CamelHttpTransportServlet"/>
  ...
  <camelContext xmlns="http://camel.apache.org/schema/blueprint">

    <restConfiguration component="servlet"
                       bindingMode="json"
                       contextPath="/camel-example-servlet-rest-blueprint/rest"
                       port="8181">
      <dataFormatProperty key="prettyPrint" value="true"/>
    </restConfiguration>
    ...
  </camelContext>

</blueprint>

要使用 REST DSL 配置 Servlet 组件,您需要配置由以下三个层组成的堆栈:

REST DSL 层
REST DSL 层由 restConfiguration 元素配置,该元素通过将 component 属性设置为值 servlet 来与 Servlet 组件集成。
servlet 组件层
Servlet 组件层作为类的实例 CamelHttpTransportServlet 实施,其中示例实例具有 bean ID( camelServlet )。
HTTP 容器层

Servlet 组件必须部署到 HTTP 容器中。Karaf 容器通常配置有默认的 HTTP 容器(a Jetty HTTP 容器),它监听端口 8181 上的 HTTP 请求。要将 Servlet 组件部署到默认的 Jetty 容器,您需要执行以下操作:

  1. 获得对 org.osgi.service.http.HttpService compliant 服务(其中这个服务)是标准的 OSGi 接口,它提供了一个标准化的 OSGi 接口,提供对 OSGi 中默认 HTTP 服务器的访问。
  2. 创建 utility 类的实例 OsgiServletRegisterer,以在 HTTP 容器中注册 Servlet 组件。OsgiServletRegister 类是简化 Servlet 组件生命周期的实用程序。创建此类实例时,它会自动调用 HttpService OSGi 服务中的 registerServlet 方法;在实例被销毁时,它会自动调用 unregister 方法。

所需的依赖项

这个示例有两个依赖项,它们是 REST DSL 的关键重要,如下所示:

servlet 组件

提供 REST DSL 的底层实施。这在 Maven POM 文件中指定,如下所示:

<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-servlet</artifactId>
  <version>${camel-version}</version>
</dependency>

在将应用程序捆绑包部署到 OSGi 容器之前,您必须安装 Servlet 组件功能,如下所示:

JBossFuse:karaf@root> features:install camel-servlet
jackson 数据格式

提供 JSON 数据格式实施。这在 Maven POM 文件中指定,如下所示:

<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-jackson</artifactId>
  <version>${camel-version}</version>
</dependency>

在将应用程序捆绑包部署到 OSGi 容器之前,您必须安装 Jackson 数据格式功能,如下所示:

JBossFuse:karaf@root> features:install camel-jackson

Java 类型用于响应

示例应用程序会在 HTTP 请求和 Response 消息中回传递 User 类型对象。User Java 类定义为 例 4.2 “用于 JSON 响应的用户类” 所示。

例 4.2. 用于 JSON 响应的用户类

// Java
package org.apache.camel.example.rest;

public class User {

    private int id;
    private String name;

    public User() {
    }

    public User(int id, String name) {
        this.id = id;
        this.name = name;
    }

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

User 类具有 JSON 数据格式相对简单表示。例如,此类的典型实例以 JSON 格式表示:

{
    "id" : 1234,
    "name" : "Jane Doe"
}

带有 JSON 绑定的 REST DSL 路由示例

本例中的 REST DSL 配置和 REST 服务定义显示在 例 4.3 “带有 JSON 绑定的 REST DSL 路由” 中。

例 4.3. 带有 JSON 绑定的 REST DSL 路由

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           ...>
  ...
  <!-- a bean for user services -->
  <bean id="userService" class="org.apache.camel.example.rest.UserService"/>

  <camelContext xmlns="http://camel.apache.org/schema/blueprint">

    <restConfiguration component="servlet"
                       bindingMode="json"
                       contextPath="/camel-example-servlet-rest-blueprint/rest"
                       port="8181">
      <dataFormatProperty key="prettyPrint" value="true"/>
    </restConfiguration>

    <!-- defines the REST services using the  base path, /user -->
    <rest path="/user" consumes="application/json" produces="application/json">
      <description>User rest service</description>

      <!-- this is a rest GET to view a user with the given id -->
      <get uri="/{id}" outType="org.apache.camel.example.rest.User">
        <description>Find user by id</description>
        <to uri="bean:userService?method=getUser(${header.id})"/>
      </get>

      <!-- this is a rest PUT to create/update a user -->
      <put type="org.apache.camel.example.rest.User">
        <description>Updates or create a user</description>
        <to uri="bean:userService?method=updateUser"/>
      </put>

      <!-- this is a rest GET to find all users -->
      <get uri="/findAll" outType="org.apache.camel.example.rest.User[]">
        <description>Find all users</description>
        <to uri="bean:userService?method=listUsers"/>
      </get>

    </rest>

  </camelContext>

</blueprint>

REST 操作

例 4.3 “带有 JSON 绑定的 REST DSL 路由” 中的 REST 服务定义以下 REST 操作:

GET /camel-example-servlet-rest-blueprint/rest/user/{id}
获取 {id} 识别的用户的详细信息,其中以 JSON 格式返回 HTTP 响应。
PUT /camel-example-servlet-rest-blueprint/rest/user
创建新用户,其中用户详情包含在 PUT 消息正文中,采用 JSON 格式编码(与 User 对象类型匹配)。
GET /camel-example-servlet-rest-blueprint/rest/user/findAll
获取 所有用户 的详情,其中 HTTP 响应作为用户数组返回,格式为 JSON 格式。

调用 REST 服务的 URL

通过检查 例 4.3 “带有 JSON 绑定的 REST DSL 路由” 中的 REST DSL 定义,您可以将调用每个 REST 操作所需的 URL 组成。例如,要调用第一个 REST 操作,它会返回具有给定 ID 的用户详情,其 URL 会按如下方式构建:

http://localhost:8181
restConfiguration 中,协议默认为 http,端口明确设置为 8181
/camel-example-servlet-rest-blueprint/rest
restConfiguration 元素的 contextPath 属性指定。
/user
rest 元素的 path 属性指定。
/{id}
get verb 元素的 uri 属性指定。

因此,您可以在命令行中输入以下命令来使用 curl 实用程序调用此 REST 操作:

curl -X GET -H "Accept: application/json" http://localhost:8181/camel-example-servlet-rest-blueprint/rest/user/123

同样,可以通过 curl 调用剩余的 REST 操作,输入以下示例命令:

curl -X GET -H "Accept: application/json" http://localhost:8181/camel-example-servlet-rest-blueprint/rest/user/findAll

curl -X PUT -d "{ \"id\": 666, \"name\": \"The devil\"}" -H "Accept: application/json" http://localhost:8181/camel-example-servlet-rest-blueprint/rest/user

4.4. 配置 REST DSL

使用 Java 配置

在 Java 中,您可以使用 restConfiguration() 构建器 API 配置 REST DSL。例如,要将 REST DSL 配置为使用 Servlet 组件作为底层实现:

restConfiguration().component("servlet").bindingMode("json").port("8181")
    .contextPath("/camel-example-servlet-rest-blueprint/rest");

使用 XML 配置

在 XML 中,您可以使用 restConfiguration 元素配置 REST DSL。例如,要将 REST DSL 配置为使用 Servlet 组件作为底层实现:

<?xml version="1.0" encoding="UTF-8"?>
<blueprint ...>
  ...
  <camelContext xmlns="http://camel.apache.org/schema/blueprint">
    ...
    <restConfiguration component="servlet"
                       bindingMode="json"
                       contextPath="/camel-example-servlet-rest-blueprint/rest"
                       port="8181">
      <dataFormatProperty key="prettyPrint" value="true"/>
    </restConfiguration>
    ...
  </camelContext>

</blueprint>

配置选项

表 4.3 “配置 REST DSL 的选项” 显示使用 restConfiguration() 构建器(Java DSL)或 restConfiguration 元素(XML DSL)配置 REST DSL 的选项。

表 4.3. 配置 REST DSL 的选项

Java DSLXML DSL描述

component()

@component

指定用作 REST 传输的 Camel 组件(如 servletrestletspark-rest 等等)。该值可以是标准组件名称,也可以是自定义实例的 bean ID。如果没有指定这个选项,Camel 会在类路径或 bean registry 中查找 RestConsumerFactory 实例。

scheme()

@scheme

用于公开 REST 服务的协议。通常支持基于底层 REST 的实施,但 httphttps。默认为 http

host()

@host

用于公开 REST 服务的主机名。

port()

@port

用于公开 REST 服务的端口号。

注: 此设置将被 Servlet 组件 忽略,它使用容器的标准 HTTP 端口。对于 Apache Karaf OSGi 容器,标准 HTTP 端口通常为 8181。为采用 JMX 和工具设置端口值的好方法是个好办法。

contextPath()

@contextPath

为 REST 服务设置领先的上下文路径。这可以用于 Servlet 等组件,使用 上下文路径 设置部署部署的 Web 应用。

hostNameResolver()

@hostNameResolver

如果没有显式设置主机名,则此解析器决定 REST 服务的主机。可能的值有 RestHostNameResolver.localHostName (Java DSL)或 localHostName (XML DSL),它解析为主机名格式;以及 RestHostNameResolver.localIp (Java DSL)或 localIp (XML DSL),它解析为点十进制 IP 地址格式。从 Camel 2.17 RestHostNameResolver.allLocalIp 解析为所有本地 IP 地址。

默认值为 localHostName 最多 Camel 2.16。从 Camel 2.17,默认值 是所有LocalIp

bindingMode()

@bindingMode

为 JSON 或 XML 格式消息启用绑定模式。可能的值有: offautojsonxmljson_xml。默认为 off

skipBindingOnErrorCode()

@skipBindingOnErrorCode

指定是否在输出上跳过绑定,如果存在自定义 HTTP 错误代码标头。这可让您构建不绑定到 JSON 或 XML 的自定义错误消息,否则会成功消息。默认为 true

enableCORS()

@enableCORS

如果为 true,请在 HTTP 响应中启用 CORS(跨原始资源共享)标头。默认为 false

jsonDataFormat()

@jsonDataFormat

指定 Camel 用来实施 JSON 数据格式的组件。可能的值有: json-jackson,json-gson,json-xstream.默认为 json-jackson

xmlDataFormat()

@xmlDataFormat

指定 Camel 用于实施 XML 数据格式的组件。可能的值有: jaxb。默认为 jaxb

componentProperty()

componentProperty

允许您在底层 REST 实现上设置任意 组件级别 属性。

endpointProperty()

endpointProperty

允许您在底层 REST 实现上设置任意 端点级别 属性。

consumerProperty()

consumerProperty

允许您在底层 REST 实现上设置任意 使用者端点 属性。

dataFormatProperty()

dataFormatProperty

允许您在底层数据格式组件上设置任意属性(如 Jackson 或 JAXB)。从 Camel 2.14.1 开始,您可以将以下前缀附加到属性键:

  • json.in
  • json.out
  • xml.in
  • xml.out

要将属性设置限制为特定格式类型(JSON 或 XML)以及特定消息方向(INOUT)。

corsHeaderProperty()

corsHeaders

允许您将自定义 CORS 标头指定为键/值对。

默认 CORS 标头

如果启用了 CORS(跨原始资源共享),则默认设置以下标头。您可以通过调用 corsHeaderProperty DSL 命令来选择覆盖默认设置。

表 4.4. 默认 CORS 标头

标头密钥标头值

access-Control-Allow-Origin

\*

access-Control-Allow-Methods

获取,HEAD,POST, PUT , DELETE ,TRACE,OPTIONS,CONNECT,PATCH

access-Control-Allow-Headers

origin,Accept,X-Requested-With,Content-Type,Access-Control-Request-Method,Access-Control-Request-Headers

access-Control-Max-Age

3600

启用或禁用 Jackson JSON 功能

您可以通过在 dataFormatProperty 选项中配置以下键来启用或禁用特定的 Jackson JSON 功能:

  • json.in.disableFeatures
  • json.in.enableFeatures

例如,要禁用 Jackson 的 FAIL_ON_UN_PROPERTIES 功能(如果 JSON 输入包含无法映射到 Java 对象的属性,这会导致 Jackson 将失败):

restConfiguration().component("jetty")
    .host("localhost").port(getPort())
    .bindingMode(RestBindingMode.json)
    .dataFormatProperty("json.in.disableFeatures", "FAIL_ON_UNKNOWN_PROPERTIES");

您可以通过指定一个以逗号分隔的列表来禁用 多个功能。例如:

.dataFormatProperty("json.in.disableFeatures", "FAIL_ON_UNKNOWN_PROPERTIES,ADJUST_DATES_TO_CONTEXT_TIME_ZONE");

以下是如何在 Java DSL 中禁用和启用 Jackson JSON 功能的示例:

restConfiguration().component("jetty")
    .host("localhost").port(getPort())
    .bindingMode(RestBindingMode.json)
    .dataFormatProperty("json.in.disableFeatures", "FAIL_ON_UNKNOWN_PROPERTIES,ADJUST_DATES_TO_CONTEXT_TIME_ZONE")
    .dataFormatProperty("json.in.enableFeatures", "FAIL_ON_NUMBERS_FOR_ENUMS,USE_BIG_DECIMAL_FOR_FLOATS");

以下是如何在 XML DSL 中禁用和启用 Jackson JSON 功能的示例:

<restConfiguration component="jetty" host="localhost" port="9090" bindingMode="json">
  <dataFormatProperty key="json.in.disableFeatures" value="FAIL_ON_UNKNOWN_PROPERTIES,ADJUST_DATES_TO_CONTEXT_TIME_ZONE"/>
  <dataFormatProperty key="json.in.enableFeatures" value="FAIL_ON_NUMBERS_FOR_ENUMS,USE_BIG_DECIMAL_FOR_FLOATS"/>
</restConfiguration>

可以禁用或启用的 Jackson 功能与以下 Jackson 类中的 enum ID 对应

4.5. OpenAPI 集成

概述

您可以使用 OpenAPI 服务为 CamelContext 文件中的任何 REST 定义路由和端点创建 API 文档。要做到这一点,使用 Camel REST DSL 及 camel-openapi-java 模块,它完全基于 Java。camel-openapi-java 模块会创建一个 servlet,它与 CamelContext 集成,并从每个 REST 端点中提取信息,以 JSON 或 YAML 格式生成 API 文档。

如果使用 Maven,请编辑 pom.xml 文件,以添加对 camel-openapi-java 组件的依赖项:

<dependency>
   <groupId>org.apache.camel</groupId>
   <artifactId>camel-openapi-java</artifactId>
   <version>x.x.x</version>
   <!-- Specify the version of your camel-core module. -->
</dependency>

配置 CamelContext 以启用 OpenAPI

要在 Camel REST DSL 中使用 OpenAPI,调用 apiContextPath() 设置 OpenAPI 生成的 API 文档的上下文路径。例如:

public class UserRouteBuilder extends RouteBuilder {
    @Override
    public void configure() throws Exception {
        // Configure the Camel REST DSL to use the netty4-http component:
        restConfiguration().component("netty4-http").bindingMode(RestBindingMode.json)
            // Generate pretty print output:
            .dataFormatProperty("prettyPrint", "true")
            // Set the context path and port number that netty will use:
            .contextPath("/").port(8080)
            // Add the context path for the OpenAPI-generated API documentation:
            .apiContextPath("/api-doc")
                .apiProperty("api.title", "User API").apiProperty("api.version", "1.2.3")
                // Enable CORS:
                .apiProperty("cors", "true");

        // This user REST service handles only JSON files:
        rest("/user").description("User rest service")
            .consumes("application/json").produces("application/json")
            .get("/{id}").description("Find user by id").outType(User.class)
                .param().name("id").type(path).description("The id of the user to get").dataType("int").endParam()
                .to("bean:userService?method=getUser(${header.id})")
            .put().description("Updates or create a user").type(User.class)
                .param().name("body").type(body).description("The user to update or create").endParam()
                .to("bean:userService?method=updateUser")
            .get("/findAll").description("Find all users").outTypeList(User.class)
                .to("bean:userService?method=listUsers");
    }
}

OpenAPI 模块配置选项

下表描述的选项可让您配置 OpenAPI 模块。设置如下选项:

  • 如果您将 camel-openapi-java 模块用作 servlet,通过更新 web.xml 文件并为每个要设置的每个配置选项指定 init-param 元素来设置选项。
  • 如果您使用来自 Camel REST 组件的 camel-openapi-java 模块,请通过调用适当的 RestConfigurationDefinition 方法来设置选项,如 enableCORS()、 host()contextPath()。使用 RestConfigurationDefinition.apiProperty() 方法设置 api.xxx 选项。
选项类型描述

api.contact.email

字符串

用于 API 相关的对应电子邮件地址。

api.contact.name

字符串

要联系的人员或机构的名称。

api.contact.url

字符串

网站 URL 获取更多信息。

apiContextIdListing

布尔值

如果您的应用程序使用多个 CamelContext 对象,则默认行为是仅列出当前 CamelContext 中的 REST 端点。如果您希望在运行 REST 服务的 JVM 中运行的每个 CamelContext 中的 REST 端点列表,则此选项设置为 true。当 apiContextIdListing 为 true 时,OpenAPI 在根路径中输出 CamelContext ID,例如 /api-docs,作为 JSON 格式的名称列表。要访问 OpenAPI 生成的文档,请在 CamelContext ID 中附加 REST 上下文路径,如 api-docs/myCamel。您可以使用 apiContextIdPattern 选项过滤此输出列表中的名称。

apiContextIdPattern

字符串

过滤 CamelContext ID 出现在上下文列表中的模式。您可以指定正则表达式,并将 * 用作通配符。这与 Camel 拦截器功能所使用的模式匹配功能相同。

api.license.name

字符串

用于 API 的许可证名称。

api.license.url

字符串

用于 API 的许可证的 URL。

api.path

字符串

设置为 生成文档的 REST API 的路径,例如 /api-docs。指定一个相对路径。不要指定,例如 httphttpscamel-openapi-java 模块以以下格式计算运行时的绝对路径: protocol://host:port/context-path/api-path

api.termsOfService

字符串

API 服务条款的 URL。

api.title

字符串

应用程序的标题。

api.version

字符串

API 的版本。默认值为 0.0.0。

base.path

字符串

必需。设置 REST 服务可用的路径。指定一个相对路径。也就是说,不要指定 httphttpscamel-openapi-java modul 以以下格式计算运行时的绝对路径: protocol://host:port/context-path/base.path

CORS

布尔值

是否启用 HTTP 访问控制(CORS)。这只为查看 REST API 文档启用 CORS,而不可用于访问 REST 服务。默认值为 false。建议改为使用 CorsFilter 选项,如此表中所述。

主机

字符串

设置运行 OpenAPI 服务的主机的名称。默认值是根据 localhost 计算主机名。

方案

字符串

要使用的协议方案。使用逗号分隔多个值,如 "http,https"。默认值为 http

opeapi.version

字符串

OpenAPI 规格版本。默认值为 3.0。

获取 JSON 或 YAML 输出

从 Camel 3.1 开始,camel-openapi-java 模块支持 JSON 和 YAML 格式的输出。要指定您需要的输出,将 /openapi.json/openapi.yaml 添加到请求 URL。如果请求 URL 没有指定格式,则 camel-openapi-java 模块将检查 HTTP Accept 标头以检测 JSON 或 YAML 是否可以接受。如果两者都被接受,或者没有设置为接受状态,则 JSON 是默认的返回格式。

例子

在 Apache Camel 3.x 分发中,cal-example-openapi-cdicamel-example-openapi-java 演示了使用 camel-openapi-java 模块。

在 Apache Camel 2.x 发行版中,camel-example-swagger-cdicamel-example-swagger-java 演示了使用 camel-swagger-java 模块。

增强 OpenAPI 生成的文档

从 Camel 3.1 开始,您可以通过定义参数详情(如名称、描述、数据类型、参数类型等)来增强 OpenAPI 生成的文档。如果使用 XML,请指定 param 元素来添加此信息。以下示例演示了如何提供有关 ID 路径参数的信息:

<!-- This is a REST GET request to view information for the user with the given ID: -->
<get uri="/{id}" outType="org.apache.camel.example.rest.User">
     <description>Find user by ID.</description>
     <param name="id" type="path" description="The ID of the user to get information about." dataType="int"/>
     <to uri="bean:userService?method=getUser(${header.id})"/>
</get>

以下是 Java DSL 中相同的示例:

.get("/{id}").description("Find user by ID.").outType(User.class)
   .param().name("id").type(path).description("The ID of the user to get information about.").dataType("int").endParam()
   .to("bean:userService?method=getUser(${header.id})")

如果您定义了名称为 正文 的参数,那么您还必须将 正文 指定为这个参数的类型。例如:

<!-- This is a REST PUT request to create/update information about a user. -->
<put type="org.apache.camel.example.rest.User">
     <description>Updates or creates a user.</description>
     <param name="body" type="body" description="The user to update or create."/>
     <to uri="bean:userService?method=updateUser"/>
</put>

以下是 Java DSL 中相同的示例:

.put().description("Updates or create a user").type(User.class)
     .param().name("body").type(body).description("The user to update or create.").endParam()
     .to("bean:userService?method=updateUser")

另请参阅: Apache Camel 发行版中 的示例/camel-example-servlet-rest-tomcat

第 5 章 消息传递系统

摘要

本章介绍消息传递系统的基本构建块,如端点、消息通道和消息路由器。

5.1. 消息

概述

消息 是传输消息传递系统的最小单元(由下图中的灰色点代表)。消息本身可能含有一些内部结构(即一个消息),其中包含了与 图 5.1 “消息模式” 中的 grey dot 连接的 geometrical figures 来表示的多部分(即 a geometrical figure)。

图 5.1. 消息模式

Message pattern

消息类型

Apache Camel 定义以下不同消息类型:

  • 在消息 ,在从消费者端点通过路由传输到制作者端点的消息中(通常,启动消息交换)。
  • 从生产者端点到消费者端点(通常是响应 In 消息)的消息中出发消息(通常要通过来自生产者端点的路由)。

所有这些消息类型都由 org.apache.camel.Message 接口在内部表示。

消息结构

默认情况下,Apache Camel 将以下结构应用到所有消息类型:

  • 标头 相应数据包含从消息中提取的元数据或标头数据。
  • 正文 abrt-sually 以原始形式包含整个消息。
  • Attachments abrt-jaxb Message attachments(需要与特定的消息传递系统(如 JBI)集成。

务必要记住,这个部门分为标头、正文和附件,是消息的抽象模型。Apache Camel 支持许多不同的组件,生成各种消息格式。最终,这是底层组件实施,决定将什么放置到邮件的标头和正文中。

关联消息

在内部,Apache Camel 记住消息 ID,用于关联各个消息。但是,在实践中,Apache Camel 关联消息的最重要方法是 交换 对象。

Exchange 对象

Exchange 对象是封装相关消息的实体,其中相关消息的集合被称为 消息交换,并且管理消息序列的规则被称为 交换模式。例如,两个常见的交换模式是:单向事件消息(与 In 消息一致)和请求检查交换(记录 In 消息,后接 Out 消息)。

访问消息

在 Java DSL 中定义路由规则时,您可以使用以下 DSL 构建器方法访问消息的标头和正文:

  • header(String name), body() Curve- the returns the named header and the current In message 的正文。
  • outBody() libselinux- the return the current Out 消息的正文。

例如,若要填充 In 消息 的用户名 标头,您可以使用以下 Java DSL 路由:

from(SourceURL).setHeader("username", "John.Doe").to(TargetURL);

5.2. Message Channel

概述

频道 是消息传递系统中的逻辑频道。也就是说,将消息发送到不同的消息通道提供了将消息排序到不同消息类型的元素方法。消息队列和消息主题是消息频道的示例。您应该记住,逻辑频道与物理频道不同。物理实现了逻辑通道的几种不同方法。

在 Apache Camel 中,消息频道由面向消息组件的端点 URI 代表,如 图 5.2 “Message Channel Pattern” 所示。

图 5.2. Message Channel Pattern

Message channel pattern

面向消息的组件

Apache Camel 中的以下面向消息的组件支持消息频道的注意:

ActiveMQ

在 ActiveMQ 中,消息通道由 队列或主题 表示。特定队列 QueueName 的端点 URI,其格式如下:

activemq:QueueName

特定主题的端点 URI TopicName 的格式如下:

activemq:topic:TopicName

例如,要将消息发送到队列 Foo.Bar,请使用以下端点 URI:

activemq:Foo.Bar

如需有关设置 ActiveMQ 组件的更多详细信息和说明,请参阅 Apache Camel 组件参考指南 中的 ActiveMQ。

JMS

Java 消息传递服务(JMS)是一个通用打包程序层,用于访问许多不同类型的消息系统(例如,您可以使用它来嵌套 ActiveMQ、MQSeries、Tibco、BEA、Sunic 等)。在 JMS 中,消息通道由队列或主题表示。特定队列 QueueName 的端点 URI,其格式如下:

jms:QueueName

特定主题的端点 URI TopicName 的格式如下:

jms:topic:TopicName

有关设置 JMS 组件的详情和说明,请参阅 Apache Camel 组件参考指南 中的 Jms

AMQP

在 AMQP 中,消息通道由队列或主题表示。特定队列 QueueName 的端点 URI,其格式如下:

amqp:QueueName

特定主题的端点 URI TopicName 的格式如下:

amqp:topic:TopicName

有关设置 AMQP 组件的详情和说明,请参阅 Apache Camel 组件参考指南 中的 Amqp

5.3. Message Endpoint

概述

消息端点 是应用程序与消息传递系统间的接口。如 图 5.3 “Message Endpoint Pattern” 所示,您可以有一个发件人端点,有时也称为代理或服务消费者,它负责发送 In 消息和接收器端点,有时也称为端点或服务,该服务负责接收 In 消息。

图 5.3. Message Endpoint Pattern

Message endpoint pattern

端点类型

Apache Camel 定义两种基本端点类型:

  • 消费者端点 Apache Camel 路由开始时出现,并读取来自传入频道的消息(等同于 接收器 端点)。
  • Apache Camel 路由结束时 制作者端点 producer-latex Appears,并在消息中写入传出频道(等同于 发送方 端点)。可以使用多个制作者端点定义路由。

端点 URI

在 Apache Camel 中,端点由 端点 URI 代表,它通常会封装以下数据类型:

  • 消费者端点 IFL Advertises 一个特定位置的端点 URI (例如,公开发送方可以连接到的服务)。另外,URI 可以指定消息源,如消息队列。端点 URI 可以包含用于配置端点的设置。
  • 制作制作者端点的端点 URI 进行登录,包含要发送消息以及配置端点的设置的详细信息。在某些情况下,URI 指定远程接收器端点的位置;在其他情况下,目的地可以有一个抽象形式,如队列名称。

Apache Camel 中的端点 URI 有以下通用形式:

ComponentPrefix:ComponentSpecificURI

其中 component Prefix 是一个识别特定 Apache Camel 组件的 URI 前缀(有关所有支持组件的详细信息,请参阅 Apache Camel 组件参考 )。URI(Pack SpecificURI )的其余部分具有特定组件定义的语法。例如,要连接到 JMS 队列 Foo.Bar,您可以定义类似如下的端点 URI:

jms:Foo.Bar

若要定义将消费者端点 file://local/router/messages/foo 直接连接到制作者 端点的路由,可以使用以下 Java DSL 片段:

from("file://local/router/messages/foo").to("jms:Foo.Bar");

另外,您可以在 XML 中定义相同的路由,如下所示:

<camelContext id="CamelContextID" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="file://local/router/messages/foo"/>
    <to uri="jms:Foo.Bar"/>
  </route>
</camelContext>

动态到

& lt;toD > 参数允许您使用串联在一起的一个或多个表达式向动态计算端点发送消息。

默认情况下,使用 Simple 语言计算端点。以下示例向标头定义的端点发送信息:

<route>
  <from uri="direct:start"/>
  <toD uri="${header.foo}"/>
</route>

在 Java DSL 中,同一命令的格式是:

from("direct:start")
  .toD("${header.foo}");

URI 也可以带有字面的前缀,如下例所示:

<route>
  <from uri="direct:start"/>
  <toD uri="mock:${header.foo}"/>
</route>

在 Java DSL 中,同一命令的格式是:

from("direct:start")
  .toD("mock:${header.foo}");

在上例中,如果 header.foo 的值为 orange,则 URI 将解析为 模拟:orange

要使用简单以外的语言,您需要定义 language: 参数。请参阅 第 II 部分 “路由表达式和指定语言”

使用不同语言的格式是使用语言 :语言名称: 在 URI 中。例如,要使用 Xpath,请使用以下格式:

<route>
  <from uri="direct:start"/>
  <toD uri="language:xpath:/order/@uri/">
</route>

以下是 Java DSL 中相同的示例:

from("direct:start")
  .toD("language:xpath:/order/@uri");

如果没有指定 语言: 如果端点是一个组件名称。在某些情况下,组件和语言的名称相同,比如 xquery。

您可以使用 + 符号连接多个语言。在以下示例中,URI 是 Simple 和 Xpath 语言的组合。simple 是默认值,因此不需要定义语言。+ 符号为 Xpath 指令后,使用 language:xpath 表示。

<route>
  <from uri="direct:start"/>
  <toD uri="jms:${header.base}+language:xpath:/order/@id"/>
</route>

在 Java DSL 中,格式如下:

from("direct:start")
  .toD("jms:${header.base}+language:xpath:/order/@id");

很多语言可以同时相互连接,只需使用 + 分开,并使用语言指定每个 语言:语言名称

以下选项可用于 D

名称

默认值

描述

uri

 

必需:要使用的 URI。

pattern

 

设置一个在发送到端点时要使用的特定 Exchange Pattern。原始 MEP 随即被恢复。

cacheSize

 

配置 ProducerCache 的缓存大小,它将缓存制作者以供重复使用。默认缓存大小为 1000,如果未指定其他值,则将使用该大小。将值设为 -1 会完全关闭缓存。

ignoreInvalidEndpoint

false

指定是否忽略无法解析的端点 URI。如果禁用,Camel 将抛出一个指定无效端点 URI 的异常。

5.4. pipes 和 Filters

概述

pipes 和过滤器 模式在 图 5.4 “pipes 和 Filters Pattern” 中显示的是,它通过创建过滤器链来构造路由的方法,其中单个过滤器的输出将反馈到管道中下一个过滤器的输入(与 UNIX pipe 命令相同)。管道方法的优点在于,它可让您编写服务(某些服务可能是 Apache Camel 应用程序外部)以创建更加复杂的消息处理。

图 5.4. pipes 和 Filters Pattern

pipes 和过滤器特征

InOut Exchange 模式的管道

通常,管道中的所有端点都有一个输入(在消息中)和一个输出(输出),这意味着它们与 In Out 消息交换模式兼容。图 5.5 “InOut Exchanges 的管道” 中显示了通过 InOut 管道的典型消息流。

图 5.5. InOut Exchanges 的管道

InOut 交换的管道

管道将每个端点的输出连接到下一端点的输入。来自最终端点的 Out 消息会发回到原始调用者。您可以为这个管道定义路由,如下所示:

from("jms:RawOrders").pipeline("cxf:bean:decrypt", "cxf:bean:authenticate", "cxf:bean:dedup", "jms:CleanOrders");

同一路由可以在 XML 中配置,如下所示:

<camelContext id="buildPipeline" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="jms:RawOrders"/>
    <to uri="cxf:bean:decrypt"/>
    <to uri="cxf:bean:authenticate"/>
    <to uri="cxf:bean:dedup"/>
    <to uri="jms:CleanOrders"/>
  </route>
</camelContext>

XML 中没有专用管道元素。和 元素的前一个组合有语义等同于管道。请参阅 “pipeline()和 to()DSL 命令的比较”一节

InOnly 和 RobustInOnly Exchange 模式的管道

如果没有来自管道中端点的 Out 消息(如 InOnly 和 Robust InOnly 交换模式的情况),则管道不能以正常方式连接。在这种特殊情况下,管道通过将原始 In 消息的副本传递给管道中的每个端点,如 图 5.6 “InOnly Exchanges 的管道” 所示。这个管道类型等同于带有固定目的地的接收者列表(请参阅 第 8.3 节 “接收者列表”)。

图 5.6. InOnly Exchanges 的管道

用于 InOnly 交换的管道

此管道的路由使用与 InOut 管道(Java DSL 或 XML)相同的语法来定义。

pipeline()和 to()DSL 命令的比较

在 Java DSL 中,您可以使用以下语法之一定义管道路由:

  • 使用 pipeline()处理器命令 the the pipeline processor 使用管道处理器构建管道路由,如下所示:

    from(SourceURI).pipeline(FilterA, FilterB, TargetURI);
  • 使用 to()命令 abrt- theUse the to() 命令构建管道路由,如下所示:

    from(SourceURI).to(FilterA, FilterB, TargetURI);

    另外,您可以使用等同的语法:

    from(SourceURI).to(FilterA).to(FilterB).to(TargetURI);

在使用 to() 命令语法时要谨慎,因为它 并不总是 等同于管道处理器。在 Java DSL 中,可以通过以上命令在路由中修改 to() 的含义。例如,当 multicast() 命令前面是 to() 命令,它会将列出的端点绑定到多播模式,而不是管道模式(请参阅 第 8.13 节 “多播”)。

5.5. Message Router

概述

图 5.7 “Message Router Pattern”显示的消息路由器 是根据特定决策条件消耗来自单一消费者端点的消息的过滤器类型。邮件路由器仅关注重定向消息,它不会修改消息内容。

但是,默认情况下,当 Camel 将消息交换路由到接收者端点时,它发送是原始交换对象的相对副本。在虚构副本中,原始交换的元素(如消息正文、标头和附件)仅由引用进行复制。通过发送能够复制资源,Camel 可以优化性能。但是,由于这些应该副本都是链接的,因此当 Camel 将消息路由到多个端点时,折衷是,您失去应用自定义逻辑来将自定义逻辑复制到路由到不同接收方的功能。有关如何启用 Camel 将唯一消息版本路由到不同端点的信息,请参阅 "应用自定义处理到传出消息"。

图 5.7. Message Router Pattern

Message router pattern

可以使用 choice() 处理器在 Apache Camel 中轻松实施消息路由器,其中每个替代目标端点都可以使用 when() 子clause(有关所选处理器的详细信息,请参阅 第 1.5 节 “处理器”)。

Java DSL 示例

以下 Java DSL 示例演示了如何根据 foo 标头的内容将消息路由到三个替代目的地( seda:aseda: b、seda:b ):

from("seda:a").choice()
    .when(header("foo").isEqualTo("bar")).to("seda:b")
    .when(header("foo").isEqualTo("cheese")).to("seda:c")
    .otherwise().to("seda:d");

XML 配置示例

以下示例演示了如何在 XML 中配置相同的路由:

<camelContext id="buildSimpleRouteWithChoice" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="seda:a"/>
    <choice>
      <when>
        <xpath>$foo = 'bar'</xpath>
        <to uri="seda:b"/>
      </when>
      <when>
        <xpath>$foo = 'cheese'</xpath>
        <to uri="seda:c"/>
      </when>
      <otherwise>
        <to uri="seda:d"/>
      </otherwise>
    </choice>
  </route>
</camelContext>

无其他选择

如果您使用没有 otherwise() 子句的 choice(),则默认丢弃任何不匹配的交换。

5.6. message Translator

概述

图 5.8 “Message Translator Pattern”显示的消息转换器 模式描述了一个修改信息内容的组件,将其转换为不同的格式。您可以使用 Apache Camel 的 Bean 集成功能来执行消息转换。

图 5.8. Message Translator Pattern

消息转换器模式

Bean 集成

您可以使用 bean 集成转换消息,允许您在任何注册的 Bean 上调用方法。例如,要在带有 ID 的 Bean、myTransformerBean 上调用方法 myMethodName()

from("activemq:SomeQueue")
  .beanRef("myTransformerBean", "myMethodName")
  .to("mqseries:AnotherQueue");

在 Spring XML 文件或 JNDI 中定义 myTransformer Bean。如果省略 beanRef() 中的 method name 参数,则 bean 集成将尝试推断方法名称通过检查消息交换来调用。

您还可以添加自己的显式处理器 实例 以执行转换,如下所示:

from("direct:start").process(new Processor() {
    public void process(Exchange exchange) {
        Message in = exchange.getIn();
        in.setBody(in.getBody(String.class) + " World!");
    }
}).to("mock:result");

或者,您可以使用 DSL 来显式配置转换,如下所示:

from("direct:start").setBody(body().append(" World!")).to("mock:result");

您还可以使用 模板 (template)来消耗来自一个目的地的消息,将其转换为 Velocity 或 XQuery 等内容,然后将其发送到另一个目的地。例如,使用 InOnly Exchange 模式(单向消息):

from("activemq:My.Queue").
  to("velocity:com/acme/MyResponse.vm").
  to("activemq:Another.Queue");

如果要使用 InOut (请求)语义来处理在 ActiveMQ 上的请求,使用模板生成的响应,那么您可以使用类似以下内容的路由来回 JMSReplyTo 目的地:

from("activemq:My.Queue").
  to("velocity:com/acme/MyResponse.vm");

5.7. 消息历史

概述

Message History 模式允许您在松散耦合系统中分析和调试消息流。如果您在消息中附加了消息历史记录,则会显示一条从其原始消息传递的所有应用程序的列表。

在 Apache Camel 中,使用 getTracedRouteNodes 方法,您可以使用 Tracer 跟踪消息流或使用 UnitOfWork 中的 Java API 访问信息。

限制日志中的字符长度

当您使用日志记录机制运行 Apache Camel 时,它可让您及时记录消息及其内容。

有些消息可能包含非常大的有效负载。默认情况下,Apache Camel 将关闭日志消息,并只显示前 1000 个字符。例如,它以以下方式显示以下日志:

[DEBUG ProducerCache  - >>>> Endpoint[direct:start] Exchange[Message: 01234567890123456789... [Body clipped after 20 characters, total length is 1000]

当 Apache Camel clips log 中的正文时,您可以自定义限制。您还可以设置零或负值,如 -1,表示消息正文没有被记录。

使用 Java DSL 自定义限制

您可以使用 Java DSL 在 Camel 属性中设置限制。例如,

 context.getProperties().put(Exchange.LOG_DEBUG_BODY_MAX_CHARS, "500");
使用 Spring DSL 自定义限制

您可以使用 Spring DSL 在 Camel 属性中设置限制。例如,

<camelContext>
    <properties>
        <property key="CamelLogDebugBodyMaxChars" value="500"/>
   </properties>
</camelContext>

第 6 章 消息传递频道

摘要

消息传递频道为消息传递应用程序提供 plumbing。本章论述了消息传递系统中可用的不同类型的消息通道,以及它们所扮演的角色。

6.1. 点到点频道

概述

图 6.1 “指向点频道模式” 中显示的 点对点频道 是保证只有一个接收器消耗任何给定信息的消息 频道。这与 发布与订阅频道 不同,后者允许多个接收方使用相同的消息。特别是,通过 publish-subscribe 频道,多个接收方可以订阅同一频道。如果多个接收器竞争使用一条消息,则最多可使用消息频道,以确保只有一个接收器实际消耗这个信息。

图 6.1. 指向点频道模式

指向指向频道模式

支持点到点频道的组件

以下 Apache Camel 组件支持点到点频道模式:

JMS

在 JMS 中,点到点频道由 队列 表示。例如,您可以为名为 Foo.Bar 的 JMS 队列指定端点 URI,如下所示:

jms:queue:Foo.Bar

限定符 queue: 是可选的,因为 JMS 组件默认创建一个队列端点。因此,您还可以指定以下等同的端点 URI:

jms:Foo.Bar

如需了解更多详细信息,请参阅 Apache Camel 组件参考指南中的 Jms

ActiveMQ

在 ActiveMQ 中,点到点频道由队列表示。例如,您可以为名为 Foo.Bar 的 ActiveMQ 队列指定端点 URI,如下所示:

activemq:queue:Foo.Bar

如需了解更多详细信息,请参阅 Apache Camel 组件参考指南 中的 ActiveMQ

SEDA

Apache Camel Staged 事件架构(SEDA)组件使用块队列实施。如果要创建一个 Apache Camel 应用程序 内部的 轻量级点到点频道,请使用 SEDA 组件。例如,您可以为名为 SedaQueue 的 SEDA 队列指定端点 URI,如下所示:

seda:SedaQueue

JPA

Java Persistence API(JPA)组件是一种 EJB 3 持久性标准,用于将实体 Bean 写入数据库。如需了解更多详细信息,请参阅 Apache Camel 组件参考指南 中的 JPA

XMPP

XMP(Jabber)组件支持点对点频道模式。如需了解更多详细信息,请参阅 Apache Camel 组件参考指南 中的 XMPP

6.2. publish-Subscribe Channel

概述

图 6.2 “发布 Subscribe Channel Pattern” 中显示的 发布订阅频道第 5.2 节 “Message Channel”,它允许多个订阅者消耗任何给定消息。这与 第 6.1 节 “点到点频道” 不同。发布订阅频道经常用作向多个订阅者广播事件或通知的方法。

图 6.2. 发布 Subscribe Channel Pattern

发布订阅频道模式

支持发布订阅频道的组件

以下 Apache Camel 组件支持发布订阅频道模式:

  • JMS
  • ActiveMQ
  • XMPP
  • 适用于同一 CamelContext 的使用 SEDA 的 SEDA,可以在 pub-sub 中工作,但允许多个消费者。
  • 请参阅 Apache Camel 组件参考指南 中的 VM 作为 SEDA,但可用于同一 JVM。

JMS

在 JMS 中,发布订阅频道由一个 主题 表示。例如,您可以为名为 StockQuotes 的 JMS 主题指定端点 URI,如下所示:

jms:topic:StockQuotes

如需了解更多详细信息,请参阅 Apache Camel 组件参考指南中的 Jms

ActiveMQ

在 ActiveMQ 中,发布订阅频道由一个主题表示。例如,您可以为名为 StockQuotes 的 ActiveMQ 主题指定端点 URI,如下所示:

activemq:topic:StockQuotes

如需了解更多详细信息,请参阅 Apache Camel 组件参考指南 中的 ActiveMQ

XMPP

XMPP(Jabber)组件在组通信模式中使用时支持 publish-subscribe channel 模式。如需了解更多详细信息,请参阅 Apache Camel 组件参考指南中的 Xmpp

静态订阅列表

如果您愿意,也可以在 Apache Camel 应用程序本身中实施发布订阅逻辑。简单方法是定义一个 静态订阅列表,其中目标端点均在路由末尾明确列出。但是,这种方法不如 JMS 或 ActiveMQ 主题。

Java DSL 示例

以下 Java DSL 示例演示了如何使用单个发布者、seda:a 和三个订阅者、seda:b、seda:c 和 seda:d 来模拟发布订阅频道:

from("seda:a").to("seda:b", "seda:c", "seda:d");
注意

这只适用于 InOnly 消息交换模式。

XML 配置示例

以下示例演示了如何在 XML 中配置相同的路由:

<camelContext id="buildStaticRecipientList" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="seda:a"/>
    <to uri="seda:b"/>
    <to uri="seda:c"/>
    <to uri="seda:d"/>
  </route>
</camelContext>

6.3. 死信频道

概述

死信频道 模式(如 图 6.3 “死的频道模式” 所示)描述了当消息系统无法向预期收件人发送邮件时要执行的操作。这包括重试交付等功能,如果交付最终失败,则向死信频道发送消息,以存档未发送的消息。

图 6.3. 死的频道模式

死信频道模式

在 Java DSL 中创建死信频道

以下示例演示了如何使用 Java DSL 创建死信频道:

errorHandler(deadLetterChannel("seda:errors"));
from("seda:a").to("seda:b");

其中 errorHandler() 方法是一个 Java DSL 拦截器,这意味着当前路由构建器中定义的所有路由都受到此设置的影响。deadLetterChannel() 方法是一个 Java DSL 命令,它使用指定的目标端点 seda:errors 创建新的死信频道。

errorHandler() 拦截器提供了一种 catch- all 机制,用于处理所有错误类型。如果要应用更精细的方法来例外处理,您可以使用 onException 子句(请参阅 “onException 子句”一节)。

XML DSL 示例

您可以在 XML DSL 中定义死信频道,如下所示:

 <route errorHandlerRef="myDeadLetterErrorHandler">
    ...
 </route>

 <bean id="myDeadLetterErrorHandler" class="org.apache.camel.builder.DeadLetterChannelBuilder">
     <property name="deadLetterUri" value="jms:queue:dead"/>
     <property name="redeliveryPolicy" ref="myRedeliveryPolicyConfig"/>
 </bean>

 <bean id="myRedeliveryPolicyConfig" class="org.apache.camel.processor.RedeliveryPolicy">
     <property name="maximumRedeliveries" value="3"/>
     <property name="redeliveryDelay" value="5000"/>
 </bean>

重新传送策略

通常,如果发送尝试失败,您不会直接向 dead letter 频道发送邮件。相反,您会重新尝试交付到一些最大限制,且在所有重新发送尝试失败时,您会将消息发送到 dead letter 频道。要自定义消息重新传送,您可以将死信频道配置为具有 重新传送策略。例如,要指定最多两个重新传送尝试,并在交付尝试之间应用 exponential backoff 算法到时间延迟,您可以配置死信频道,如下所示:

errorHandler(deadLetterChannel("seda:errors").maximumRedeliveries(2).useExponentialBackOff());
from("seda:a").to("seda:b");

您可以通过调用链中的相关方法在 dead letter 频道上设置重新传送选项(链中每个方法都将引用当前 RedeliveryPolicy 对象)。表 6.1 “重新传送策略设置” 总结了可用于设置重新传送策略的方法。

表 6.1. 重新传送策略设置

方法签名默认描述

allowRedeliveryWhileStopping()

true

控制在安全关闭期间或路由停止期间是否尝试重新发送。在启动停止时,已经进行的交付不会中断。

BackOffMultiplier(倍数)

2

如果启用了 exponential backoff,让 m 设置为 backoff 数,并让 d 为初始延迟。然后重新发送尝试的顺序如下:

d, m*d, m*m*d, m*m*m*d, ...

collisionAvoidancePercent(double collisionAvoidancePercent)

15

如果启用了冲突,请 冲突避免了百分比。冲突策略随后调整下一个延迟,最大为当前值的加号/减去 p%

deadLetterHandleNewException

true

Camel 2.15:指定是否在死信频道中处理消息时是否处理异常。如果为 true,则会处理异常并记录在 WARN 级别(因此保证死信频道完成)。如果为 false,则异常不会处理,因此死信频道失败,并传播新的异常。

delayPattern(String delayPattern)

Apache Camel 2.0:请参阅 “redeliver delay pattern”一节

disableRedelivery()

true

Apache Camel 2.0:禁用重新传送功能。要启用重新传送,将 maximumRedeliveries() 设置为正整数值。

handled(布尔值已处理)

true

Apache Camel 2.0:如果为 true,则当消息移动到 dead letter 频道时清除当前异常;如果为 false,则异常将传回给客户端。

initialRedeliveryDelay(long initialRedeliveryDelay)

1000

指定在尝试第一个重新发送前的延迟(以毫秒为单位)。

logNewException

true

指定是否在 WARN 级别登录,当在死信频道引发异常时。

logStackTrace(boolean logStackTrace)

false

Apache Camel 2.0:如果为 true,则 JVM 堆栈追踪包含在错误日志中。

maximumRedeliveries(int maximumRedeliveries)

0

Apache Camel 2.0:最大交付尝试次数.

maximumRedeliveryDelay(long maxDelay)

60000

Apache Camel 2.0:当使用指数级 backoff 策略时(请参阅 useExponentialBackOff())时,重建延迟可能会在不限制的情况下增加。此属性对重新发送延迟(以毫秒为单位)实施上限。

onRedelivery(处理器)

Apache Camel 2.0:配置在每次重新发送尝试之前调用的处理器。

redeliveryDelay(long int)

0

Apache Camel 2.0:指定重新传送尝试之间的延时(以毫秒为单位)。Apache Camel 2.16.0 : 默认重新传送延迟为一秒钟。

retriesExhaustedLogLevel(LoggingLevel logLevel)

LoggingLevel.ERROR

Apache Camel 2.0:指定日志记录级别,在其中记录发送失败(指定为 org.apache.camel.LoggingLevel constant)。

retryAttemptedLogLevel(LoggingLevel logLevel)

LoggingLevel.DEBUG

Apache Camel 2.0:指定日志记录级别,在其中重新发送尝试(指定为 org.apache.camel.LoggingLevel constant)。

useCollisionAvoidance()

false

启用冲突可避免,这会在 backoff 计时中添加一些随机性,以减少竞争概率。

useOriginalMessage()

false

Apache Camel 2.0:如果启用了此功能,则发送到 dead letter 频道的消息是 原始消息 交换的副本,因为它存在于路由的开头(在 from() 节点上)。

useExponentialBackOff()

false

启用 exponential backoff。

重新传送标头

如果 Apache Camel 尝试重新发送一条信息,它会在 In 消息中自动设置 表 6.2 “死 Letter Redelivery Headers” 中描述的标头。

表 6.2. 死 Letter Redelivery Headers

标头名称类型描述

CamelRedeliveryCounter

整数

Apache Camel 2.0:计数发送尝试失败的次数。Exchange.REDELIVERY_COUNTER 中也设置了这个值。

CamelRedelivered

布尔值

Apache Camel 2.0: True(如果进行了一个或多个重新发送尝试)。此值在 Exchange.REDELIVERED 中设定。

CamelRedeliveryMaxCounter

整数

Apache Camel 2.6:包含最大重新传送设置(也在 Exchange.REDELIVERY_MAX_COUNTER 交换属性中设置)。如果使用 retryWhile,或者配置了无限重新传送,则缺少此标头。

重新传送交换属性

如果 Apache Camel 尝试恢复信息,它会自动设置 表 6.3 “重新传送交换属性” 中描述的交换属性。

表 6.3. 重新传送交换属性

Exchange Property Name类型描述

Exchange.FAILURE_ROUTE_ID

字符串

提供失败的路由 ID。这个属性的字面名称是 CamelFailureRouteId

使用原始消息

自 Apache Camel 2.0 起,由于交换对象通过路由,因此交换对象会被修改,所以当引发异常时,这个交换不一定要存储在死信频道中的副本。在许多情况下,最好在路由开始时记录到达路由的消息,然后再记录路由受到任何转换的转换。例如,请考虑以下路由:

from("jms:queue:order:input")
       .to("bean:validateOrder");
       .to("bean:transformOrder")
       .to("bean:handleOrder");

前面的路由会侦听传入的 JMS 消息,然后使用 Beans 序列处理消息: validateOrdertransformOrderhandleOrder。但是,当发生错误时,我们不知道该消息所处的状态。转换 操作程序或之后是否发生错误?我们可以通过启用 useOriginalMessage 选项来确保来自 jms:queue:order:input 的原始消息记录到 dead letter 频道:

// will use original body
errorHandler(deadLetterChannel("jms:queue:dead")
       .useOriginalMessage().maximumRedeliveries(5).redeliveryDelay(5000);

redeliver delay pattern

可作为 Apache Camel 2.0 使用 delayPattern 选项为重新传送计数的特定范围指定延迟。delay 模式具有以下语法: limit1:delay1;limit2:delay2;limit3:delay3;…​ ,其中每个 delayN 应用到红色的 delayN PERC redeliveryCount < limitN+1

例如,假设模式为 5:1000;10:5000;20:20000,它定义了三个组,并导致以下重新发送延迟:

  • 尝试编号 1.4 = 0 毫秒(作为第一个组以 5 开始)。
  • 尝试编号 5..9 = 1000 毫秒(第一个组)。
  • 尝试编号 10.19 = 5000 毫秒(第二个组)。
  • 尝试编号 20.. = 20000 毫秒(最后一个组)。

您可以启动具有限制 1 的组来定义启动延迟。例如,1:1000;5:5000 会产生以下重新传送延迟:

  • 尝试编号 1.4 = 1000 millis(第一个组)
  • 尝试编号 5.. = 5000 millis(最后一个组)

不要求下一个延迟应高于上述延迟,您可以使用您喜欢的任何延迟值。例如,延迟模式 1:5000;3:1000,以 5 秒延迟开头,然后将延迟减少到 1 秒。

哪一端点失败?

当 Apache Camel 路由消息时,它会更新包含 Exchange 发送到 的最后一个 端点的 Exchange 属性。因此,您可以使用以下代码获取当前交换最新目的地的 URI:

// Java
String lastEndpointUri = exchange.getProperty(Exchange.TO_ENDPOINT, String.class);

这里的 Exchange.TO_ENDPOINT 是一个等于 CamelToEndpoint 的字符串。当 Camel 发送消息 到任何 端点时,都会更新此属性。

如果在路由过程中发生错误,并且交换被移到死信队列中,Apache Camel 将额外设置名为 CamelFailureEndpoint 的属性,该属性标识在发生错误之前交换的最后一个目的地。因此,您可以使用以下代码从死信队列中访问失败端点:

// Java
String failedEndpointUri = exchange.getProperty(Exchange.FAILURE_ENDPOINT, String.class);

这里的 Exchange.FAILURE_ENDPOINT 是一个字符串常量,相当于 CamelFailureEndpoint

注意

这些属性保留在当前交换中设置的,即使给定目标端点完成处理后失败也是如此。例如,请考虑以下路由:

        from("activemq:queue:foo")
        .to("http://someserver/somepath")
        .beanRef("foo");

现在假定 foo an 中出现失败。在这种情况下,Exchange.TO_ENDPOINT 属性和 Exchange.FAILURE_ENDPOINT 属性仍包含该值。

onRedelivery 处理器

当死信频道执行红色时,可以在每次重新发送尝试 配置只执行的处理器。这可用于您需要在消息被红色前修改消息的情况。

例如,以下死信频道被配置为在红色发生交换前调用 MyRedeliverProcessor

// we configure our Dead Letter Channel to invoke
// MyRedeliveryProcessor before a redelivery is
// attempted. This allows us to alter the message before
errorHandler(deadLetterChannel("mock:error").maximumRedeliveries(5)
        .onRedelivery(new MyRedeliverProcessor())
        // setting delay to zero is just to make unit teting faster
        .redeliveryDelay(0L));

MyRedeliveryProcessor 进程在其中实现,如下所示:

// This is our processor that is executed before every redelivery attempt
// here we can do what we want in the java code, such as altering the message
public class MyRedeliverProcessor implements Processor {

    public void process(Exchange exchange) throws Exception {
        // the message is being redelivered so we can alter it

        // we just append the redelivery counter to the body
        // you can of course do all kind of stuff instead
        String body = exchange.getIn().getBody(String.class);
        int count = exchange.getIn().getHeader(Exchange.REDELIVERY_COUNTER, Integer.class);

        exchange.getIn().setBody(body + count);

        // the maximum redelivery was set to 5
        int max = exchange.getIn().getHeader(Exchange.REDELIVERY_MAX_COUNTER, Integer.class);
        assertEquals(5, max);
    }
}

在关闭或停止过程中控制重新发送

如果您停止路由或启动安全关闭,则错误处理程序的默认行为将继续尝试重新发送。因为这通常不是所需的行为,所以可以选择通过在关闭或停止期间禁用重新传送,方法是将 allowRedeliveryWhileStopping 选项设置为 false,如下例所示:

errorHandler(deadLetterChannel("jms:queue:dead")
    .allowRedeliveryWhileStopping(false)
    .maximumRedeliveries(20)
    .redeliveryDelay(1000)
    .retryAttemptedLogLevel(LoggingLevel.INFO));
注意

出于向后兼容的原因,allowRedeliveryWhileStopping 选项默认为 true。但是,在主动关闭过程中,重新传送始终会被隐藏,这与这个选项设置无关(例如,安全关闭超时)。

使用ExceptionOccurred Processor

死 Letter 通道支持 onExceptionOccurred 处理器,允许在发生异常后对消息进行自定义处理。您还可以将其用于自定义日志记录。从 onExceptionOccurred 处理器中引发的新异常都会记录为 WARN 并忽略,而不是覆盖现有异常。

onRedelivery 处理器和在ExceptionOccurred processor 之间的区别在于,您可以在重新发送尝试前完全处理前一个。但是,在发生异常后不会立即发生。例如,如果您将错误处理程序配置为在重新传送尝试之间执行 5 秒的延迟,则稍后在出现异常后调用重新发送处理器。

以下示例说明了如何在出现异常时执行自定义日志记录。您需要配置 onExceptionOccurred 以使用自定义处理器。

errorHandler(defaultErrorHandler().maximumRedeliveries(3).redeliveryDelay(5000).onExceptionOccurred(myProcessor));

onException 子句

您无需在路由构建器中使用 errorHandler() 拦截器,您可以定义一系列 onException() 子句,以定义不同的重新传送策略,以及为各种异常类型定义不同的死信频道。例如,若要为每个 NullPointerExceptionIOExceptionException 类型定义不同的行为,您可以使用 Java DSL 在路由构建器中定义以下规则:

onException(NullPointerException.class)
    .maximumRedeliveries(1)
    .setHeader("messageInfo", "Oh dear! An NPE.")
    .to("mock:npe_error");

onException(IOException.class)
    .initialRedeliveryDelay(5000L)
    .maximumRedeliveries(3)
    .backOffMultiplier(1.0)
    .useExponentialBackOff()
    .setHeader("messageInfo", "Oh dear! Some kind of I/O exception.")
    .to("mock:io_error");

onException(Exception.class)
    .initialRedeliveryDelay(1000L)
    .maximumRedeliveries(2)
    .setHeader("messageInfo", "Oh dear! An exception.")
    .to("mock:error");

from("seda:a").to("seda:b");

如果通过串联重新传送策略方法来指定重新传送选项(如 表 6.1 “重新传送策略设置”中列出的),再使用 to() DSL 命令指定 dead letter 频道的端点。您也可以在 Exception() 子句中调用其他 Java DSL 命令。例如,前面的示例调用 setHeader() 在名为 messageInfo 的消息标头中记录一些错误详情。

在本例中,NullPointerExceptionIOException 异常类型是特别配置的。所有其他例外类型由通用 Exception 异常拦截器进行处理。默认情况下,Apache Camel 应用最符合所引发异常异常的异常拦截器。如果无法找到完全匹配,它将尝试匹配最接近的基本类型,以此类推。最后,如果没有其他拦截器匹配,则 Exception 类型的拦截器与所有剩余的例外匹配。

OnPrepareFailure

在将交换传递给死信队列之前,您可以使用 onPrepare 选项来允许一个自定义处理器准备交换。它可让您添加有关交换的信息,如交换失败的原因。例如,以下处理器添加带有异常消息的标头。

public class MyPrepareProcessor implements Processor {
    @Override
    public void process(Exchange exchange) throws Exception {
        Exception cause = exchange.getProperty(Exchange.EXCEPTION_CAUGHT, Exception.class);
        exchange.getIn().setHeader("FailedBecause", cause.getMessage());
    }
}

您可以将错误处理程序配置为使用处理器,如下所示:

errorHandler(deadLetterChannel("jms:dead").onPrepareFailure(new MyPrepareProcessor()));

但是,Prepare 选项也可以使用默认错误处理程序来使用。

<bean id="myPrepare"
class="org.apache.camel.processor.DeadLetterChannelOnPrepareTest.MyPrepareProcessor"/>

<errorHandler id="dlc" type="DeadLetterChannel" deadLetterUri="jms:dead" onPrepareFailureRef="myPrepare"/>

6.4. 保证交付

概述

保证交付 意味着,当消息被放入消息频道后,消息系统会保证该消息将到达其目的地,即使应用程序的一部分也失败。通常,消息传递系统实施保证交付模式(如 图 6.4 “保证交付模式” ),在尝试将它们发送到目的地前,先向持久性存储写入信息。

图 6.4. 保证交付模式

保证交付模式

支持保证交付的组件

以下 Apache Camel 组件支持保证交付模式:

JMS

在 JMS 中,deliveryPersistent 查询选项指示是否启用了消息的持久性存储。通常,设置这个选项是不需要的,因为默认行为是启用持续交付。要配置保证交付的所有详情,需要在 JMS 提供程序上设置配置选项。这些详情会根据您使用的 JMS 供应商的不同而有所不同。例如, MQSeries、TibCo、BEA、Sunic 等,它们都提供各种服务质量来支持保证交付。

如需了解更多详细信息,请参阅 Apache Camel 组件参考指南 &gt; 中的 Jms

ActiveMQ

在 ActiveMQ 中,消息持久性默认为启用。从版本 5 开始,ActiveMQ 使用 AMQ 消息存储作为默认的持久性机制。您可以使用几种不同方法在 ActiveMQ 中放入消息持久性。

最简单的选项(与 图 6.4 “保证交付模式”不同)是在中央代理中启用持久性,然后使用可靠的协议连接到该代理。将消息发送到中央代理后,可以保证传递给消费者。例如,在 Apache Camel 配置文件 META-INF/spring/camel-context.xml 中,您可以配置 ActiveMQ 组件以使用 OpenWire/TCP 协议连接到中央代理,如下所示:

<beans ... >
  ...
  <bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent">
    <property name="brokerURL" value="tcp://somehost:61616"/>
  </bean>
  ...
</beans>

如果您希望实施在发送到远程端点前本地存储的信息的构架(类似于 图 6.4 “保证交付模式”),请通过在 Apache Camel 应用程序中实例化嵌入式代理来执行此操作。实现这一点的一个简单方法是使用 ActiveMQ Peer-to-Peer 协议,可隐式创建嵌入式代理来与其他对等端点通信。例如,在 camel-context.xml 配置文件中,您可以将 ActiveMQ 组件配置为连接到组 GroupA 中的所有 peer,如下所示:

<beans ... >
  ...
  <bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent">
    <property name="brokerURL" value="peer://GroupA/broker1"/>
  </bean>
  ...
</beans>

其中 broker1 是嵌入的代理的代理名称(组中的其他对等点应使用不同的代理名称)。Peer-to-Peer 协议的一个限制功能是它依赖于 IP 多播来在其组中定位其他对等点。这使得用于广泛的区域网络(在一些没有启用 IP 多播的本地网络中)的使用变得不重要。

在 ActiveMQ 组件中创建嵌入式代理的更灵活方法是利用 ActiveMQ 的 VM 协议,它连接到嵌入式代理实例。如果所需名称的代理不存在,VM 协议会自动创建。您可以使用此机制创建带有自定义配置的嵌入式代理。例如:

<beans ... >
  ...
  <bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent">
    <property name="brokerURL" value="vm://broker1?brokerConfig=xbean:activemq.xml"/>
  </bean>
  ...
</beans>

其中 activemq.xml 是一个 ActiveMQ 文件,用于配置嵌入的代理实例。在 ActiveMQ 配置文件中,您可以选择启用以下持久性机制之一:

如需了解更多详细信息,请参阅 Apache Camel 组件参考指南 中的 ActiveMQ

ActiveMQ Journal

ActiveMQ Journal 组件针对特殊的用例进行了优化,其中多个并发制作者将消息写入队列,但只有一个活跃的使用者。消息存储在滚动日志文件中,并并发写入聚合在一起,以提高效率。

6.5. 消息总线

概述

消息总线 指的是 图 6.5 “消息总线模式” 中显示的消息传递架构,可让您连接在不同计算平台中运行的不同应用程序。实际上,Apache Camel 及其组件构成了消息总线。

图 6.5. 消息总线模式

消息总线模式

消息总线模式的以下功能反映在 Apache Camel 中:

  • 通用通信基础架构 10.10.10.2- the 路由器本身提供 Apache Camel 中常见通信基础架构的核心。但是,与一些消息总线架构不同,Apache Camel 提供了一个异构基础架构:消息可以使用各种不同传输方式发送到总线,并使用各种不同消息格式。
  • Apache Camel 可以转换消息格式并使用不同传输来传播信息。实际上,Apache Camel 能够像适配器一样工作,以便外部应用程序可以 hook 到消息总线中,而不必重构它们的消息传递协议。

    在某些情况下,也可以将适配器直接集成到外部应用程序中。例如,如果您使用 Apache CXF 开发应用,该服务使用 JAX-WS 和 JAXB 映射来实施,则可以将各种不同传输绑定到该服务。这些传输绑定功能作为适配器。

第 7 章 消息构建

摘要

消息构建模式描述了通过系统传递的消息的各种形式和功能。

7.1. 关联标识符

概述

图 7.1 “关联标识符模式” 所示的 关联标识符 模式描述了如何匹配带有请求消息的回复信息,因为使用了异步消息系统来实施请求备份协议。这种理念的本质在于,请求消息应当通过唯一令牌生成,请求 ID,用于标识请求消息并回复消息应包含令牌、关联 ID(包含匹配请求 ID )的关联 ID。

Apache Camel 通过获取或设置消息上的标头,支持来自 EIP 模式的识别标识符。

在使用 ActiveMQ 或 JMS 组件时,关联标识符标识符标头被称为 JMSCorrelationID。您可以在任何消息交换中添加您自己的关联标识符,以帮助将消息与单一对话(或业务流程)相关联。关联标识符通常存储在 Apache Camel 消息标头中。

有些 EIP 模式会加快子消息,在这种情况下,Apache Camel 会在 Exchanges 中添加一个关联 ID,作为其键为 Exchange.CORRELATION_ID 的属性,该模式将链接回源 Exchanges。例如,分割器多播接收者列表线 tap EIP 执行此操作。

图 7.1. 关联标识符模式

关联识别符模式

7.2. 事件消息

事件消息

Camel 支持 企业集成模式 中的事件 消息,方法是支持 Exchange Pattern on a message,该消息可设为 InOnly 以指示单向事件信息。然后,Camel Apache Camel 组件参考 使用底层传输或协议实施此模式。

事件消息解决方案

许多 Apache Camel 组件参考 的默认行为只是用于 JMS、file 或 SEDA等。https://access.redhat.com/documentation/en-us/red_hat_fuse/7.11/html-single/apache_camel_component_reference/index#file-component

明确指定 InOnly

如果您使用默认为 InOut 的组件,您可以使用 pattern 属性覆盖端点 的消息交换 模式。

foo:bar?exchangePattern=InOnly

从 Camel 上的 2.0 开始,您可以使用 DSL 指定 消息交换模式

使用 Fluent Builders

from("mq:someQueue").
  inOnly().
  bean(Foo.class);

或者,您可以使用显式模式调用端点

from("mq:someQueue").
  inOnly("mq:anotherQueue");

使用 Spring XML 扩展

<route>
    <from uri="mq:someQueue"/>
    <inOnly uri="bean:foo"/>
</route>
<route>
    <from uri="mq:someQueue"/>
    <inOnly uri="mq:anotherQueue"/>
</route>

7.3. 返回地址

返回地址

Apache Camel 支持使用 JMSReplyTo 标头从 Enterprise Integration Patterns 中的 返回地址

return address solution

例如,在将 JMSInOut 搭配使用时,组件默认返回到 JMSReplyTo 中给出的地址。

示例

请求者代码

 getMockEndpoint("mock:bar").expectedBodiesReceived("Bye World");
 template.sendBodyAndHeader("direct:start", "World", "JMSReplyTo", "queue:bar");

使用 Fluent Builder 的路由

 from("direct:start").to("activemq:queue:foo?preserveMessageQos=true");
 from("activemq:queue:foo").transform(body().prepend("Bye "));
 from("activemq:queue:bar?disableReplyTo=true").to("mock:bar");

使用 Spring XML 扩展的路由

 <route>
   <from uri="direct:start"/>
   <to uri="activemq:queue:foo?preserveMessageQos=true"/>
 </route>

 <route>
   <from uri="activemq:queue:foo"/>
   <transform>
       <simple>Bye ${in.body}</simple>
   </transform>
 </route>

 <route>
   <from uri="activemq:queue:bar?disableReplyTo=true"/>
   <to uri="mock:bar"/>
 </route>

有关此模式的完整示例,请参阅此 JUnit 测试案例

第 8 章 消息路由

摘要

消息路由模式描述了将消息通道链接到一起的各种方法。这包括可应用于消息流的各种算法(无需修改消息的正文)。

8.1. 基于内容的路由器

概述

一个 基于内容的路由器 (在 图 8.1 “基于内容的路由器模式” 中)可让您根据消息内容将信息路由到适当的目的地。

图 8.1. 基于内容的路由器模式

基于内容的路由器模式

Java DSL 示例

以下示例演示了如何根据各种 predicate 表达式评估从输入、seda:a、端点路由到 seda:bqueue:cseda:d 的请求:

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        from("seda:a").choice()
          .when(header("foo").isEqualTo("bar")).to("seda:b")
          .when(header("foo").isEqualTo("cheese")).to("seda:c")
          .otherwise().to("seda:d");
    }
};

XML 配置示例

以下示例演示了如何在 XML 中配置相同的路由:

<camelContext id="buildSimpleRouteWithChoice" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="seda:a"/>
    <choice>
      <when>
        <xpath>$foo = 'bar'</xpath>
        <to uri="seda:b"/>
      </when>
      <when>
        <xpath>$foo = 'cheese'</xpath>
        <to uri="seda:c"/>
      </when>
      <otherwise>
        <to uri="seda:d"/>
      </otherwise>
    </choice>
  </route>
</camelContext>

8.2. Message Filter

概述

消息过滤器 是一个处理器,用于根据特定标准消除不需要的消息。在 Apache Camel 中,消息过滤器特征(如 图 8.2 “消息过滤器模式” )通过 filter() Java DSL 命令实现。filter() 命令使用一个控制过滤器的 predicate 参数。当 predicate 为 true 时,允许传入的信息继续,如果 predicate 为 false,则会阻断传入的信息。

图 8.2. 消息过滤器模式

消息过滤器特征

Java DSL 示例

以下示例演示了如何从端点( seda:a )创建路由到端点, seda:b,它将阻断除 foo 标头具有值、bar 的消息之外的所有消息:

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        from("seda:a").filter(header("foo").isEqualTo("bar")).to("seda:b");
    }
};

要评估更复杂的过滤器 predicates,您可以调用其中一个受支持的脚本语言,如 XPath、XQuery 或 SQL(请参阅 第 II 部分 “路由表达式和指定语言”)。以下示例定义了一个路由,它阻止所有包含 name 属性等于 James 的个人元素外的所有消息:

from("direct:start").
        filter().xpath("/person[@name='James']").
        to("mock:result");

XML 配置示例

以下示例演示了如何使用 XML 中的 XPath predicate 配置路由(请参阅 第 II 部分 “路由表达式和指定语言”):

<camelContext id="simpleFilterRoute" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="seda:a"/>
    <filter>
      <xpath>$foo = 'bar'</xpath>
      <to uri="seda:b"/>
    </filter>
  </route>
  </camelContext>
过滤 </filter> 标签中所需的端点

在关闭 </filter> 标签前,确保您将要过滤的端点(例如,&lt ;to uri="seda:b"/>),或者过滤器不会被应用(在 2.8+ 中,省略此操作会导致错误)。

使用 Bean 过滤

以下是使用 bean 定义过滤器行为的示例:

from("direct:start")
     .filter().method(MyBean.class, "isGoldCustomer").to("mock:result").end()
     .to("mock:end");

public static class MyBean {
    public boolean isGoldCustomer(@Header("level") String level) {
        return level.equals("gold");
    }
}

使用 stop()

可作为 Camel 2.0 提供

stop 是过滤 所有消息的 特殊过滤器。当您需要在其中一个 predicates 中停止进一步处理时,停止便可在 基于内容的路由器 中使用。

在以下示例中,我们不需要在邮件正文中传递单词的消息,以便在路由中进一步传播信息。我们防止在 when() predicate 中使用 .stop()

from("direct:start")
    .choice()
        .when(bodyAs(String.class).contains("Hello")).to("mock:hello")
        .when(bodyAs(String.class).contains("Bye")).to("mock:bye").stop()
        .otherwise().to("mock:other")
    .end()
    .to("mock:result");

了解是否过滤 Exchange

可作为 Camel 2.5 提供。

消息过滤器 EIP 将添加 Exchange 的属性,该属性将说明(如果已过滤或未过滤)。

该属性具有关键 Exchange.FILTER_MATCHED,其字符串值为 CamelFilterMatched。其值是一个布尔值,代表 truefalse。如果值为 true,则在 filter 块中路由 Exchange。

8.3. 接收者列表

概述

一个 接收者列表 (在 图 8.3 “接收者列表模式” 中显示的是路由器类型),将每个传入的信息发送到多个不同的目的地。此外,接收者列表通常要求在运行时计算接收者列表。

图 8.3. 接收者列表模式

接收者列表特征

带有固定目的地的接收者列表

最简单的接收者列表是预先固定并已知的目的地列表,而交换模式是 Only。在这种情况下,您可以硬编码到 to() Java DSL 命令中的目的地列表。

注意

此处提供的示例,对于具有固定目的地的接收者列表,仅适用于 InOnly Exchange 模式(类似于 管道和过滤器模式)。如果要创建用于使用 Out 消息交换模式的接收者列表,请使用 多播 模式。

Java DSL 示例

以下示例演示了如何将来自消费者端点 queue:aInOnly exchange 路由到固定目的地列表:

from("seda:a").to("seda:b", "seda:c", "seda:d");

XML 配置示例

以下示例演示了如何在 XML 中配置相同的路由:

<camelContext id="buildStaticRecipientList" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="seda:a"/>
    <to uri="seda:b"/>
    <to uri="seda:c"/>
    <to uri="seda:d"/>
  </route>
</camelContext>

运行时计算的接收者列表

在大多数情况下,当您使用接收者列表模式时,应在运行时计算接收者列表。为此,可使用 recipientList() 处理器,它将目的地列表视为其唯一参数。由于 Apache Camel 将类型转换器应用到列表参数,因此应该使用大多数标准 Java 列表类型(如集合、列表或数组)。有关类型转换器的详情,请参考 第 34.3 节 “内置(In Type Converters)”

接收者收到 同一 交换实例的副本,而 Apache Camel 会按顺序执行它们。

Java DSL 示例

以下示例演示了如何从名为 recipientListHeader 的消息标头提取目的地列表,其中标头值是以逗号分隔的端点 URI 列表:

from("direct:a").recipientList(header("recipientListHeader").tokenize(","));

在某些情况下,如果标头值是一个列表类型,您可以将其直接用作 接收者List() 的参数。例如:

from("seda:a").recipientList(header("recipientListHeader"));

但是,这个示例完全依赖于底层组件如何解析这个特定标头。如果组件将标头解析为简单字符串,则该示例 将无法工作。标头必须解析到某种类型的 Java 列表。

XML 配置示例

以下示例演示了如何在 XML 中配置前面的路由,其中标头值是一个用逗号分开的端点 URI 列表:

<camelContext id="buildDynamicRecipientList" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="seda:a"/>
    <recipientList delimiter=",">
      <header>recipientListHeader</header>
    </recipientList>
  </route>
</camelContext>

并行发送到多个接收者

可作为 Camel 2.2 提供

接收者列表模式 支持 parallelProcessing,这与 splitter 模式中的相应功能类似。使用并行处理功能将交换发送到多个接收方,同时为 example.

from("direct:a").recipientList(header("myHeader")).parallelProcessing();

在 Spring XML 中,并行处理功能作为 接收者List tag>_<-abrtfor 示例上的属性实现:

<route>
  <from uri="direct:a"/>
  <recipientList parallelProcessing="true">
    <header>myHeader</header>
  </recipientList>
</route>

异常停止

可作为 Camel 2.2 提供

接收者列表 支持 stopOnException 功能,如果任何接收者失败,您可以使用它停止发送到任何进一步的接收者。

from("direct:a").recipientList(header("myHeader")).stopOnException();

以及在 Spring XML 中,其接收者列表标签上的属性。

在 Spring XML 中,异常功能的停止是作为 接收者List tag>_<-abrtfor 示例的属性实现:

<route>
  <from uri="direct:a"/>
  <recipientList stopOnException="true">
    <header>myHeader</header>
  </recipientList>
</route>
注意

您可以在同一 路由中组合并行处理 和停止OnException

忽略无效的端点

从 Camel 2.3 开始可用

接收者列表模式 支持 ignoreInvalidEndpoints 选项,它允许接收者列表跳过无效的端点(路由 slips 模式 也支持此选项)。例如:

from("direct:a").recipientList(header("myHeader")).ignoreInvalidEndpoints();

在 Spring XML 中,您可以通过在 recipientList 标签上设置 ignoreInvalidEndpoints 属性来启用这个选项,如下所示

<route>
  <from uri="direct:a"/>
  <recipientList ignoreInvalidEndpoints="true">
    <header>myHeader</header>
  </recipientList>
</route>

请考虑 myHeader 包含两个端点的情况,direct:foo,xxx:bar。第一个端点有效且可以正常工作。第二个是无效,因此忽略。当遇到无效的端点时,Apache Camel 都会在 INFO 级别记录。

使用自定义 AggregationStrategy

可作为 Camel 2.2 提供

您可以使用带有 接收者列表模式 的自定义 AggregationStrategy,这对于从列表中接收方发出回复很有用。默认情况下,Apache Camel 使用 UseLatestAggregationStrategy 聚合策略,以仅保留上次收到的回复。对于更复杂的聚合策略,您可以自行定义 AggregationStrategy 接口的实施。有关详细信息,请参阅 第 8.5 节 “聚合器”。例如,若要将自定义聚合策略 MyOwnAggregationStrategy 应用到答复消息,您可以按照如下所示定义 Java DSL 路由:

from("direct:a")
    .recipientList(header("myHeader")).aggregationStrategy(new MyOwnAggregationStrategy())
    .to("direct:b");

在 Spring XML 中,您可以将自定义聚合策略指定为 接收者List 标签的属性,如下所示:

<route>
  <from uri="direct:a"/>
  <recipientList strategyRef="myStrategy">
    <header>myHeader</header>
  </recipientList>
  <to uri="direct:b"/>
</route>

<bean id="myStrategy" class="com.mycompany.MyOwnAggregationStrategy"/>

使用自定义线程池

可作为 Camel 2.2 提供

这只在使用 并行处理时才需要。默认情况下,Camel 使用有 10 个线程的线程池。请注意,在我们稍后进行线程管理和配置时(在 Camel 2.2 中可能发生)时,这可能会改变。

您像使用自定义聚合策略一样配置它。

使用方法调用作为接收者列表

您可以使用 bean 集成来提供接收者,例如:

from("activemq:queue:test").recipientList().method(MessageRouter.class, "routeTo");

其中,MessageRouter bean 的定义如下:

public class MessageRouter {

    public String routeTo() {
        String queueName = "activemq:queue:test2";
        return queueName;
    }
}

bean 作为接收者列表

您可以通过将 @RecipientList 注解添加到返回接收者列表的方法,使 bean 的行为作为接收者列表。例如:

public class MessageRouter {

    @RecipientList
    public String routeTo() {
        String queueList = "activemq:queue:test1,activemq:queue:test2";
        return queueList;
    }
}

在这种情况下,不要在 路由中包含 recipientList DSL 命令。定义路由,如下所示:

from("activemq:queue:test").bean(MessageRouter.class, "routeTo");

使用超时

可作为 Camel 2.5 提供。

如果使用 并行处理,则可以以毫秒为单位配置总 超时值。然后,Camel 将并行处理消息,直到超时达到为止。这可让您在一条信息较慢时继续处理。

在以下示例中,recipientlist 标头的值为 direct: a、direct:b、direct:c,因此该邮件会发送到三个接收方。我们有 250毫秒的超时,这意味着在时间段内只有最后两条消息即可完成。因此,聚合会产生字符串结果 BC

from("direct:start")
    .recipientList(header("recipients"), ",")
    .aggregationStrategy(new AggregationStrategy() {
            public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {
                if (oldExchange == null) {
                    return newExchange;
                }

                String body = oldExchange.getIn().getBody(String.class);
                oldExchange.getIn().setBody(body + newExchange.getIn().getBody(String.class));
                return oldExchange;
            }
        })
        .parallelProcessing().timeout(250)
    // use end to indicate end of recipientList clause
    .end()
    .to("mock:result");

from("direct:a").delay(500).to("mock:A").setBody(constant("A"));

from("direct:b").to("mock:B").setBody(constant("B"));

from("direct:c").to("mock:C").setBody(constant("C"));
注意

这种 超时 功能也由 splitterreceiver List 支持

默认情况下,如果超时发生 AggregationStrategy 不会被调用。但是,您可以实施专用版本

// Java
public interface TimeoutAwareAggregationStrategy extends AggregationStrategy {

    /**
     * A timeout occurred
     *
     * @param oldExchange  the oldest exchange (is <tt>null</tt> on first aggregation as we only have the new exchange)
     * @param index        the index
     * @param total        the total
     * @param timeout      the timeout value in millis
     */
    void timeout(Exchange oldExchange, int index, int total, long timeout);

这允许您在 AggregationStrategy 中处理超时(如果您确实需要)。

timeout 是总计

超时为总计,这意味着在 X 时间后,Camel 将聚合在时间段内完成的消息。剩余部分将被取消。Camel 还将只调用 TimeoutAwareAggregationStrategy 中的 timeout 方法,用于第一个导致超时的索引。

将自定义处理应用到传出消息

recipientList 会向接收者端点发送一条信息前,它会创建一个消息副本,这是原始消息的绝对副本。在应该复制中,原始消息的标头和有效负载仅通过引用来复制。每个新副本不包含这些元素自己的实例。因此,消息的绝对副本会链接,当将其路由到不同的端点时,您无法应用自定义处理。

如果要在副本发送到端点前对每个消息副本执行一些自定义处理,您可以在 recipientList 子句中调用 onPrepare DSL 命令。onPrepare 命令只在消息被放送到其端点 插入自定义处理器。例如,在以下路由中,为每个接收者端点 在消息副本上调用 CustomProc 处理器:

from("direct:start")
  .recipientList().onPrepare(new CustomProc());

onPrepare DSL 命令的常见用例是对消息的部分或所有元素进行深入副本。这允许独立于其他消息副本修改每个消息副本。例如,以下 CustomProc 处理器类执行消息正文的深层副本,其中消息正文假定为 type、Bdy Type,而深度副本则由方法、Bdy Type.deepCopy() 执行。

// Java
import org.apache.camel.*;
...
public class CustomProc implements Processor {

    public void process(Exchange exchange) throws Exception {
        BodyType body = exchange.getIn().getBody(BodyType.class);

        // Make a _deep_ copy of of the body object
        BodyType clone =  BodyType.deepCopy();
        exchange.getIn().setBody(clone);

        // Headers and attachments have already been
        // shallow-copied. If you need deep copies,
        // add some more code here.
    }
}

选项

recipientList DSL 命令支持以下选项:

名称

默认值

描述

delimiter

,

表达式返回的多个端点时使用分隔符。

strategyRef

 

指的是 AggregationStrategy,用于将接收方的回复组合成来自 第 8.3 节 “接收者列表” 的单个传出消息。默认情况下,Camel 将使用最后的回复作为传出消息。

strategyMethodName

 

这个选项可用于明确指定要使用的方法名称,当 OVAs 用作 AggregationStrategy 时。

strategyMethodAllowNull

false

当将 POJOs 用作 AggregationStrategy 时,可以使用这个选项。如果为 false 则不会使用聚合方法,如果没有数据丰富。如果为 true,则使用空值作为 oldExchange,如果没有要增强数据,则使用null 值。

parallelProcessing

false

Camel 2.2: 如果启用然后同时向接收者发送信息。请注意,调用者线程仍会等待所有消息都完全处理,然后再继续。它只发送和处理来自同时发生的收件人的回复。

parallelAggregate

false

如果启用,则 AggregationStrategy 上的聚合方法可以同时调用。请注意,这需要实施 AggregationStrategy 为 thread-safe。默认情况下,此选项为 false,这表示 Camel 会自动同步对聚合方法的调用。然而,在一些用例中,您可以通过将 AggregationStrategy 作为 thread-safe,并将此选项设置为 true 来提高性能。

executorServiceRef

 

Camel 2.2: 请参阅自定义线程池,以用于并行处理。请注意,如果您设定了这个选项,则并行处理会被自动表示,您也不必启用该选项。

stopOnException

false

Camel 2.2: 出现异常时是否立即停止持续处理。如果禁用,则 Camel 会将信息发送到所有收件人,无论它们是否失败。您可在完全控制如何处理它的 AggregationStrategy 类中处理异常。

ignoreInvalidEndpoints

false

Camel 2.3: 如果无法解析端点 uri,它会被忽略。否则,Camel 会抛出一个异常,说明 endpoint uri 无效。

streaming

false

Camel 2.5: 如果启用,Camel 将处理顺序的回复,例如他们返回的顺序。如果禁用,Camel 将按照与指定的表达式相同的顺序进行回复。

timeout

 

Camel 2.5: 设置 millis 中指定的总超时。如果 第 8.3 节 “接收者列表” 没有可以在指定时间段内发送和处理所有回复,则超时触发器和 第 8.3 节 “接收者列表” 会中断并继续。请注意,如果您提供 AggregationStrategy,则会在中断前调用 超时 方法。

onPrepareRef

 

Camel 2.8: 请参阅自定义处理器准备每个接收方的 Exchange 副本。这可让您进行任何自定义逻辑,如 deep-cloning(如果需要)信息有效负载。

shareUnitOfWork

false

Camel 2.8: 是否应共享工作单元。详情请查看 第 8.4 节 “Splitter” 上的相同选项。

cacheSize

0

Camel 2.13.1/2.12.4: 允许配置 ProducerCache 的缓存大小,该缓存制作者在路由 slip 中重复使用。默认情况下,将使用默认的缓存大小,即 0。将值设为 -1 允许将缓存全部关闭。

在 Recipient 列表中使用 Exchange Pattern

默认情况下,Recipient List 使用当前的交换模式。但是,在有些情况下,您可以使用不同的交换模式向接收者发送信息。

例如,您可能有一个作为 InOnly 路由启动的路由。现在,如果您要通过接收者列表使用 InOut Exchange 模式,则需要直接在接收者端点中配置交换模式。

以下示例演示了新文件将作为 InOnly 开头,然后路由到接收者列表的路由。如果要将 InOut 与 ActiveMQ(JMS)端点搭配使用,则需要使用 exchangePattern 等于 InOut 选项指定该端点。但是,响应形式随后将继续路由 JMS 请求或回复,因此响应将作为文件存储在 outbox 目录中。

from("file:inbox")
  // the exchange pattern is InOnly initially when using a file route
  .recipientList().constant("activemq:queue:inbox?exchangePattern=InOut")
  .to("file:outbox");
注意

InOut Exchange 模式必须在超时时间内获得响应。但是,如果响应未接收,则会失败。

8.4. Splitter

概述

splitter 是将传入的消息拆分为一系列传出消息的路由器。每个传出消息均包含一条原始消息。在 Apache Camel 中,在 图 8.4 “Splitter Pattern” 中显示的 splitter 模式通过 split() Java DSL 命令实现。

图 8.4. Splitter Pattern

Splitter pattern

Apache Camel splitter 实际上支持两种模式,如下所示:

  • 简单的 splitter NETWORK-puppet 实施其本身的分割器模式。
  • Splitter/aggregator fsanitize->_<com 组合了带聚合器模式的 splitter 模式,以便在处理后对消息的片段重新组合。

在分割器将原始消息分成几部分之前,它会制作原始消息的绝对副本。在应该复制中,原始消息的标头和有效负载仅复制为参考。虽然 splitter 本身不会将生成的消息部分路由到不同的端点,但拆分消息的部分可能会处于二级路由下。

由于消息部分是可浏览的副本,它们仍然与原始消息相关联。因此,无法独立修改它们。如果要在将自定义逻辑路由到端点集之前,将自定义逻辑应用到消息部分的不同副本,您必须在 splitter 子句中使用 onPrepareRef DSL 选项,以制作原始消息的深度副本。有关使用选项的详情请参考 “选项”一节

Java DSL 示例

以下示例定义了一个来自 seda:aseda:b 的路由,它将传入的消息一行转换为单独的传出消息:

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        from("seda:a")
          .split(bodyAs(String.class).tokenize("\n"))
          .to("seda:b");
    }
};

splitter 可以使用任何表达式语言,因此您可以使用任何受支持的脚本语言(如 XPath、XQuery 或 SQL)分割消息(请参阅 第 II 部分 “路由表达式和指定语言”)。以下示例从传入信息中提取 元素,并将它们插入到单独的传出消息中:

from("activemq:my.queue")
  .split(xpath("//foo/bar"))
  .to("file://some/directory")

XML 配置示例

以下示例演示了如何使用 XPath 脚本语言在 XML 中配置分割路由:

<camelContext id="buildSplitter" xmlns="http://camel.apache.org/schema/spring">
    <route>
      <from uri="seda:a"/>
      <split>
        <xpath>//foo/bar</xpath>
        <to uri="seda:b"/>
      </split>
    </route>
</camelContext>

您可以使用 XML DSL 中的令牌化表达式来通过令牌分割样或标头,其中使用 tokenize 元素定义令牌化表达式。在以下示例中,消息正文使用 \n 分隔符字符进行令牌。要使用正则表达式模式,请在 tokenize 元素中设置 regex=true

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="direct:start"/>
        <split>
            <tokenize token="\n"/>
            <to uri="mock:result"/>
        </split>
    </route>
    </camelContext>

分割成一组行

要将大型文件分成 1000 行块,您可以在 Java DSL 中按照如下所示定义分割路由:

from("file:inbox")
    .split().tokenize("\n", 1000).streaming()
       .to("activemq:queue:order");

用来 令牌的 第二个参数指定应分组到一个块的行数。streaming() 子句会指示 splitter 不会一次读取整个文件(如果文件较大,则性能更高)。

同一路由可以在 XML DSL 中定义,如下所示:

<route>
  <from uri="file:inbox"/>
  <split streaming="true">
    <tokenize token="\n" group="1000"/>
    <to uri="activemq:queue:order"/>
  </split>
</route>

使用 group 选项时的输出始终为 java.lang.String 类型。

跳过第一个项目

要跳过消息中的第一个项目,您可以使用 skipFirst 选项。

在 Java DSL 中,在 tokenize 参数中使用第三个选项 true

from("direct:start")
 // split by new line and group by 3, and skip the very first element
      .split().tokenize("\n", 3, true).streaming()
         .to("mock:group");

同一路由可以在 XML DSL 中定义,如下所示:

<route>
  <from uri="file:inbox"/>
    <split streaming="true">
    <tokenize token="\n" group="1000" skipFirst="true" />
    <to uri="activemq:queue:order"/>
  </split>
</route>

Splitter reply

如果输入 splitter 的交换具有 InOut 消息更改模式(即预期为回复),则分割者将原始输入消息的副本作为 Out message 插槽中的回复消息。您可以通过实施自己的 聚合策略来覆盖此默认行为

并行执行

如果要并行执行生成的消息片段,您可以启用 parallel processing 选项,它会实例化线程池来处理消息片段。例如:

XPathBuilder xPathBuilder = new XPathBuilder("//foo/bar");
from("activemq:my.queue").split(xPathBuilder).parallelProcessing().to("activemq:my.parts");

您可以自定义并行分割器中使用的底层 ThreadPoolExecutor。例如,您可以在 Java DSL 中指定自定义 executor,如下所示:

XPathBuilder xPathBuilder = new XPathBuilder("//foo/bar");
ThreadPoolExecutor threadPoolExecutor = new ThreadPoolExecutor(8, 16, 0L, TimeUnit.MILLISECONDS, new LinkedBlockingQueue());
from("activemq:my.queue")
  .split(xPathBuilder)
  .parallelProcessing()
  .executorService(threadPoolExecutor)
  .to("activemq:my.parts");

您可以在 XML DSL 中指定自定义执行器,如下所示:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:parallel-custom-pool"/>
    <split executorServiceRef="threadPoolExecutor">
      <xpath>/invoice/lineItems</xpath>
      <to uri="mock:result"/>
    </split>
  </route>
</camelContext>

<bean id="threadPoolExecutor" class="java.util.concurrent.ThreadPoolExecutor">
  <constructor-arg index="0" value="8"/>
  <constructor-arg index="1" value="16"/>
  <constructor-arg index="2" value="0"/>
  <constructor-arg index="3" value="MILLISECONDS"/>
  <constructor-arg index="4"><bean class="java.util.concurrent.LinkedBlockingQueue"/></constructor-arg>
</bean>

使用 bean 执行分割

因为 splitter 可以使用任何 表达式进行拆分,您可以通过调用 method() 表达式来使用 bean 执行拆分。bean 应返回可迭代的值,如 java.util.Collectionjava.util.Iterator 或一个数组。

以下路由定义了一个 method() 表达式,它调用 mySplitterBean 实例上的方法:

from("direct:body")
        // here we use a POJO bean mySplitterBean to do the split of the payload
        .split()
        .method("mySplitterBean", "splitBody")
        .to("mock:result");
from("direct:message")
        // here we use a POJO bean mySplitterBean to do the split of the message
        // with a certain header value
        .split()
        .method("mySplitterBean", "splitMessage")
        .to("mock:result");

其中 mySplitterBeanMySplitterBean 类的实例,其定义如下:

public class MySplitterBean {

    /**
     * The split body method returns something that is iteratable such as a java.util.List.
     *
     * @param body the payload of the incoming message
     * @return a list containing each part split
     */
    public List<String> splitBody(String body) {
        // since this is based on an unit test you can of couse
        // use different logic for splitting as {router} have out
        // of the box support for splitting a String based on comma
        // but this is for show and tell, since this is java code
        // you have the full power how you like to split your messages
        List<String> answer = new ArrayList<String>();
        String[] parts = body.split(",");
        for (String part : parts) {
            answer.add(part);
        }
        return answer;
    }

    /**
     * The split message method returns something that is iteratable such as a java.util.List.
     *
     * @param header the header of the incoming message with the name user
     * @param body the payload of the incoming message
     * @return a list containing each part split
     */
    public List<Message> splitMessage(@Header(value = "user") String header, @Body String body) {
        // we can leverage the Parameter Binding Annotations
        // http://camel.apache.org/parameter-binding-annotations.html
        // to access the message header and body at same time,
        // then create the message that we want, splitter will
        // take care rest of them.
        // *NOTE* this feature requires {router} version >= 1.6.1
        List<Message> answer = new ArrayList<Message>();
        String[] parts = header.split(",");
        for (String part : parts) {
            DefaultMessage message = new DefaultMessage();
            message.setHeader("user", part);
            message.setBody(body);
            answer.add(message);
        }
        return answer;
    }
}

您可以使用带有 Splitter EIP 的 BeanIOSplitter 对象来分割大型有效负载,以避免将整个内容读取到内存中。以下示例演示了如何使用从 classpath 加载的映射文件设置 BeanIOSplitter 对象:

注意

BeanIOSplitter 类是 Camel 2.18 中的新类。Camel 2.17 中不提供它。

BeanIOSplitter splitter = new BeanIOSplitter();
   splitter.setMapping("org/apache/camel/dataformat/beanio/mappings.xml");
   splitter.setStreamName("employeeFile");

    // Following is a route that uses the beanio data format to format CSV data
    // in Java objects:
    from("direct:unmarshal")
        // Here the message body is split to obtain a message for each row:
         .split(splitter).streaming()
         .to("log:line")
         .to("mock:beanio-unmarshal");

以下示例添加了一个错误处理器:

BeanIOSplitter splitter = new BeanIOSplitter();
   splitter.setMapping("org/apache/camel/dataformat/beanio/mappings.xml");
   splitter.setStreamName("employeeFile");
   splitter.setBeanReaderErrorHandlerType(MyErrorHandler.class);
   from("direct:unmarshal")
      .split(splitter).streaming()
      .to("log:line")
      .to("mock:beanio-unmarshal");

Exchange 属性

在每个分割交换上设置以下属性:

headertypedescription

CamelSplitIndex

int

Apache Camel 2.0:为每个被分割交换的增加的分割计数器。计数器从 0 开始。

CamelSplitSize

int

Apache Camel 2.0:被分割的 Exchanges 总数。此标头不适用于基于流的拆分。

CamelSplitComplete

布尔值

Apache Camel 2.4:是否是最后的 Exchange。

Splitter/aggregator 模式

在处理各个组件完成后,消息组件的常见模式会聚合到单个交换中。为了支持这个模式,split() DSL 命令可让您提供 AggregationStrategy 对象作为第二个参数。

Java DSL 示例

以下示例演示了如何在处理完所有消息片段后使用自定义聚合策略重新组合分割消息:

from("direct:start")
    .split(body().tokenize("@"), new MyOrderStrategy())
        // each split message is then send to this bean where we can process it
        .to("bean:MyOrderService?method=handleOrder")
        // this is important to end the splitter route as we do not want to do more routing
        // on each split message
    .end()
    // after we have split and handled each message we want to send a single combined
    // response back to the original caller, so we let this bean build it for us
    // this bean will receive the result of the aggregate strategy: MyOrderStrategy
    .to("bean:MyOrderService?method=buildCombinedResponse")

AggregationStrategy 实施

前面路由中使用的自定义聚合策略 MyOrderStrategy 被实施,如下所示:

/**
 * This is our own order aggregation strategy where we can control
 * how each split message should be combined. As we do not want to
 * lose any message, we copy from the new to the old to preserve the
 * order lines as long we process them
 */
public static class MyOrderStrategy implements AggregationStrategy {

    public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {
        // put order together in old exchange by adding the order from new exchange

        if (oldExchange == null) {
            // the first time we aggregate we only have the new exchange,
            // so we just return it
            return newExchange;
        }

        String orders = oldExchange.getIn().getBody(String.class);
        String newLine = newExchange.getIn().getBody(String.class);

        LOG.debug("Aggregate old orders: " + orders);
        LOG.debug("Aggregate new order: " + newLine);

        // put orders together separating by semi colon
        orders = orders + ";" + newLine;
        // put combined order back on old to preserve it
        oldExchange.getIn().setBody(orders);

        // return old as this is the one that has all the orders gathered until now
        return oldExchange;
    }
}

基于流的处理

启用并行处理后,理论上可以在之前的某一部分之前为聚合做好准备。换句话说,消息片段可能会在聚合器中去除顺序。默认情况下,不会出现此情况,因为分离的实现会在将消息片段传递到聚合器之前将其重新整理到其原始顺序中。

如果您希望在消息发布就绪后立即聚合消息片段(可能使用顺序),您可以启用 streaming 选项,如下所示:

from("direct:streaming")
  .split(body().tokenize(","), new MyOrderStrategy())
    .parallelProcessing()
    .streaming()
    .to("activemq:my.parts")
  .end()
  .to("activemq:all.parts");

您还可以提供自定义迭代程序以用于流,如下所示:

// Java
import static org.apache.camel.builder.ExpressionBuilder.beanExpression;
...
from("direct:streaming")
     .split(beanExpression(new MyCustomIteratorFactory(),  "iterator"))
     .streaming().to("activemq:my.parts")
streaming 和 XPath

您不能与 XPath 一起使用 streaming 模式。XPath 需要内存中的完整 DOM XML 文档。

使用 XML 的流处理

如果传入的消息是一个非常大的 XML 文件,您可以在流传输模式中使用 tokenizeXML 子命令处理消息。

例如,如果一个包含一系列 顺序 元素的大型 XML 文件,您可以使用类似如下的路由将该文件分成 顺序 元素:

from("file:inbox")
  .split().tokenizeXML("order").streaming()
  .to("activemq:queue:order");

您可以在 XML 中进行同样的操作,方法是定义如下路由:

<route>
  <from uri="file:inbox"/>
  <split streaming="true">
    <tokenize token="order" xml="true"/>
    <to uri="activemq:queue:order"/>
  </split>
</route>

通常情况下,您需要访问在令牌元素的某一部分(原来)元素中定义的命名空间。您可以通过指定您要从哪个元素继承命名空间定义,将命名空间定义从其中一个级元素复制到 token 元素。

在 Java DSL 中,您要将 ancestor 元素指定为 tokenizeXML 的第二个参数。例如,从包含的 order 元素中继承 命名空间定义

from("file:inbox")
  .split().tokenizeXML("order", "orders").streaming()
  .to("activemq:queue:order");

在 XML DSL 中,您可以使用 inheritNamespaceTagName 属性指定 ancestor 元素。例如:

<route>
  <from uri="file:inbox"/>
  <split streaming="true">
    <tokenize token="order"
              xml="true"
              inheritNamespaceTagName="orders"/>
    <to uri="activemq:queue:order"/>
  </split>
</route>

选项

split DSL 命令支持以下选项:

名称

默认值

描述

strategyRef

 

指的是 AggregationStrategy,用于将子消息中的回复组合成来自 第 8.4 节 “Splitter” 的单个传出消息。有关默认使用的内容 ,请参阅标题为下面的 splitter 返回 的内容。

strategyMethodName

 

这个选项可用于明确指定要使用的方法名称,当 OVAs 用作 AggregationStrategy 时。

strategyMethodAllowNull

false

当将 POJOs 用作 AggregationStrategy 时,可以使用这个选项。如果为 false 则不会使用聚合方法,如果没有数据丰富。如果为 true,则使用空值作为 oldExchange,如果没有要增强数据,则使用null 值。

parallelProcessing

false

如果启用,则同时处理子消息。请注意,调用者线程仍会等待所有子消息已完全处理,然后再继续处理。

parallelAggregate

false

如果启用,则 AggregationStrategy 上的聚合方法可以同时调用。请注意,这需要实施 AggregationStrategy 为 thread-safe。默认情况下,此选项为 false,这表示 Camel 会自动同步对聚合方法的调用。然而,在一些用例中,您可以通过将 AggregationStrategy 作为 thread-safe,并将此选项设置为 true 来提高性能。

executorServiceRef

 

指的是用于并行处理的自定义线程池。请注意,如果您设定了这个选项,则并行处理会被自动表示,您也不必启用该选项。

stopOnException

false

Camel 2.2: 出现异常时是否立即停止持续处理。如果禁用,则 Camel 会继续分割并处理子消息,无论它们之一是否失败。您可在完全控制如何处理它的 AggregationStrategy 类中处理异常。

streaming

false

如果启用,Camel 将以流方式分割,这意味着它将以块的形式分割输入消息。这可减少内存开销。例如,如果您分离了建议启用流的大量消息。如果启用了流处理,则子消息回复将按其返回的顺序聚合。如果禁用,Camel 将按照子消息的回复处理与被分割的顺序相同。

timeout

 

Camel 2.5: 设置 millis 中指定的总超时。如果 第 8.3 节 “接收者列表” 无法分割并处理给定时间段内的所有回复,则超时触发器和 第 8.4 节 “Splitter” 会中断并继续。请注意,如果您提供 AggregationStrategy,则会在中断前调用 超时 方法。

onPrepareRef

 

Camel 2.8: 请参阅自定义处理器,在处理前准备 Exchange 的子消息。这可让您进行任何自定义逻辑,如 deep-cloning(如果需要)信息有效负载。

shareUnitOfWork

false

Camel 2.8: 是否应共享工作单元。详情请查看以下信息。

8.5. 聚合器

概述

借助在 图 8.5 “聚合器模式” 中显示的 聚合器 模式,您可以将相关消息批处理合并到单个消息中。

图 8.5. 聚合器模式

聚合器模式

要控制聚合器的行为,Apache Camel 允许您指定 Enterprise Integration Patterns 中描述的属性,如下所示:

  • correlation 表达式 libselinux-eviction 确定应聚合哪些消息。在每条传入消息上评估关联表达式,以生成 关联键。然后,具有相同关联密钥的传入消息被分组到同一个批处理中。例如,如果要将 所有传入 的信息聚合到一个消息中,您可以使用一个恒定表达式。
  • 完整的信息完成时,完整性条件 10.10.10.2-eviction 确定了。您可以将此设置指定为一个简单的大小限制,或者更一般,您可以指定在批处理完成后标记的 predicate 条件。
  • 聚合算法 InventoryService-jaxb Com 组合了单一关联密钥的消息交换功能到单个消息交换中。

例如,考虑一个可每秒接收 30,000 条消息的库存市场数据系统。如果您的 GUI 工具无法与如此大规模的更新率合作,则您可能希望减慢消息流。只需选择最新的报价并丢弃旧的价格,即可聚合传入的库存报价。(如果您愿意捕获历史信息,可以应用 delta 处理算法。)

注意

现在,聚合器现在使用包含更多信息的 ManagedAggregateProcessorMBean 形式列出 JMX。它允许您使用聚合控制器来控制它。

聚合器的工作方式

图 8.6 “聚合器实施” 展示了聚合器如何工作的概览,假设它通过带有关联键的交换流(如 A、B、C 或 D)进行交换流。

图 8.6. 聚合器实施

消息路由 02

图 8.6 “聚合器实施” 中显示的传入的交换流如下:

  1. 关联器负责 根据关联密钥对交换进行排序。对于每个传入的交换,评估了关联表达式,从而生成关联密钥。例如,对于 图 8.6 “聚合器实施” 中显示的交换,关联键将评估为 A。
  2. 聚合策略 负责与相同关联密钥进行合并交换。当新的交换 A 处于 A 时,聚合器会在聚合存储库中查找对应的 聚合交换、A',并将其与新交换合并。

    在完成特定的聚合周期前,传入的交换将继续与对应的聚合交换一起聚合。聚合周期持续到其中一个完成机制终止为止。

    注意

    从 Camel 2.16,新的 XSLT 聚合策略允许您将两个消息与 XSLT 文件合并。您可以从 toolbox 访问 AggregationStrategies.xslt() 文件。

  3. 如果在聚合器上指定了完成 predicate,则会测试聚合交换,以确定是否准备好发送到路由中的下一个处理器。处理继续,如下所示:

    • 如果完成,聚合交换由路由中的后方处理。这里有两种替代模型: 同步 (默认),这会导致调用线程块或 异步 (如果启用并行处理),其中将聚合交换提交至 executor 线程池(如 图 8.6 “聚合器实施”)。
    • 如果没有完成,聚合交换将返回到聚合存储库。
  4. 与同步完成测试并行,可以通过启用 completionTimeout 选项或 completionInterval 选项来启用异步完成测试。这些完成测试在单独的线程中运行,每当完成测试满意时,对应的交换都会标记为完成,并开始由路由后面的部分处理(同步或异步,具体取决于是否启用并行处理)。
  5. 如果启用了并行处理,一个线程池负责在路由后面的部分处理交换。默认情况下,这个线程池包含十个线程,但您可以选择自定义池(“线程选项”一节)。

Java DSL 示例

以下示例使用 UseLatestAggregationStrategy 聚合策略来聚合具有相同 VDDK Symbol 标头值的交换。对于给定的 prepare Symbol 值,如果收到了与该关联密钥的最后三秒钟以上,则聚合的交换被视为完成状态并发送到 模拟 端点。

from("direct:start")
    .aggregate(header("id"), new UseLatestAggregationStrategy())
        .completionTimeout(3000)
    .to("mock:aggregated");

XML DSL 示例

以下示例演示了如何在 XML 中配置相同的路由:

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="direct:start"/>
        <aggregate strategyRef="aggregatorStrategy"
                   completionTimeout="3000">
            <correlationExpression>
                <simple>header.StockSymbol</simple>
            </correlationExpression>
            <to uri="mock:aggregated"/>
        </aggregate>
    </route>
</camelContext>

<bean id="aggregatorStrategy"
      class="org.apache.camel.processor.aggregate.UseLatestAggregationStrategy"/>

指定关联表达式

在 Java DSL 中,关联表达式始终作为第一个参数传递给 aggregate() DSL 命令。这里没有限制使用 Simple 表达式语言。您可以使用任何表达式语言或脚本语言(如 XPath、XQuery、SQL 等)指定关联表达式。

对于考试,若要使用 XPath 表达式关联交换,您可以使用以下 Java DSL 路由:

from("direct:start")
    .aggregate(xpath("/stockQuote/@symbol"), new UseLatestAggregationStrategy())
        .completionTimeout(3000)
    .to("mock:aggregated");

如果无法在特定的交换中评估关联表达式,聚合器默认会抛出 CamelExchangeException。您可以通过设置 ignoreCorrelationKeys 选项来限制这个异常。例如,在 Java DSL 中:

from(...).aggregate(...).ignoreInvalidCorrelationKeys()

在 XML DSL 中,您可以设置 ignoreInvalidCorrelationKeys 选项作为属性,如下所示:

<aggregate strategyRef="aggregatorStrategy"
           ignoreInvalidCorrelationKeys="true"
           ...>
    ...
</aggregate>

指定聚合策略

在 Java DSL 中,您可以将聚合策略作为第二参数传递给 aggregate() DSL 命令,或使用 aggregationStrategy() 子句指定。例如,您可以使用 aggregationStrategy() 子句,如下所示:

from("direct:start")
    .aggregate(header("id"))
        .aggregationStrategy(new UseLatestAggregationStrategy())
        .completionTimeout(3000)
    .to("mock:aggregated");

Apache Camel 提供以下基本的聚合策略(即类属于 org.apache.camel.processor.aggregate Java 软件包):

UseLatestAggregationStrategy
返回给定关联密钥的最后交换,用该密钥丢弃之前的所有交换。例如,此策略对于对来自股票交易所馈送的换算者来说非常有用,其中您只想了解特定库存符号的最新价格。
UseOriginalAggregationStrategy
返回给定关联密钥的第一个交换,用此密钥丢弃所有之后的交换。您必须在可以使用此策略前调用 UseOriginalAggregationStrategy.setOriginal() 来设置第一个交换。
GroupedExchangeAggregationStrategy
将给定关联键 的所有 交换串联为列表,该列表存储在 Exchange.GROUPED_EXCHANGE 交换属性中。请参阅 “分组交换”一节

实施自定义聚合策略

如果要应用不同的聚合策略,可以实施以下聚合策略基础接口之一:

org.apache.camel.processor.aggregate.AggregationStrategy
基本聚合策略接口。
org.apache.camel.processor.aggregate.TimeoutAwareAggregationStrategy

实施这个接口,如果您希望实施在聚合周期超时时收到通知。超时 通知方法有以下签名:

void timeout(Exchange oldExchange, int index, int total, long timeout)
org.apache.camel.processor.aggregate.CompletionAwareAggregationStrategy

实施这个接口,如果您要在聚合周期正常完成时收到通知,则实施此接口。通知方法有以下签名:

void onCompletion(Exchange exchange)

例如,以下代码显示了两个不同的自定义聚合策略,StringAggregationStrategyArrayListAggregationStrategy::

 //simply combines Exchange String body values using '' as a delimiter
 class StringAggregationStrategy implements AggregationStrategy {

     public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {
         if (oldExchange == null) {
             return newExchange;
         }

         String oldBody = oldExchange.getIn().getBody(String.class);
         String newBody = newExchange.getIn().getBody(String.class);
         oldExchange.getIn().setBody(oldBody + "" + newBody);
         return oldExchange;
     }
 }

 //simply combines Exchange body values into an ArrayList<Object>
 class ArrayListAggregationStrategy implements AggregationStrategy {

     public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {
 	    Object newBody = newExchange.getIn().getBody();
     	ArrayList<Object> list = null;
         if (oldExchange == null) {
 		    list = new ArrayList<Object>();
 		    list.add(newBody);
 		    newExchange.getIn().setBody(list);
 		    return newExchange;
         } else {
 	        list = oldExchange.getIn().getBody(ArrayList.class);
 	    	list.add(newBody);
 		    return oldExchange;
 	    }
     }
 }
注意

从 Apache Camel 2.0 开始,在第一个交换中也调用 AggregationStrategy.aggregate() 回调方法。在 aggregate 方法的第一个调用中,oldExchange 参数为 nullnewExchange 参数包含第一个传入的交换。

要使用自定义策略类 ArrayListAggregationStrategy 来聚合消息,请按如下所示定义一个路由:

from("direct:start")
    .aggregate(header("StockSymbol"), new ArrayListAggregationStrategy())
    .completionTimeout(3000)
    .to("mock:result");

您还可以使用 XML 中的自定义聚合策略配置路由,如下所示:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <aggregate strategyRef="aggregatorStrategy"
               completionTimeout="3000">
      <correlationExpression>
        <simple>header.StockSymbol</simple>
      </correlationExpression>
      <to uri="mock:aggregated"/>
    </aggregate>
  </route>
</camelContext>

<bean id="aggregatorStrategy" class="com.my_package_name.ArrayListAggregationStrategy"/>

控制自定义聚合策略的生命周期

您可以实施自定义聚合策略,以便其生命周期与控制它的企业集成模式的生命周期一致。这可用于确保聚合策略可以安全地关闭。

要实现具有生命周期支持的聚合策略,您必须实现 org.apache.camel.Service 接口(除 AggregationStrategy 接口外),并提供 start()stop() 生命周期方法的实现。例如,以下代码示例演示了具有生命周期支持的聚合策略:

// Java
import org.apache.camel.processor.aggregate.AggregationStrategy;
import org.apache.camel.Service;
import java.lang.Exception;
...
class MyAggStrategyWithLifecycleControl
       implements AggregationStrategy, Service {

    public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {
        // Implementation not shown...
        ...
    }

    public void start() throws Exception {
        // Actions to perform when the enclosing EIP starts up
        ...
    }

    public void stop() throws Exception {
        // Actions to perform when the enclosing EIP is stopping
        ...
    }
}

Exchange 属性

每个聚合交换中会设置以下属性:

标头类型描述聚合交换属性

Exchange.AGGREGATED_SIZE

int

整合到此交换的交换总数。

Exchange.AGGREGATED_COMPLETED_BY

字符串

表示负责完成聚合交换的机制。可能的值有: predicatesizetimeoutintervalconsumer

以下属性在由 SQL 组件聚合存储库进行交换上设置(请参阅 “持久性聚合存储库”一节):

标头类型描述 Red Hatlivered Exchange Properties

Exchange.REDELIVERY_COUNTER

int

当前重新传送尝试的序列号(从 1开始)。

指定完成条件

至少需要指定一个 完成条件,它决定聚合交换离开聚合器并继续路由上的下一个节点。可以指定以下完成条件:

completionPredicate
聚合每个交换后评估 predicate,以确定完整性。true 表示聚合交换已完成。另外,您可以定义一个自定义 AggregationStrategy 来实施 Predicate 接口,在这种情况下,AggregationStrategy 将用作 completion predicate。
completionSize
聚合指定数量的传入的交换后,完成聚合的交换。
completionTimeout

(与 completionInterval兼容) 在指定的超时时间内没有聚合交换时完成聚合交换。

换句话说,超时机制会跟踪 每个 关联键值的超时。在收到带有特定密钥值的最新交换后,时钟开始选择。如果指定超时内 未收到 具有相同键值的另一个交换,则对应的聚合交换标记为完成并发送到路由上的下一个节点。

completionInterval

(与 completionTimeout兼容 )完成所有 未完成的聚合交换,经过每个时间间隔(指定长度)过后。

间隔 不会 为每个聚合交换量身定制。这种机制会强制同步完成所有未完成的聚合交换。因此,在某些情况下,这种机制可在聚合后立即完成聚合交换。

completionFromBatchConsumer
与支持 批处理消费者 机制的消费者端点结合使用时,此完成选项会根据从消费者端点接收的信息,在当前批量交换完成后自动找出出。请参阅 “批量消费者”一节
forceCompletionOnStop
启用此选项后,它会强制在当前路由上下文停止后完成所有未完成的聚合交换。

除了 completionTimeoutcompletionInterval 条件(无法同时启用)外,前面的完成条件可以任意组合使用。当条件组合使用时,触发的第一个完成条件是有效的完成条件。

指定完成 predicate

您可以指定一个任意 predicate 表达式,决定聚合交换完成后决定。评估 predicate 表达式的方法有两种:

  • 在最新的聚合交换 中,the default behavior是默认行为。
  • 当您启用 eagerCheckCompletion 选项时,会选择最新传入的 Exchange 您要将这个行为被选择。

例如,如果您想要在每次收到 ALERT 消息时终止库存引号流(如最新传入的交换中 MsgType 标头的值所示),您可以定义一个类似如下的路由:

from("direct:start")
    .aggregate(
      header("id"),
      new UseLatestAggregationStrategy()
    )
        .completionPredicate(
          header("MsgType").isEqualTo("ALERT")
         )
        .eagerCheckCompletion()
    .to("mock:result");

以下示例演示了如何使用 XML 配置同一路由:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <aggregate strategyRef="aggregatorStrategy"
               eagerCheckCompletion="true">
      <correlationExpression>
          <simple>header.StockSymbol</simple>
      </correlationExpression>
      <completionPredicate>
          <simple>$MsgType = 'ALERT'</simple>
      </completionPredicate>
      <to uri="mock:result"/>
    </aggregate>
  </route>
</camelContext>

<bean id="aggregatorStrategy"
      class="org.apache.camel.processor.aggregate.UseLatestAggregationStrategy"/>

指定动态完成超时

可以指定 动态完成超时,其中为每个传入的交换重新计算超时值。例如,若要从每个传入交换中的 超时标头设置超时值,您可以按照如下所示定义路由:

from("direct:start")
    .aggregate(header("StockSymbol"), new UseLatestAggregationStrategy())
        .completionTimeout(header("timeout"))
    .to("mock:aggregated");

您可以在 XML DSL 中配置相同的路由,如下所示:

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="direct:start"/>
        <aggregate strategyRef="aggregatorStrategy">
            <correlationExpression>
                <simple>header.StockSymbol</simple>
            </correlationExpression>
            <completionTimeout>
                <header>timeout</header>
            </completionTimeout>
            <to uri="mock:aggregated"/>
        </aggregate>
    </route>
</camelContext>

<bean id="aggregatorStrategy"
      class="org.apache.camel.processor.UseLatestAggregationStrategy"/>
注意

您还可以添加固定超时值,如果动态值是 null0, 则 Apache Camel 会返回使用这个值。

指定动态完成大小

可以指定 动态完成大小,在其中为每个传入的交换重新计算完成大小。例如,要在每个传入交换中从 mySize 标头设置完成大小,您可以按照如下所示定义路由:

from("direct:start")
    .aggregate(header("StockSymbol"), new UseLatestAggregationStrategy())
        .completionSize(header("mySize"))
    .to("mock:aggregated");

以及使用 Spring XML 相同的示例:

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="direct:start"/>
        <aggregate strategyRef="aggregatorStrategy">
            <correlationExpression>
                <simple>header.StockSymbol</simple>
            </correlationExpression>
            <completionSize>
                <header>mySize</header>
            </completionSize>
            <to uri="mock:aggregated"/>
        </aggregate>
    </route>
</camelContext>

<bean id="aggregatorStrategy"
      class="org.apache.camel.processor.UseLatestAggregationStrategy"/>
注意

您还可以添加固定大小值,如果动态值是 null0, 则 Apache Camel 会返回使用这个值。

从 AggregationStrategy 内强制完成单个组

如果实施自定义 AggregationStrategy 类,可以通过一种机制来强制完成当前消息组,方法是将 Exchange.AGGREGATION_COMPLETE_CURRENT_GROUP Exchange 属性设为 true。这种机制 仅影响 当前组:其他消息组(具有不同关联 ID) 不会被 强制完成。这种机制会覆盖任何其他完成机制,如 predicate、大小、超时等。

例如,如果消息正文大小大于 5,以下示例 AggregationStrategy 类将完成当前的组:

// Java
public final class MyCompletionStrategy implements AggregationStrategy {
    @Override
    public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {
        if (oldExchange == null) {
            return newExchange;
        }
        String body = oldExchange.getIn().getBody(String.class) + "+"
            + newExchange.getIn().getBody(String.class);
        oldExchange.getIn().setBody(body);
        if (body.length() >= 5) {
            oldExchange.setProperty(Exchange.AGGREGATION_COMPLETE_CURRENT_GROUP, true);
        }
        return oldExchange;
    }
}

强制使用特殊消息完成所有组

通过向路由发送带有特殊标头的消息,可以强制完成所有未完成的聚合消息。您可以使用两种替代标头设置来强制完成:

Exchange.AGGREGATION_COMPLETE_ALL_GROUPS
设置为 true,以强制完成当前的聚合周期。此消息仅以信号形式运作,不包含在 任何聚合周期内。处理此信号消息后,会丢弃消息的内容。
Exchange.AGGREGATION_COMPLETE_ALL_GROUPS_INCLUSIVE
设置为 true,以强制完成当前的聚合周期。此消息 包含在 当前聚合周期中。

使用 AggregateController

org.apache.camel.processor.aggregate.AggregateController 可让您使用 Java 或 JMX API 控制运行时的聚合。这可用于强制完成交换组,或者查询当前运行时统计信息。

如果没有配置自定义,聚合器提供了一个默认的实现,您可以使用 getAggregateController() 方法访问它。但是,使用 aggregateController 轻松地在路由中配置控制器。

private AggregateController controller = new DefaultAggregateController();

from("direct:start")
   .aggregate(header("id"), new MyAggregationStrategy()).completionSize(10).id("myAggregator")
      .aggregateController(controller)
      .to("mock:aggregated");

另外,您可以使用 AggregateController上的 API 来强制完成。例如,使用键 foo 完成组

int groups = controller.forceCompletionOfGroup("foo");

数值返回将是已完成的组数。以下是完成所有组的 API:

 int groups = controller.forceCompletionOfAllGroups();

强制唯一关联密钥

在一些聚合场景中,您可能希望强制关联密钥对每批交换是唯一的条件。换而言之,当特定关联键的聚合交换完成时,您希望确保不进一步的聚合交换,不能与这个关联键进行进一步的交换。例如,如果路由中的后者部分与唯一关联键值进行交换,您可能希望强制执行此条件。

根据配置完成条件的方式,可能会遇到使用特定关联密钥生成多个聚合交换的风险。例如,虽然您可以定义一个完成 predicate,以便等到接收具有特定关联密钥 的所有 交换前,您也可以定义完成超时,这可以在与该密钥到达的所有交换之前触发。在这种情况下,较晚的交换可能会给 第二个 聚合交换带来的增加,具有相同关联键的值。

对于这样的场景,您可以通过设置 closeCorrelationKeyOnCompletion 选项,将聚合器配置为绕过重复之前关联键值的聚合交换。为绕过重复的关联键值,聚合器需要在缓存中记录之前的关联键值。此缓存的大小(缓存的关联键的数量)被指定为 closeCorrelationKeyOnCompletion() DSL 命令的参数。要指定无限大小的缓存,您可以传递一个零个或一个负整数。例如,指定 10000 个键值的缓存大小:

from("direct:start")
    .aggregate(header("UniqueBatchID"), new MyConcatenateStrategy())
        .completionSize(header("mySize"))
        .closeCorrelationKeyOnCompletion(10000)
    .to("mock:aggregated");

如果聚合交换以重复的关联键值完成,聚合器会抛出 ClosedCorrelationKeyException 异常。

使用简单表达式的基于流的处理

您可以将 Simple 语言表达式用作使用流模式的 tokenizeXML 子命令的令牌。使用简单语言表达式将支持动态令牌。

例如,要使用 Java 将一系列名称分割成标签用户角色,您可以使用 令牌izeXML bean 和简单语言令牌将 文件分成 名称 元素。

public void testTokenizeXMLPairSimple() throws Exception {
        Expression exp = TokenizeLanguage.tokenizeXML("${header.foo}", null);

获取由 < person > 划分的名称输入字符串,并将 &lt ;person& gt; 设置为令牌。

        exchange.getIn().setHeader("foo", "<person>");
        exchange.getIn().setBody("<persons><person>James</person><person>Claus</person><person>Jonathan</person><person>Hadrian</person></persons>");

列出从输入中分割的名称。

        List<?> names = exp.evaluate(exchange, List.class);
        assertEquals(4, names.size());

        assertEquals("<person>James</person>", names.get(0));
        assertEquals("<person>Claus</person>", names.get(1));
        assertEquals("<person>Jonathan</person>", names.get(2));
        assertEquals("<person>Hadrian</person>", names.get(3));
    }

分组交换

您可以将传出批处理中的所有聚合交换组合为一个 org.apache.camel.impl.GroupedExchange holder 类。要启用分组的交换,请指定 groupExchanges() 选项,如以下 Java DSL 路由中所示:

from("direct:start")
    .aggregate(header("StockSymbol"))
        .completionTimeout(3000)
        .groupExchanges()
    .to("mock:result");

发送至 模拟:result 的分组交换列表包含消息正文中的聚合交换列表。以下行显示后续的处理器如何以列表的形式访问分组交换的内容:

// Java
List<Exchange> grouped = ex.getIn().getBody(List.class);
注意

当您启用分组的交换功能时,不得 配置聚合策略(分组交换功能本身就是一个聚合策略)。

注意

从传出交换的属性访问分组交换的旧方法是已弃用,并将在以后的发行版本中删除。

批量消费者

聚合器可以和 批处理消费者 模式一起工作,以汇总批处理消费者报告的消息总数(批处理端点设置 CamelBatchSizeCamelBatchIndexCamelBatchComplete 属性)。例如,若要聚合由文件消费者端点找到的所有文件,您可以按照以下方式使用路由:

from("file://inbox")
    .aggregate(xpath("//order/@customerId"), new AggregateCustomerOrderStrategy())
    .completionFromBatchConsumer()
    .to("bean:processOrder");

目前,以下端点支持批处理消费者机制:文件、FTP、邮件、iBatis 和 JPA。

持久性聚合存储库

默认聚合器只使用内存的 AggregationRepository。如果要永久存储待处理聚合交换,您可以使用 SQL 组件 作为持久聚合存储库。SQL 组件包含一个 JdbcAggregationRepository,可持续保留聚合的消息,并确保您不会丢失任何消息。

当成功处理交换后,当存储库上调用 确认方法时,它将标记为 complete。这意味着,如果同样的交换再次失败,它将重试,直到成功为止。

添加对 camel-sql 的依赖

要使用 SQL 组件,您必须在项目中包含对 camel-sql 的依赖。例如,如果您使用 Maven pom.xml 文件:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-sql</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

创建聚合数据库表

您必须创建一个单独的聚合和已完成的数据库表以实现持久性。例如,以下查询会为名为 my_aggregation_repo 的数据库创建表:

CREATE TABLE my_aggregation_repo (
 id varchar(255) NOT NULL,
 exchange blob NOT NULL,
 constraint aggregation_pk PRIMARY KEY (id)
);

CREATE TABLE my_aggregation_repo_completed (
 id varchar(255) NOT NULL,
 exchange blob NOT NULL,
 constraint aggregation_completed_pk PRIMARY KEY (id)
);
}

配置聚合存储库

您还必须在框架 XML 文件中配置聚合存储库(如 Spring 或 Blueprint):

<bean id="my_repo"
    class="org.apache.camel.processor.aggregate.jdbc.JdbcAggregationRepository">
    <property name="repositoryName" value="my_aggregation_repo"/>
    <property name="transactionManager" ref="my_tx_manager"/>
    <property name="dataSource" ref="my_data_source"/>
    ...
</bean>

repositories NametransactionManagerdataSource 属性是必需的。有关持久性聚合存储库的更多信息,请参阅 Apache Camel 组件参考指南 中的 SQL 组件

线程选项

图 8.6 “聚合器实施” 所示,聚合器与路由中的后方分离,后者将发送到路由后面的部分,后者由专用线程池处理。默认情况下,这个池仅包含单个线程。如果要指定多个线程的池,启用 parallelProcessing 选项,如下所示:

from("direct:start")
    .aggregate(header("id"), new UseLatestAggregationStrategy())
        .completionTimeout(3000)
        .parallelProcessing()
    .to("mock:aggregated");

默认情况下,这会创建一个有 10 个 worker 线程的池。

如果要对创建的线程池进行更多控制,请使用 executorService 选项指定自定义 java.util.concurrent.ExecutorService 实例(在这种情况下,不需要启用 parallelProcessing 选项)。

聚合到列表中

常见的聚合场景涉及将一系列传入的消息正文聚合到一个 List 对象中。为便于这种情况,Apache Camel 提供了 AbstractListAggregationStrategy 抽象类,您可以快速扩展来为本例创建聚合策略。传入类型为 T 的消息正文,聚合到一个完成的交换中,以及类型为 List<T> 的消息正文。

例如,若要将一系列 Integer 消息正文聚合到一个 List<Integer > 对象中,您可以使用以下定义的聚合策略:

import org.apache.camel.processor.aggregate.AbstractListAggregationStrategy;
...
/**
 * Strategy to aggregate integers into a List<Integer>.
 */
public final class MyListOfNumbersStrategy extends AbstractListAggregationStrategy<Integer> {
 
    @Override
    public Integer getValue(Exchange exchange) {
        // the message body contains a number, so just return that as-is
        return exchange.getIn().getBody(Integer.class);
    }
}

aggregator 选项

聚合器支持以下选项:

表 8.1. 聚合器选项

选项默认值描述

correlationExpression

 

强制表达式,用于评估用于聚合的关联密钥。具有相同关联密钥的 Exchange 会聚合在一起。如果无法评估关联密钥,则引发 Exception。您可以使用 ignoreBadCorrelationKeys 选项禁用此功能。

aggregationStrategy

 

mandatory AggregationStrategy,用于将传入的 Exchange 与现有的合并交换合并。首先调用 oldExchange 参数是 null。在随后的调用中,oldExchange 包含合并的交换,newExchange 则属于新传入的 Exchange。从 Camel 2.9.2 开始,该策略可以选择是一个 TimeoutAwareAggregationStrategy 实现,它支持超时回调。从 Camel 2.16 开始,该策略也可以是 PreCompletionAwareAggregationStrategy 实施。它可在预补全模式下运行完成检查。

strategyRef

 

在 registry 中查询 AggregationStrategy 的引用。

completionSize

 

聚合完成前聚合的消息数量。这个选项可以被设置为固定值或使用表达式(允许您动态评估大小)将使用 Integer。如果两者均被设置为 null0, 则 Camel 将回退设置为使用固定的值。

completionTimeout

 

聚合交换的时间在完成前应不活跃。这个选项可以设置为固定值或使用允许您动态评估超时的表达式 - 将因此使用 长长。如果两者均被设置为 null0, 则 Camel 将回退设置为使用固定的值。您不能将此选项与 completionInterval 一起使用,只能同时使用这两者之一。

completionInterval

 

在聚合器中重复一个期间,聚合器将完成所有当前的聚合交换。Camel 有一个后台任务,每个任务都会触发。您不能将此选项与 completionTimeout 一起使用,只能同时使用其中之一。

completionPredicate

 

指定 predicate( org.apache.camel.Predicate 类型),它会在聚合交换完成后发出信号。另外,您可以定义一个自定义 AggregationStrategy 来实施 Predicate 接口,在这种情况下,AggregationStrategy 将用作 completion predicate。

completionFromBatchConsumer

false

这个选项是,如果交换来自一个 Batch Consumer。然后,当启用 第 8.5 节 “聚合器” 时,将使用在消息标头 CamelBatchSize 中由 Batch Consumer 决定的批处理大小。如需更多相关信息,请参阅 Batch Consumer。这可用于汇总给定轮询中来自 查看文件 端点的所有文件。

eagerCheckCompletion

false

在收到新传入的 Exchange 时,是否检查是否完成。这个选项会影响 completionPredicate 选项的行为,因为 Exchange 会相应地传递更改。为防止 在 Predicate 传递的 Exchange 是 聚合的 Exchange 时,这意味着您可以在 AggregationStrategy 聚合的 Exchange 中存储任何信息。为使该前文中传递的 Exchange 是 传入 Exchange,这意味着您可以从进入的 Exchange 访问数据。

forceCompletionOnStop

false

如果为 true,则在停止当前路由上下文时完成所有聚合的交换。

groupExchanges

false

如果启用,Camel 将所有聚合的 Exchanges 分组到一个整合的 org.apache.camel.impl.GroupedExchange holder 类中,该类包含所有聚合的 Exchanges。因此,只有一个 Exchange 从聚合器中发出。可用于将许多进入的 Exchanges 组合为一个输出 Exchange,而无需自己编写自定义 AggregationStrategy

ignoreInvalidCorrelationKeys

false

是否忽略无法被评估到值的关联键。默认情况下,Camel 将抛出 Exception,但您可以启用这个选项并忽略这种情况。

closeCorrelationKeyOnCompletion

 

是否应该接受 后期 的 Exchanges。您可以启用此项来指示是否已完成关联密钥,然后与相同关联密钥的任何新交换都将被拒绝。然后,CamelationKeyException 异常会引发 closedCorrelationKeyException 异常。当使用这个选项时,会将一个整数传递,这是 LRUCache 的数字,保留最后 X 号右关联键。您可以传递 0 或负数值来指示未绑定缓存。通过使用不同的关联密钥的日志,通过通过数字,确保缓存不会变得太大。

discardOnCompletionTimeout

false

Camel 2.5: 由于超时而完成的交换应该被丢弃。如果启用,则当超时发生时,聚合的消息 不会 发出出去但丢弃(无意图)。

aggregationRepository

 

允许您自行插入 org.apache.camel.spi.AggregationRepository 实施,用于跟踪当前动态的聚合交换。Camel 默认使用基于内存的实施。

aggregationRepositoryRef

 

引用在 registry 中查询聚合Repository

parallelProcessing

false

当聚合完成后,它们将从聚合器中发送。此选项指明 Camel 是否应使用带有多个线程的线程池来实现并发性。如果没有指定自定义线程池,Camel 会创建一个带有 10 个并发线程的默认池。

executorService

 

如果使用 并行处理 功能,您可以指定要使用的自定义线程池。实际上,如果您不使用 并行处理 这一自定义线程池,也用于发送聚合的交换。

executorServiceRef

 

在 Registry 中查询 executorService 的引用

timeoutCheckerExecutorService

 

如果使用一个 completionTimeoutcompletionTimeoutExpressioncompletionInterval 选项,则会创建一个后台线程来检查每个聚合器的完成情况。设置这个选项,以提供使用自定义线程池,而不是为每个聚合器创建新线程。

timeoutCheckerExecutorServiceRef

 

在 registry 中查找 timeoutCheckerExecutorService 的引用。

completeAllOnStop

 

当您停止聚合器时,这个选项允许它完成来自聚合存储库的所有待处理交换。

optimisticLocking

false

打开开放式锁定,它可以与聚合存储库结合使用。

optimisticLockRetryPolicy

 

为选择锁定配置重试策略。

8.6. Resequencer

概述

resequencer 模式(如 图 8.7 “重新排序模式” )可让您根据顺序表达式重新排序信息。为 sequencing 表达式生成 low 值的消息将移到生成高值的批处理和消息前面的消息。

图 8.7. 重新排序模式

Resequencer 模式

Apache Camel 支持两种重新排序算法:

  • 批处理重新排序 InventoryService-10.10.10.2 Collects 消息进入批处理中,对消息进行排序,并将它们发送到其输出。
  • 根据消息间差距的检测,流重新排序 IFL 排序(持续)消息流。

默认情况下,resequencer 不支持重复消息,在消息到达相同的消息时,将仅保留最后一条消息。但是,在批处理模式下,您可以启用重新排序以允许重复。

批处理重新排序

默认启用批处理重新排序算法。例如,根据 TimeStamp 标头中包含的时间戳值重新排序传入的消息,您可以在 Java DSL 中定义以下路由:

from("direct:start").resequence(header("TimeStamp")).to("mock:result");

默认情况下,通过收集所有传入消息,以间隔 1000 毫秒(默认 批处理超时),最多获取批处理信息(默认 批处理大小)。您可以通过附加 batch() DSL 命令来自定义批处理超时和批处理大小的值,该命令使用 BatchResequencerConfig 实例作为唯一参数。例如,若要修改前面的路由,使批处理由 4000 毫秒时间内收集的消息组成,最多 300 个消息,您可以定义 Java DSL 路由,如下所示:

import org.apache.camel.model.config.BatchResequencerConfig;

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        from("direct:start").resequence(header("TimeStamp")).batch(new BatchResequencerConfig(300,4000L)).to("mock:result");
    }
};

您还可以使用 XML 配置指定批处理重新排序模式。以下示例定义了批处理大小为 300 的批处理重新排序,批处理超时为 4000 毫秒:

<camelContext id="resequencerBatch" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start" />
    <resequence>
      <!--
        batch-config can be omitted for default (batch) resequencer settings
      -->
      <batch-config batchSize="300" batchTimeout="4000" />
      <simple>header.TimeStamp</simple>
      <to uri="mock:result" />
    </resequence>
  </route>
</camelContext>

批处理选项

表 8.2 “批处理重新排序选项” 显示仅在批处理模式下可用的选项。

表 8.2. 批处理重新排序选项

Java DSLXML DSL默认描述

allowDuplicates()

batch-config/@allowDuplicates

false

如果为 true,则不丢弃批处理中的重复消息(其中 重复 意味着消息表达式评估为相同的值)。

reverse()

batch-config/@reverse

false

如果为 true,则以相反顺序放置消息(其中应用于消息表达式的默认排序基于 Java 的字符串字典顺序,由 String.compareTo()定义)。

例如,如果要根据 JMSPriority 重新排序来自 JMS 队列的消息,则需要组合选项、allowDuplicatreverse,如下所示:

from("jms:queue:foo")
        // sort by JMSPriority by allowing duplicates (message can have same JMSPriority)
        // and use reverse ordering so 9 is first output (most important), and 0 is last
        // use batch mode and fire every 3th second
        .resequence(header("JMSPriority")).batch().timeout(3000).allowDuplicates().reverse()
        .to("mock:result");

流重新排序

要启用流重新排序算法,您必须将 stream() 附加到 resequence() DSL 命令中。例如,根据 seqnum 标头中的序列号值重新排序传入的信息,您需要定义一个 DSL 路由,如下所示:

from("direct:start").resequence(header("seqnum")).stream().to("mock:result");

流处理重新排序算法基于消息流中空缺的检测,而不是固定批量大小。差错检测与超时相结合,无需事先知道序列数(即批处理大小)的约束。消息必须包含唯一序列号,即 predecessor 和 a successor is known。例如,带有序列号 3 的消息带有序列号 2 的前身消息,以及序列号为 4 的后序消息。由于缺少 3 的后续情况,消息序列 2,3,5 有差距。因此,resequencer 必须保留消息 5,直到消息 4 到达(或超时发生)。

默认情况下,流 resequencer 配置超时为 1000 毫秒,最大消息容量为 100。要自定义流的超时和消息容量,您可以将 StreamResequencerConfig 对象作为参数传递到 stream()。例如,若要将消息容量为 5000 且超时为 4000 毫秒配置流重新排序器,您需要定义路由,如下所示:

// Java
import org.apache.camel.model.config.StreamResequencerConfig;

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        from("direct:start").resequence(header("seqnum")).
            stream(new StreamResequencerConfig(5000, 4000L)).
            to("mock:result");
    }
};

如果成功消息之间的最大时间延迟(即,消息流中带有相邻顺序的消息)是已知的,则 resequencer 的 timeout 参数应设置为这个值。在这种情况下,您可以保证流中的所有信息都会被正确传送到下一个处理器。与不不透明时间的差值相比,超时值越低,可能更有可能将消息传送出序列。大型超时值应该获得足够高的容量值的支持,其中使用 capacity 参数以防止重新排序内存不足。

如果要使用 长期 某些类型的序列号,则必须定义自定义比较器,如下所示:

// Java
ExpressionResultComparator<Exchange> comparator = new MyComparator();
StreamResequencerConfig config = new StreamResequencerConfig(5000, 4000L, comparator);
from("direct:start").resequence(header("seqnum")).stream(config).to("mock:result");

您还可以使用 XML 配置指定流重新排序模式。以下示例定义了消息容量为 5000 且超时为 4000 毫秒的流重新排序:

<camelContext id="resequencerStream" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <resequence>
      <stream-config capacity="5000" timeout="4000"/>
      <simple>header.seqnum</simple>
      <to uri="mock:result" />
    </resequence>
  </route>
</camelContext>

忽略无效交换

如果由于某种原因无法评估 sequencing 表达式,requencer EIP 会抛出 CamelExchangeException 异常。如果传入交换无效,如果由于某种原因无法评估不同的表达式。您可以使用 ignoreInvalidExchanges 选项忽略这些异常,这意味着重新排序器会跳过任何无效的交换。

from("direct:start")
  .resequence(header("seqno")).batch().timeout(1000)
    // ignore invalid exchanges (they are discarded)
    .ignoreInvalidExchanges()
  .to("mock:result");

拒绝旧消息

rejectOld 选项可用于防止以任何顺序发送的消息,而不考虑用于重新排序消息的机制。启用 rejectOld 选项时,重新排序器拒绝传入的消息(通过抛出 MessageRejectedException 异常),如果传入的消息是 旧的 (由当前比较器定义)而不是上次发送的消息。

from("direct:start")
    .onException(MessageRejectedException.class).handled(true).to("mock:error").end()
    .resequence(header("seqno")).stream().timeout(1000).rejectOld()
    .to("mock:result");

8.7. 路由 Slip

概述

路由 slip 模式(如 图 8.8 “路由 Slip Pattern” 所示)可让您连续通过一系列处理步骤路由消息,在设计时不已知这些步骤序列,并可能因每条消息而异。消息应传递的端点列表存储在标头字段中( slip),Apache Camel 会在运行时读取以即时构建管道。

图 8.8. 路由 Slip Pattern

路由 slip

slip 标头

路由 slip 出现在用户定义的标头中,其中标头值是一个用逗号分开的端点 URI 列表。例如,一个路由 slip 用于指定一系列安全任务用于对:验证、验证和删除重复数据信息,类似于以下内容:

cxf:bean:decrypt,cxf:bean:authenticate,cxf:bean:dedup

当前的端点属性

从 Camel 2.5 中,路由 Slip 将在交换上设置一个属性(Exchange.SLIP_ENDPOINT),该交换中包含了当前端点,这可以通过 slip 实现高级。这可让您了解交换是通过 slip 进行的。

第 8.7 节 “路由 Slip” 将预先计算一个滑动,即仅计算一次滑动。如果您需要计算 slip on-the-f,则使用 第 8.18 节 “动态路由器” 模式。

Java DSL 示例

以下路由从 direct:a 端点获取信息,并从 aRoutingSlipHeader 标头中读取路由 slip:

from("direct:b").routingSlip("aRoutingSlipHeader");

您可以将标头名称指定为字符串文字或表达式。

您也可以使用 routingSlip() 的双参数形式自定义 URI 分隔符。以下示例定义了路由 slip 使用 aRoutingSlipHeader 标头密钥的路由,并使用 # 字符作为 URI 分隔符:

from("direct:c").routingSlip("aRoutingSlipHeader", "#");

XML 配置示例

以下示例演示了如何在 XML 中配置相同的路由:

<camelContext id="buildRoutingSlip" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:c"/>
    <routingSlip uriDelimiter="#">
      <headerName>aRoutingSlipHeader</headerName>
    </routingSlip>
  </route>
</camelContext>

忽略无效的端点

第 8.7 节 “路由 Slip” 现在支持 忽略InvalidEndpoints第 8.3 节 “接收者列表” 模式支持它。您可以使用它来跳过无效端点。例如:

    from("direct:a").routingSlip("myHeader").ignoreInvalidEndpoints();

在 Spring XML 中,通过在 < routingSlip> 标签上设置 ignoreInvalidEndpoints 属性来 启用这个功能:

   <route>
       <from uri="direct:a"/>
       <routingSlip ignoreInvalidEndpoints="true">
         <headerName>myHeader</headerName>
       </routingSlip>
   </route>

请考虑 myHeader 包含两个端点的情况,direct:foo,xxx:bar。第一个端点有效且可以正常工作。第二个是无效,因此忽略。当遇到无效的端点时,Apache Camel 都会在 INFO 级别记录。

选项

routingSlip DSL 命令支持以下选项:

名称

默认值

描述

uriDelimiter

,

表达式返回的多个端点时使用分隔符。

ignoreInvalidEndpoints

false

如果无法解析 endpoint uri,它应该被忽略。否则,Camel 会抛出一个异常,说明 endpoint uri 无效。

cacheSize

0

Camel 2.13.1/2.12.4: 允许配置 ProducerCache 的缓存大小,该缓存制作者在路由 slip 中重复使用。默认情况下,将使用默认的缓存大小,即 0。将值设为 -1 允许将缓存全部关闭。

8.8. Throttler

概述

throttler 是一个处理器,限制了传入消息的流率。您可以使用此模式来保护目标端点不受过载。在 Apache Camel 中,您可以使用 throttle() Java DSL 命令实施节流模式。

Java DSL 示例

要将流率限制为每秒 100 个消息,请定义路由,如下所示:

from("seda:a").throttle(100).to("seda:b");

如果需要,您可以使用 timePeriodMillis() DSL 命令自定义管理流率的时间段。例如,要将流率限制为每 30000 毫秒的 3 个消息,请按如下所示定义路由:

from("seda:a").throttle(3).timePeriodMillis(30000).to("mock:result");

XML 配置示例

以下示例演示了如何在 XML 中配置前面的路由:

<camelContext id="throttleRoute" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="seda:a"/>
    <!-- throttle 3 messages per 30 sec -->
    <throttle timePeriodMillis="30000">
      <constant>3</constant>
      <to uri="mock:result"/>
    </throttle>
  </route>
</camelContext>

动态更改每个期间的最大请求

可用的 Camel 2.8 Since 使用 Expression,您可以在运行时调整这个值,例如,为标头提供值。运行时 Camel 评估表达式并将结果转换为 java.lang.Long 类型。在以下示例中,我们使用邮件中的标头来决定每个期间的最大请求。如果缺少标头,则 第 8.8 节 “Throttler” 使用旧值。因此,在要更改值时,只允许提供标头:

<camelContext id="throttleRoute" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:expressionHeader"/>
    <throttle timePeriodMillis="500">
      <!-- use a header to determine how many messages to throttle per 0.5 sec -->
      <header>throttleValue</header>
      <to uri="mock:result"/>
    </throttle>
  </route>
</camelContext>

异步延迟

throttler 可以启用 非阻塞异步延迟,这意味着 Apache Camel 将计划以后要执行的任务。该任务负责处理路由的后方(throttler 后)。这允许调用器线程取消阻塞和服务进一步传入的信息。例如:

from("seda:a").throttle(100).asyncDelayed().to("seda:b");
注意

从 Camel 2.17 中,Throttler 将使用滚动窗口进行时间,以便更好地处理消息。但是,它将提高节流的性能。

选项

throttle DSL 命令支持以下选项:

名称

默认值

描述

maximumRequestsPerPeriod

 

节流时的最大请求数。必须提供这个选项和正数。注意在 XML DSL 中,从 Camel 2.8 开始使用此选项时,使用 Expression 而不是属性来配置。

timePeriodMillis

1000

millis 中的时间周期,在 millis 中,节流允许 最多允许最大RequestsPerPeriod 的消息数。

asyncDelayed

false

Camel 2.4: 如果启用,则任何使用调度的线程池延迟的消息都会进行。

executorServiceRef

 

Camel 2.4: 如果已启用 asyncDelay,请参阅使用自定义线程池。

callerRunsWhenRejected

true

Camel 2.4: 如果启用了 asyncDelayed,则会使用它。这将控制在线程池中拒绝该任务时调用器线程是否应该执行该任务。

8.9. Delayer

概述

delayer 是一个处理器,可让您对传入消息应用 相对 时间延迟。

Java DSL 示例

您可以使用 delay() 命令为传入消息添加 相对 时间延迟(以毫秒为单位)。例如,以下路由会根据 2 秒将所有传入的信息延迟:

from("seda:a").delay(2000).to("mock:result");

另外,您可以使用表达式指定时间延迟:

from("seda:a").delay(header("MyDelay")).to("mock:result");

以下 delay() 的 DSL 命令解释为 delay() 的子clauses。因此,在某些上下文中,需要通过插入 end() 命令来终止 delay()的子使用。例如,当 delay() 出现在 onException() 子句内时,您将按以下方式将它终止:

from("direct:start")
    .onException(Exception.class)
        .maximumRedeliveries(2)
        .backOffMultiplier(1.5)
        .handled(true)
        .delay(1000)
            .log("Halting for some time")
            .to("mock:halt")
        .end()
    .end()
    .to("mock:result");

XML 配置示例

以下示例演示了 XML DSL 中的延迟:

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="seda:a"/>
        <delay>
            <header>MyDelay</header>
        </delay>
        <to uri="mock:result"/>
    </route>
    <route>
        <from uri="seda:b"/>
        <delay>
            <constant>1000</constant>
        </delay>
        <to uri="mock:result"/>
    </route>
</camelContext>

创建自定义延迟

您可以使用一个表达式与 bean 合并来确定延迟,如下所示:

from("activemq:foo").
  delay().expression().method("someBean", "computeDelay").
  to("activemq:bar");

这里可以定义 bean 类,如下所示:

public class SomeBean {
  public long computeDelay() {
     long delay = 0;
     // use java code to compute a delay value in millis
     return delay;
 }
}

异步延迟

您可以让延迟者使用 非阻塞异步延迟,这意味着 Apache Camel 将调度以后要执行的任务。该任务负责处理路由的后方(延迟者之后)。这允许调用器线程取消阻塞和服务进一步传入的信息。例如:

from("activemq:queue:foo")
    .delay(1000)
    .asyncDelayed()
    .to("activemq:aDelayedQueue");

同一路由可以使用 XML DSL 编写,如下所示:

<route>
   <from uri="activemq:queue:foo"/>
   <delay asyncDelayed="true">
       <constant>1000</constant>
   </delay>
   <to uri="activemq:aDealyedQueue"/>
   </route>

选项

delayer 模式支持以下选项:

名称

默认值

描述

asyncDelayed

false

Camel 2.4: 如果启用,则使用调度的线程池以异步方式进行延迟。

executorServiceRef

 

Camel 2.4: 如果已启用 asyncDelay,请参阅使用自定义线程池。

callerRunsWhenRejected

true

Camel 2.4: 如果启用了 asyncDelayed,则会使用它。这将控制在线程池中拒绝该任务时调用器线程是否应该执行该任务。

8.10. Load Balancer

概述

负载均衡器 模式允许您使用各种不同负载平衡策略将消息处理委派给多个端点之一。

Java DSL 示例

以下路由利用轮询负载平衡策略在目标端点和模拟 :x模拟:y模拟:z 之间分发传入的消息:

from("direct:start").loadBalance().roundRobin().to("mock:x", "mock:y", "mock:z");

XML 配置示例

以下示例演示了如何在 XML 中配置相同的路由:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <loadBalance>
        <roundRobin/>
        <to uri="mock:x"/>
        <to uri="mock:y"/>
        <to uri="mock:z"/>
    </loadBalance>
  </route>
</camelContext>

负载均衡策略

Apache Camel 负载均衡器支持以下负载均衡策略:

轮循

轮循负载平衡策略循环遍历所有目标端点,并将每个传入的消息发送到循环中的下一个端点。例如,如果目标端点列表为 模拟:x模拟、模拟模拟:z,则传入的消息将发送到以下端点序列: 模拟:x模拟模拟模拟、模拟模拟模拟、模拟:z 等。

您可以在 Java DSL 中指定循环负载均衡策略,如下所示:

from("direct:start").loadBalance().roundRobin().to("mock:x", "mock:y", "mock:z");

另外,您可以在 XML 中配置相同的路由,如下所示:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <loadBalance>
        <roundRobin/>
        <to uri="mock:x"/>
        <to uri="mock:y"/>
        <to uri="mock:z"/>
    </loadBalance>
  </route>
</camelContext>

随机

随机负载均衡策略从指定的列表随机选择目标端点。

您可以在 Java DSL 中指定随机负载均衡策略,如下所示:

from("direct:start").loadBalance().random().to("mock:x", "mock:y", "mock:z");

另外,您可以在 XML 中配置相同的路由,如下所示:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <loadBalance>
        <random/>
        <to uri="mock:x"/>
        <to uri="mock:y"/>
        <to uri="mock:z"/>
    </loadBalance>
  </route>
</camelContext>

sticky

粘性负载均衡策略将 In 消息定向到通过从指定表达式计算哈希值来选择的端点。此负载均衡策略的优点在于,相同值的表达式始终发送到同一服务器。例如,通过计算包含用户名的标头的 hash 值,可确保特定用户的消息始终发送到同一目标端点。另一个有用的方法是指定从传入消息中提取会话 ID 的表达式。这样可确保属于同一会话的所有信息都发送到同一目标端点。

您可以在 Java DSL 中指定粘性负载均衡策略,如下所示:

from("direct:start").loadBalance().sticky(header("username")).to("mock:x", "mock:y", "mock:z");

另外,您可以在 XML 中配置相同的路由,如下所示:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <loadBalance>
      <sticky>
        <correlationExpression>
          <simple>header.username</simple>
        </correlationExpression>
      </sticky>
      <to uri="mock:x"/>
      <to uri="mock:y"/>
      <to uri="mock:z"/>
    </loadBalance>
  </route>
</camelContext>
注意

当您将 sticky 选项添加到故障切换负载均衡器时,负载均衡器将从上次已知良好的端点启动。

Topic

主题负载平衡策略会将每个 In 消息的副本发送到所有列出的目的地端点(以经济的方式将消息广播到所有目的地,如 JMS 主题)。

您可以使用 Java DSL 指定主题负载均衡策略,如下所示:

from("direct:start").loadBalance().topic().to("mock:x", "mock:y", "mock:z");

另外,您可以在 XML 中配置相同的路由,如下所示:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <loadBalance>
        <topic/>
        <to uri="mock:x"/>
        <to uri="mock:y"/>
        <to uri="mock:z"/>
    </loadBalance>
  </route>
</camelContext>

故障切换

Apache Camel 2.0 起,当 Exchange 失败时,故障转移 负载均衡器可以在处理过程中 出现异常 时尝试下一个处理器。您可以使用触发 故障切换 的特定例外列表配置故障切换。如果您没有指定任何例外,则异常会触发故障切换。故障转移负载均衡器使用与 onException 异常相同的策略来匹配异常。

如果使用流启用流缓存

如果使用 streaming,您应该在使用 故障切换负载均衡器时启用流缓存。这是必要的,以便在失败时重新读取流。

故障转移 负载均衡器支持以下选项:

选项

类型

默认值

描述

inheritErrorHandler

布尔值

true

Camel 2.3: 指定是否使用路由中配置的 错误Handler。如果要立即切换到下一个端点,您应该禁用这个选项(值为 false)。如果您启用这个选项,Apache Camel 将首先尝试使用 错误Handler 来处理消息。

例如,错误Handler 可能会配置为红色等消息,并在尝试间使用延迟。Apache Camel 最初会 尝试恢复原始 端点,并且仅在 错误Handler 耗尽时切换到下一个端点。

maximumFailoverAttempts

int

-1

Camel 2.3: 指定切换到新端点的最大尝试次数。值 0 表示 不会进行故障转移 尝试,并且值 -1 表示故障转移尝试无限数。

roundRobin

布尔值

false

Camel 2.3: 指定 故障转移 负载均衡器是否以轮循模式运行。否则,它将在 处理新消息时始终从第一个端点启动。换句话说,它会在每次消息的顶部重新启动。如果启用了轮循,它会保持状态并以轮循方式继续。使用 round robin 时,它将不 切换为最后已知的好端点,它将始终选择要使用的下一个端点。

只有在引发 IOException 异常时,以下示例才会切换到 fail。

from("direct:start")
    // here we will load balance if IOException was thrown
    // any other kind of exception will result in the Exchange as failed
    // to failover over any kind of exception we can just omit the exception
    // in the failOver DSL
    .loadBalance().failover(IOException.class)
        .to("direct:x", "direct:y", "direct:z");

您可以选择指定多个例外来故障切换,如下所示:

// enable redelivery so failover can react
errorHandler(defaultErrorHandler().maximumRedeliveries(5));

from("direct:foo")
    .loadBalance()
    .failover(IOException.class, MyOtherException.class)
    .to("direct:a", "direct:b");

您可以在 XML 中配置相同的路由,如下所示:

<route errorHandlerRef="myErrorHandler">
    <from uri="direct:foo"/>
    <loadBalance>
        <failover>
            <exception>java.io.IOException</exception>
            <exception>com.mycompany.MyOtherException</exception>
        </failover>
        <to uri="direct:a"/>
        <to uri="direct:b"/>
    </loadBalance>
</route>

以下示例演示了如何以 round robin 模式进行故障切换:

from("direct:start")
    // Use failover load balancer in stateful round robin mode,
    // which means it will fail over immediately in case of an exception
    // as it does NOT inherit error handler. It will also keep retrying, as
    // it is configured to retry indefinitely.
    .loadBalance().failover(-1, false, true)
    .to("direct:bad", "direct:bad2", "direct:good", "direct:good2");

您可以在 XML 中配置相同的路由,如下所示:

<route>
    <from uri="direct:start"/>
    <loadBalance>
        <!-- failover using stateful round robin,
        which will keep retrying the 4 endpoints indefinitely.
        You can set the maximumFailoverAttempt to break out after X attempts -->
        <failover roundRobin="true"/>
        <to uri="direct:bad"/>
        <to uri="direct:bad2"/>
        <to uri="direct:good"/>
        <to uri="direct:good2"/>
    </loadBalance>
</route>

如果要尽快切换到下一个端点,您可以通过配置 inheritErrorHandler =false 来禁用 inheritErrorHandler。通过禁用 Error Handler,您可以确保它不会干预。这样,故障转移负载均衡器可以尽快处理故障切换。如果您还要启用 roundRobin 模式,则会一直重试,直到成功为止。然后,您可以将 maximumFailoverAttempts 选项配置为高值,以便其最终耗尽和失败。

加权轮循,权重为随机

在许多企业环境中,如果无数处理能力的服务器节点正在托管服务,通常最好根据各个服务器处理容量来分发负载。可以使用 加权轮循 算法或 加权随机 算法来解决这个问题。

通过加权负载平衡策略,您可以为其他每台服务器指定处理负载 分布比。您可以将这个值指定为每台服务器的正处理权重。大于数字表示服务器可以处理更大的负载。处理 weight 用于确定与其他人相关的每个处理端点的有效负载分发率。

下表中描述了可以使用的参数:

表 8.3. 加权选项

选项类型默认值描述

roundRobin

布尔值

false

round-robin 的默认值为 false。如果没有这一设置或参数,使用的负载平衡算法是随机的。

distributionRatioDelimiter

字符串

,

distributionRatioDelimiter 是用于指定 distributionRatio 的分隔符。如果没有指定此属性 逗号是默认分隔符。

以下 Java DSL 示例演示了如何定义加权轮循路由和加权随机路由:

// Java
// round-robin
from("direct:start")
  .loadBalance().weighted(true, "4:2:1" distributionRatioDelimiter=":")
  .to("mock:x", "mock:y", "mock:z");

//random
from("direct:start")
  .loadBalance().weighted(false, "4,2,1")
  .to("mock:x", "mock:y", "mock:z");

您可以在 XML 中配置循环路由,如下所示:

<!-- round-robin -->
<route>
  <from uri="direct:start"/>
  <loadBalance>
    <weighted roundRobin="true" distributionRatio="4:2:1" distributionRatioDelimiter=":" />
    <to uri="mock:x"/>
    <to uri="mock:y"/>
    <to uri="mock:z"/>
  </loadBalance>
</route>

自定义负载均衡器

您还可以使用自定义负载均衡器(如您自己的实施)。

使用 Java DSL 的示例:

from("direct:start")
     // using our custom load balancer
     .loadBalance(new MyLoadBalancer())
     .to("mock:x", "mock:y", "mock:z");

以及使用 XML DSL 相同的示例:

<!-- this is the implementation of our custom load balancer -->
 <bean id="myBalancer" class="org.apache.camel.processor.CustomLoadBalanceTest$MyLoadBalancer"/>

 <camelContext xmlns="http://camel.apache.org/schema/spring">
   <route>
     <from uri="direct:start"/>
     <loadBalance>
       <!-- refer to my custom load balancer -->
       <custom ref="myBalancer"/>
       <!-- these are the endpoints to balancer -->
       <to uri="mock:x"/>
       <to uri="mock:y"/>
       <to uri="mock:z"/>
     </loadBalance>
   </route>
 </camelContext>

请注意,在上面的 XML DSL 中,使用 <custom>,它只在 Camel 2.8 起提供。在旧的版本中,您必须按如下操作:

       <loadBalance ref="myBalancer">
         <!-- these are the endpoints to balancer -->
         <to uri="mock:x"/>
         <to uri="mock:y"/>
         <to uri="mock:z"/>
       </loadBalance>

要实现自定义负载均衡器,您可以扩展一些支持类,如 LoadBalancerSupportSimpleLoadBalancerSupport。前者支持异步路由引擎,而后者则不支持。下面是一个示例:

public static class MyLoadBalancer extends LoadBalancerSupport {

     public boolean process(Exchange exchange, AsyncCallback callback) {
         String body = exchange.getIn().getBody(String.class);
         try {
             if ("x".equals(body)) {
                 getProcessors().get(0).process(exchange);
             } else if ("y".equals(body)) {
                 getProcessors().get(1).process(exchange);
             } else {
                 getProcessors().get(2).process(exchange);
             }
         } catch (Throwable e) {
             exchange.setException(e);
         }
         callback.done(true);
         return true;
     }
 }

断路器

Circuit Breaker 负载均衡器是一个有状态模式,用于监控特定异常的所有调用。最初,断路器处于关闭状态并传递所有消息。如果失败并且达到阈值,则会进入 open 状态并拒绝所有调用,直到达到 一半OpenAfter 超时。在超时后,如果存在新调用,则 Circuit Breaker 将传递所有消息。如果结果成功,则 Circuit Breaker 将变为闭路状态(如果不是),它会重新变为开状态。

Java DSL 示例:

from("direct:start").loadBalance()
    .circuitBreaker(2, 1000L, MyCustomException.class)
    .to("mock:result");

Spring XML 示例:

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
    <route>
    <from uri="direct:start"/>
    <loadBalance>
        <circuitBreaker threshold="2" halfOpenAfter="1000">
            <exception>MyCustomException</exception>
        </circuitBreaker>
        <to uri="mock:result"/>
    </loadBalance>
</route>
</camelContext>

8.11. Hystrix

概述

由 Camel 2.18 提供。

Hystrix 模式可让应用程序与 Netflix Hystrix 集成,这可以在 Camel 路由中提供断路器。Hystrix 是一个延迟和容错库,旨在

  • 隔离对远程系统、服务和第三方库的访问点
  • 停止级联失败
  • 在复杂的分布式系统中启用弹性,其中故障不可避免

如果您使用 maven,请在 pom.xml 文件中添加以下依赖项以使用 Hystrix:

<dependency>
      <groupId>org.apache.camel</groupId>
      <artifactId>camel-hystrix</artifactId>
      <version>x.x.x</version>
      <!-- Specify the same version as your Camel core version. -->
</dependency>

Java DSL 示例

以下是一个示例路由,它演示了 Hystrix 端点,通过回退到行的回退路由来防止运行缓慢。默认情况下,超时请求只是 1000ms,因此 HTTP 端点必须相当快速成功。

from("direct:start")
    .hystrix()
        .to("http://fooservice.com/slow")
    .onFallback()
        .transform().constant("Fallback message")
    .end()
    .to("mock:result");

XML 配置示例

以下是相同的示例,但在 XML 中:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <hystrix>
      <to uri="http://fooservice.com/slow"/>
      <onFallback>
        <transform>
          <constant>Fallback message</constant>
        </transform>
      </onFallback>
    </hystrix>
    <to uri="mock:result"/>
  </route>
</camelContext>

使用 Hystrix 回退功能

onFallback() 方法用于本地处理,您可以转换消息或调用 bean 或其他内容作为回退。如果您需要通过网络调用外部服务,那么您应该使用 onFallbackViaNetwork() 方法,它在使用其自己的线程池的独立 HystrixCommand 对象中运行,使它不会耗尽第一个命令对象。

Hystrix 配置示例

Hystrix 有许多选项,如下一节中所述。以下示例显示,用于将执行超时设置为 5 秒的 Java DSL,而不是默认的 1 秒,并让断路器等待 10 秒,而不是 5 秒(默认),在状态停止打开前再次尝试请求。

from("direct:start")
    .hystrix()
        .hystrixConfiguration()
             .executionTimeoutInMilliseconds(5000).circuitBreakerSleepWindowInMilliseconds(10000)
        .end()
        .to("http://fooservice.com/slow")
    .onFallback()
        .transform().constant("Fallback message")
    .end()
    .to("mock:result");

以下是相同的示例,但在 XML 中:

<camelContext xmlns="http://camel.apache.org/schema/spring">
<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <hystrix>
      <hystrixConfiguration executionTimeoutInMilliseconds="5000" circuitBreakerSleepWindowInMilliseconds="10000"/>
      <to uri="http://fooservice.com/slow"/>
      <onFallback>
        <transform>
          <constant>Fallback message</constant>
        </transform>
      </onFallback>
    </hystrix>
    <to uri="mock:result"/>
  </route>
</camelContext>
 You can also configure Hystrix globally and then refer to that
configuration. For example:
<camelContext xmlns="http://camel.apache.org/schema/spring">
   <!-- This is a shared config that you can refer to from all Hystrix patterns. -->
   <hystrixConfiguration id="sharedConfig" executionTimeoutInMilliseconds="5000" circuitBreakerSleepWindowInMilliseconds="10000"/>

   <route>
         <from uri="direct:start"/>
         <hystrix hystrixConfigurationRef="sharedConfig">
         <to uri="http://fooservice.com/slow"/>
         <onFallback>
            <transform>
               <constant>Fallback message</constant>
            </transform>
         </onFallback>
      </hystrix>
      <to uri="mock:result"/>
   </route>
</camelContext>

选项

ths Hystrix 组件支持以下选项:Hystrix 提供默认值。

名称默认值类型描述

circuitBreakerEnabled

true

布尔值

决定断路器是否用于跟踪健康和短路请求(如果它出差)。

circuitBreakerErrorThresholdPercentage

50

整数

设置在 或以上处的错误百分比,电路应开路并启动短路到回退逻辑。

circuitBreakerForceClosed

false

布尔值

值 true 会强制断路器进入闭路状态,而无论错误百分比如何,它都允许请求请求。

circuitBreakerForceOpen

false

布尔值