JMS リスナーは、JMS 準拠のメッセージングシステムのキューまたはトピックから送信されたメッセージに対して Active Sync 処理を実行する機能を備えた、JMS (Java Message Service) クライアントです。
このアダプタはソース専用アダプタで、メッセージをキューやトピックに書き戻しすることはできません。
JMS リスナーリソースアダプタは、com.waveset.adapter.JmsListenerResourceAdapter クラスで定義されます。
JMS リスナーアダプタは、JMS (Java Message Service) オープン標準のバージョン 1.1 以降をサポートするメッセージングシステムのみと対話できます。
アダプタは、指定した接続ファクトリおよび宛先の標準の JNDI 検索を通して、ソース JMS メッセージングシステムのトピックまたはキューと対話します。したがって、メッセージングシステムの管理者は、接続ファクトリと宛先があらかじめ作成済みで、標準の JNDI 検索によって使用可能であることを確認する必要があります。
JMS リスナーリソースアダプタは、次のものをサポートするアプリケーションサーバー環境でのみ使用されます。
Client API for JMS、バージョン 1.1 以降
JNDI (Java Naming and Directory Interface) API 1.1 以降
アプリケーションサーバーの管理者は、Identity Manager の Web アプリケーションが、ソース JMS メッセージングシステムに適した JMS 接続ファクトリと宛先オブジェクトに対して、JNDI 経由で正常にバインドできることを確認する必要があります。
ここでは、JMS リスナーリソースアダプタの使用に関する情報を示します。 次のトピックで構成されています。
Active Sync 処理が開始されると、まず、「接続ファクトリの JNDI 名」リソースパラメータフィールドで指定された接続ファクトリを使用して、ソースメッセージングシステムへの接続が作成されます。「ユーザー」および「パスワード」フィールドが指定されている場合は、接続を確立するときに、これらが認証に使用されます。これらのフィールドが指定されていない場合は、デフォルトの認証を使用して接続が確立されます。
JMS リスナーアダプタは、同期モードで操作します。「宛先の JNDI 名」フィールドによって指定されたキューまたはトピックの宛先で、同期メッセージコンシューマが確立されます。各ポーリング間隔で、アダプタは提供されるすべてのメッセージを受信および処理します。「メッセージセレクタ」フィールドの有効な JMS メッセージセレクタ文字列を定義することで、メッセージを必要に応じて追加修飾することもできます。
接続ファクトリと宛先の属性によって、指定した宛先タイプに対応するオブジェクトを指定します。宛先タイプに「永続性トピック」を指定した場合、「永続性トピック ClientID」および「永続性トピック登録ラベル」という追加フィールドを使用して、永続性登録を設定します。
修飾されたメッセージをアダプタが処理する場合、まず、「メッセージマッピング」フィールドによって指定されたメカニズムを使用して、受信した JMS メッセージを名前付きの値のマップに変換します。変換されたマップは、メッセージ値マップと呼ばれます。
次に、メッセージ値マップは、アカウント属性のスキーママップを使用して、Active Sync マップに変換されます。アダプタにアカウント属性が指定されている場合、アダプタは、スキーママップにリソースユーザー属性としても表示されているキー名で、メッセージ値マップを検索します。値が存在すれば Active Sync マップにコピーされますが、Active Sync マップ内のエントリ名は、スキーママップ内のアイデンティティーシステムのユーザー属性の列で指定された名前に変換されます。
メッセージ値マップにアカウント属性のスキーママップを使用して変換できないエントリが存在する場合は、メッセージ値マップのエントリは、変更されずに Active Sync マップにコピーされます。
配信の保証は、メッセージの送信者側に責任があります。メッセージシステムによって配信されるまで、持続的に送信されたメッセージのみが保存されます。これにより、メッセージシステムのクラッシュまたはシャットダウンのためにメッセージが失われることを確実に防止できます。この仕組みは once-and-only-once 配信と呼ばれます。
「Reliable Messaging サポート」フィールドは、アダプタが処理する信頼性の高いメッセージ処理の書式を示します。
LOCAL に設定すると、アダプタに対して JMS セッションが実行されます。処理段階でエラーが発生したかどうかに関係なく、このセッションはメッセージが処理されたあとに常にコミットされます。これにより、メッセージが確実に 1 回だけ処理されます。
AUTO に設定すると、セッションは処理されませんが、メッセージは AUTO_ACK の JMS 定義に従って即座に自動認識されます。
DUPS_OK に設定すると、セッションは処理されませんが、メッセージは DUPS_OK_ACK の JMS 定義に従って即座に自動認識されます。
CLIENT に設定すると、セッションは処理されず、メッセージはアダプタに認識されません。その代わりに、「メッセージライフサイクルリスナー」フィールドに指定されたライフサイクルリスナーが、必要に応じてメッセージを認識します。ライフサイクルリスナーは、AWAITING_CLIENT_ACK ライフサイクルイベントとともに、受信確認が行われる典型的なポイントで呼び出されます。このモードが必要になることはほとんどありません。
「メッセージライフサイクルリスナー」フィールドでは、任意のライフサイクルリスナークラスをアダプタに登録できます。ライフサイクルリスナーを使用すると、次のものを実行できます。
アダプタの処理段階のカスタムログ
アダプタの処理段階におけるデータのカスタム操作
CLIENT_ACK モードで受信したメッセージのカスタム認識
メッセージングシステムに対する接続を失った場合 (メッセージングシステムサーバーがシャットダウンされた場合など)、リスナーを再度確立するために、メッセージングシステムに対して定期的に再接続を試みるように、アダプタを設定できます。
「例外発生時に再初期化」チェックボックスをオンにすると、再接続動作が使用可能になります。「接続再試行間隔 (秒)」フィールドを使用して、再接続の試行間隔が設定できます。
JMS リスナーアダプタは、Java Management Extensions (JMX) で監視できる複数の属性および操作を提供します。Identity Manager サーバーでの JMX の設定については、『Business Administrator's Guide』の設定に関する章を参照してください。
Active Sync プロセスが実行されている (かつ信頼できる MBean を含む) サーバーでは、指定されたウィンドウの時間に基づいて統計値が計算されます。setWindowMillis 操作は、期間の長さを設定します。統計値が計算されるたびに、統計ウィンドウの実際の期間が ActualWindowTime 属性として記録されます。
たとえば setWindowMillis 操作が 10000 (10 秒) に設定できても、ActualWindowTime には実際のウィンドウが 10.005 秒であったことを示す値 10005 が含まれる可能性があります。MsgCountInWindow などその他の属性は、実際のウィンドウを使用して統計値を計測またはカウントします。MsgCountInWindow に値 63 が含まれる場合、10.005 秒間に 63 個のメッセージが JMS から取得されたことになります。
次の表に、アダプタが JMX で使用できるようにする属性および操作を示します。属性および操作は、JMX コンソールから IDM/Cluster/ Synchronization/Active Sync/JMS Listener/SyncStats:DestinationName で確認できます。DestinationName の値は、「宛先タイプ」および「宛先の JNDI 名」リソースパラメータの値を結合して生成されます。
属性 |
説明 |
---|---|
ActualWindowTime |
最新のウィンドウの実際の時間 (ミリ秒) を示します。 |
Attributes |
アダプタのリソースパラメータの値を一覧表示します。 |
Authoritative |
サーバーが Active Sync プロセスを実行しているサーバーであるかどうかを示します。 |
AvgMsgWaitTime |
メッセージの待機に費やされた平均の時間 (ミリ秒) を示します。 |
AvgProcessTime |
メッセージの処理に費やされた平均の時間 (ミリ秒) を示します。 |
CurrentMsgWaitStart |
現在のメッセージ待機の待機が開始した日付と時刻を示します。 保留中の待機がない場合は NULL です。 |
CurrentMsgWaitTime |
メッセージの待機に費やされたミリ秒を示します。 |
CurrentPollStart |
Active Sync が現在実行中の場合に、Active Sync が最後に開始した日付と時刻を示します。 |
CurrentProcessStart |
現在処理中のメッセージの処理が開始した日付と時刻を示します。 |
CurrentProcessTime |
現在のメッセージの処理に費やされたミリ秒の合計を示します。値が 0 の場合は、メッセージが処理されていないことを示しています。 |
LastCalculatedPollTime |
現在のポーリングが含まれるポーリングループにおけるミリ秒について、最後に計算された時点での合計を示します。 |
MaxMsgWaitTime |
1 メッセージの待機に費やされる最大ミリ秒を示します。 |
MaxPollTime |
1 ポーリングサイクルの最大ミリ秒を示します。 |
MaxProcessTime |
1 メッセージの処理に費やされる最大ミリ秒を示します。 |
MsgCountInWindow |
最後のウィンドウの時間中に受信したメッセージ数を示します。 |
MsgPerUnittime |
指定されたウィンドウ中に処理されたメッセージ数を示します。 |
PollMsgWaitPercent |
メッセージの待機に費やされた時間の割合を示します。 |
PollOtherPercent |
オーバーヘッドとして費やされた時間の割合を示します。 |
PollProcessPercent |
メッセージの処理に費やされた時間の割合を示します。 |
PollStatistics |
最新のウィンドウの実際の時間を示します。 |
TotMsgCount |
受信したメッセージの合計数を示します。 |
TotMsgWaitTime |
メッセージの待機に費やされたミリ秒の合計を示します。 |
TotProcessTime |
メッセージの処理に費やされたミリ秒の合計を示します。 |
操作 |
説明 |
---|---|
getWindowMillis |
統計ウィンドウの期間 (ミリ秒) を取得します。この操作は、Authoritative 属性が true の場合のみ使用できます。 |
refreshAttributes |
リソース属性の最新の値を返します。 |
resetStatistics |
アダプタの統計値をリセットします。この操作は、Authoritative 属性が true の場合のみ使用できます。 |
setWindowMillis |
統計ウィンドウの期間 (ミリ秒) を設定します。この操作は、Authoritative 属性が true の場合のみ使用できます。 |
ここでは、サポートされる接続と特権の要件について説明します。
多くのメッセージングシステムが、クライアントとブローカ間のメッセージの暗号化機能をサポートしています。設定方法は、メッセージングシステムによって異なります。ただし、通常、暗号は抽象化されるので、JMS リスナーアダプタとメッセージングシステムのブローカ間の暗号を有効にするには、特別に設定された接続ファクトリを選択するだけで十分です。
JMS リスナーアダプタに対して設定するユーザーおよびパスワードは、JMS メッセージングシステムで認証されたユーザーでなくてはなりません。 また、そのユーザーには、JMS 宛先からのメッセージを読み取るために十分な特権を許可してください。
メッセージングシステム管理者は、デフォルト認証を無効にすることで、JMS 接続を保護するようにしてください。それ以上の保護については、メッセージングシステム管理者が、承認 (アクセス制御) を設定してセキュリティーを最適化します。
次の表に、JMS リスナーアダプタのプロビジョニング機能の概要を示します。
機能 |
サポート状況 |
---|---|
アカウントの作成 |
なし |
アカウントの更新 |
なし |
アカウントの削除 |
なし |
アカウントの有効化/無効化 |
なし |
アカウントの名前の変更 |
なし |
パススルー認証 |
なし |
前アクションと後アクション |
なし |
データ読み込みメソッド |
なし |
アカウント属性はトピックまたはキューから読み取られるメッセージによってかなり異なるため、JMS リスナーアダプタにはデフォルトのアカウント属性が用意されていません。
アイデンティティーシステムユーザー属性の名前が accountId であるアカウント属性を定義する必要があります。
なし。有効な値を持つアイデンティティーテンプレートを設定する必要があります。
JmsListenerActiveSync.xml
Identity Manager のデバッグページを使用して、次のクラスでトレースオプションを設定します。
com.waveset.adapter.JmsListenerResourceAdapter
リソースインスタンスに対して、次の Active Sync ログパラメータを設定することもできます。
ログアーカイブの最大数
アクティブログの最大有効期間
ログファイルの最大サイズ
ログファイルパス
ログレベル
タイプ JMS リスナーのリソースを作成時または編集時に、リソースウィザードの「設定のテスト」ボタンを使用すると、広範囲に及ぶチェックが実行されます。これは、設定上の問題のトラブルシューティングに非常に役立ちます。
また、Send JMS Message という名前のレポートでは、キューやトピックにメッセージを送信または発行するための単純なツールも使用できます。このレポートを使用するには、最初に交換ファイル $WSHOME/sample/SendJMSMessageReport.xml をインポートします。すると、Send JMS Message レポートのインスタンスを作成できます。このレポートのインスタンスが実行されているときには、指定したキューまたはトピックに、指定したメッセージが書き込まれます。