フローサービス クライアント開発者ガイド

  1. 概要
    1. JDK・クラスパス
    2. JavaDoc
    3. AsteriaClient
  2. FlowExecuteClient
  3. FlowRequest
    1. UserName, ProjectName, FlowName
    2. SessionId, Lifetime
    3. ExecuteMode
    4. ExecuteUser, LoginUserAsExecuteUser
    5. Stream
    6. Params
  4. FlowResponse
    1. isSucceed
    2. ReturnValue
    3. Exception, ErrorCode
    4. SessionId
    5. RequestId
    6. Stream
  5. FlowDeployClient
  6. FlowAdminClient
  7. サンプルアプリケーション - FlowExec
  8. その他のサンプル

1 概要

flowthinclientは任意のJavaアプリケーションから、フローを実行したりフローの情報を取得したりするためのクライアント開発ライブラリです。
可能な限り依存性を小さくすることを目標に設計されており、JDK8.0以降の環境で使用することができます。
これを利用してServletやJavaで記述できるストアドプロシージャとフローを連携させることも可能です。


フローサービスの開発キットには別のクライアント開発ライブラリが含まれています。
そちらのクライアント開発ライブラリは、製品内部で使用しているクラスを直接使用しより細かな制御が可能となっていますが、依存するライブラリも多くなっています。
通常はこちらのライブラリを使用してください。


このライブラリは、Standard/Enterpriseエディションでのみ使用することができます。その他のエディションではライセンス違反となりますのでご注意ください。

1.1 JDK・クラスパス

クライアントプログラムの開発と実行はJDK8.0以降の環境で行ってください。
開発及び実行環境には以下のライブラリが必要です。


flowthinclient.jarはflowthinclientキット(ZIP形式)の中に含まれています。

1.2 JavaDoc

flowthinclientのJavaDoc

1.3 AsteriaClient

AsteriaClientはフローサービスとの通信を行うクライアントの基底クラスです。
サブクラスとして次の3つがあります。

FlowExecuteClientなどのAsteriaClientサブクラスを作成するコンストラクタの引数にはフローサービスの稼働している サーバーのサーバー名とポート番号を指定します。
デフォルトポートでローカルホストにインストールしたフローサービスを指定する場合は、

FlowExecuteClient client = new FlowExecuteClient("localhost", 21381);

となります。フローサービスインストール時にポートを変更した場合はそのポートを使用してください。

AsteriaClientではloginメソッドとlogoutメソッドが定義されており、ユーザー名とパスワードを指定して フローサービスにログインすることで各種操作を行うことが可能になります。

login/logoutはすべてのAsteriaClientサブクラス共通の操作ですが、別のAsteriaClientをコンストラクタの引数 とすることでログイン状態を引き継いだまま別のクライアントを作成することも可能です。

FlowExecuteClient execClient = new FlowExecuteClient("localhost", 21381);
execClient.login("user1", "password");
...

FlowDeployClient deployClient = new FlowDeployClient(execClient);
//別のAsteriaClientを引数として作成した場合はそのログイン状態が引き継がれます。
//つまりloginメソッドのコールを行わずに情報取得を行うことが可能です。
String[] projectNames = deployClient.getProjectList();

2 FlowExecuteClient

FlowExecuteClientはフローを実行するためのクライアントクラスです。
このクラスを作成して任意のユーザでログインするとフローを実行可能な状態になります。
フローの実行メソッドにはexecuteメソッドとpostメソッドがありますが、それぞれのメソッドの意味は以下の通りです。

execute
フローを実行し、その終了を待ってその終了情報(返り値と出力ストリーム)を取得します。
メソッドの返り値はFlowResponseクラスになります。
post
フローの実行リクエストをキューにポストして直ちに終了します。
つまりこのメソッドを使用した場合は実際にフローの実行結果がどのようになったかは取得することができません。
メソッドの返り値はフローのリクエストIDがStringで返ります。
rerun
異常終了しているチェックポイントフローのリクエストを、異常終了する直前のチェックポイントから再実行します。
postと同様にフローの実行結果がどのようになったかは取得することができません。
メソッドの返り値はフローのリクエストIDがStringで返ります。

3 FlowRequest

