TCP 送信アダプタの使用法

この章では、TCP 送信アダプタのそれぞれ (EnsLib.TCP.CountedOutboundAdapterOpens in a new tab、EnsLib.TCP.CountedXMLOutboundAdapterOpens in a new tab、および EnsLib.TCP.TextLineOutboundAdapterOpens in a new tab) の使用方法について説明します。この章は以下の節で構成されています。

Tip:

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

また、EnsLib.TCP.OutboundAdapterOpens in a new tab またはそのサブクラスのいずれかに基づいて新しい送信アダプタ・クラスを開発することもできます。後述する “カスタム TCP アダプタ・クラスの作成” の節を参照してください。

TCP 送信アダプタの概要

Ensemble には、すべてが EnsLib.TCP.OutboundAdapterOpens in a new tab のサブクラスである以下の送信 TCP アダプタが用意されています。

EnsLib.TCP.CountedOutboundAdapterOpens in a new tab には、TCP 接続経由でデータのブロックを読み書きするためのメソッドが含まれています。Ensemble は、TCP リスナとデータ・ブロックを交換する TCP クライアントとして動作します。ブロック長はブロックの先頭 4 バイトで指定されています。この規則を使用することで、外部 TCP サーバが要求を処理できるように、Ensemble ビジネス・オペレーションは要求を送信します。
EnsLib.TCP.CountedXMLOutboundAdapterOpens in a new tab は、XML エクスポート・オブジェクトをカウントされたバイト・ブロックとして TCP 接続経由で送信し、応答オブジェクトをインポートします。
EnsLib.TCP.TextLineOutboundAdapterOpens in a new tab には、TCP 接続経由でテキスト文字列を読み書きするためのメソッドが含まれています。Ensemble は、TCP リスナとデータ・ブロックを交換する TCP クライアントとして動作します。テキスト文字列の終端文字のデフォルトは新規行文字 (ASCII 10) です。

全般的な動作

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

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

TCP 送信アダプタを使用するビジネス・オペレーションを作成するために、新しいビジネス・オペレーション・クラスを作成します。後で、それをプロダクションに追加して、構成します。

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

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

ビジネス・オペレーション・クラスは、Ens.BusinessOperationOpens in a new tab を拡張するものでなければなりません。
クラス内の ADAPTER パラメータは EnsLib.TCP.CountedOutboundAdapterOpens in a new tab、EnsLib.TCP.CountedXMLOutboundAdapterOpens in a new tab、または EnsLib.TCP.TextLineOutboundAdapterOpens 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 メッセージの定義” を参照してください。
メッセージ・ハンドラ・メソッドの定義方法は、後述する “メッセージ・ハンドラ・メソッドの作成” を参照してください。
クラスは OnConnect() コールバック・メソッドを実装できます。このメソッドは、TCP 送信アダプタがリモート・システムとの新しい接続を確立するたびに呼び出されます。
OnConnect() メソッドを実装する場合は、以下のシグニチャを付与する必要があります。
```
Method OnConnect(pTimeout As %Numeric) As %Status
```
新しい接続が確立されるたびに何らかの処理 (ログオン・シーケンスやハンドシェーク・トークンの送信など) を実行する必要がある場合は、このメソッドを実装します。timeout 引数は、TCP 送信アダプタによって自動的に指定されます。この引数の値は、ConnectTimeout アダプタ設定から取得されます。詳細は、“TCP 送信アダプタに関する設定” を参照してください。
OnConnect() がエラー・ステータスを返した場合は、新しい接続が失敗して、アダプタが切り離されます。トラップされない例外が OnConnect() 内で発生した場合、アダプタはその例外をキャッチして、OnConnect() が実装されていなかった場合と同じように処理を継続します。
その他のオプションと一般情報は、"Ensemble プロダクションの開発" の “ビジネス・オペレーション・クラスの定義” を参照してください。

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

Class ETCP.NewOperation1 Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.TCP.CountedOutboundAdapter";

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] をクリックします。

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

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

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

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

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

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

受信要求メッセージを調べます。
受信要求の情報を使用して、ビジネス・オペレーションの Adapter プロパティのメソッドを呼び出します。例えば、Connect() メソッドを呼び出す行は次のようになります。
```
 set sc=..Adapter.Connect()
```
“ビジネス・オペレーションからのアダプタ・メソッドの呼び出し” を参照してください。
必ず出力引数 (pOutput) を設定します。通常、応答メッセージと同じように設定します。この手順は必須です。
適切なステータスを返します。この手順は必須です。

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

