XML 仮想ドキュメントのデータ変換の定義
この章では、ルール・セットで使用できるように、XML 仮想ドキュメントのデータ変換 (特に、DTL ベースの変換) を作成する方法を示します。以下のトピックについて説明します。
データ変換の作成
XML 仮想ドキュメントのデータ変換を作成するには、以下の操作を行います。
-
必要に応じて、1 つまたは複数の適用可能な XML スキーマを Ensemble にロードします。
前述した “Ensemble への XML スキーマのロード” を参照してください。
-
"DTL 変換の開発" 内の説明に従って、管理ポータルまたはスタジオで DTL エディタを使用します。
-
データ変換内で、以下の値を使用します。
-
[ソースクラス] および [ターゲットクラス] で、Ensemble で XML 仮想ドキュメントを示すためのクラスである [EnsLib.EDI.XML.Document] を使用します。
-
[ソース・ドキュメント・タイプ] で、必要に応じてそのメッセージで想定される XML タイプを選択します。Ensemble にロードした XML スキーマのいずれかから XML タイプを選択します。
スキーマをロードしていない、またはスキーマを使用したくない場合は、この値を空白のままにしてください。
-
[ターゲット・ドキュメント・タイプ] で、必要に応じて異なる XML タイプを選択するか、値を削除します。
[ソース・ドキュメント・タイプ] でユーザが選択した値がある場合はそれを使用して、[ターゲット・ドキュメント・タイプ] が初期化されます。
-
-
前の章で説明した XML プロパティ・パスを使用して、通常どおりデータ変換内にアクションを作成します。これには、以下の 2 つの基本的なシナリオがあります。
-
スキーマをロードし、ソースおよびターゲットの各ドキュメント・タイプを指定済みの場合は、DTL エディタに各ドキュメント構造がツリーとして表示されます。これにより、ドラッグ・アンド・ドロップすることで変換を作成できます。Ensemble によって、スキーマ依存パスを使用するアクションが作成されます。何らかの理由で DOM スタイル・パスをそれらのアクションで使用する必要がある場合は、そのように編集することもできます。
-
ドキュメント・タイプを指定しない場合、ドキュメント構造はツリーとして表示されません。その場合、アクションを手動で追加および編集する必要があります。使用できるのは、DOM スタイル・パスのみです。
いずれの場合も、より複雑な処理をサポートするためにコード要素を追加できます。
-
データ変換を保存してコンパイルすると、ルール・セットで使用できるようになります。これについては、“XML 仮想ドキュメントのルール・セットの定義” を参照してください。
XML 仮想ドキュメントの使用可能な割り当てアクション
XML 仮想ドキュメントに対して、Ensemble では以下の割り当てアクションがサポートされています。
-
[set] — 値を設定します。ターゲット要素のタイプが "any" の場合は、テキストに XML マークアップを含めることができます。XML マークアップは適切に構成される必要がありますが、何らかのスキーマに対して検証されることはありません。
-
[append] — ターゲット要素内のサブノードの後に新しい値を追加します。
-
[clear] — ターゲットのテキスト・コンテキストは消去しますが、その要素およびすべての子は保持します。または、ターゲットが属性の場合、このアクションによってその値は消去されますが、属性は保持されます。
-
[remove] — ターゲット要素または属性を削除します。
[insert] はサポートされていません。
コードの使用
より複雑な処理をサポートするためにコード要素を追加する必要がある場合は、source および target 変数の GetValueAt() と SetValueAt() メソッドを直接呼び出します。EnsLib.EDI.XML.DocumentOpens in a new tab の場合、これらのメソッドは以下のようになります。
method GetValueAt(pPropertyPath As %String,
pFormat As %String,
Output pStatus As %Status) as %String
説明 ：
-
pPropertyPath は、このドキュメントで前述したように、XML プロパティ・パスです。
-
pFormat は、返される文字列の形式を制御する一連のフラグです。次の項を参照してください。
-
pStatus は、成功または失敗を示すステータスです。
このメソッドによって、指定されたプロパティ・パスの現在の値、またはパスが有効でない場合は空の文字列が返されます。
method SetValueAt(pValue As %String,
pPropertyPath As %String,
pAction As %String = "set",
pKey As %String = "") as %Status
説明 ：
-
pValue は、指定された XML プロパティ・パスの適切な値です。
-
pPropertyPath は、前の章で説明したように、XML プロパティ・パスです。
-
pAction は、"set"、"append"、"clear"、"remove" のいずれかです。詳細は、前の節を参照してください。
-
pKey は、XML 仮想ドキュメントには使用されません。
このメソッドによって、指定されたプロパティ・パスが評価され、(パスが有効な場合は) そのパスで pValue および pAction を使用して値が変更されます。
これらのメソッドによって返されたステータス値をチェックすると便利です。無効なパスを指定した場合や、許可されていないアクションを試行した場合、ステータスに具体的な情報が含まれます。特にこの情報はデバッグを行う際に役立ち、時間を節約することができます。
pFormat 引数
GetValueAt() の pFormat 引数は、返される文字列の形式を制御するオプション文字列です。この文字列には、以下の表に示す任意の文字の適切な組み合わせを含めることができます。
| 概要 | 形式設定に含める文字 | 特定の動作 |
|---|---|---|
| 改行と復改 | w | テキストが含まれていないすべての要素の後に、Windows スタイルの復改と改行を追加します。 |
| r | 保存された改行と復改を使用します。このオプションは、オプションの w および n より優先されます。 | |
| n | テキストが含まれていないすべての要素の後に、新しい行 (改行) を追加します。w とは対照的に、このオプションは復改を追加しません。 | |
| インデント。これらのオプションは出力に新しい行が含まれている場合にのみ使用されます。 | i | 新しい行ごとに 4 つのスペースを使ってインデントします。 |
| 1 ～ 9 の整数 | 新しい行ごとにこの数のスペースを使ってインデントします。このオプションは前のインデント・オプションより優先されます。 | |
| t | 新しい行ごとに 1 つのタブを使ってインデントします。このオプションは前のどちらのインデント・オプションより優先されます。 | |
| s | 保存されたインデント空白文字を使用します。このオプションは前のインデント・オプションより優先されます。 | |
| 属性の処理 | a | 要素内の属性をアルファベットで表現します。 |
| q | 可能な場合は、二重引用符 (一重引用符ではなく) で属性値を囲みます。 | |
| ネームスペースの処理 | p | ネームスペース接頭語の出力を抑制します。 |
| x | ネームスペース宣言の出力を抑制します。 | |
| 空の要素の処理 | e | オープン・タグとクローズ・タグのペアを使用して空の要素ごとの出力を生成します。このオプションが設定されていない場合は、空の要素が単一の空タグとして出力されます。 |
| その他 | c | 標準的な出力。このオプションは、オプションの e、i、n、t、および w より優先されます。 |
| f | 要素の中身だけでなく、完全な要素 (開始タグと終了タグの両方を含む) を生成します。 | |
| l | Ensemble にロードされたスキーマの場所に関する情報を追加します。このオプションは f が使用されている場合にのみ有効です。 | |
| o | XML エンティティをそのまま追加します。これらのエンティティに対して XML エスケープ処理は行われません。 | |
| C(e) | 特定の文字エンコーディングを宣言する XML ヘッダ行を生成します。e は UTF–8 などの文字エンコーディングの引用符抜きの名前です。e が空の場合は、アダプタで定義されているエンコードを使用します。e が ! で始まる場合は、出力ストリームのエンコーディングを強制します。これは、UTF-8 以外の文字セットで構成されるファイル・オペレーションに自動的に適用されることに留意してください。 |
前述したように、pFormat 引数はこれらの項目の組み合わせと一致させることができます。例えば、値の C(UTF-8)q を使用した場合は、送信ドキュメントが UTF-8 文字セットになり、属性が二重引用符で囲まれます。また、値の C(UTF-16)a を使用した場合は、送信ドキュメントが UTF-16 文字セットになり、属性がアルファベットで表現されます。
例 1 ：ソース・ドキュメントの大部分をコピーする
ソース・ドキュメントの大部分をコピーするデータ変換を簡単に定義するには、データ変換ビルダで以下の操作を行います。
-
[変換] タブで、[作成] ドロップダウン・リストから [copy] を選択します。
これにより、デフォルトで、新しいドキュメントは元のドキュメントのコピーになります。
-
選択された要素または属性を部分的または完全に削除するアクションを定義します。そのようなアクションを定義するには、以下の操作を行います。
-
[アクション追加] で、[clear] または [remove] をクリックします。
-
クリアまたは削除したいターゲット・プロパティをダブルクリックします。
-
[値] に任意の値を入力します。このフィールドは必要ですが、この場合は無視されます。
-
以下に、スキーマ依存パスを使用する例を紹介します。
Class Demo02.MyDTL Extends Ens.DataTransformDTL
{
XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
{
<transform sourceClass='EnsLib.EDI.XML.Document' targetClass='EnsLib.EDI.XML.Document'
sourceDocType='Demo02:Patient' targetDocType='Demo02:Patient' create='copy' language='objectscript' >
<assign value='"this value is ignored"' property='target.{WorkAddress}' action='remove' />
<assign value='"this value is ignored"' property='target.{HomeAddress}' action='remove' />
</transform>
}
Parameter REPORTERRORS = 1;
}
このデータ変換では、ソース・ドキュメントがターゲットにコピーされた後、<WorkAddress> および <HomeAddress> 要素がターゲットから削除されます。
以下に、DOM スタイル・プロパティ・パスを使用する同等の例を紹介します。
Class Demo02A.MyDTL Extends Ens.DataTransformDTL
{
XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
{
<transform sourceClass='EnsLib.EDI.XML.Document' targetClass='EnsLib.EDI.XML.Document'
create='copy' language='objectscript' >
<assign value='"this value is ignored"' property='target.{/Patient/WorkAddress}' action='remove' />
<assign value='"this value is ignored"' property='target.{/Patient/HomeAddress}' action='remove' />
</transform>
}
Parameter REPORTERRORS = 1;
}
この場合、このデータ変換では、ドキュメント・タイプが不要なために指定されていないことに注意してください。
例 2 ：ソース・ドキュメントのいくつかの部分のみを使用する
ソース・ドキュメントのいくつかの部分のみを使用するデータ変換を簡単に定義するには、データ変換ビルダで以下の操作を行います。
-
[変換] タブで、[作成] ドロップダウン・リストから [new] を選択します。
これにより、デフォルトで、新しいドキュメントが空になります。
-
選択された要素または属性をコピーするアクションを定義します。そのようなアクションを定義するには、ソース・ドキュメント領域からターゲット・ドキュメント領域にドラッグ・アンド・ドロップします。この方法で追加する各アクションは、[set] アクションです。
以下に、スキーマ依存パスを使用する例を紹介します。
Class Demo05.MyDTL Extends Ens.DataTransformDTL
{
XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
{
<transform sourceClass='EnsLib.EDI.XML.Document' targetClass='EnsLib.EDI.XML.Document'
sourceDocType='Demo05:Patient' targetDocType='Demo05:Patient' create='new' language='objectscript' >
<assign value='source.{MRN}' property='target.{MRN}' action='set' />
<assign value='source.{PrimaryCarePhysician}' property='target.{PrimaryCarePhysician}' action='set' />
</transform>
}
Parameter REPORTERRORS = 1;
}
このデータ変換では、MRN および PrimaryCarePhysician プロパティのみがソースからターゲットにコピーされます。
以下に、DOM スタイル・プロパティ・パスを使用する同等の例を紹介します。
Class Demo05A.MyDTL Extends Ens.DataTransformDTL
{
XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
{
<transform sourceClass='EnsLib.EDI.XML.Document' targetClass='EnsLib.EDI.XML.Document'
create='new' language='objectscript' >
<assign value='source.{/Patient/MRN}' property='target.{/Patient/MRN}' action='set' />
<assign value='source.{/Patient/PrimaryCarePhysician}'
property='target.{/Patient/PrimaryCarePhysician}' action='set' />
</transform>
}
Parameter REPORTERRORS = 1;
}
例 3 ：code および SetValueAt() を使用する
以下の例では、[code] アクション・タイプ、および DOM スタイル・パスが使用されています。これにより、ルート要素に属性と XML コメントが追加されます。
Class Demo06.MyDTL Extends Ens.DataTransformDTL
{
XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
{
<transform sourceClass='EnsLib.EDI.XML.Document' targetClass='EnsLib.EDI.XML.Document'
create='copy' language='objectscript' >
<code>
//this part adds an attribute to the document
set path="/1/@NewAttribute"
set status=target.SetValueAt("New attribute value",path)
if 'status {do ##class(MyApp.Utils).Trace("Demo06.MyDTL","Error setting path: ",path)}
//this part adds a comment to the document
set path="/1/comment()"
set status=target.SetValueAt("This is an XML comment",path)
if 'status {do ##class(MyApp.Utils).Trace("Demo06.MyDTL","Error setting path: ",path)}
</code>
</transform>
}
Parameter REPORTERRORS = 1;
}
SetValueAt() メソッドによってエラーが返されたら、この変換ではユーティリティ・メソッドを使用して詳細が記録されます。
