jp.co.intra_mart.foundation.propagation

インタフェース PropagationManager

すべてのスーパーインタフェース:

AutoCloseable, Closeable

public interface PropagationManager
extends Closeable

IM-Propagation (伝搬機能) マネージャのインタフェース。

伝搬機能を使用するための基本的な API を提供します。
伝搬機能を利用することで、他モジュールに対して依存関係を考慮せずに任意のデータを渡すことができます。
また、データ送信側と受信側を同じモジュール内に配置することで、自モジュール内のプログラムを起動させるためのトリガーとリスナーのような動作を行わせることもできます。

伝搬機能では、データの送信側に Encoder (データ変換クラス)、データの受信側に Decoder (データ変換クラス) と Procedure (データ処理クラス) を用意することでデータの伝搬を行い、依存関係を動的に結んでモジュール間の連携を実現しています。
おおまかな処理の流れは以下の通りです。

1. 伝搬機能マネージャからデータを送信します。
2. データの送信側の Encoder (データ変換クラス) で渡されたデータを共通モデルに変換します。
3. 伝搬機能が設定ファイルを参照して、データの種類と操作種別からデータの受信側を決定します。
4. データの受信側の Decoder (データ変換クラス) でデータを共通モデルから受信側のモジュールでのモデルへ変換します。
5. データの受信側の Procedure (データ処理クラス) でデータを受け取り、受信側のモジュール内で処理後、処理結果を返却します。
6. 伝搬機能が全ての受信側の処理結果を取りまとめ、データの送信側へ返却します。

マネージャのインスタンスを取得する場合は、直接実装クラスを参照せずに PropagationManagerFactory クラスから取得してください。
final PropagationManager manager = PropagationManagerFactory.getInstance().getPropagationManager();

基本的な API の使い方は以下の通りです。

1. begin メソッドを呼び出し、伝搬機能のセッションを開始します。
2. send メソッドを呼び出し、伝搬機能へデータを送信します。 送信したいデータが複数ある場合は send メソッドをその都度呼び出します。
3. データ送信後に decide メソッドを呼び出し、伝搬機能のセッションを確定してコミット処理を行います。
4. 1 ～ 3 の処理中に何らかの例外が発生した場合は、例外処理を行います。
5. 最終処理として abort メソッドを呼び出し、伝搬機能のセッションを確実に終了します。
   このとき decide メソッドがまだ呼び出されていない場合は、セッションが中断してロールバック処理が行われます。

 final PropagationManager manager = PropagationManagerFactory.getInstance().getPropagationManager();
 try {
     manager.begin();
     manager.send(OperationType.DATA_CREATED, data, EmptyObject.class);
     manager.decide();
 } catch (final Exception e) {
     ...
 } finally {
     manager.abort();
 }
 

伝搬機能のセッション管理が不要で単純にデータを伝搬したい場合は、 begin、 decide、 abort メソッドの呼び出しを省略することができます。
この場合、リソースを解放するために最終処理として close メソッドを呼び出してください。
ただし、この実装が有効なケースは以下のいずれかの場合に限られます。

• データの受信側がセッションの開始 (データベースのトランザクション、または、独自のセッション管理) を要求していない場合。
• 自分のモジュール内へデータを伝搬する目的で使用する場合 (他のモジュールへデータを伝搬しない場合)。
• この実装の外側で伝搬機能のセッション管理がすでに行われている場合。

 final PropagationManager manager = PropagationManagerFactory.getInstance().getPropagationManager();
 try {
     manager.send(OperationType.DATA_CREATED, data, EmptyObject.class);
 } catch (final Exception e) {
     ...
 } finally {
     manager.close();
 }
 