Connect()

Method Connect(pTimeout As %Numeric) As %Status

すべての TCP 送信アダプタに適用されます。

Connect() は、TCP リスナ・マシン上のポートに対して TCP ソケットを開きます。Connect() には、接続試行が成功するのを待つ秒数を指定する %NumericOpens in a new tab という 1 つの入力引数があります。Connect() メソッドの一般的な呼び出しでは、構成可能な ConnectTimeout プロパティの値がこの入力引数の値として使用されます。

Stay Connected アダプタ設定が –1 に設定されている場合は、Ensemble の起動時に、OnInit() メソッド内から自動的に接続が確立されます。“設定の参照先” を参照してください。

Disconnect()

Method Disconnect()

すべての TCP 送信アダプタに適用されます。

Disconnect() は TCP リスナへの接続を解除します。

SendMessageStream()

Method SendMessageStream(pRequestStream As %Stream.Object,
  ByRef pResponseStream As %CharacterStream = "%GlobalCharacterStream")
  As %Status

EnsLib.TCP.CountedOutboundAdapterOpens in a new tab に適用されます。

SendMessageStream() は、ストリーム・コンテンツを TCP ソケット上のカウントされたブロックとして送信します。

SendMessageString()

Method SendMessageString(pRequestString As %String,
                Output pResponseString As %String) As %Status

EnsLib.TCP.CountedOutboundAdapterOpens in a new tab と EnsLib.TCP.TextLineOutboundAdapterOpens in a new tab に適用されます。

SendMessageString() は、文字列コンテンツを TCP ソケット上のカウントされたブロックとして送信します。

SendMessageXMLObj()

Method SendMessageXMLObj(pRequest As %RegisteredObject,
                Output pResponse As %RegisteredObject) As %Status

EnsLib.TCP.CountedXMLOutboundAdapterOpens in a new tab に適用されます。

SendMessageXMLObj() は、要求オブジェクトをカウントされた XML ブロックとして TCP リスナに送信します。Get Reply アダプタ設定が真 (True) の場合は、SendMessageXMLObj() が TCP リスナからの応答をカウントされた XML ブロックとして取得します。これは、Ensemble オブジェクトとしてインポートされます。Get Replyの詳細は、“設定の参照先” を参照してください。

TestConnection()

Method TestConnection()

すべての TCP 送信アダプタに適用されます。

TestConnection() は、接続状態を反映しているプロパティを修正します。アダプタが接続されている場合は、TestConnection() は True を返します。接続されていない場合は、TestConnection() は Disconnect() を呼び出して、False を返します。

EnsLib.TCP.CountedOutboundAdapter の例

EnsLib.TCP.CountedOutboundAdapterOpens in a new tab を参照するビジネス・オペレーション・クラスの例を以下に示します。

Class Test.GeneralTCPOperation Extends Ens.BusinessOperation
{
 Parameter ADAPTER = "EnsLib.TCP.CountedOutboundAdapter";
 Parameter MAXREAD=30000;

 Method OnMessage(pReq As Test.GeneralSendRequest,
                 Output pResponse As Test.GeneralSendResponse) As %Status
 {
  Set str=
    pReq.Hr_pReq.DataLth_pReq.BID_pReq.Hr2_pReq.HrVacant_pReq.Cat_pReq.Hr3_pReq.Hr4
  Set tTextStream= ##class(%GlobalCharacterStream).%New()
  Set tSC=tTextStream.Write(str)
  Do pReq.Body2.Read(32) // Throw it away
  Set len=..#MAXREAD
  Set token= pReq.Body2.Read(.len)
  Set i=0
  While(len>0) {
     Set i=i+1
     Do tTextStream.Write(token)
     Set len=..#MAXREAD
     Set token= pReq.Body2.Read(.len)
  }
  Set tSC=
  ..Adapter.SendMessageStream(tTextStream,.tStreamReply) Quit:$$$ISERR(tSC) tSC
  Set pResponse=##class(Test.GeneralSendResponse).%New()
  Do tStreamReply.Rewind()
  Set pResponse.Body = tStreamReply.Read(,.tSC)
  Quit tSC
 }
}

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

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

ビジネス・オペレーション・クラスのインスタンスを Ensemble プロダクションに追加します。
ビジネス・オペレーションを構成します。設定の詳細は、“設定の参照先” を参照してください。
ビジネス・オペレーションを有効化します。
プロダクションを実行します。