FTP 送信アダプタの使用法

全般的な動作

EnsLib.FTP.OutboundAdapterOpens in a new tab を使用すれば、Ensemble プロダクションから FTP プロトコル経由でファイルを送信できます。このアダプタを使用するために、アダプタを使用するビジネス・オペレーションを作成して構成します。このビジネス・オペレーションはプロダクション内からメッセージを受信し、メッセージ・タイプを調べ、適切なメソッドを実行します。このメソッドは、通常、関連するアダプタのメソッドを実行します。

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

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

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

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

• ビジネス・オペレーション・クラスは、Ens.BusinessOperationOpens in a new tab を拡張するものでなければなりません。

• クラスの ADAPTER パラメータは EnsLib.FTP.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 プロダクションの開発" の “ビジネス・オペレーション・クラスの定義” を参照してください。

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

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

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

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

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

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

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

2. EnsLib.FTP.OutboundAdapterOpens in a new tab 内のメソッドの 1 つを呼び出すときは、Adapter プロパティを使用してアダプタ・オブジェクトを指定します。下の例は、ビジネス・オペレーション・メソッドから PutStream() メソッドを呼び出します。

     Quit ..Adapter.PutStream(pFilename,..%TempStream)
   

   

   同様の構文を使用して、“ビジネス・オペレーションからのアダプタ・メソッドの呼び出し” の節に記載されているメソッドのいずれかを呼び出すことができます。

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

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

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

ビジネス・オペレーション・クラスが EnsLib.FTP.OutboundAdapterOpens in a new tab を参照するときに、以下のアダプタ・メソッドが使用可能になります。前のトピックで説明した Adapter プロパティを使用して、ビジネス・オペレーション・クラス内のメソッドからこれらのアダプタ・メソッドを呼び出せます。

Connect()

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

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

FTP 送信アダプタには再試行サイクルがあり、以下の場合に実行して接続を再確立します。

• FTP サーバへの TCP 接続の確立を試行している間に、TCP ソケットの失敗またはタイムアウトが発生した場合。

• ローカル・クライアントがネットワーク・コードで応答した場合 (タイムアウト)。

• ローカル・クライアントが再試行可能コードで応答した場合 (タイムアウトのコード 529 などの FTP コード 52x または 4xx)。

CreateTimestamp()

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

基準として pFilename 文字列を使用し、pSpec で指定されているタイム・スタンプ指定子を組み込んで、結果の文字列を返します。デフォルトのタイム・スタンプ指定子は %f_%Q です。指定子のそれぞれの意味は次のとおりです。

• %f は、データ・ソースの名前 (この場合は入力ファイル名) を表します。

• _ は、リテラルのアンダースコア文字で、出力ファイル名に表示されます。

• %Q は、ODBC 形式の日付と時刻を表します。

書式コード %f に具体的な値を使用すると、その値に使用している |、?、\、/、:、[、]、<、>、&、,、;、NUL、BEL、TAB、CR、LF の各文字はすべて削除され、空白は下線 (_)、スラッシュ (/) はハイフン (-)、コロン (:) はドット (.) にそれぞれ置き換えられます。

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

Delete()

Method Delete(pFilename As %String) As %Status

指定されたファイルを FTP サーバから削除します。サーバ、ユーザ名、パスワード、およびファイル・パスは、このアダプタの設定としてすでに構成されています。FTP オペレーションの成功を示すステータス値を返します。

Disconnect()

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

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

GetStream()

Method GetStream(pFilename As %String,
                ByRef pStream As %Stream.Object = $$$NULLOREF) As %Status

指定されたファイルを FTP サーバから取得して、ストリームとして返します。サーバ、ユーザ名、パスワード、ファイル・パス、および転送モード (文字セット) は、このアダプタの設定としてすでに構成されています。このメソッドは、FTP オペレーションの成功を示すステータス値を返します。呼び出し元がストリームを提供する場合、このストリームは転送に適したタイプ (文字またはバイナリ) である必要があります。何も提供されていない場合は、このメソッドはストリームを作成します。

NameList()

Method NameList(Output pFileList As %ListOfDataTypes) As %Status

FTP サーバ上のファイルのリストを取得します。サーバ、ユーザ名、パスワード、およびファイル・パスは、このアダプタの設定としてすでに構成されています。ファイル名は %ListOfDataTypes オブジェクト内に返されます。このメソッドは、FTP オペレーションの成功を示すステータス値を返します。

PutStream()

Method PutStream(pFilename As %String,
                pStream As %Stream.Object) As %Status

FTP サーバにストリームを指定されたファイルとして保存します。サーバ、ユーザ名、パスワード、ファイル・パス、および転送モード (文字セット) は、このアダプタの設定としてすでに構成されています。このメソッドは、FTP オペレーションの成功を示すステータス値を返します。

Rename()

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

FTP サーバ上のファイルの名前を変更します。サーバ、ユーザ名、パスワード、およびファイル・パスは、このアダプタの設定としてすでに構成されています。このメソッドは、FTP オペレーションの成功を示すステータス値を返します。

TestConnection()

Method TestConnection()

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

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

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.OutboundAdapterOpens in a new tab を参照するビジネス・オペレーション・クラスのコードの例を以下に示します。

Class EnsLib.FTP.PassthroughOperation Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.FTP.OutboundAdapter";

/// Name of file to output the document(s) to. May include timestamp
/// specifiers. The %f specifier if present will be replaced with the
/// name of the document's original source filename (stripped of 
/// characters illegal in filenames).  See the method 
/// Ens.Util.File.CreateTimestamp() for documentation of timestamping options.

Property Filename As %String(MAXLEN = 1000);

Parameter SETTINGS As %String = "Filename";

Method OnMessage(pRequest As Ens.StreamContainer,
                 Output pResponse As %Persistent) As %Status
  {
  Set tFilename=
  ..Adapter.CreateTimestamp(##class(%File).GetFilename(
    pRequest.Stream.Attributes("Filename")),..Filename)
  Quit ..Adapter.PutStream(tFilename, pRequest.Stream)
  }
}

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

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

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

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

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

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