クロージャ対応の execute メソッドを使用した場合は、セッション管理系 (send 以外) のメソッドを呼び出さずに、データを伝搬することができます。
伝搬機能のセッション管理、および、データベースのトランザクション制御は、伝搬機能側が自動的に行います。
詳細は execute メソッドの説明をご覧ください。

 final PropagationManager manager = PropagationManagerFactory.getInstance().getPropagationManager();
 manager.execute(new Callable<SendResult<EmptyObject>>() {
     @Override
     public SendResult<EmptyObject> call() throws Exception {
         return manager.send(OperationType.DATA_CREATED, data, EmptyObject.class);
     }
 });
 

通常は send メソッドの引数 data に指定されたインスタンスのクラス名で設定ファイルを参照して Encoder 等を検索しますが、以下のいずれかの場合にクラス名が特定できない場合があります。

• data に指定するクラスが、 class ではなく interface を対象としている場合。
• data に指定するクラスが、想定しているクラスだけでなく、それを継承したクラスまで対象となる可能性がある場合。

上記に該当する場合は、引数 dataClass が用意されている send メソッドを利用することで、引数 data のクラスを明示的に指定することができます。
詳細は send メソッドの説明をご覧ください。

 final PropagationManager manager = PropagationManagerFactory.getInstance().getPropagationManager();
 manager.execute(new Callable<SendResult<EmptyObject>>() {
     @Override
     public SendResult<EmptyObject> call() throws Exception {
         return manager.send(OperationType.DATA_CREATED, ModelIF.class, data, EmptyObject.class);
     }
 });
 

バージョン:

8.0.0

メソッドのサマリー

修飾子とタイプ	メソッドと説明
void	abort() 伝搬機能で使用するセッションを中断します。
void	begin() 伝搬機能で使用するセッションを開始します。
void	close() 伝搬機能で使用したリソースを解放します。
void	decide() 伝搬機能で使用するセッションを確定します。
<V> V	execute(Callable<V> caller) 伝搬機能で使用するセッションを開始して、処理終了後にセッションを自動的に終了します。
<D,R extends Serializable> SendResult<R>	send(String operationType, Class<D> dataClass, D data, Class<R> resultClass) 指定されたデータ操作の種別とデータが格納されたクラスを使用して、データを伝搬します。
<D,R extends Serializable> SendResult<R>	send(String operationType, D data, Class<R> resultClass) 指定されたデータ操作の種別とデータが格納されたクラスのインスタンスを使用して、データを伝搬します。

メソッドの詳細

abort

void abort()

伝搬機能で使用するセッションを中断します。

send メソッドで送られたデータの受信側に対して、セッション中断のイベントを通知します。
その後、伝搬機能のセッションを終了した後に close メソッドを呼び出し、伝搬機能で使用したリソースを解放します。
データベースのトランザクションが開始されている場合は、自動的にロールバックします。

すでにセッションが終了して、リソースが解放されている場合は、このメソッドを呼び出しても何も行われません。
そのため、 try ～ catch 内にデータ送信処理を記述して、 finally でこのメソッドを呼び出すことを推奨します。

クロージャ対応の execute メソッドを呼び出した場合は、自動的にこのメソッドが呼び出されるため、明示的に呼び出す必要はありません。

begin

void begin()
    throws BeginException

伝搬機能で使用するセッションを開始します。

データベースのトランザクションが開始されていない場合は、このメソッドを呼び出した際に自動的に開始します。
伝搬機能を使用する前に 1 度だけ呼び出してください。 すでにセッションが開始されている場合にこのメソッドを呼び出すと、例外がスローされます。

decide、 abort、 execute メソッドを呼び出してセッションが終了した状態でこのメソッドを呼び出すと、セッションを再開することができますが、なるべく 1 セッション内で処理を完結させてください。

クロージャ対応の execute メソッドを呼び出した場合は、このメソッドが自動的に呼び出されるため、明示的に呼び出す必要はありません。

例外:

BeginException - セッションを開始できない場合

close

void close()

伝搬機能で使用したリソースを解放します。

伝搬機能マネージャのインスタンス内で保持しているリソースを解放します。
begin メソッドを呼び出さずセッションを開始していない場合は、このメソッドを呼び出すことでリソースの解放処理のみを行うことができます。

