2.10. 定期実行ルートポリシー
2.10.1. 定期実行ルートポリシーの概要
概要
定期実行ルートポリシーは、実行時にルートに影響するイベントをトリガーすることができます。特に、現在利用可能な実装では、ポリシーで指定された任意の時刻 (または複数時刻) にルートを開始、停止、中断、または再開することができます。
タスクのスケジューリング
定時実行ルートポリシーは、次のようなイベントを発生させることができます。
- ルートの開始: 指定した時刻 (または複数時刻) でルートを開始します。このイベントは、ルートが現在停止状態にあり、起動を待っている場合にのみ有効になります。
- ルートの停止: 指定した時刻 (または複数時刻) でルートを停止します。このイベントは、ルートが現在アクティブの場合にのみ有効になります。
-
ルートの一時停止: ルートの先頭にあるコンシューマーエンドポイントを (
from()
で指定したように) 一時的に非アクティブにします。ルートの残りの部分はアクティブですが、クライアントはルートに新しいメッセージを送信することはできません。 - ルートの再開 : ルートの先頭にあるコンシューマーエンドポイントを再アクティブにし、ルートを完全にアクティブな状態に戻します。
Quartz コンポーネント
Quartz コンポーネントは、ジョブスケジューラーのオープンソース実装である Terratania の Quartz をベースにした Timer コンポーネントです。Quartz コンポーネントは、単純な定期実行ルートポリシーと cron 定期実行ルートポリシーの両方の基礎となる実装を提供しています。
2.10.2. 単純な定期実行ルートポリシー
概要
定期実行ルートポリシーは、ルートの開始、停止、一時停止、および再開を可能にするルートポリシーで、これらのイベントのタイミングは、初回イベントの発生時刻で指定し、(オプションで) その後の繰り返し回数も指定できます。単純な定期実行ルートポリシーを定義するには、以下のクラスのインスタンスを作成します。
org.apache.camel.routepolicy.quartz.SimpleScheduledRoutePolicy
依存関係
単純な定期実行ルートポリシーは、Quartz コンポーネント camel-quartz
に依存しています。たとえば、Maven をビルドシステムとして使用する場合は、アーティファクト camel-quartz
の依存関係を追加してください。
Java DSL の例
例2.7「単純な定期実行ルートの Java DSL の例」 は、Java DSL を使用して起動するルートをスケジュールする方法を示しています。初回の起動時刻 startTime
は、現在時刻から 3 秒後に設定されています。また、このポリシーは、初期起動時刻の 3 秒後に、2 回目のルートを開始するように設定されています。これは、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 では、route
要素に 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()
を呼び出して 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();
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]
これらのログを表示したくない場合は、logInflightExchangesOnTimeout
オプションを false に設定してこれをオフにできます。
context.getShutdownStrategegy().setLogInflightExchangesOnTimeout(false);
タスクのスケジューリング
単純な定期実行ルートポリシーを使用して、以下のスケジュールタスクのいずれかを定義することができます。
ルートの開始
次の表は、ルートの開始を 1 回以上スケジューリングするためのパラメーターを示しています。
パラメーター | 型 | デフォルト | 説明 |
---|---|---|---|
|
| なし | ルートの初回起動日時を指定します。 |
|
|
| 0 以外の値に設定すると、ルートの開始回数が指定されます。 |
|
|
| 開始の間隔 (ミリ秒単位) を指定します。 |
ルートの停止
次の表は、ルートの停止を 1 回以上スケジューリングするためのパラメーターを示しています。
パラメーター | 型 | デフォルト | 説明 |
---|---|---|---|
|
| なし | ルートの初回停止日時を指定します。 |
|
|
| 0 以外の値に設定すると、ルートの停止回数が指定されます。 |
|
|
| 停止の間隔 (ミリ秒単位) を指定します。 |
|
|
| ルートを強制停止する前に、現在のエクスチェンジの処理が終了するまで待つ時間 (猶予期間) を指定します。猶予期間が無限の場合は 0 に設定します。 |
|
|
| 猶予期間の時間単位を指定します。 |
ルートの一時停止
次の表は、ルートの一時停止を 1 回以上スケジュールするためのパラメーターを示しています。
パラメーター | 型 | デフォルト | 説明 |
---|---|---|---|
|
| なし | ルートが初めて一時停止される日時を指定します。 |
|
| 0 | 0 以外の値に設定すると、ルートが一時停止される回数が指定されます。 |
|
| 0 | 一時停止の間隔 (ミリ秒単位) を指定します。 |
ルートの再開
次の表は、ルートの再開を 1 回以上スケジュールするためのパラメーターを示しています。
パラメーター | 型 | デフォルト | 説明 |
---|---|---|---|
|
| なし | ルートの初回再開日時を指定します。 |
|
| 0 | 0 以外の値に設定すると、ルートの再開回数が指定されます。 |
|
| 0 | 再開の間隔をミリ秒単位で指定します。 |
2.10.3. cron 定期実行ルートポリシー
概要
cron 定期実行ルートポリシーは、cron 式で指定することで、ルートの開始、停止、一時停止、および再開を可能にするルートポリシーです。cron 定期実行ルートポリシーを定義するには、以下のクラスのインスタンスを作成します。
org.apache.camel.routepolicy.quartz.CronScheduledRoutePolicy
依存関係
単純な定期実行ルートポリシーは、Quartz コンポーネント camel-quartz
に依存しています。たとえば、Maven をビルドシステムとして使用する場合は、アーティファクト camel-quartz
の依存関係を追加してください。
Java DSL の例
例2.9「cron 定期実行ルートの Java DSL の例」 は、Java DSL を使用して起動するルートをスケジュールする方法を示しています。このポリシーは、3 秒ごとに開始イベントをトリガーする cron 式 \*/3 * * * * ?
で設定されています。
Java DSL では、ルート内で routePolicy()
DSL コマンドを呼び出して、ルートポリシーをルートにアタッチします。
例2.9 cron 定期実行ルートの 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 定期実行ルートの XML DSL の例」 は、XML DSL を使用して起動するルートをスケジュールする方法を示しています。
XML DSL では、route
要素に routePolicyRef
属性を設定して、ルートポリシーをルートにアタッチします。
例2.10 cron 定期実行ルートの 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 システム上でバックグラウンドで実行するジョブをスケジュールする UNIX cron
ユーティリティーに由来しています。cron 式は、日付と時刻にワイルドカードを使用することで、単一のイベントまたは定期的に繰り返される複数のイベントを効果的に指定することができる構文です。
cron 式は、以下の順序の 6 または 7 個のフィールドで設定されます。
Seconds Minutes Hours DayOfMonth Month DayOfWeek [Year]
Year
フィールドは任意のフィールドで、一度だけ発生するイベントを定義する場合を除き、通常は省略できます。各フィールドは、リテラルと特殊文字の組み合わせで設定されます。たとえば、以下の cron 式は、毎日 1 回夜 12 時に発生するイベントを指定します。
0 0 24 * * ?
*
文字は、フィールドのすべての値にマッチするワイルドカードです。したがって、上記の式は毎月の毎日を意味します。?
の文字は、フィールドの無視を意味するダミーのプレースホルダーです。DayOfMonth
フィールド または DayOfWeek
フィールドの両方を同時に指定するのは論理的ではないので、常にどちらかのフィールドにこの文字を指定します。たとえば、1 日 1 回発生するイベントを、月曜日から金曜日までのみスケジュールする場合は、以下の cron 式を使用します。
0 0 24 ? * MON-FRI
MON-FRI
は、ハイフン文字で範囲を指定しています。/
(スラッシュ) を使用してインクリメントを指定することもできます。たとえば、5 分ごとにイベントが発生するように指定するには、以下の cron 式を使用します。
0 0/5 * * * ?
cron 式構文の完全な説明は、Wikipedia の CRON 式 に関する記事を参照してください。
タスクのスケジューリング
cron 定期実行ルートポリシーを使用して、以下のスケジューリングタスクのいずれかを定義することができます。
ルートの開始
次の表は、ルートの開始を 1 回以上スケジューリングするためのパラメーターを示しています。
パラメーター | 型 | デフォルト | 説明 |
---|---|---|---|
|
| なし | 1 つ以上のルート開始イベントをトリガーする cron 式を指定します。 |
ルートの停止
次の表は、ルートの停止を 1 回以上スケジューリングするためのパラメーターを示しています。
パラメーター | 型 | デフォルト | 説明 |
---|---|---|---|
|
| なし | 1 つ以上のルート停止イベントをトリガーする cron 式を指定します。 |
|
|
| ルートを強制停止する前に、現在のエクスチェンジの処理が終了するまで待つ時間 (猶予期間) を指定します。猶予期間が無限の場合は 0 に設定します。 |
|
|
| 猶予期間の時間単位を指定します。 |
ルートの一時停止
次の表は、ルートの一時停止を 1 回以上スケジュールするためのパラメーターを示しています。
パラメーター | 型 | デフォルト | 説明 |
---|---|---|---|
|
| なし | 1 つ以上のルート一時停止イベントをトリガーする cron 式を指定します。 |
ルートの再開
次の表は、ルートの再開を 1 回以上スケジュールするためのパラメーターを示しています。
パラメーター | 型 | デフォルト | 説明 |
---|---|---|---|
|
| なし | 1 つ以上のルート再開イベントをトリガーする cron 式を指定します。 |
2.10.4. ルートポリシーファクトリー
ルートポリシーファクトリーの使用
Camel 2.14 から利用可能
すべてのルートにルートポリシーを使用する場合は、org.apache.camel.spi.RoutePolicyFactory
をファクトリーとして使用して、個々のルートに RoutePolicy
インスタンスを作成することができます。これは、すべてのルートに同じ種類のルートポリシーを使用する場合に使用することができます。そうすれば、ファクトリーの設定は 1 度だけで済み、作成されたすべてのルートにポリシーが割り当てられます。
CamelContext には、以下のようなファクトリーを追加するための API が用意されています。
context.addRoutePolicyFactory(new MyRoutePolicyFactory());
XML DSL では、ファクトリーで <bean>
を定義するだけです。
<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);
ルートポリシーファクトリーはいくつでも持つことができます。addRoutePolicyFactory
を再度呼び出すか、他のファクトリーを XML で <bean>
と宣言します。