FTP 受信アダプタの使用法

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

Tip:

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

全般的な動作

EnsLib.FTP.InboundAdapterOpens in a new tab により、Ensemble は FTP プロトコル経由でファイルを受信できます。このアダプタは、構成された場所から FTP 入力を受信したり、入力を読み取ったり、入力をストリームとして関連するビジネス・サービスに送信したりします。ユーザが作成および構成するビジネス・サービスは、このストリームを使用してプロダクションの他の部分と通信します。

入力に対する通知または応答が FTP サーバに必要な場合、この応答の作成とデータ・ソースへの返送も、ビジネス・サービスが EnsLib.FTP.InboundAdapterOpens in a new tab を経由して行います。アダプタは応答を評価したり補足したりしませんが、応答を受け取った場合はこれを渡します。

下の図は、受信メッセージの全体フローを示しています (応答は含まれていません)。

詳細は、以下のとおりです。

アダプタは、構成されたデータ・ソースからの入力を検出するたびに、ビジネス・サービス・クラスの内部 ProcessInput() メソッドを呼び出して、ストリームを入力引数として渡します。
ビジネス・サービス・クラスの内部 ProcessInput() メソッドが実行されます。このメソッドは、すべてのビジネス・サービスが必要とする内部情報の保持など、基本的な Ensemble タスクを実行します。ビジネス・サービス・クラスが継承するこのメソッドは、カスタマイズや上書きを行いません。
次に、ProcessInput() メソッドがカスタムの OnProcessInput() メソッドを呼び出し、ストリーム・オブジェクトを入力として渡します。このメソッドに関する要件については、後述の “OnProcessInput() メソッドの実装” で説明します。
データ・ソースが何らかの確認または応答を必要としている場合は、ビジネス・サービスの OnProcessInput() メソッドがそれを作成します。受信アダプタは、単にこの応答を外部データ・ソースに返すだけです。

応答メッセージは、同じパスを逆向きにたどります。

受信アダプタを使用するビジネス・サービスの作成

このアダプタをプロダクションで使用するには、ここに記載されているように新しいビジネス・サービスを作成します。後で、それをプロダクションに追加して、構成します。存在しなければ、該当するメッセージ・クラスを作成する必要もあります。"Ensemble プロダクションの開発" の “Ensemble メッセージの定義” を参照してください。

ビジネス・サービス・クラスの基本要件を以下に列挙します。

ビジネス・サービス・クラスは Ens.BusinessServiceOpens in a new tab を拡張するものでなければなりません。
クラス内の ADAPTER パラメータは EnsLib.FTP.InboundAdapterOpens in a new tab と一致する必要があります。
クラスは、“OnProcessInput メソッドの実装” に記載されているように、OnProcessInput() メソッドを実装する必要があります。
その他のオプションと一般情報は、"Ensemble プロダクションの開発" の “ビジネス・サービス・クラスの定義” を参照してください。

OnProcessInput() メソッドの実装

カスタム・ビジネス・サービス・クラスにおいて、OnProcessInput() メソッドは以下のシグニチャを持つ必要があります。

Method OnProcessInput(pInput As %CharacterStream,pOutput As %RegisteredObject) As %Status

または、以下のようになります。

Method OnProcessInput(pInput As %BinaryStream,pOutput As %RegisteredObject) As %Status

説明：

pInput は、アダプタがこのビジネス・サービスに送信するメッセージ・オブジェクトです。これは、予想されるストリームの内容に応じて、%CharacterStreamOpens in a new tab と %BinaryStreamOpens in a new tab のどちらかの型にすることができます。アダプタ設定 ([文字セット]) を使用して、入力ストリームが文字かバイナリかを指定します。“設定の参照先” を参照してください。
pOutput は、メソッド・シグニチャに必要な汎用出力引数です。

OnProcessInput() メソッドは、以下の一部またはすべてを実行する必要があります。

入力ストリーム (pInput) を検査して、その使用方法を決定します。
この入力の型は、Charset アダプタ設定の値により異なります。
- Charset 設定にバイナリ値がある場合、pInput は %BinaryStreamOpens in a new tab 型となり、バイトが含まれます。
- バイナリ値がない場合は、pInput は %CharacterStream Opens in a new tab 型となり、文字が含まれます。
  Charset の詳細は、“設定の参照先” を参照してください。
ビジネス・サービスから送信されることになる要求メッセージのインスタンスを作成します。
メッセージ・クラスの作成方法は、"Ensemble プロダクションの開発" の “Ensemble メッセージの定義” を参照してください。
要求メッセージの場合は、必要に応じて、入力内の値を使用してそのプロパティを設定します。
ビジネス・サービスの適切なメソッドを呼び出して、要求をプロダクション内の宛先に送信します。具体的には、SendRequestSync()、SendRequestAsync()、または (あまり一般的ではない) SendDeferredResponse() を呼び出します。詳細は、"Ensemble プロダクションの開発" の “要求メッセージの送信” を参照してください。
これらの各メソッドは、ステータス (具体的には、%StatusOpens in a new tab のインスタンス) を返します。
必ず出力引数 (pOutput) を設定します。通常、受信した応答メッセージと同じように設定します。この手順は必須です。
適切なステータスを返します。この手順は必須です。

