BatchRecord OTD (通信アダプタ用 OTD の開発)

通信アダプタ用 OTD の開発

BatchRecord OTD

バッチアダプタのレコード処理 OTD である BatchRecord を使用すると、受信ペイロード (ペイロードデータ) からレコードを解析 (抽出) したり、レコードから構成される送信ペイロードを作成したりできます。この OTD の処理と使用方法の理解のために、いくつかの用語を説明します。

ここでペイロードという用語は、インメモリーバッファーを指します。つまり、バイトシーケンスまたはストリームです。また、このコンテキストでのレコードとは、データベースの場合のレコードとは異なります。レコードとは、単に、固定長や区切りレコードなど、既知の単純な構造を持つバイトシーケンスを意味します。

たとえば、この OTD では次の各レコードタイプを解析または作成できます。

長さがそれぞれ 1024 バイトの SAP IDoc を多数含む大規模データファイル。
それぞれが特別なバイトシーケンスで終端処理された X12 注文書を多数含むデータファイル。

レコード処理 OTD は、次の形式のレコードを処理できます。

固定長: ペイロード内の各レコードはまったく同じサイズです。
区切り: 各レコードの後に、CR、LF などの特定のバイトシーケンスが続きます。
単一: ペイロード全体がレコードです。

DBCS データに文字区切りを使用する場合は、単一バイト文字を使用するか、または 2 バイト文字のいずれのバイトとも一致しない 16 進値を持つ同等な 16 進値を使用します。

BatchRecord OTD の構造

BatchRecord OTD には、Client、Configuration、PersistentState、および StateManager という 4 つの上位レベルノードが含まれます (次の図を参照)。これらのノードを展開すると、サブノードが表示されます。

図 1–12 BatchRecord OTD の構造

OTD の構造と処理

OTD の Configuration ノードの下の各フィールドノードは、アダプタのレコード処理設定パラメータのいずれかに対応します。

レコード処理 OTD ノードの機能

次のリストは、レコード処理 OTD のこれらの主要ノードについて、その機能などを説明しています。

BatchRecord: OTD のルートノードを表します。
Configuration: このノード内の各サブノードは、アダプタの設定パラメータに対応し、対応する設定情報を含みます。ただし、Parse または Create パラメータを除きます。詳細は、BatchRecord の接続マッププロパティーを参照してください。
- InputStreamAdapter および OutputStreamAdapter: OTD のデータストリーミング機能を使用および制御できます。その処理については、「コンポーネント間でのデータのストリーミング」を参照してください。
  
  注 –
  データは、Payload ノードを使用するか、またはデータストリーミング (InputStreamAdapter および OutputStreamAdapter ノード) を使用して転送できますが、同じ OTD 内で両方の方法を使用することはできません。
  
  注 –
  レコード処理 OTD の場合、これらの設定ノードは読み取り専用です。これらのノードは、実行時に設定情報にアクセスしたり、確認したりすることのみを目的として提供されています。
Record: 次のいずれかを表すプロパティーノードです。
- get() の呼び出しが成功した場合に、このメソッドを介して取得されたばかりの現在のレコード
- put() が呼び出されたときに、データペイロードに追加される現在のレコード
Payload: 解析中または作成中のデータペイロードのバイト配列を含むインメモリーバッファー。

注意 –
どんな場合でもバイト配列を使用することをお勧めします。バイト配列を使用しないと、データを失うことがあります。
- put(): 現在 Record ノードにあるすべてをデータペイロードに追加します。呼び出しが成功すると、このメソッドは true を返します。
- get(): データペイロード (またはストリーム) から次のレコードを取得し、Record ノードに取得したレコードを取り込みます。呼び出しが成功すると、get() は true を返します。
- finish(): put() と get() の両方に対して、解析ループまたは作成ループのいずれかが正常に完了したことを示すことができます。
  
  注 –
  エラーを示し、OTD で不要な内部データ構造をクリーンアップできるようにするには、reset() を使用します。

レコード処理 OTD の使用法

この OTD には次の基本的な使用法があります。

ペイロードの解析: ペイロードを外部システムから受信するとき
ペイロードの作成: ペイロードを外部システムに送信する前

OTD の単一のインスタンスは、同じコラボレーション内で同時に両方の目的に使用するようになっていません。この制限を強制するには、アダプタの「一般設定」パラメータの下に「解析または作成モード」と呼ばれる設定があります。この設定で「解析」または「作成」のいずれかを選択できます。

`get()` および `put()` の使用法

get() および put() メソッドは、この OTD の機能の中核です。いずれかのメソッドを呼び出すと、取得または追加するレコードは、固定長または区切りなど、アダプタの設定で指定されたタイプであると見なされます。

