3.3.2 業務アプリケーションからFNSシステムの呼出し
(エージェントプログラムの作成方法)
通常のFNSの利用者はWebブラウザを使用してFNSシステムを呼出しますが、Webブラウザを用いずに利用者に代わってプログラムからFNSシステムを呼出すことができます。このプログラムをFNSエージェントプログラムと呼びます。本項ではエージェントプログラムの作成方法について説明します。
エージェントプログラムは電子フォームの通信で用意されている各種通信機能を用いて送受信を制御します。
FNSでは、エージェントプログラムを作成するために必要な各種通信機能をエージェントプログラムJavaパッケージ(FnsAgentPkg)として用意しています。このパッケージはFNSシステムのインストールプログラムの一つとして提供されます。
エージェントプログラムの作成に先立ち、エージェントプログラムで用いるFNSの通信機能について、それがどのようなものかを知るには2.3 運用者(A端利用者)の(2)マイ・メニューの受信閲覧/送信履歴閲覧および3.2 電子フォームのデザイン (2) HTMLフォームのデザインが役立ちます。マイ・メニューの受信閲覧/送信履歴閲覧およびHTMLフォームのデザインではWebブラウザを用いた方式を述べていますが、エージェントプログラムではこれらのことをWebブラウザではなく、Javaプログラムとして行います。
エージェントプログラムは次ぎのような作業を伴います。
(@)FNSグループへのログイン/FNSグループからのログアウト
FNSグループの管理者、運用者、あるいは利用者としてFNSグループにログインするとセッションが確立されます。セッションが確立されている間、FNSとの間でメッセージ交換を行います。メッセージ交換が終了するとFNSグループからログアウトします。
(A)メッセージ交換
FNSグループのメンバ(管理者、運用者、あるいは利用者)はそれぞれ固有の情報領域を割当てられています。この情報領域内にはメッセージ交換に必要な次ぎの2つのキュー(最初に入ったものが最初に出て行くという構造をもった器)をもっています。
左図のように、a、b、c、d、e、・・・の順に入れると、a、b、c、d、eの順に取り出せる器のことを“キュー”と呼んでいます。 FNSの2つのキューは“受信キュー”と“送信履歴キュー”です。キューに入れるものはファイルです。つまり、受信キューと送信履歴キューはキュー構造のフォルダーと見なすことができます。
メッセージ交換の操作は電子フォームを用いる方法と、エージェントプログラムを用いる方法があります。両者を混在して使用することができます。
(a)電子フォームを使用してメッセージを送信し、エージェントプログラムで受信する
(b)エージェントプログラムでメッセージを送信し、電子フォーム(or Webページ)で受信する
(c)エージェントプログラムでメッセージを送信し、エージェントプログラムで受信する
(d)電子フォームを使用してメッセージを送信し、電子フォーム(or Webページ)で受信する (FNSの通常の使用法)
エージェントプログラムを使用して、上記の(a)、(b)、(c)のいずれの方法でもメッセージ交換を行うことができます。
エージェントプログラムで送信したメッセージは宛先メンバの受信キューに入ります。同時に送信者の送信履歴キューにも同じメッセージが入ります。受信キューおよび送信履歴キューのメッセージ:即ちファイルはメンバあるいはエージェントプログラムが削除操作を行わない限りキューに保存されます。
受信キューあるいは送信履歴キュー内のファイルはエージェントプログラムで取出すことができます。ファイルの扱いはエージェントプログラム作成者の裁量範囲です。
エージェントプログラムを作成するために、FNSではエージェントプログラムJavaパッケージとして次のクラスを提供しております。
jp.co.ITNetInc.fns.agent.FnsRunner (受信キュー、送信履歴キュー、送信操作を実行)
jp.co.ITNetInc.fns.agent.Response (FnsRunnerのメソッド操作の返却値の操作を実行)
注)複数のクラスをまとめてパッケージとしており、パッケージ名は「jp.co.ITNetInc.fns.agent」です。
FNSのインストールプログラムとして提供されるこれらのエージェントプログラムJavaパッケージをお客様のJava開発環境にコピーし、エージェントプログラムの中に、
import jp.co.ITNetInc.fns.agent.*;
を置くことによりエージェントプログラムJavaパッケージの各機能が利用可能となります。
以下では、エージェントプログラムJavaパッケージのクラスFnsRunnerおよびResponseについて説明します。続いて、エージェントプログラムの動作環境およびエージェントプログラムの作成例を示します。
(1)jp.co.ITNetInc.Agent.fnsRunnerクラス
受信キュー、送信履歴キュー、送信操作のために、以下に示すコンストラクタおよび各種メソッドがあります。
(a) コンストラクタ
(@)FnsRunner(String host,int port,String zone)
host,port,zoneで示すFNSサーバ向けのサーブレットランナー(※)を生成します。
host,port,zoneで指定する値は、
URL : https://www.domain/zone/servlet/MfUsPage
を例にすると、host : www.domain
zone : zone
port : 通常は443 ※httpを使用する場合通常は80
です。
(A)FnsRunner()
サーブレットランナー(※)を生成します。FNSサーバの決定は詳細制御メソッドpublic void setServer(String host,int port,String zone)で行います。
※サーブレットランナーとはサーブレットを作動させるプログラムです。
(b)基本メソッド
(@)public int login(
String enterGrpName,
String usrName,
String usrPassWord)サーブレットランナーで指定しているFNSサーバにenterGrpNameを入場グループ名、usrNameを利用者名、usrPassWordをパスワードとしてログイン処理を行います。このとき、指定した利用者でのセッションが確立されます。
返却値 : 0 正常終了
-1 異常終了
(A)public int logout()
現在ログイン中のFNSサーバから現在の利用者のログアウト処理(セッションの切断)を行います。
返却値 : 0 正常終了
-1 異常終了
(B)public Response UsPage(String path)
現在の入場グループの利用者ページを参照します。
(C)public Response KnPage(String path)
現在の入場グループの管理者ページを参照します。
(D)public Response UcPage(String path)
現在の入場グループの利用者共用ページを参照します。利用者共用ページはグループ種別が“1対多”と“多対多”のグループに存在します。
(E)public Response CmPage(String path)
現在ログインしているFNSシステムの“システム共通ページ”を参照します。
(F)public Response FormPool(String formid,String use)
現在の入場グループの電子フォームを参照します。
useパラメータの指定値は次の通りです。
"RW" : 書込用の電子フォームを要求 "RDONLY" : 読出専用の電子フォームを要求 "WTREPLY" : 返信記入用の電子フォームを要求 "PIC" : 縮小表示用の画面イメージファイルを要求 (c)詳細制御メソッド
(@)public void setEnterGroupName(String grpName)
入場先グループを変更します。grpNameを新しい入場グループ名とします。
(A)public String getEnterGroupName()
現在設定されている入場グループ名を得ます。
(B)public Response getLastResponse()
最近のFNSサーブレットの応答情報をResponseの形で取出します。基本メソッドおよび通信メソッドで、クラスResponseのインスタンスを返却しないメソッドでの、直前の返却値をクラスResponseの形で取出すことができます。エラー処理の原因分析などに役立ちます。
(C)public void setServer(String host,int port,String zone)
FNSサーバを変更します。host,port,zoneで示すサーバに変更あるいは設定します。
(D)public void notSSL()
SSL通信は使用しないことを指示します。HTTPで送受信します。
(E)public void setSSL()
SSL通信を使用することを指示します。HTTPSで送受信します。既定値はSSL通信です。
(F)public void setNotConv()
XMLデータの取出しを指示します。下記メソッドで取出す情報がXMLデータの場合に、HTMLフォームイメージではなく、XMLデータ自体を取出します。
・ actQue_getData 受信キュー情報取出し ・ actJnl_getData 送信履歴情報取出し ・ UsPage 利用者ページ参照 ・ KnPage 管理者ページ参照 ・ UcPage 利用者共用ページ参照 初期状態は、このメッソドが実行された状態です。
(G)public void clearNotConv()
XMLデータの取出しを指示を解除します。
(d)通信メソッド
(@)タイプ1:public FnsRunner.ResActQue_query actQue_query(
String dataid,
String filename)タイプ2:public FnsRunner.ResActQue_query actQue_query(
String refGrpName,
String dataid,
String filename)両タイプ共に、受信キューを検索し、検索結果(クラスResActQue_queryのインスタンス)を返却します。タイプ1とタイプ2の違いは、タイプ1が現入場中グループを対象としているのに対して、タイプ2は全グループあるいは特定のグループを対象とすることです。
タイプ1 ・ dataidにnullを指定した場合:
現入場中グループからの受信情報の内、最小のDATAID を取出します。
※DATAID はキュー内の1 つのファイルを識別するためのFNS 内部データです。最初のDATAID の取出しを行う場合はnullを指定します。
・ dataidにnull以外の値を指定した場合:
現入場中グループからの受信情報の内、指定DATAID より大きく最小のDATAID を取出します。これは2 番目以降のDATAID の取出しに使用します。
・ 上記の検索条件に加えて、受信閲覧画面の項目:“文書フォーム”との一致が指定できます。“文書フォーム”との一致を必要としない場合はfilenameにはnullを指定します。受信閲覧画面の“文書フォーム”項の内容はmfformid指定値あるいは“_NONNAME”です。
タイプ2 ・ refGrpNameに検索対象のグループ名を指定する以外はタイプ1と同じです。
※refGrpNameの値として“_ALL”あるいはnullを指定した場合は全グループが対象となります。
実行結果がエラーの場合はnullを、正常の場合はResActQue_queryを返却します。正常でかつ対象データが存在しない場合はResActQue_queryのdataid値にnullを返却します。
返却クラス形式:
public class ResActQue_query {
public String dataid; // DATAID
public String grpname; // グループ名
public String fromusername; // 発信者名
public String filename; // 受信閲覧画面の項目:“文書フォーム”
// (mfformid or "_NONNAME")
public String recdaytime; // 受信日時 YYYYMMDDHHMMSSmmm
public String tousername; // 宛先名
public String title; // タイトル
}(A)public Response actQue_getData(String dataid)
受信キュー内のdataidで指定する情報を保持したResponseクラス(のインスタンス)を生成して返却します。返却値の読み出しは(2)jp.co.ITNetInc.fns.agent.Responseの(E)public byte[] content()で行います。
actQue_getDatを使用するプログラムは返却されたResponseクラスのcontent()メソッドを呼び出して返却値を受け取ります。例えば次のようにコーディングします。
FnsRunner.ResActQue_query rq =run.actQue_query(oldid,null);
if (rq ==null){error 処理 }
if (rq.dataid ==null){対象データ無し処理 }
Response res =run.actQue_getData(rq.dataid);
if (res ==null){error 処理 }
byte ret[ ] =res.content(); // ret[ ] に内容が返却されます。(B)public int actQue_delete(String dataids[])
受信キュー内のdataidsで指定する情報を削除します(複数指定可)。削除するDATAIDが1つの場合もこのメソッドを使用します。
返却値 : 0 正常終了
-1 異常終了
(C)タイプ1:public FnsRunner.ResActJnl_query actJnl_query(
String dataid,
String filename)タイプ2:public FnsRunner.ResActJnl_query actJnl_query(
String refGrpName,
String dataid,
String filename)両タイプ共に、送信履歴キューを検索し、検索結果(クラスResActJnl_queryのインスタンス)を返却します。タイプ1とタイプ2の違いは、タイプ1が現入場中グループを対象としているのに対して、タイプ2は全グループあるいは特定のグループを対象とすることです。
タイプ1 ・ dataidにnullを指定した場合:
現入場中グループからの送信情報の内、最小のDATAID を取出します。
※DATAID はキュー内の1 つのファイルを識別するためのFNS 内部データです。最初のDATAID の取出しを行う場合はnullを指定します。
・ dataidにnull以外の値を指定した場合:
現入場中グループからの送信情報の内、指定DATAID より大きく最小のDATAID を取出します。これは2 番目以降のDATAID の取出しに使用します。
・ 上記の検索条件に加えて、送信履歴閲覧画面の項目:“文書フォーム”との一致が指定できます。“文書フォーム”との一致を必要としない場合はfilenameにはnullを指定します。送信履歴閲覧画面の“文書フォーム”項の内容はmfformid指定値あるいは“_NONNAME”です。
タイプ2 ・ refGrpNameに検索対象のグループ名を指定する以外はタイプ1と同じです。
※refGrpNameの値として“_ALL”あるいはnullを指定した場合は全グループが対象となります。
実行結果がエラーの場合はnullを、正常の場合はResActJnl_queryを返却します。正常でかつ対象データが無い場合はResActJnl_queryのdataid値にnullを返却します。
返却クラス形式:
public class ResActJnl_query {
public String dataid; // DATAID
public String grpname; // グループ名
public String tousername; // 宛先名
public String filename; // 送信履歴閲覧画面の項目:“文書フォーム”
// (mfformid or "_NONNAME")
public String senddaytime; // 受信日時 YYYYMMDDHHMMSSmmm
public String result; // 処理結果
public String fromusername; // 発信者名
public String title; // タイトル
}(D)public Response actJnl_getData(String dataid)
送信履歴キュー内のdataidで指定する情報を返却します。返却値の読み出しは(2)jp.co.ITNetInc.fns.agent.Responseのメソッドpublic byte[] content()で行います。
(E)public int actJnl_delete(String dataids[])
送信履歴キュー内のdataidsで指定する情報を削除します(複数指定可)。削除するDATAIDが1つの場合もこのメソッドを使用します。
返却値 : 0 正常終了
-1 異常終了
(F)public int transfer_text(
String dist,
String title,
String cntnt,
String mime,
String formid)cntntで示す情報をdist宛てに送信します。
mimeにはcntntのマイムタイプを指定します(通常「text/plain」あるいは「text/html」)。
title,formid,fileの各項はnull指定を可とします。
上記のdist、title、cntnt、mime、formidは3.2電子フォームのデザイン (2)HTMLフォームのデザインにおけるmfdist、mftitle、mfcntnt、mfmime、mfformidに対応します。意味についてはHTMLフォームの説明を参照してください。
返却値 : 0 正常終了
-1 異常終了
(G)public int transfer_file(
String dist,
String title,
byte cntnt[],
String fileExtension,
String formid)cntntで示す情報をdist宛てに送信(マルチパートフォーム転送:バイナリファイル転送可)します。
fileExtentionにはcntntの内容形式を表わすファイル拡張子(“.txt”あるいは“.html”)を指定します。
title,formidの各項はnull指定を可とします。
上記のdist、title、cntnt、formidは3.2電子フォームのデザイン (2)HTMLフォームのデザインにおけるmfdist、mftitle、mfcntnt、mfformidに対応します。意味についてはHTMLフォームの説明を参照してください。
返却値 : 0 正常終了
-1 異常終了
(e)Web画面アップロードメソッド
(@)タイプ1:public int mtPage_upload(
char kind, // U,R,K,M,A,B,C
String pathname, // path name
byte cntnt[],
String fileExtension, // .zip|.txt|...
boolean extendWhenZip // true,false )
タイプ2:public int mtPage_upload(
char kind, // U,R,K,M,A,B,C
String pathname, // path name
byte cntnt[],
String fileExtension, // .zip|.txt|...
boolean extendWhenZip, // true,false
boolean overWrite // true,false )・ cntntで示す情報をWeb画面にpathnameで指定したファイル名(パス名)で登録します。タイプ1では当該ファイル名が既に存在すれば更新し、存在しなければ新規登録されます。タイプ2では当該ファイル名が既に存在する場合の処置(上書き又は中断)が指定可能です。
・ kindにはWeb画面登録先のWeb画面の種類を1文字で指定します。
U: 運用者画面(1対多:運用者、多対多:A端利用者、その他:指定不可) R: 利用者画面(1対多:末端利用者、多対多:B端利用者、その他グループ:利用者) K: 管理者画面 M: 利用者画面(1対多:末端利用者、多対多:B端利用者、その他のグループ:利用者) A: A端利用者画面(1対多:運用者、多対多:A端利用者、その他のグループ:指定不可) B: B端利用者画面(1対多:末端利用者、多対多:B端利用者、その他のグループ:指定不可) C: グループ内共用画面(1対多および多対多で使用可能、他グループ:指定不可) ・ fileExtensionではcntntの内容の形式を示すファイル拡張子を指定します。
(例:「.zip」「.txt」「.html」...)
・ 登録画面情報にZIPファイルを使用する場合、extendWhenZipに「true」を指定するとZIPファイルはFNSシステムにアップロードされた後解凍されてベースディレクトリからの相対位置に登録されます。pathnameはベースディレクトリを指定します。
extendWhenZipに「false」を指定するとZIPファイルは解凍されずに、他ファイルと同様に1つのファイルとして登録されます。・ タイプ2のoverWriteに「true」を指定すると、pathname(ZIP解凍後登録が指定されている場合は解凍後の各ファイル名)で指定したファイル名が既に存在している場合には上書き更新となります(タイプ1と同様処理)。overWriteに「false」を指定した場合は更新せずエラーによる中断となります。なお既存ファイルが存在しなければ追加されます。
・ 返却値 : 0 : 正常終了
-1 : 異常終了
(2)jp.co.ITNetInc.fns.agent.Responseクラス
FnsRunnerのメソッドの返却値の操作のために、以下に示す各種メソッドがあります。
(a)メソッド
(@)public int httpRetCode()
・ HTTPで規定されたリターンコードを取得し、返却します。
(A)public int fnsRetCode()
・ FNSのリターンコードを返却します。
・ 応答がFNSリターンメッセージである場合のみ意味があり、応答がFNSリターンメッセージでない場合は-1を返却します。
・ 返却値 : 0 : FNSは正常終了。
1以上の数: FNSは異常終了。“数値”は異常コードを表わします。
-1 : FNS以外(通信路等)の異常終了。
(B)public boolean isFnsDone()
・ FNSのリターンコードが正常終了である場合trueを返却します。応答がFNSリターンメッセージでありかつ正常終了である場合trueを返却します。
(C)public boolean isFnsError()
・ FNSのリターンコードが異常終了である場合trueを返却します。
・ 応答がFNSリターンメッセージであり、かつ異常終了である場合trueを返却します。
(D)public String mime()
・ 返却値読出し(メソッドcontent())のMIMEタイプを取得します。
・ このメソッドの返却値がnullの場合、メソッドcontent()のMIMEタイプは不明です。このメソッドの返却値がnullでない場合、それはcontent()の返却値のmimeタイプです。
(E)public byte[] content()
・ 返却値がnullの場合、contentはありません。
・ 返却値がnullでない場合、content(即ちファイルの内容)をバイト配列で返却します。
(F)public long length()
・ 応答内容情報のバイト長を返却します。
(G)public byte[] header()
・ 応答ヘッダーを返却します。
(H)public String httpRetCodeLine()
・ 応答ヘッダー内のHTTPステータス行のみを返却します。
(I)public String fnsRetCodeLine()
・ 返却値としてFNSリターンメッセージを取得します。
・ メソッドisFnsDoneの返却値がtrueの場合FNSの正常メッセージが取得できます。
注意:ページ参照(XXPageメソッド)や電子フォーム参照(FormPoolメソッド)および受信情報取出し(actXXX_getDataメソッド)等では、正常終了時にはリターンメッセージを返却しません。これはisFnsDoneによる判定は行えないと云うことを意味します。
(3)エージェントプログラムの動作環境
(a)エージェントプログラムを動作させるためには、Sun Microsystems, Inc. のjava1.4.0以上の実行環境を必要とします。
(b)FNSエージェントプログラムとFNSサーバ間の通信はSSL(Secure Sockets Layer)で行われます。エージェントプログラム側では、証明書メンテナンスプログラムを使用して、接続するFNSサーバの証明書を「信頼している証明書」に含める必要があります。証明書メンテナンスプログラムはFNSインストール後のフォルダー内のサブフォルダーCertMntにありますので、FNSエージェントプログラムを稼動するコンピュータにコピーしてご利用ください。
(4)エージェントプログラムの作成例
// An example of FNS agent program.
// DemoPkg.java
//
// 本エージェントプログラムが動作するFNSグループとして下記が作成済みであると
// 仮定しています。
// (1)FNSグループ名:t10
// (2)グループ種別:1対多
// (3)グループ名:t10
// (4)管理者名:un パスワード:un
// (5)利用者1の名前:u1 パスワード:u1
//
// Java標準パッケージのインポート
import java.util.*;
import java.io.*;
//
// FNSエージェントプログラムJavaパッケージのインポート
import jp.co.ITNetInc.fns.agent.*;
//
public class DemoPkg {
public static void main(String args[]){
System.out.println("--------- start -----------");
//
// サーブレットランナーを生成します
// このエージェントプログラムが、FNSサーバがインストールされたマシン上で
// 動作するものと仮定していますのでホストは"127.0.0.1"としています。
FnsRunner run = new FnsRunner("127.0.0.1",443,"fns");
//
try{
int retcd;
/*--- 利用者u1がFNSグループt10にログイン ---*/
retcd = run.login("t10","u1","u1");
if (retcd != 0) {
errmes("u1-login()" ,run);
return;
}
// テキストデータの送信
retcd = run.transfer_text("_ALLOTHERSIDE","title of message-u1-string"
,"message-u1-string. hello.","text/plain",null);
if (retcd != 0) {
errmes("u1-transfer_text()" ,run);
return;
}
// ファイルの送信
File fl = new File("meesage-u1-file.htm");
FileInputStream fin = new FileInputStream(fl);
byte fl_cntnt[] = new byte[(int)fl.length()];
fin.read(fl_cntnt);
retcd = run.transfer_file("_ALLOTHERSIDE","title of meesage-u1-file"
, fl_cntnt,".htm",null);
if (retcd != 0) {
errmes("u1-transfer_file()" ,run);
return;
}
// 現在の利用者u1のセッションをログアウト
retcd = run.logout();
if (retcd != 0) {
errmes("u1-logout()" ,run);
return;
}
/*--- 運用者unがFNSグループt10にログイン ---*/
retcd = run.login("t10","un","un");
if (retcd != 0) {
errmes("un-login()" ,run);
return;
}
//
// **運用者unが受信キューから情報を読み出します。**
System.out.println("--------- un received next data. ------------");
Vector vids = new Vector();
String oldid = null;
// 受信キューをDATAIDで検索し、クラスResActQue_queryを得ます。
for (int cnt=1; ;cnt +=1) {
FnsRunner.ResActQue_query rqq = run.actQue_query(oldid, null);
if (rqq == null) {
errmes("un-actQue_query() No" + cnt ,run);
return;
}
if (rqq.dataid == null) {
break;
}
// 正常にクラスResActQue_queryを得たので、データを読み出します。
Response res = run.actQue_getData(rqq.dataid);
if (res == null) {
errmes("un-actQue_getData() No" + cnt ,run);
return;
}
System.out.println("-------- No" + cnt +". data-content:");
byte ret[] = res.content();
System.out.write(ret,0,ret.length);
System.out.println("-------- No" + cnt +". content end ------------");
oldid = rqq.dataid;
vids.addElement(oldid);
}
// 読出したデータを受信キューから削除
String ids[] = new String[vids.size()];
for (int i=0; i < vids.size(); i += 1) {
ids[i] = (String)vids.elementAt(i);
}
retcd = run.actQue_delete(ids);
if (retcd != 0) {
errmes("un-actQue_delete()" ,run);
return;
}
// 運用者unのセッションをログアウト
retcd = run.logout();
if (retcd != 0) {
errmes("un-logout()" ,run);
return;
}
} catch (Exception e){
System.out.println("exception:" + e + "");
}
System.out.println("--------- end -----------");
return;
}
static void errmes(
String position,
FnsRunner run
){
System.out.println("**** error(" + position + ")*****");
Response res = run.getLastResponse();
byte ret[] = res.content();
System.out.write(ret,0,ret.length);
return;
}
}