2.10. 定期実行ルートポリシー

定期実行ルートポリシーは、実行時にルートに影響するイベントをトリガーすることができます。特に、現在利用可能な実装では、ポリシーで指定された任意の時刻 (または複数時刻) にルートを開始、停止、中断、または再開することができます。

定時実行ルートポリシーは、次のようなイベントを発生させることができます。

Quartz コンポーネントは、ジョブスケジューラーのオープンソース実装である Terratania の Quartz をベースにした Timer コンポーネントです。Quartz コンポーネントは、単純な定期実行ルートポリシーと cron 定期実行ルートポリシーの両方の基礎となる実装を提供しています。

定期実行ルートポリシーは、ルートの開始、停止、一時停止、および再開を可能にするルートポリシーで、これらのイベントのタイミングは、初回イベントの発生時刻で指定し、(オプションで) その後の繰り返し回数も指定できます。単純な定期実行ルートポリシーを定義するには、以下のクラスのインスタンスを作成します。

org.apache.camel.routepolicy.quartz.SimpleScheduledRoutePolicy

org.apache.camel.routepolicy.quartz.SimpleScheduledRoutePolicy

単純な定期実行ルートポリシーは、Quartz コンポーネント camel-quartz に依存しています。たとえば、Maven をビルドシステムとして使用する場合は、アーティファクト camel-quartz の依存関係を追加してください。

例2.7「単純な定期実行ルートの Java DSL の例」 は、Java DSL を使用して起動するルートをスケジュールする方法を示しています。初回の起動時刻 startTime は、現在時刻から 3 秒後に設定されています。また、このポリシーは、初期起動時刻の 3 秒後に、2 回目のルートを開始するように設定されています。これは、routeStartRepeatCount を 1 に設定し、routeStartRepeatInterval を 3000 ミリ秒に設定することで設定されます。

Java DSL では、ルート内で routePolicy() 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");

// 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");

例2.8「単純な定期実行ルートの XML DSL の例」 は、XML DSL を使用して起動するルートをスケジュールする方法を示しています。

XML DSL では、route 要素に routePolicyRef 属性を設定して、ルートポリシーをルートにアタッチします。

<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>

<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>

単純な定期実行ルートポリシーで使用されるトリガーの初動時刻は、java.util.Date タイプを使用して指定します。Date インスタンスを定義する最も柔軟な方法は、java.util.GregorianCalendar クラスを使用することです。GregorianCalendar クラスの便利なコンストラクターとメソッドを使用して日付を定義し、GregorianCalendar.getTime() を呼び出して Date インスタンスを取得します。

たとえば、2011 年 1 月 1 日正午の日時を定義するには、以下のように GregorianCalendar コンストラクターを呼び出します。

// 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();

// 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 クラスは、異なるタイムゾーンの時間の定義もサポートします。デフォルトでは、コンピューターのローカルタイムゾーンを使用します。

単純な定期実行ルートポリシーを設定してルートを停止すると、ルートの停止アルゴリズムが自動的に正常シャットダウンの手順に統合されます (「ルートの起動およびシャットダウンの制御」 を参照)。よって、タスクは現在のエクスチェンジが処理を完了するまで待機してから、ルートをシャットダウンします。ただし、タイムアウトを設定することで、ルートがエクスチェンジの処理を終了したかどうかにかかわらず、指定した時間後にルートを強制的に停止することができます。

指定のタイムアウト期間内に正常シャットダウンが適切に行われなかった場合、Apache Camel はより強行なシャットダウンを実行します。ルートやスレッドプールなどを強制的にシャットダウンします。

タイムアウト後、Apache Camel は現在処理中のエクスチェンジの情報をログに記録します。エクスチェンジの元および現在のルートをログに記録します。

たとえば、以下のログは、1 つの処理中のエクスチェンジがあり、その元のルートは 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]

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);

  context.getShutdownStrategegy().setLogInflightExchangesOnTimeout(false);

単純な定期実行ルートポリシーを使用して、以下のスケジュールタスクのいずれかを定義することができます。

次の表は、ルートの開始を 1 回以上スケジューリングするためのパラメーターを示しています。

次の表は、ルートの停止を 1 回以上スケジューリングするためのパラメーターを示しています。

次の表は、ルートの一時停止を 1 回以上スケジュールするためのパラメーターを示しています。

次の表は、ルートの再開を 1 回以上スケジュールするためのパラメーターを示しています。

cron 定期実行ルートポリシーは、cron 式で指定することで、ルートの開始、停止、一時停止、および再開を可能にするルートポリシーです。cron 定期実行ルートポリシーを定義するには、以下のクラスのインスタンスを作成します。

org.apache.camel.routepolicy.quartz.CronScheduledRoutePolicy

org.apache.camel.routepolicy.quartz.CronScheduledRoutePolicy