executeメソッドとpostメソッドの引数となるのがFlowRequestオブジェクトです。
このオブジェクトに実行するフローとそのパラメーターを設定して、フローの実行をリクエストします。
FlowRequestには以下のパラメーターを設定することができます。

3.1 UserName, ProjectName, FlowName

実行するフローのプロジェクトオーナー名、プロジェクト名、フロー名を指定します。
必須です。

UserNameにはログインしたユーザーとは別のユーザー名を指定することもできますが、その場合は実行対象のフローが ログインユーザーに対して実行を許可していなければなりません。
(プロジェクトまたはフローの「実行を許可するユーザー」プロパティにログインユーザーが指定されている必要があります。)

3.2 SessionId, Lifetime

セッションIDを指定すると実行のセッションIDは指定のIDとなります。
サーバー上に既にそのIDのセッションが存在する場合は、そのセッションが使用され、ない場合は新規にそのIDでセッションが作成されます。
セッションIDを指定しなかった場合はリクエスト毎に新規のセッションが作成されます。

新規にセッションが作成される場合、そのセッションのライフタイム(タイムアウトまでの時間)はLifetimeの設定値となります。
Lifetimeが設定されなかった場合のデフォルト値は30分です。

3.3 ExecuteMode

フローの実行モードを指定します。
指定されなかった場合はNormalモードとなります。

3.4 ExecuteUser, LoginUserAsExecuteUser

フローの実行ユーザーを指定します。
setLoginUserAsExecuteUserにtrueを設定した場合はログインユーザーがフローの実行ユーザーになります。

3.5 Stream

ストリームを設定するためのメソッドはオーバーロードされていて何種類かあります。
用途に応じて使い分けてください。

引数 ストリーム型
int, byte[] Binary|Text|HTML|CSV|FixedLength|XML|MIME
int, java.io.InputStream Binary|Text|HTML|CSV|FixedLength|XML|MIME
int, java.io.File Binary|Text|HTML|CSV|FixedLength|XML|MIME
int, java.lang.String Text|HTML|CSV|XML
org.w3c.dom.Document XML
java.sql.ResultSet Record
String[], Value[]のList Record

設定するストリームのプロパティやフィールド定義は作成するフローのStartコンポーネントの OutputStreamFormat定義として行います。

3.6 Params

実行するフローの引数を設定します。
ここで指定された引数はフローの公開フロー変数に設定されます。
指定された引数がフローの公開変数に存在しない場合は、その値は無視されます。
逆に存在するフローの公開変数に引数が指定されなかった場合は、その値はフロー作成時に指定したデフォルト値になります。

4 FlowResponse

executeメソッドの返り値はFlowResponseオブジェクトとなります。
FlowResponseからは以下の内容が取得できます。

4.1 isSucceed

実行したフローが正常終了したか異常終了したかを示します。
このメソッドがfalseを返すのはリクエストしたフローが実行され、異常終了した場合です。
通信エラーやリクエストされたフローが見つからない場合などはFlowExecuteClient#executeメソッドがExceptionとなります。

4.2 ReturnValue

正常終了した場合にフローのReturnValueを取得できます。
ReturnValueとは終了コンポーネントの「戻り値」プロパティの値です。

4.3 Exception, ErrorCode

異常終了した場合のエラーメッセージを取得できます。
Exceptionにエラーコードが設定されている場合はそれも取得できます。

4.4 SessionId

実行に使用されたセッションIDです。
同一クライアントから再度リクエストを発行する際にこのセッションIDを使用すれば、そのリクエストは同一セッションで動作します。

4.5 RequestId

実行に使用されたリクエストIDです。
標準ではFlowService.logにフローの実行ログがリクエストIDと共に出力されるので実行結果をログから検索する場合などに使用できます。

4.6 Stream

ストリームの取得方法はストリームの種類に応じて、何種類かのメソッドが用意されています。
用途に応じて使い分けてください。
フローに結果ストリームがない場合(フローがEndコンポーネントで終了した場合)はnullになります。

メソッド 返り値 ストリーム型
getStreamAsBytes byte[] 全てのストリーム型
getStreamAsString java.lang.String Text|HTML|CSV|XML
getStreamAsDocument org.w3c.dom.Document XML
getStreamAsParameterList java.util.Map ParameterList
getStreamAsCSV (java.lang.String[]の)java.util.List CSV
getStreamAsRecord (Value[]の)java.util.List Record