すでにリソースが解放されている場合は、このメソッドを呼び出しても何も行われません。
そのため、 try ～ catch 内にデータ送信処理を記述して、 finally でこのメソッドを呼び出すことを推奨します。

begin メソッドでセッションを開始した場合は、このメソッドではなく decide、 abort メソッドを呼び出してセッションを終了させてください。
このメソッドを呼び出しても、セッションの終了処理は行いません。

クロージャ対応の execute メソッドを呼び出した場合は、伝搬機能によってこのメソッドが自動的に呼び出されるため、明示的に呼び出す必要はありません。

定義:

close インタフェース内 AutoCloseable

定義:

close インタフェース内 Closeable

関連項目:

Closeable.close()

decide

void decide()
     throws DecideException

伝搬機能で使用するセッションを確定します。

send メソッドで送られたデータの受信側に対して、セッション確定のイベントを通知します。
その後、伝搬機能のセッションを終了した後に close メソッドを呼び出し、伝搬機能で使用したリソースを解放します。
データベースのトランザクションが開始されている場合は、自動的にコミットします。

すでにセッションが終了して、リソースが解放されている場合は、このメソッドを呼び出しても何も行われません。

クロージャ対応の execute メソッドを呼び出した場合は、伝搬機能によってこのメソッドが自動的に呼び出されるため、明示的に呼び出す必要はありません。

例外:

DecideException - セッションを確定できない場合

execute

<V> V execute(Callable<V> caller)
       throws Exception

伝搬機能で使用するセッションを開始して、処理終了後にセッションを自動的に終了します。

このメソッドは伝搬機能で使用するセッション管理を簡単に行うためのクロージャを提供します。
最初に begin メソッドを呼び出してセッションの準備を行った後、引数 caller で指定された Callable#call メソッドを呼び出します。

Callable#call メソッドで任意のオブジェクトのインスタンスが返却された場合は decide メソッドを呼び出して、自動的にセッションを確定します。
null が返却された、または、例外が発生した場合は abort メソッドを呼び出して、自動的にセッションを中断します。
Callable#call メソッドで返却された値が、このメソッドの戻り値としてそのまま返却されます。

型パラメータ:

V - Callable#call メソッドで返却する値のクラスタイプ

パラメータ:

caller - セッション内で行う処理が実装された Callable インタフェース

戻り値:

Callable#call メソッドで返却された値

例外:

Exception - 処理中に例外が発生した場合。 以下の例外を含みます。

• BeginException - セッションを開始できない場合
• SendException - データを送信できない場合
• DecideException - セッションを確定できない場合

send

<D,R extends Serializable> SendResult<R> send(String operationType,
                                              Class<D> dataClass,
                                              D data,
                                              Class<R> resultClass)
                                       throws SendException

指定されたデータ操作の種別とデータが格納されたクラスを使用して、データを伝搬します。

引数 operationType と dataClass に指定された値を条件値として、伝搬機能がデータの受信側を決定します。
最初にデータを送信する側の Encoder (データ変換クラス) が呼び出されデータが変換されます。
その後、受信側の Decoder (データ変換クラス) を経由して Procedure (データ処理クラス) へデータが伝搬されます。
このメソッドは同期型のため、受信側の処理が全て終了するまで制御が返りません。

伝搬機能のセッションを開始する前にこのメソッドを呼び出すことはできますが、データの受信側がセッション中であることを前提としている場合、例外がスローされます。
また、このメソッドを呼び出してからセッションを開始した場合の動作は不定です。 なるべく、あらかじめ begin メソッドを呼び出してセッションを開始してください。

引数 operationType にはデータに対する操作の種別を OperationType から選択して指定します。
データの送信側と受信側が同じモジュール内で完結しており、他モジュールへの伝搬を想定していない場合は、独自の値を指定することができます。
その場合は、モジュールID を接頭子にした値を指定してください。 例えば "im_propagation.CALL_LISTENER" のような文字列を指定します。

