この章では、ノンブロッキング API 固有の性能を紹介します。また、ノンブロッキング API のすべての操作を説明し、コードの例をいくつか示します。
ノンブロッキング API は、信頼モードと非信頼モードという 2 つの異なるモードで動作可能です。これらのモードについては以下で詳しく説明します。モードを指定しない場合、デフォルト値として信頼モードが使用されます。
• 「信頼モード」
• 「非信頼モード」
信頼モードでは、API は SM への要求が失われないように保証します。API は、SM に送信されたすべての API 要求を内部ストレージに維持しています。SM からの応答が受信されるまで、要求は確定したとはみなされず、API はその要求を内部ストレージから削除できません。API と SM の間に接続エラーが生じた場合、SM への接続が確立されるまで、API はすべての要求をその内部ストレージに蓄積します。再接続時に、API は確定していないすべての要求を SM に再送信するため、要求が失われることはありません。
(注) 信頼モードでは、要求の再送信順序が保証されます。API は、呼び出された順番に要求を再送信します。
非信頼モードでは、API は SM に送信された要求の実行を保証しません。さらに、外部の信頼性メカニズムを実装しないかぎり、SM への接続が切断されると、API によって送信される要求はすべて失われます。
ノンブロッキング API は、接続エラー時の SM への自動再接続をサポートしています。このオプションが有効になっていると、API は SM への接続の切断を知ることができます。API は、接続が切断されると、再接続タスクを起動して、接続されるまで SM への再接続を試行します。
(注) 自動再接続サポートのオプションは信頼性モードとは関係なく設定できます。
ノンブロッキング API では、メソッドを同時に呼び出すスレッド数に制限はありません。
(注) ノンブロッキング API でマルチスレッドにする場合、呼び出しの順序は保証されます。API は、呼び出された順番に操作を実行します。
ノンブロッキング API では、結果ハンドラを設定できます。結果ハンドラは、2 つのメソッド、 handleSuccess と handleError を持つインターフェイスです。以下のコードを参照してください。
API を通じて実行された操作結果(成功またはエラー)について通知を受けたい場合は、このインターフェイスを実装する必要があります。
(注) これは、結果を取得する 唯一のインターフェイスです。結果は、API メソッドが呼び出し側に戻った直後に戻すことはできません。
(注) 操作結果を受信できるようにするには、結果を受信する API メソッドを呼び出す前に API の結果ハンドラを設定する必要があります。以下の例のように、API の接続後に結果ハンドラを設定することを推奨します。
handleSuccess と handleError のメソッドは、次に示す 2 つのパラメータを受け入れます。
• Handle ― 各 API の戻り値は、 long 型のハンドルです。このハンドルによって、操作の呼び出しとその結果を関連付けることができます。値 X のハンドルを指定して handle... 操作が呼び出された場合、その結果は同じハンドル値( X )を呼び出し側に返した操作の結果と一致します。
• Result ― 実際の操作結果。NULL の結果を返す操作もあります。
以下の例は、 stdout (結果が成功の場合)または stderr (結果がエラーの場合)にメッセージを出力する単純な結果ハンドラの実装です。この main メソッドは API を開始し、結果ハンドラを割り当てます。
結果ハンドラを正しく機能させるためには、以下の例に示されているコード シーケンスを守る必要があります。
(注) この例は、コールバック ハンドルの使用方法を示すものではありません。
ノンブロッキング API には、「API の構築」で説明したコンストラクタに加えて、再接続期間や信頼性モードを設定できるコンストラクタもあります。
ノンブロッキング API の追加コンストラクタの構文については、次のコード ブロックを参照してください。
ノンブロッキング API の追加コンストラクタ用のコンストラクタ引数は、次のとおりです。
次のように、再接続タスクの再接続試行間隔(ミリ秒単位)を決めます。
–0 以下の値:再接続タスクは起動されません(自動再接続は試行されません)。
–0 より大きい値:接続エラーの場合、 autoReconnectInterval ミリ秒ごとに再接続タスクが起動されます。
(注) 自動再接続サポートを有効にするには、API の connect メソッドが少なくとも 1 回起動される必要があります。詳細は、「ノンブロッキング API のコード例」を参照してください。
API が信頼モードで動作するかどうかを決定するフラグです。
• デフォルト値:TRUE(API は信頼モードで動作します)
LEG の名前。「API の構築」を参照してください。
次のコードで構築される API は、信頼モードで動作し、自動再接続間隔は 10 秒です。
次のコードで構築される API は、信頼モードで動作し、自動再接続は試行しません。
次のコードで構築される API は、非信頼モードで動作し、自動再接続を試行します。
ノンブロッキング API では、一部の内部プロパティを初期化することによって、API をカスタマイズできます。この初期化は、 init メソッドを使用して実行されます。
(注) この設定を有効にするには、connect メソッドの前にinit メソッドを呼び出す必要があります。
• 出力キュー サイズ ― 内部バッファ サイズ。これによって、SM に送信されるまで API が蓄積できる最大要求数が決まります。デフォルトは 1024 です。
• 操作タイムアウト ― 応答のない PRPC プロトコル接続の望ましいタイムアウトに関するヒント(ミリ秒)。デフォルトは 45 秒です。
ノンブロッキング API の init メソッドの構文は、次のとおりです。
ノンブロッキング API の init メソッドのパラメータは次のとおりです。
• properties ( java.util.Properties )
–出力キュー サイズを設定するには、 prpc.client.output.machinemode.recordnum を使用します。
ノンブロッキング API では、次のコード例のような方法で、初期化時にプロパティをカスタマイズできます。 connect メソッドの 前 に init メソッドが呼び出されている点に注意してください。
ここでは、ノンブロッキング API のメソッドについて説明します。
すべてのメソッドが long 型のハンドルを返します。これは、操作呼び出しとその結果を関連付けるために使用できます。(ResultHandler インターフェイス を参照)。
結果ハンドラに渡される操作結果は、次の点を除けば「ブロッキング API」の同じメソッドで説明した戻り値と同じです。
• 基本の型は Java クラスの表現に変換されます。たとえば、 int は java.lang.Integer に変換されます。
(注) エラーと一緒に結果ハンドラが渡されるのは、ブロッキング API の一致する操作が、呼び出し時の SM データベースの状態に応じて、同じ引数を持つ例外を生成する場合 だけです。
メソッドはどれも、SM との接続が確立される前に呼び出されると、 java.lang.IllegalStateException を生成します。
• 「login」
操作機能は、一致するブロッキング API 操作と同じです。詳細は、 第 3 章「ブロッキング API のコード例」 の「login」を参照してください。
操作機能は、一致するブロッキング API 操作と同じです。詳細は、 第 3 章「ブロッキング API のコード例」 の「logoutByName」を参照してください。
操作機能は、一致するブロッキング API 操作と同じです。詳細は、 第 3 章「ブロッキング API のコード例」 の「logoutByNameFromDomain」を参照してください。
操作機能は、一致するブロッキング API 操作と同じです。詳細は、 第 3 章「ブロッキング API のコード例」 の「logoutByMapping」を参照してください。
操作機能は、一致するブロッキング API 操作と同じです。詳細は、 第 3 章「ブロッキング API のコード例」 の「loginCable」を参照してください。
操作機能は、一致するブロッキング API 操作と同じです。詳細は、 第 3 章「ブロッキング API のコード例」 の「logoutCable」を参照してください。
ここでは、サブスクライバのログインおよびログアウトのコード例を紹介します。
次に例では、事前定義された数のサブスクライバが SM にログインしたのち、ログアウトします。切断リスナと結果ハンドラが実装されている点に注意してください。