単純な定期実行ルートポリシーは、Quartz コンポーネント camel-quartz に依存しています。たとえば、Maven をビルドシステムとして使用する場合は、アーティファクト camel-quartz の依存関係を追加してください。

例2.9「cron 定期実行ルートの Java DSL の例」 は、Java DSL を使用して起動するルートをスケジュールする方法を示しています。このポリシーは、3 秒ごとに開始イベントをトリガーする cron 式 \*/3 * * * * ? で設定されています。

Java DSL では、ルート内で routePolicy() DSL コマンドを呼び出して、ルートポリシーをルートにアタッチします。

// Java
CronScheduledRoutePolicy policy = new CronScheduledRoutePolicy();
policy.setRouteStartTime("*/3 * * * * ?");

from("direct:start")
    .routeId("test")
    .routePolicy(policy)
    .to("mock:success");;

// Java
CronScheduledRoutePolicy policy = new CronScheduledRoutePolicy();
policy.setRouteStartTime("*/3 * * * * ?");

from("direct:start")
    .routeId("test")
    .routePolicy(policy)
    .to("mock:success");;

例2.10「cron 定期実行ルートの XML DSL の例」 は、XML DSL を使用して起動するルートをスケジュールする方法を示しています。

XML DSL では、route 要素に routePolicyRef 属性を設定して、ルートポリシーをルートにアタッチします。

<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>

<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>

cron 式 の構文は、UNIX システム上でバックグラウンドで実行するジョブをスケジュールする UNIX cron ユーティリティーに由来しています。cron 式は、日付と時刻にワイルドカードを使用することで、単一のイベントまたは定期的に繰り返される複数のイベントを効果的に指定することができる構文です。

cron 式は、以下の順序の 6 または 7 個のフィールドで設定されます。

Seconds Minutes Hours DayOfMonth Month DayOfWeek [Year]

Seconds Minutes Hours DayOfMonth Month DayOfWeek [Year]

Year フィールドは任意のフィールドで、一度だけ発生するイベントを定義する場合を除き、通常は省略できます。各フィールドは、リテラルと特殊文字の組み合わせで設定されます。たとえば、以下の cron 式は、毎日 1 回夜 12 時に発生するイベントを指定します。

0 0 24 * * ?

0 0 24 * * ?

* 文字は、フィールドのすべての値にマッチするワイルドカードです。したがって、上記の式は毎月の毎日を意味します。? の文字は、フィールドの無視を意味するダミーのプレースホルダーです。DayOfMonth フィールド または DayOfWeek フィールドの両方を同時に指定するのは論理的ではないので、常にどちらかのフィールドにこの文字を指定します。たとえば、1 日 1 回発生するイベントを、月曜日から金曜日までのみスケジュールする場合は、以下の cron 式を使用します。

0 0 24 ? * MON-FRI

0 0 24 ? * MON-FRI

MON-FRI は、ハイフン文字で範囲を指定しています。/ (スラッシュ) を使用してインクリメントを指定することもできます。たとえば、5 分ごとにイベントが発生するように指定するには、以下の cron 式を使用します。

0 0/5 * * * ?

0 0/5 * * * ?

cron 式構文の完全な説明は、Wikipedia の CRON 式 に関する記事を参照してください。

cron 定期実行ルートポリシーを使用して、以下のスケジューリングタスクのいずれかを定義することができます。

次の表は、ルートの開始を 1 回以上スケジューリングするためのパラメーターを示しています。

次の表は、ルートの停止を 1 回以上スケジューリングするためのパラメーターを示しています。

次の表は、ルートの一時停止を 1 回以上スケジュールするためのパラメーターを示しています。

次の表は、ルートの再開を 1 回以上スケジュールするためのパラメーターを示しています。

Camel 2.14 から利用可能

すべてのルートにルートポリシーを使用する場合は、org.apache.camel.spi.RoutePolicyFactory をファクトリーとして使用して、個々のルートに RoutePolicy インスタンスを作成することができます。これは、すべてのルートに同じ種類のルートポリシーを使用する場合に使用することができます。そうすれば、ファクトリーの設定は 1 度だけで済み、作成されたすべてのルートにポリシーが割り当てられます。

CamelContext には、以下のようなファクトリーを追加するための API が用意されています。

context.addRoutePolicyFactory(new MyRoutePolicyFactory());

context.addRoutePolicyFactory(new MyRoutePolicyFactory());

XML DSL では、ファクトリーで <bean> を定義するだけです。

<bean id="myRoutePolicyFactory" class="com.foo.MyRoutePolicyFactory"/>

<bean id="myRoutePolicyFactory" class="com.foo.MyRoutePolicyFactory"/>

ファクトリーには、ルートポリシーを作成するための 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);

/**
 * 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 で <bean> と宣言します。