ファイル送信アダプタの使用法
ここでは、ファイル送信アダプタ (EnsLib.File.OutboundAdapterOpens in a new tab) の使用方法について説明します。
InterSystems IRIS® では、このアダプタを使用する特殊なビジネス・サービス・クラスとユーザのニーズに適したビジネス・サービス・クラスの 1 つも提供されます。そのため、プログラミングの必要がありません。"接続オプション" を参照してください。
全般的な動作
プロダクション内で、送信アダプタは、ユーザが作成および構成するビジネス・オペレーションに関連付けられます。このビジネス・オペレーションはプロダクション内からメッセージを受信し、メッセージ・タイプを調べ、適切なメソッドを実行します。このメソッドは、通常、関連するアダプタのメソッドを実行します。
アダプタを使用するビジネス・オペレーションの作成
EnsLib.File.OutboundAdapterOpens in a new tab を使用するビジネス・オペレーションを作成するために、新しいビジネス・オペレーション・クラスを作成します。後で、そのクラスをプロダクションに追加して構成します。
存在しなければ、該当するメッセージ・クラスを作成する必要もあります。"メッセージの定義" を参照してください。
ビジネス・オペレーション・クラスの基本要件を以下に列挙します。
-
ビジネス・オペレーション・クラスは、Ens.BusinessOperationOpens in a new tab を拡張するものでなければなりません。
-
クラスの ADAPTER パラメータは EnsLib.File.OutboundAdapterOpens in a new tab と一致する必要があります。
-
クラスの INVOCATION パラメータは、使用する呼び出しスタイルを指定する必要があります。以下のいずれかを使用します。
-
Queue は、メッセージが 1 つのバックグラウンド・ジョブ内で作成され、元のジョブが解放された段階でキューに配置されます。後で、メッセージが処理されるときに、別のバックグラウンド・ジョブがこのタスクに割り当てられます。これは最も一般的な設定です。
-
InProc は、メッセージが、作成されたジョブと同じジョブで生成、送信、および配信されることを意味します。このジョブは、メッセージが対象に配信されるまで送信者のプールに解放されません。これは特殊なケースのみに該当します。
-
-
クラスでは、少なくとも 1 つのエントリを含むメッセージ・マップを定義します。メッセージ・マップは、以下の構造を持つ XData ブロック・エントリです。
XData MessageMap { <MapItems> <MapItem MessageType="messageclass"> <Method>methodname</Method> </MapItem> ... </MapItems> }
-
クラスでは、メッセージ・マップ内で名前が付けられたすべてのメソッドを定義します。これらのメソッドは、メッセージ・ハンドラと呼ばれます。各メッセージ・ハンドラは、以下のシグニチャを持っている必要があります。
Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
ここで、Sample はメソッド名、RequestClass は要求メッセージ・クラスの名前、ResponseClass は応答メッセージ・クラスの名前です。通常、メソッド・コードは、ビジネス・オペレーションのプロパティおよび Adapter プロパティのメソッドを参照します。
メッセージ・クラスの定義方法は、"メッセージの定義" を参照してください。
メッセージ・ハンドラ・メソッドの定義方法は、"メッセージ・ハンドラ・メソッドの作成" を参照してください。
-
その他のオプションと一般情報は、"ビジネス・オペレーション・クラスの定義" を参照してください。
以下の例は、必要となる一般的な構造を示しています。
Class EHTP.NewOperation1 Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.File.OutboundAdapter";
Parameter INVOCATION = "Queue";
Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
{
Quit $$$ERROR($$$NotImplemented)
}
XData MessageMap
{
<MapItems>
<MapItem MessageType="RequestClass">
<Method>Sample</Method>
</MapItem>
</MapItems>
}
}
メッセージ・ハンドラ・メソッドの作成
EnsLib.File.OutboundAdapterOpens in a new tab で使用されるビジネス・オペレーション・クラスを作成する場合の最大のタスクは、このアダプタで使用されるメッセージ・ハンドラ、つまり、プロダクション・メッセージを受信してファイルを書き込むメソッドの作成です。
各メッセージ・ハンドラ・メソッドは、以下のシグニチャを持っている必要があります。
Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
ここで、Sample はメソッド名、RequestClass は要求メッセージ・クラスの名前、ResponseClass は応答メッセージ・クラスの名前です。
通常、このメソッドは以下の操作を実行します。
-
受信要求メッセージを調べます。
-
受信要求の情報を使用して、ビジネス・オペレーションの Adapter プロパティのメソッドを呼び出します。下の例は、EnsLib.File.OutboundAdapterOpens in a new tab メソッドの PutString() を呼び出します。
/// Send an approval to the output file Method FileSendReply(pRequest As Demo.Loan.Msg.SendReply, Output pResponse As Ens.Response) As %Status { $$$TRACE("write to file "_pRequest.Destination) Set tSC=..Adapter.PutString(pRequest.Destination, pRequest.Text) Quit tSC }
同様の構文を使用して、"ビジネス・オペレーションからのアダプタ・メソッドの呼び出し" に記載された EnsLib.File.OutboundAdapterOpens in a new tab メソッドのいずれかを呼び出すことができます。
-
必ず出力引数 (pOutput) を設定します。通常、応答メッセージと同じように設定します。この手順は必須です。
-
適切なステータスを返します。この手順は必須です。
ビジネス・オペレーションからのアダプタ・メソッドの呼び出し
ビジネス・オペレーション・クラスは、以下の EnsLib.File.OutboundAdapterOpens in a new tab のインスタンス・メソッドを使用できます。
ClassMethod CreateTimestamp(pFilename As %String = "",
pSpec As %String = "_%C") As %String
開始点に pFilename 文字列を使用し、pSpec で指定されているタイム・スタンプ指定子を組み入れて、結果文字列を返します。デフォルトのタイム・スタンプ指定子は _%C で、これはミリ秒までの完全な日時を表します。
タイム・スタンプ規則の詳細は、"ファイル名に関するタイム・スタンプ指定" を参照してください。
Method Delete(pFilename As %String) As %Status
ファイルを削除します。
Method Exists(pFilename As %String) As %Boolean
ファイルが存在するときは 1 (真)、存在しないときは 0 (偽) を返します。
Method GetStream(pFilename As %String,
ByRef pStream As %AbstractStream = {$$$NULLOREF})
As %Status
ファイルからストリームを取得します。
Method NameList(Output pFileList As %ListOfDataTypes,
pWildcards As %String = "*",
pIncludeDirs As %Boolean = 0) As %Status
FilePath 設定で指定したディレクトリ内のファイルのリストを取得します。ファイル名は %ListOfDataTypesOpens in a new tab オブジェクト内に返されます。各エントリは、以下のようにセミコロンで区切られた文字列の列挙で構成されます。
Filename;Type;Size;DateCreated;DateModified;FullPathName
Method PutLine(pFilename As %String, pLine As %String) As %Status
文字列をファイルに書き込み、LineTerminator プロパティで指定されている文字を文字列に付加します。デフォルトでは、LineTerminator は復帰改行で、その後に改行が続きます (ASCII 13、ASCII 10)。
LineTerminator プロパティに異なる値を必要とするオペレーティング・システムの場合は、ビジネス・オペレーションの OnInit() メソッドに値を設定します。以下に例を示します。
Method OnInit() As %Status
{
Set ..Adapter.LineTerminator="$C(10)"
Quit $$$OK
}
また、プロパティ値がオペレーティング・システムに依存するように設定することもできます。
Set ..Adapter.LineTerminator="$Select($$$isUNIX:$C(10),1:$C(13,10))"
Method PutString(pFilename As %String, pData As %String) As %Status
ファイルに文字列を書き込みます。
Method PutStream(pFilename As %String,
pStream As %Stream,
ByRef pLen As %Integer = -1) As %Status
ファイルにストリームを書き込みます。
Method Rename(pFilename As %String,
pNewFilename As %String,
pNewPath As %String = "") As %Status
現在のパスにあるファイルの名前を変更します。または、pNewPath で指定されているパスにファイルを移動します。
ビジネス・オペレーション・クラスの例
EnsLib.File.OutboundAdapterOpens in a new tab を参照するビジネス・オペレーション・クラスのコードの例を以下に示します。このクラスは 2 つの操作を実行します。このクラスが有効な Person データを受信すると、クラスは Person のステータスに基づいて Person の情報を保管します。このクラスが無効な Person データを受信すると、その情報を個別にログに記録します。
Class training.operation.OpeFilePerson extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.File.OutboundAdapter";
Parameter INVOCATION = "Queue";
/* write on log file wrong person records */
Method writeMessage(
pRequest As MyData.Message,
Output pResponse As Ens.StringResponse)
As %Status
{
$$$LOGINFO("called Writer")
set ..Adapter.FilePath="C:\InterSystems\test\ftp"
set st=..Adapter.PutLine("person.log",message)
Quit $$$OK
}
/* write on log file wrong person records */
Method logWrongPerson(
pRequest As training.healthcare.message.MsgPerson,
Output pResponse As Ens.StringResponse)
As %Status
{
$$$LOGINFO("called OpeFilePerson")
set ..Adapter.FilePath="C:\InterSystems\test\errorparh"
set message="some information are missing from record: " _
pRequest.sso _ ", " _
pRequest.name _ ", " _
pRequest.surname
set st=..Adapter.PutLine("Person.log",message)
Quit $$$OK
}
/* write in xml format the list of active/inactive/requested Persons */
Method writeSSOList(
pRequest As Ens.StringRequest,
Output pResponse As Ens.StringResponse)
As %Status
{
set ..Adapter.FilePath="C:\InterSystems\test\ftp"
set status=pRequest.StringValue
if status="ACTIVE" set fileName="ActiveSSO.xml"
if status="INACTIVE" set fileName="InactiveSSO.xml"
if status="REQUESTED" set fileName="RequestedSSO.xml"
set st=..Adapter.PutLine(fileName,"<Persons>")
set rs=
##class(training.healthcare.data.TabPerson).selectPersons("",status)
while rs.Next(){
set st=..Adapter.PutLine(fileName,"<Person>")
for i=1:1:rs.GetColumnCount() {
set st=..Adapter.PutLine(fileName,
"<"_ rs.GetColumnName(i)_">" _
rs.GetData(i)_"</"_ rs.GetColumnName(i)_">")
}
set st=..Adapter.PutLine(fileName,"<Person>")
}
set st=..Adapter.PutLine(fileName,"<Persons>")
set pResponse=##class(Ens.StringResponse).%New()
set pResponse.StringValue="done"
quit $$$OK
}
XData MessageMap
{
<MapItems>
<MapItem MessageType="training.healthcare.message.MsgPerson">
<Method>logWrongPerson</Method>
</MapItem>
<MapItem MessageType="Ens.StringRequest">
<Method>writeSSOList</Method>
</MapItem>
</MapItems>
}
}
ビジネス・オペレーションの追加と構成
ビジネス・オペレーションをプロダクションに追加するには、管理ポータルを使用して以下の操作を行います。
-
ビジネス・オペレーション・クラスのインスタンスをプロダクションに追加します。
-
ビジネス・オペレーションを構成します。設定の詳細は、設定のリファレンスを参照してください。
-
ビジネス・オペレーションを有効化します。
-
プロダクションを実行します。