Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

ファイル送信アダプタの使用法

この章では、ファイル送信アダプタ (EnsLib.File.OutboundAdapterOpens in a new tab) の使用方法について説明します。この章は以下の節で構成されています。

Tip:

Ensemble では、このアダプタを使用する特殊なビジネス・サービス・クラスとユーザのニーズに適したビジネス・サービス・クラスの 1 つも提供されます。そのため、プログラミングの必要がありません。"Ensemble の紹介" の “接続オプション” の節を参照してください。

全般的な動作

プロダクション内で、送信アダプタは、ユーザが作成および構成するビジネス・オペレーションに関連付けられます。このビジネス・オペレーションはプロダクション内からメッセージを受信し、メッセージ・タイプを調べ、適切なメソッドを実行します。このメソッドは、通常、関連するアダプタのメソッドを実行します。

アダプタを使用するビジネス・オペレーションの作成

EnsLib.File.OutboundAdapterOpens in a new tab を使用するビジネス・オペレーションを作成するために、新しいビジネス・オペレーション・クラスを作成します。後で、そのクラスをプロダクションに追加して構成します

存在しなければ、該当するメッセージ・クラスを作成する必要もあります。"Ensemble プロダクションの開発" の “Ensemble メッセージの定義” を参照してください。

ビジネス・オペレーション・クラスの基本要件を以下に列挙します。

  • ビジネス・オペレーション・クラスは、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 は Ensemble 要求メッセージ・クラスの名前、ResponseClass は Ensemble 応答メッセージ・クラスの名前です。通常、メソッド・コードは、ビジネス・オペレーションのプロパティおよび Adapter プロパティのメソッドを参照します。

    メッセージ・クラスの定義方法は、"Ensemble プロダクションの開発" の “Ensemble メッセージの定義” を参照してください。

    メッセージ・ハンドラ・メソッドの定義方法は、後述する “メッセージ・ハンドラ・メソッドの作成” を参照してください。

  • その他のオプションと一般情報は、"Ensemble プロダクションの開発" の “ビジネス・オペレーション・クラスの定義” を参照してください。

以下の例は、必要となる一般的な構造を示しています。

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>
}
}
Note:

スタジオには、上記のようなビジネス・オペレーション・スタブの作成に使用できるウィザードが用意されています。このウィザードにアクセスするには、[ファイル][新規作成] をクリックし、[プロダクション] タブをクリックします。 次に [ビジネス・オペレーション] をクリックして [OK] をクリックします。

メッセージ・ハンドラ・メソッドの作成

EnsLib.File.OutboundAdapterOpens in a new tab で使用されるビジネス・オペレーション・クラスを作成する場合の最大のタスクは、このアダプタで使用されるメッセージ・ハンドラ、つまり、Ensemble メッセージを受信してファイルを書き込むメソッドの作成です。

各メッセージ・ハンドラ・メソッドは、以下のシグニチャを持っている必要があります。

Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status

ここで、Sample はメソッド名、RequestClass は Ensemble 要求メッセージ・クラスの名前、ResponseClass は Ensemble 応答メッセージ・クラスの名前です。

通常、このメソッドは以下の操作を実行します。

  1. 受信要求メッセージを調べます。

  2. 受信要求の情報を使用して、ビジネス・オペレーションの 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 メソッドのいずれかを呼び出すことができます。

  3. 必ず出力引数 (pOutput) を設定します。通常、応答メッセージと同じように設定します。この手順は必須です。

  4. 適切なステータスを返します。この手順は必須です。

ビジネス・オペレーションからのアダプタ・メソッドの呼び出し

ビジネス・オペレーション・クラスは、以下の EnsLib.File.OutboundAdapterOpens in a new tab のインスタンス・メソッドを使用できます。

CreateTimestamp()
ClassMethod CreateTimestamp(pFilename As %String = "",
                            pSpec As %String = "_%C") As %String

開始点に pFilename 文字列を使用し、pSpec で指定されているタイム・スタンプ指定子を組み入れて、結果文字列を返します。デフォルトのタイム・スタンプ指定子は _%C で、これはミリ秒までの完全な日時を表します。