引数 dataClass には、送信するデータが格納されているクラスタイプを指定することができます。
クラスタイプを明示的に指定することで、 引数 data に指定されるクラスが不定の場合でも確実なクラスの指定ができます。
ただし、引数 data に指定するクラスと互換性のあるクラスタイプを指定する必要があります。
送信するデータがない場合は、明示的にデータがないことを示すために EmptyObject.class を指定してください。

引数 data に指定したデータは、データ変換クラスによって別の形に変換されるため、そのままの形で受信側へ伝わることはありません。
どのようなデータが格納されているか判別できるクラス名を使用してください (パッケージ名を含むクラス名がデータの伝搬時のキーとして使用されます)。
引数 data は必ず指定する必要があり、 null または Java の標準的なクラス (java.lang.String 等) は許可されていません。
送信するデータがない場合は、明示的にデータがないことを示すために new EmptyObject() を指定してください。

引数 resultClass には、受信側のデータ処理クラスが処理結果を返却した場合に値を格納するクラスを指定することができます。
ただし、指定したクラスとまったく同じ構造で受信側が返却値を設定するとは限りません。
指定するクラスタイプには、総称型を指定できない、フィールドで使用できるクラスが制限されている等、 制約 がありますのでご注意ください。
処理結果を受け取らない場合は、 EmptyObject.class を指定してください。

型パラメータ:

D - 送信するデータのクラスタイプ

R - 各モジュールから受け取る処理結果のクラスタイプ

パラメータ:

operationType - データ操作の種別。 OperationType を参照。 独自の値を指定する場合は、データ送信側のモジュールID を接頭子とする

dataClass - 送信するデータが格納されたクラス。 特に指定しない場合は EmptyObject.class を指定する

data - 送信するデータが格納されたクラスのインスタンス。 特に指定しない場合は new EmptyObject() を指定する

resultClass - 各モジュールから受け取る処理結果のクラス。 特に受け取らない場合は EmptyObject.class を指定する

戻り値:

データの送信結果。 受信側のデータ処理クラスが処理結果を返却した場合は、返却値が格納される

例外:

SendException - データを送信できない場合

send

<D,R extends Serializable> SendResult<R> send(String operationType,
                                              D data,
                                              Class<R> resultClass)
                                       throws SendException

指定されたデータ操作の種別とデータが格納されたクラスのインスタンスを使用して、データを伝搬します。

引数 operationType と data に指定された値を条件値として、伝搬機能がデータの受信側を決定します。
最初にデータを送信する側の Encoder (データ変換クラス) が呼び出されデータが変換されます。
その後、受信側の Decoder (データ変換クラス) を経由して Procedure (データ処理クラス) へデータが伝搬されます。
このメソッドは同期型のため、受信側の処理が全て終了するまで制御が返りません。

send(String, Class<D>, D, Class<R>) メソッドとの違いは、引数 data のクラスを明示的に指定するかどうかです。
通常、このメソッドは以下のコードと等価です。

 send(operationType, data.getClass(), data, resultClass);
 

このメソッドの引数と動作についての詳細は send(String, Class<D>, D, Class<R>) メソッドの説明をご覧ください。

型パラメータ:

D - 送信するデータのクラスタイプ

R - 各モジュールから受け取る処理結果のクラスタイプ

パラメータ:

operationType - データ操作の種別。 OperationType を参照。 独自の値を指定する場合は、データ送信側のモジュールID を接頭子とする

data - 送信するデータが格納されたクラスのインスタンス。 特に指定しない場合は new EmptyObject() を指定する

resultClass - 各モジュールから受け取る処理結果のクラス。 特に受け取らない場合は EmptyObject.class を指定する

戻り値:

データの送信結果。 受信側のデータ処理クラスが処理結果を返却した場合は、返却値が格納される

例外:

SendException - データを送信できない場合

関連項目:

send(String, Class, Object, Class)