get() メソッドは例外をスローできますが、この動作は、通常、重大な失敗がある場合のみ起こります。ペイロードデータ (またはストリーミングしている場合はストリーム) が設定される前に get() を呼び出そうとすることは、こうした失敗の一例です。get() 呼び出しからの戻り値を確認するようにコラボレーションをコーディングすることをお勧めします。戻り値 true は取得処理が成功したことを意味し、false は失敗を意味します。

「解析または作成モード」の選択

アダプタは、モード設定に従って、適切な呼び出しが行われているかどうかを確認します。たとえば、解析モード環境で put() を呼び出すと、アダプタは、原因を説明する該当エラーメッセージを添えて、例外をスローします。作成モードで get() を呼び出してもエラーになります。

アダプタがこうした制限を必要とするのは、次の理由からです。

インバウンドペイロードを処理している場合は、ペイロードからレコードを抽出 (解析) するために get() を呼び出します。この状況では、put() を呼び出すことはほとんど意味はありません。この時点で呼び出すと、ペイロードからレコードを抽出しようとしているのに、ペイロードは変更されます。put() を呼び出すとペイロードは上書きされ、取得しようとしてるデータは破壊されます。
反対に、put() を呼び出すことでペイロードを作成している場合、この時点でデータを抽出、つまり解析する必要はありません。したがって、get() を呼び出すことはできません。

このため、OTD は、特定のコラボレーションの転送元側または転送先側に必要に応じて配置し、OTD をペイロードの解析または作成に使用します。しかし、同時に解析と作成を行うことはできません。OTD をコラボレーションに実装するには、コラボレーションルールエディタを使用します。

ペイロードの作成

ペイロードデータを外部システムに送信する場合は、そのシステムとインタフェースをとっているコラボレーションのアウトバウンド側に OTD を配置できます。連続して put() を呼び出すと、アダプタ設定で定義した形式でペイロードデータが構築されます。

すべてのレコードがペイロードに追加されたら、コラボレーションのアウトバウンドの転送先を表すノード (複数可) にペイロードをドラッグ＆ドロップできます。また、ペイロードの転送先として出力ストリームを設定できます (ペイロードのストリーミングの詳細は、表 1–3 を参照)。

データペイロードを構築するときは、送信するデータのタイプと形式を考慮します。アダプタでは、次の形式を使用できます。

単一レコード: このタイプのペイロードは、送信する単一レコードを表します。put() を連続して呼び出すごとに、ペイロードは出力中のデータのサイズ単位で大きくなります。ペイロードは、隣接する 1 つのバイトストリームです。
固定サイズレコード: このタイプのペイロードは、レコードで構成されており、各レコードのサイズはまったく同じです。指定されたサイズではないレコードを put() しようとすると、例外がスローされます。
区切りレコード: このタイプのペイロードは、末尾に区切り文字を持つレコードで構成されます。各レコードのサイズは異なってもかまいません。このデータタイプが put() に渡されるときには、区切り文字を追加しないでください。区切り文字は、アダプタによって自動的に追加されます。
ユーザー定義: このタイプのペイロードでは、セマンティクスはユーザー自身の実装によって完全に制御されます。

ペイロードの解析

外部システムからのインバウンドのペイロードデータを表すには、(コラボレーションルールエディタから) OTD のペイロードノードにデータをマップします。また、入力ストリームを転送元として指定することもできます。

いずれの場合も、連続して get() を呼び出すごとに、ペイロードから次のレコードが抽出されます。抽出されるレコードのタイプは、固定サイズ、区切りなどのアダプタの設定で設定したパラメータによって決まります。

解析コラボレーションは、抽出した各レコードに対する処理を含めて設計します。通常、レコードを別のコラボレーションに送り、そこにあるカスタム OTD がレコード形式を記述し、さらに処理を実行するという方法がとられます。

ペイロードの完全な消費

ペイロードは完全に消費することができます。つまり、get() を連続して何度も呼び出すと、ペイロード内のすべてのレコードを取得できます。この時点で連続して get() を呼び出すと、ブール型の false が返されます。サブジェクトコラボレーションのビジネスルールは、この可能性を考慮に入れて設計します。

データストリーミングでのレコード処理の使用法

データストリーミングでレコード処理 OTD を使用している場合は、出力ファイルを上書きしないように注意してください。OTD が、同じ出力ファイル名を使用する BatchLocalFile OTD に絶えずストリーミングしている場合、OTD は出力側のファイルを上書きすることがあります。

この問題を回避するためには、ファイルのシーケンス番号付けを使用するか、またはコラボレーションルールの出力ファイル名を変更します。シーケンス番号付けを使用すると、BatchLocalFile OTD は、個々のファイルにシーケンス番号を追加することでそれぞれを区別します。ターゲットファイル名と転送後ファイル名のいずれか、または両方を使用すると、出力ファイルの名前を別のファイル名に変更できます。

これらの機能の使用法については、「シーケンス番号付け」および「ファイル転送前/転送後コマンド」を参照してください。