タイム・スタンプ規則の詳細は、"Ensemble プロダクションの構成" の “ファイル名に関するタイム・スタンプ指定” を参照してください。

Delete()
Method Delete(pFilename As %String) As %Status

ファイルを削除します。

Exists()
Method Exists(pFilename As %String) As %Boolean

ファイルが存在するときは 1 (真)、存在しないときは 0 (偽) を返します。

GetStream()
Method GetStream(pFilename As %String,
                 ByRef pStream As %AbstractStream = {$$$NULLOREF})
                 As %Status

ファイルからストリームを取得します。

NameList()
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

PutLine()
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))"

PutString()
Method PutString(pFilename As %String, pData As %String) As %Status

ファイルに文字列を書き込みます。

PutStream()
Method PutStream(pFilename As %String,
                 pStream As %Stream,
                 ByRef pLen As %Integer = -1) As %Status

ファイルにストリームを書き込みます。

Rename()
Method Rename(pFilename As %String,
              pNewFilename As %String,
              pNewPath As %String = "") As %Status

現在のパスにあるファイルの名前を変更します。または、pNewPath で指定されているパスにファイルを移動します。

ビジネス・オペレーション・クラスの例

EnsLib.File.OutboundAdapterOpens in a new tab を参照するビジネス・オペレーション・クラスのコードの例を以下に示します。このクラスは 2 つの操作を実行します。このクラスが有効な患者データを受信すると、クラスは患者のステータスに基づいて患者情報を保管します。このクラスが無効な患者データを受信すると、その情報を個別にログに記録します。

Class training.healthcare.operation.OpeFilePatient Extends Ens.BusinessOperation
{

Parameter ADAPTER = "EnsLib.File.OutboundAdapter";

Parameter INVOCATION = "Queue";

/* write on log file wrong patient records */
Method writeHL7Message(
       pRequest As EnsLib.HL7.Message,
       Output pResponse As Ens.StringResponse)
       As %Status
{
  $$$LOGINFO("called HL7 Writer")

  set ..Adapter.FilePath="C:\Intersystems\ensemble\test\ftp"

  set st=..Adapter.PutLine("patient.log",message)

  Quit $$$OK
}

/* write on log file wrong patient records */
Method logWrongPatient(
       pRequest As training.healthcare.message.MsgPatient,
       Output pResponse As Ens.StringResponse)
       As %Status
{
  $$$LOGINFO("called OpeFilePatient")

  set ..Adapter.FilePath="C:\Intersystems\ensemble\test\errorparh"
  set message="some information are missing from record: " _
              pRequest.sso _ ", " _
              pRequest.name _ ", " _
              pRequest.surname

  set st=..Adapter.PutLine("patient.log",message)

  Quit $$$OK
}

/* write in xml format the list of active/inactive/requested patients */
Method writeSSOList(
       pRequest As Ens.StringRequest,
       Output pResponse As Ens.StringResponse)
       As %Status
{
  set ..Adapter.FilePath="C:\Intersystems\ensemble\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,"<patients>")

  set rs=
  ##class(training.healthcare.data.TabPatient).selectPatients("",status)
  while rs.Next(){
    set st=..Adapter.PutLine(fileName,"<patient>")
    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,"<patient>")
  }

  set st=..Adapter.PutLine(fileName,"<patients>")

  set pResponse=##class(Ens.StringResponse).%New()
  set pResponse.StringValue="done"

  quit $$$OK
}

XData MessageMap
{
<MapItems>
  <MapItem MessageType="training.healthcare.message.MsgPatient">
    <Method>logWrongPatient</Method>
  </MapItem>
   <MapItem MessageType="Ens.StringRequest">
    <Method>writeSSOList</Method>
  </MapItem>
</MapItems>
}

}

ビジネス・オペレーションの追加と構成

ビジネス・オペレーションを Ensemble プロダクションに追加するには、管理ポータルを使用して以下の操作を行います。

  1. Ensemble プロダクションにビジネス・オペレーション・クラスのインスタンスを追加します。

  2. ビジネス・オペレーションを構成します。設定の詳細は、“設定の参照先” を参照してください。

  3. ビジネス・オペレーションを有効化します。

  4. プロダクションを実行します。

FeedbackOpens in a new tab