ASTERIA クライアント開発者ガイド

  1. 概要
    1. JDK・クラスパス
      1. JDK1.4の環境で使用する場合の注意
  2. FlowExecuteClient
  3. FlowRequest
    1. UserName, ProjectName, FlowName
    2. SessionId, Lifetime
    3. ExecuteMode
    4. Stream
    5. Params
  4. FlowResponse
    1. isSucceed
    2. ReturnValue
    3. Exception
    4. SessionId
    5. Stream
  5. サンプル
  6. 制限事項
    1. ストリームのサイズについて

1 概要

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


ASTERIAのSDKにはこれとは別のクライアント開発ライブラリが含まれています。
こちらはASTERIA内部で使用しているるクラスを直接使用しているので、より細かな制御が可能となっていますが、 JDK1.4.1以降の環境が必要で依存するライブラリも多くなっています。

1.1 JDK・クラスパス

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

1.1.1 JDK1.4の環境で使用する場合の注意

JDK1.4には標準でXMLパーサとしてcrimsonがバンドルされています。
しかし、crimsonはネームスペースの扱いに不具合があるため、flowthinclientをcrimsonで使用とするとloginメソッドのところで 「org.xml.sax.SAXParseException: ドキュメントのルート要素がありません。」というExceptionが発生します。
JDK1.4の環境でflowthinclientを使用する場合はxercesなどの別のXMLパーサを使用するようにしてください。

2 FlowExecuteClient

FlowExecuteClientはASTERIAと通信するためのクライアントクラスです。
このクラスを作成して任意のユーザでログインするとフローを実行可能な状態になります。
ログイン後にexecuteメソッドまたはpostメソッドを使用することでフローを実行します。

FlowExecuteClientを作成するコンストラクタの引数には先に設定したサーバのリクエスト実行のためのURLを指定します。
つまり、

http://<SERVENAME>:21381/flow-rpc

です。ASTERIAインストール時にポートを変更した場合はそのポートを使用してください。

ログイン後はそのユーザがプロジェクトオーナーであるフローだけでなく、別ユーザのフローも実行することができます。
ログインユーザはフローの実行ユーザとなります。

3 FlowRequest

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

3.1 UserName, ProjectName, FlowName

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

3.2 SessionId, Lifetime

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

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

3.3 ExecuteMode

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

3.4 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.5 Params

実行するフローの引数を設定します。
ここで指定された引数はStartコンポーネントのArgumentにマップされます。
指定された引数がStartコンポーネントのArgumentに存在しない場合は、その値は無視されます。
逆にArgumentにある引数が指定されなかった場合は、その値はnullになります。

4 FlowResponse

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

4.1 isSucceed

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

4.2 ReturnValue

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

4.3 Exception

異常終了した場合のExceptionを取得できます。
ただし、クライアント側で取得できる情報はほとんどエラーメッセージのみです。

4.4 SessionId

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

4.5 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

5 サンプル

sampleディレクトリには「/guest」ユーザで作成した「Project1.Flow1」というフローを実行するコマンドラインアプリケーションのサンプルが含まれています。

6 制限事項

6.1 ストリームのサイズについて

フローに受け渡すストリームとして扱うことができるサイズはファイルサイズで最大8MBまでになります。
また、8MB以内の場合でもフローサービスの最大メモリサイズを指定しない場合はOutOfMemoryErrorが発生することがあります。