ストリームがCSV, FixedLength, Record, ParameterListのいずれかの場合はgetFieldNamesメソッドで そのフィールド名を取得することができます。

5 FlowDeployClient

FlowDeployClientはフローの情報を取得・設定するためのクラスです。

を行うことができます。

FlowDeployClient client;

//URL実行設定の登録
URLTrigger t = new URLTrigger();
t.setFlow("Project1", "Flow1");
t.setURL("/hoge");
t.setName("URL実行設定1");
t.setDescription("URL実行設定1の説明");
//registerTriggerによって返されるTriggerはサーバーに登録された実行設定であり引数のTriggerとは別インスタンスです。
URLTrigger t2 = (URLTrigger)client.registerTrigger(t);

//実行設定の更新
t2.setEnabled(false);
t2.setExecuteMode(Trigger.MODE_DEBUG);
client.updateTrigger(t2);//クライアント側でnew したTriggerはupdateTriggerメソッドに渡すとエラーになるのでサーバーから取得したインスタンスを引数にします。

6 FlowAdminClient

FlowAdminClientはフローの実行状態を取得したり強制終了を行うためのクラスです。

を行うことができます。

//ある程度時間のかかるフローをpostメソッドで実行する
FlowExecuteClient execClient;
FlowRequest request = new FlowRequest();
request.setUserName("/guest");
request.setProjectName("Project1");
request.setFlowName("Flow1");
String requestId = execClient.post(request);

//フローの実行状態の表示
FlowAdminClient adminClient = new FlowAdminClient(execClient);
RunningStatus rs = adminClient.showRequest(requestId);
//フローの実行が終了している場合はnullが返ります。
if (rs != null) {
    System.out.println(rs);
    System.out.println("強制終了前に最後に実行したコンポーネント:" + adminClient.killRequest(requestId));
}

7 サンプルアプリケーション - FlowExec

FlowExecは指定のフローを実行するための汎用アプリケーションです。
その実行クラスはflowthinclient.jarの中に含まれているので、このjarにクラスパスを通すだけで実行することができます。
また、その完全なソースコードはsampleフォルダーで公開されています。

FlowExecでは「-<パラメーター名>:XXXX」のような形式でパラメーターを指定します。
指定できるパラメーターの一覧は以下です。

パラメーター名 指定する値
host フローサービスの稼働しているサーバーのサーバー名(またはIPアドレス)
省略した場合は「localhost」
port フローサービスの稼働しているサーバーのポート番号
省略した場合は「21381」
user 実行するフローのユーザー名。必須
password ユーザーのパスワード
省略した場合はパスワードなし
project 実行するフローのプロジェクト名。必須
flow 実行するフローのフロー名。必須
mode フローを実行するモード
「normal」「debug」「profile」「high」のいずれか
省略した場合は「normal」
output 実行結果のストリームをファイルに出力する場合のファイル名
省略した場合は実行結果はコンソールに出力されます。
p 実行するフローの引数
「NAME=VALUE」の形式で複数指定可能
retryCount リクエストがエラーとなった場合のリトライ回数
省略した場合は「0」
リトライが実行されるのはキューあふれなどのフロー実行以外の要因でエラーとなった場合です。実行したフローが異常終了した場合はリトライは実行されません。
retryInterval リトライを実行する場合の待機間隔(秒単位)
省略した場合は「1」

フローの戻り値はFlowExecアプリケーションの戻り値となります。(戻り値が数値以外の場合は無視されます。)

実際にフローを実行するコマンドラインは以下のようになります。
(flowthinclient.zipの中にはWindows/Unix用のFlowExec実行スクリプトが含まれています。)

//ローカルホストで実行中のフローサービスで/guestユーザーのProject1.Flow1を実行
//引数として「var1」と「var2」を指定
java -cp flowthinclient.jar com.infoteria.asteria.flowengine2.thinclient.app.FlowExec -user:/guest -password:guest -project:Project1 -flow:Flow1 -p:var1=aaa -p:var2=5

8 その他のサンプル

sampleフォルダーにはFlowExecのほかに「/guest」ユーザで作成した「Project1.Flow1」というフローを実行するサンプルも含まれています。