アダプタ・メソッドの呼び出し

ビジネス・サービス内では、以下のアダプタのインスタンス・メソッドを呼び出すことができます。

Connect()

Method Connect(pTimeout As %Numeric = 30,
                pInbound As %Boolean = 0) As %Status

FTP サーバに接続してログインし、ディレクトリと転送モードを設定します。

Disconnect()

Method Disconnect(pInbound As %Boolean = 0) As %Status

FTP サーバから切断します。

ParseFilename()

Method ParseFilename(pFilenameLine As %String,
                     Output pTimestamp As %String,
                     Output pSize As %String) As %Boolean

TestConnection()

Method TestConnection()

接続されていてもソケットを失っているとアダプタが判断した場合に、接続状態を示すプロパティを修正します。

以下のメソッドも使用できます。各メソッドは、ユーザが管理ポータルで調整可能なアダプタ設定に対応しています。ユーザが [適用] をクリックして [設定] の値の変更内容を受け入れるたびに、対応の SettingSet メソッドが実行します。いずれかの設定を変更した後に、これらのメソッドを使用して以下のように調整することができます。各設定の詳細な説明は、“設定の参照先” を参照してください。

ArchivePathSet()

Method ArchivePathSet(pInVal As %String) As %Status

ArchivePath は、アダプタがファイルの処理を完了した後に、各ファイルのコピーを格納するディレクトリです。

CharsetSet()

Method CharsetSet(cset As %String) As %Status

[文字セット] は、入力ファイルの文字セットです。

ConnectedSet()

Method ConnectedSet(pValue As %Boolean) As %Status

[Connected] は、FTP サーバへのアダプタの接続を追跡する内部プロパティです。

CredentialsSet()

Method CredentialsSet(pInVal As %String) As %Status

[Credentials] は、FTP サーバへの接続を承認できる Ensemble 資格情報エントリです。Ensemble 認証情報の作成方法は、"Ensemble プロダクションの構成" を参照してください。

FilePathSet()

Method FilePathSet(path As %String) As %Status

[FilePath] は、FTP サーバ上のファイルの検索先ディレクトリです。

FTPPortSet()

Method FTPPortSet(port As %String) As %Status

[FTPPort] は、接続先の FTP サーバ上の TCP ポートです。

FTPServerSet()

Method FTPServerSet(server As %String) As %Status

[FTPServer] は、接続先の FTP サーバです。ここには IP アドレスか、ドメイン・ホスト・コントローラが名前を解決できるのであればサーバ名を指定できます。

SSLConfigSet()

Method SSLConfigSet(sslcfg As %String) As %Status

[SSLConfig] は、この接続の認証に使用する SSL または TLS の構成エントリです。

ビジネス・サービス・クラス

EnsLib.FTP.InboundAdapterOpens in a new tab を参照するビジネス・サービス・クラスのコードの例を以下に示します。

Class EnsLib.FTP.PassthroughService Extends Ens.BusinessService
{

Parameter ADAPTER = "EnsLib.FTP.InboundAdapter";

/// Configuration item(s) to which to send file stream messages
Property TargetConfigNames As %String(MAXLEN = 1000);

Parameter SETTINGS = "TargetConfigNames";

/// Wrap the input stream object in a StreamContainer message object and send
/// it. If the adapter has a value for ArchivePath, send async; otherwise send
/// synchronously to ensure that we don't return to the Adapter and let it
/// delete the file before the target Config Item is finished processing it.

Method OnProcessInput(pInput As %Stream.Object,
                      pOutput As %RegisteredObject) As %Status
{
  Set tSC=$$$OK, tSource=pInput.Attributes("Filename"),
                 pInput=##class(Ens.StreamContainer).%New(pInput)
  Set tWorkArchive=(""'=..Adapter.ArchivePath)

  For iTarget=1:1:$L(..TargetConfigNames, ",") {
    Set tOneTarget=$ZStrip($P(..TargetConfigNames,",",iTarget),"<>W")
    Continue:""=tOneTarget
    $$$sysTRACE("Sending input Stream ...")

    If tWorkArchive {
      Set tSC1=..SendRequestAsync(tOneTarget,pInput)
      Set:$$$ISERR(tSC1) tSC=$$$ADDSC(tSC,tSC1)
    } Else {
      #; If not archiving send Sync to avoid Adapter deleting file before
      #; Operation gets it
      Set tSC1=..SendRequestSync(tOneTarget,pInput)
      Set:$$$ISERR(tSC1) tSC=$$$ADDSC(tSC,tSC1)
      }
    }
    Quit tSC
  }
}

この例では、tSource 変数を、受信ストリーム (pInput) が持つ Attributes プロパティの Filename 添え字に格納されている元のファイル名に設定します。

ビジネス・サービスの追加と構成

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

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