4. クライアントAPI¶

4.1. クライアント環境の準備¶

JavaのクライアントAPIは、製品DVD-ROMの 「client/cfro1100client.zip」 に含まれています。 ファイルを展開すると 「doc」 「lib」 「sample」 という3つのディレクトリが展開されます。

JavaのクライアントAPIは「lib」ディレクトリに含まれる「cfro-client.jar」です。 このファイルをご利用の環境にコピーもしくはクラスパスを設定して利用します。

動作に最低限必要なものは「cfro-client.jar」のみですが、クライアント設定ファイルを使用して動作を制御することも可能です。 設定ファイルについては クライアント設定ファイル をご覧ください。

JavaのクライアントAPIのクラスライブラリは以下のパッケージに含まれます。

net.createform.ro

以下の説明では上記パッケージ名は省略しています。 APIのメソッドの詳細については製品DVD-ROMの 「client/cfroclient1100.zip」 に含まれているAPIリファレンス（doc/api/index.html）をご覧ください。

4.2. サーバへの接続¶

まずは CreateForm オブジェクトを使用してサーバとの接続を確立します。

CreateForm server = CreateForm.getInstance("servername", 56789);

getInstance メソッドを使用して CreateForm オブジェクトのインスタンスを取得します。 その際、引数として接続サーバ名とポート番号を指定します。

取得したインスタンスに対して isAvailable メソッドを呼ぶと指定したサーバに接続可能かどうかを確認することができます。

boolean connected = server.isAvailable();

false が返ってくる場合は接続に失敗しています。 接続先サーバ名、ポート番号が正しいか、アクセス可能なポート番号かどうかを確認してください。 また、サーバが起動し Create!Form RemoteObject が開始状態となっているかを確認してください。

接続確認にはsonarメソッドを使用することもできます。

try {
   server.sonar();
}
catch (RemoteObjectException e) {
   e.printStackTrace();
}

sonar メソッドは接続に失敗すると例外を発生させます。 これにより接続エラーの内容を例外として取得することができます。

4.3. 帳票出力の実行¶

帳票出力を実行する場合は、Job オブジェクトを使用します。 Job オブジェクトは、CreateForm オブジェクトの newJob メソッドにより取得します。

Job job = server.newJob();

次にどの出力ランタイムを使用するかを Job オブジェクトの setMode メソッドで指定します。

job.setMode(CreateFormMode.CAST);

setMode で指定できる引数は、CreateFormMode という列挙型のオブジェクトです。 以下のものが指定できます。

Create!Form ランタイムの実行オプションを指定するには addOpt メソッドを使用します。

job.addOpt("D", "C:/ProgramData/Infotec/CreateForm/11/work/sample/04_名簿・一覧");
job.addOpt("s", "sheet");

“-D” オプションで指定するパスは 「サーバ側の作業ディレクトリ」 のパスを指定します。

実行オプションを削除する場合はremoveOptメソッドを使用します。

job.removeOpt("o");

次に入力データファイルを指定します。

job.getSource().addFile("D07_sheet_p1.csv");

ここでのファイルは 「クライアント側にある入力データファイル」 を指定します。

ここまでで実行パラメータのセットアップは完了しました。 execute メソッドを実行して帳票出力を実行します。

JobResult result = job.execute();

execute メソッドを実行するとサーバへ情報が送信され、サーバ上で帳票出力が実行されます。 そして実行結果がサーバから送信されます。

実行結果は JobResult オブジェクトとして取得されます。 成功したかどうかは getErrorCode メソッドの値で確認できます。

int code = result.getErrorCode();
if (code == 0) {
   // 正常終了
}
else {
   // エラー発生
}

実行に成功した場合、JobResult オブジェクトの publish メソッドによって、サーバ上に生成された帳票データをクライアント側で OutputStream に書き出すことができます。

OutputStream out = new FileOutputStream("result.pdf");
result.publish(out);
out.close();

また、ページ数取得オプション 「-P」 「-Pn」 が指定されていた場合は、JobResult オブジェクトの getPages メソッドでページ数を取得することができます。

job.addOpt("P");
JobResult result = job.execute();
int pages = result.getPages();

4.4. 非同期実行¶

execute メソッドはサーバ上で帳票生成処理が終了するまで処理をブロックします。 処理をブロックさせずに一旦処理を返し、結果は後から任意のタイミングで取得する場合は、execute メソッドの代わりに post メソッドを使用します。

job.post();

JobStatus オブジェクトを取得することで、ジョブの実行状態を確認することができます。

JobStatus status = job.getStatus();
if (status.done()) {
   // ジョブの実行が正常に完了している
}
else if (status.fail()) {
   // ジョブの実行中にエラーが発生している
}
else {
   // ジョブを実行中
}

done または fail メソッドが true を返す場合は、ジョブの実行が完了しているため実行結果を取得することができます。 結果を取得するには getResult メソッドを使用します。

JobResult result = job.getResult();

また、ジョブはそれぞれユニークなID(ジョブID)を持ちます。 このIDを保持しておいて、後からそのIDを使ってそのジョブを再取得することもできます。

String jobId = job.getId();
...
Job job = server.lookupJob(jobId);

これによって、post メソッドの後で一旦クライアントのプロセスが終了したとしても、ジョブIDさえ分かっていれば別のプロセスから Job オブジェクトにアクセスして結果を受け取ることができます。

非同期実行機能を使用するためにはサーバの ジョブ設定 にて実行済みジョブの有効期限を 「無期限」 または 「1」 以上の値に設定しておく必要があります。 もしくは次のコードのように setExpiration メソッドで有効期限を指定してから post メソッドを実行する必要があります。

job.setExpiration(1);
job.post();

Job job = server.newJobWithId("myjob0001");

4.5. 再実行¶

一度実行された帳票出力ジョブは再実行することができます。

再実行機能を使用するためにはサーバの ジョブ設定 にて実行済みジョブの有効期限を 「無期限」 または 「1」 以上の値に設定しておく必要があります。 もしくは Job オブジェクトの setExpiration メソッドで有効期限を設定する必要があります。

非同期実行 で説明したようにジョブはそれぞれユニークなID(ジョブID)を持っています。 このジョブIDを指定することで実行済みのジョブに再度アクセスすることができます。

Job job = server.lookupJob(jobId);

再取得した Job オブジェクトに対しては、実行時と同じように execute メソッドや post メソッドを実行することができます。 実行オプションを追加したり出力ランタイム種別を変えて実行することも可能です。

job.addOpt("Pse", "3"); // 3ページ目だけ出力
job.setMode(CreateForm.PRINTSTAGE); // PrintStageに変更
JobResult result = job.execute();

List<JobDescriptor> jobs = server.listJobs();

for (Iterator<JobDescriptor> it = jobs.iterator(); it.hasNext(); ) {
   JobDescriptor descriptor = it.next();
   String jobId = descriptor.getId();
}

JobDescriptor descriptor = job.getDescriptor();
int times = descriptor.getTimes();

int timesOfCast = descriptor.getTimes(CreateFormMode.CAST);
int timesOfPrintST = descriptor.getTimes(CreateFormMode.PRINTSTAGE);

job.remove();