ストリームデータ処理基盤 uCosminexus Stream Data Platform - Application Framework アプリケーション開発ガイド
![[目次]](FIGURE/CONTENT.GIF)
![[索引]](FIGURE/INDEX.GIF)
![[前へ]](FIGURE/FRONT.GIF)
10.2.2 外部定義関数のメソッドの実装
外部定義関数を実装するメソッドは,次の規則に従って作成してください。
- 修飾子とメソッド名
メソッドは,修飾子に必ずpublicを指定し,名前は「executeStreamFunc」で作成してください。
- メソッドの引数
外部定義ストリーム間演算関数に使用するメソッドの引数は,次の二つです。
- 第1引数:Collection<Object[]>[]型
メソッドの実行時,この引数には,クエリ定義ファイルで指定した入力ストリームごとに,同時刻に発生したタプルが格納されたデータオブジェクト配列を渡します。
- 第2引数:Timestamp型
メソッドの実行時,この引数には,第1引数で渡されるタプルの時刻情報を渡します。
同時刻のタイムスタンプを持つタプルを複数回に分けてメソッドに渡す場合があるため,第2引数の時刻情報には,前回のメソッド実行時と同時刻のタイムスタンプが渡されることがあります。
- メソッドの戻り値
外部定義関数に使用するメソッドの戻り値は,List<Object[]>型とします。
- メソッドの実行時,出力ストリームのタプルが格納されたデータオブジェクト配列のリストを返してください。出力対象のタプルが存在しない場合は,空のリストを返してください。
- メソッドの戻り値(List<Object[]>型)のObject[]に格納する各要素(タプル)のデータ型は,CQLのデータ型に対応するJavaのデータ型をすべて使用できます。しかし,外部定義関数定義ファイルで指定する出力ストリームのカラムのデータ型(CQLのデータ型)に対応する型で実装してください。
また,これらのデータ型でプリミティブ型と対応するラッパークラスを持つデータ型(intなど)は,プリミティブ型とラッパークラスのどちらも使用できます。
それ以外のデータ型を指定した場合は,クエリ実行時にエラーになります。
- メソッドの戻り値の検証
外部定義関数を使用するクエリの実行木は,外部定義関数定義ファイルに指定した戻り値の情報を基に生成されます。
クエリ実行時の外部定義関数の戻り値が,外部定義関数定義ファイルの戻り値の情報と一致していない場合,結果の不正や例外の発生などの意図しない動作が発生するおそれがあります。これらの現象を回避するため,双方の戻り値の情報が一致しているかどうかを検証できます。
戻り値の情報の一致を検証するかどうかは,system_config.propertiesのengine.externalStreamFuncVerifyModeパラメーターで指定します。
このパラメーターにtrueを指定し,検証結果が不正だった場合は,エラーメッセージが出力されて,クエリグループが閉塞されます。この場合は,実装メソッドの処理および外部定義関数定義ファイルを見直してください。
外部定義関数のクラスファイルまたは外部定義関数定義ファイルを修正する場合は,クエリグループの削除と再登録が必要です。外部定義関数の変更,またはクエリグループの変更については,マニュアル「uCosminexus Stream Data Platform - Application Framework システム構築・運用ガイド」を参照してください。
外部定義関数を実装するメソッドの注意事項を次に示します。
- メソッドの実行時に,一つの入力ストリームに対して複数のタプルが入力された場合,そのタプル間の順序は不定となります。メソッドでは,引数で渡されるタプルの順序に依存しない処理を実装する必要があります。
- メソッドでは,次の処理を実行しないでください。
- SDPサーバのプロセスを終了する処理(System#exit(),Runtime#halt()など)
- Thread#currentThread()などで取得したSDPサーバのスレッドに対するメソッドの実行
- 無限ループなど,メソッドが終了しない処理
- SDPサーバに対して,直接API(put()など)を発行する処理や,運用コマンドを実行する処理
これらの処理を外部定義関数で実行した場合,SDPサーバの動作は保障されません。
- メソッドでは,新たにスレッドを起動する場合には,スレッドを停止させる処理も実装してください。
- メソッドでは,次に示すような事象の発生でクエリを続行できないと判断する場合には,戻り値を返さないで例外をスローしてください。
- エラーの発生によって,次回の関数の実行でもエラーが発生する確率が高く,関数が正しい戻り値を返せない場合。
- 関数内での演算によってNaNが発生したなど,以降の関数の戻り値がNaNになって正しい戻り値を返せない場合。
例外をスローすると,メッセージKFSP42401-Eを出力して,クエリグループを閉塞します。
なお,今回は一時的な要因で正しい戻り値を返せなくても,次回の関数の実行では正常に動作可能と判断できる場合には,例外をスローしないで空のリストを返すことで,クエリ処理を継続できます。
- メソッドの戻り値,および戻り値の各要素としてnullを返さないでください。nullを返した場合,メッセージKFSP42400-EまたはKFSP42403-Eを出力して,クエリグループを閉塞します。
- メソッドでは,長さを指定できるデータ型を返すときに,定義値を超えるデータを返さないでください。返した場合には,メッセージを出力して,クエリグループを閉塞します。
ただし,system_config.propertiesのengine.externalStreamFuncVerifyModeパラメーターにfalseを指定した場合には,外部定義関数が返したデータをクエリ実行結果としてそのまま利用するため,メソッドを実装するときに注意してください。
- クエリ定義ファイルで外部定義関数の引数に指定した入力ストリームの数が,実装したメソッドの処理内容に対応しているかはSDPサーバではチェックしません。引数のチェック処理が必要な場合は,メソッド内でチェック処理を実装してください。
All Rights Reserved. Copyright (C) 2010, 2014, Hitachi, Ltd.