オブジェクトの XML への投影
ここでは、InterSystems IRIS® データ・プラットフォーム・オブジェクトを XML ドキュメントとして投影する方法を説明します。
このページで説明されているクラスとプロパティのパラメータ |
---|
|
InterSystems IRIS オブジェクトの XML への投影
オブジェクトを XML に投影 (または、そのオブジェクトの XML プロジェクションを定義) するには、以下の手順を実行します。
-
オブジェクトを定義するクラスのスーパークラス・リストに %XML.AdaptorOpens in a new tab を追加します。
以下はその例です。
Class MyApp.MyClass Extends (%Persistent, %XML.Adaptor) { //class details }
この手順でクラスが XML 対応になります。
また、投影するオブジェクトがシステム・クラスのインスタンスの場合は、代わりにサブクラスを作成して使用します。このサブクラスで、スーパークラス・リストに %XML.AdaptorOpens in a new tab を追加します。
また、InterSystems IRIS には、XML 対応の専用クラスが数多く、そのクラス・ライブラリに用意されています。これらには、%Net、%SOAP などのパッケージにおけるクラスが含まれます。これらの XML 対応クラスはすべて、%XML.AdaptorOpens in a new tab から継承されます。
-
%ListOfDataTypesOpens in a new tab、%ArrayOfDataTypesOpens in a new tab、%ListOfObjectsOpens in a new tab、または %ArrayOfObjectsOpens in a new tab のXML 対応サブクラスを作成する場合は、そのサブクラスで ELEMENTTYPE クラス・パラメータを指定します。以下はその例です。
Class MyApp.MyIntegerCollection Extends %ListOfDataTypes { Parameter ELEMENTTYPE="%Library.Integer"; }
ELEMENTTYPE には、コレクションで使用されるクラスの詳細なパッケージ名およびクラス名を指定します。そのパラメータを指定しないと、タイプは文字列と見なされます。
この手順は、完全な XML スキーマが必要な場合にのみ必要です。
-
次のセクションの説明に従って、XML 対応クラスの各プロパティに、適切であれば XML プロジェクションがあることを確認してください。
ほとんどの場合、プロパティにオブジェクト値があれば、プロパティを定義するクラスを XML 対応にする必要があります。例外は、プロパティとして使用される際のコレクションとストリームです。詳細は次のセクションを参照してください。
データ型クラスでは、作業は不要です。
-
変更されたクラスをリコンパイルします。
これで、オブジェクトを XML ドキュメントに書き込むことなどができます。詳細は、"XML ツールの使用法" を参照してください。
Web メソッドで使用されるオブジェクトの例外
%ListOfDataTypesOpens in a new tab、%ListOfObjectsOpens in a new tab、%ArrayOfDataTypesOpens in a new tab、%ArrayOfObjectsOpens in a new tab を Web メソッドの入力や出力として使用する場合、XML 対応サブクラスの作成は不要です。ELEMENTTYPE を指定することは必要ですが、その処理はメソッド・シグニチャでできます。
ストリーム・クラスを Web メソッドの入力や出力として使用する場合、XML 対応サブクラスの作成は不要です。
詳細は、"Web サービスおよび Web クライアントの作成" を参照してください。
プロパティに XML へのプロジェクションがあることの確認
オブジェクトの各プロパティに XML プロジェクションがあることを確認するには、以下の手順を実行します。
-
このオブジェクトの単純な (オブジェクトでない) 各プロパティに対しては、作業は不要です。InterSystems IRIS の各データ型には XML プロジェクションがあります。
-
各ストリーム・プロパティに対しては、作業は不要です。XML 対応クラスのプロパティとして使用される場合、XML ツールではストリーム・オブジェクトが特別に処理されます。
-
コレクション以外のオブジェクト値プロパティの場合、参照されるクラスのスーパークラス・リストに %XML.AdaptorOpens in a new tab を追加します。
これには、リレーションシップ・プロパティなどがあります。
-
コレクションの詳細は、以下のサブセクションを参照してください。
InterSystems IRIS XML ツールで各種タイプのプロパティ値をどのように扱うかの詳細は、"値の変換の制御" を参照してください。プロパティ・タイプを XML タイプにどのように投影するかの詳細は、"XML スキーマへの投影の制御" を参照してください。
配列のリストで定義されるプロパティ
Property PropName As List of classname 構文や Property PropName As Array of classname 構文で定義されているプロパティごとに、以下の手順を実行します。
-
classname がオブジェクト・クラスである場合、クラスを XML 対応にします。つまり、classname のスーパークラス・リストに %XML.AdaptorOpens in a new tab を追加します。
-
classname がデータ型クラスの場合、必要な作業はありません。
-
classname がストリーム・クラスであり、プロパティがリストの場合は、必要な作業はありません。ストリームは、文字列として XML に投影されます。
InterSystems IRIS では、ストリーム配列の XML 投影をサポートしていません。オブジェクトがストリーム配列として定義されているプロパティを持つ場合は、プロパティに XMLPROJECTION="none" を追加します。
以下はその例です。
Class MyApp.MyXMLObject Extends (%RegisteredObject, %XML.Adaptor)
{
Property MyListOfObjects As list Of MyApp.OtherXMLObject;
Property MyArrayOfObjects As array Of MyApp.OtherXMLObject;
Property MyListOfDT As list Of %String;
Property MyArrayOfDT As array Of %String;
Property MyListOfStreams As list Of %GlobalCharacterStream;
Property MyArrayOfStreams As array Of %GlobalCharacterStream(XMLPROJECTION = "NONE");
}
%ListOfDataTypes または %ArrayOfDataTypes のプロパティ
XML ツールでは、%ListOfDataTypesOpens in a new tab や %ArrayOfDataTypesOpens in a new tab のタイプのプロパティがコンテナとして自動的に投影されます。既定では、コンテナには文字列要素が含まれます。
適切な XML スキーマが必要な場合と、要素を文字列と想定することが適切でない場合は、コレクション・クラスのサブクラスを作成して使用します。サブクラスで、ELEMENTTYPE クラス・パラメータを指定します。以下はその例です。
Class MyApp.MyIntegerCollection Extends %ListOfDataTypes
{
Parameter ELEMENTTYPE="%Library.Integer";
}
ELEMENTTYPE には、コレクションで使用されるクラスの詳細なパッケージ名およびクラス名を指定します。
%ListOfObjects タイプまたは %ArrayOfObjects タイプのプロパティ
XML ツールでは、%ListOfObjectsOpens in a new tab や %ArrayOfObjectsOpens in a new tab のタイプのプロパティがコンテナとして自動的に投影されます。ただし、コレクションで使用されるクラスを XML 対応にする必要があります。
%ArrayOfObjectsOpens in a new tab タイプのプロパティでは、コレクション内でストリーム・クラスを使用できません。
完全な XML スキーマが必要な場合、コレクションの要素タイプを指定する必要があります。そのためには、コレクション・クラスのサブクラスを作成して使用します。前のセクションで示したように、サブクラスで、ELEMENTTYPE クラス・パラメータを指定します。
例外
指定されたプロパティが XML に投影されない場合、参照されるクラスを XML 対応にする必要はありません。以下のプロパティは、XML に投影されません。
"ELEMENT" などの適切な値に XMLPROJECTION プロパティ・パラメータを設定すると、プライベート・プロパティと多次元プロパティを投影できます。多次元プロパティの場合、プロジェクションに含めることができるのは最上位ノードのみです。
既定のプロジェクションの概要
既定の XML プロジェクションは、以下のとおりです。
-
オブジェクトのインスタンスは、最上位レベルの XML 要素に対応します。
-
投影されるのはプロパティのみです。他のクラス・メンバは投影されません。
また、プライベート・プロパティと多次元プロパティは無視されます。
-
プロパティは、スタジオに表示された順に XML に投影されます。
-
指定された型のないプロパティは、文字列と見なされます。
-
各オブジェクト値プロパティは、囲まれる最上位レベルの XML 要素内にある XML 要素に対応します。
そのプロパティは、この要素内で入れ子にされます。
-
コレクションは、入れ子にされた要素として投影されます。これは、データ型のコレクションでもオブジェクトのコレクションでも変わりません。
リストと配列では、下位レベルの詳細が少し異なります。
-
リレーションシップは、リスト・プロパティと同じように扱われます。
XML プロジェクションには、リレーションシップの片側のみが含まれます。両側を投影しようとすると、エラーが発生します。
-
文字ストリームは、文字列として投影されます。
-
バイナリ・ストリームは、Base 64 のエンコードを行った文字列を使用して投影されます。
XML プロジェクションの例
このセクションでは、XML 対応クラスとその XML プロジェクションを示します。
XML 対応クラスの例
以下は、構造的プロパティの主要バリエーションがある XML 対応クラスを示します。
Class Basics.BasicDemo Extends (%RegisteredObject, %XML.Adaptor)
{
Parameter XMLTYPENAMESPACE = "mytypes";
Property SimpleProp As %String;
Property ObjProp As SimpleObject;
Property Collection1 As list Of %String;
Property Collection2 As list Of SimpleObject;
Property MultiDimProp As %String [ MultiDimensional ];
Property PrivateProp As %String [ Private ];
}
XMLTYPENAMESPACE パラメータは、このクラスで定義されたタイプのターゲット・ネームスペースを指定します。
SimpleObject クラスも XML 対応です。
Class Basics.SimpleObject Extends (%RegisteredObject, %XML.Adaptor)
{
Parameter XMLTYPENAMESPACE = "mytypes";
Property MyProp As %String;
Property AnotherProp As %String;
}
XML ドキュメントの例
以下は、BasicDemo クラスのインスタンスから生成された XML ドキュメントを示します。
<?xml version="1.0" encoding="UTF-8"?>
<BasicDemo>
<SimpleProp>abc</SimpleProp>
<ObjProp>
<MyProp>12345</MyProp>
<AnotherProp>67890</AnotherProp>
</ObjProp>
<Collection1>
<Collection1Item>list item 1</Collection1Item>
<Collection1Item>list item 2</Collection1Item>
</Collection1>
<Collection2>
<SimpleObject>
<MyProp>12345</MyProp>
<AnotherProp>67890</AnotherProp>
</SimpleObject>
<SimpleObject>
<MyProp>12345</MyProp>
<AnotherProp>67890</AnotherProp>
</SimpleObject>
</Collection2>
</BasicDemo>
スキーマの例
以下は、2 つのサンプル・クラスで使用されている XML タイプのネームスペースのスキーマを示します。
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:s="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" targetNamespace="mytypes">
<complexType name="BasicDemo">
<sequence>
<element minOccurs="0" name="SimpleProp" type="s:string"/>
<element minOccurs="0" name="ObjProp" type="s01:SimpleObject" xmlns:s01="mytypes"/>
<element minOccurs="0" name="Collection1" type="s02:ArrayOfCollection1ItemString" xmlns:s02="mytypes"/>
<element minOccurs="0" name="Collection2" type="s03:ArrayOfSimpleObjectSimpleObject" xmlns:s03="mytypes"/>
</sequence>
</complexType>
<complexType name="SimpleObject">
<sequence>
<element minOccurs="0" name="MyProp" type="s:string"/>
<element minOccurs="0" name="AnotherProp" type="s:string"/>
</sequence>
</complexType>
<complexType name="ArrayOfCollection1ItemString">
<sequence>
<element maxOccurs="unbounded" minOccurs="0" name="Collection1Item" nillable="true" type="s:string"/>
</sequence>
</complexType>
<complexType name="ArrayOfSimpleObjectSimpleObject">
<sequence>
<element maxOccurs="unbounded" minOccurs="0" name="SimpleObject"
nillable="true" type="s04:SimpleObject" xmlns:s04="mytypes"/>
</sequence>
</complexType>
</schema>
投影された XML ドキュメントのフォーマット・オプションの指定
XML ドキュメントの基本的な形式には、リテラルとエンコード (SOAP エンコード) の 2 つがあります。これらの形式の例については、"InterSystems XML ツールの概要" を参照してください。XML 対応クラスからデータをエクスポートしたりこのクラスにデータをインポートする際に、これらの形式のいずれかを指定します。
クラスに %XML.AdaptorOpens in a new tab を追加してコンパイルすると、InterSystems IRIS により、生成されたルーチンに追加のコードが記述されます。既定では、この追加コードで両方の形式がサポートされています。1 つの形式のみが必要な場合、もう一方の形式を抑制すると、生成されたコードの量を軽減できます。そのためには、そのクラスの XMLFORMAT パラメータを指定します。以下の値のいずれかを使用します (大文字と小文字は区別されません)。
-
"LITERAL" — このクラスではリテラル形式のみがサポートされます。
-
"ENCODED" — このクラスではエンコード形式のみがサポートされます (SOAP 1.1 と SOAP 1.2 の両方がサポートされています)。
-
Null (既定) — このクラスでは、リテラル形式とエンコード形式の両方がサポートされます。
単純なプロパティのプロジェクションが持つ形式の制御
単純なプロパティとは、その型がデータ型クラスであるプロパティやその型が宣言されていないプロパティのことです (指定された型のないプロパティは、文字列と見なされます)。
単純なプロパティの XML プロジェクションが持つ形式を制御するには、そのプロパティの XMLPROJECTION パラメータを設定します。以下の値のいずれかを使用します (大文字と小文字は区別されません)。
XMLPROJECTION の値 | 非コレクション・プロパティへの影響 |
---|---|
"ELEMENT" | プロパティは、要素として投影されます。これは非コレクション・プロパティに対する既定の設定です。 |
"ATTRIBUTE" | プロパティは、属性として投影されます。 |
"XMLATTRIBUTE" | プロパティは、接頭語 xml を持つ属性として投影されます。 |
"WRAPPED" | このプロパティは、下位要素を持つ要素として投影されます。下位要素の名前は、このプロパティのデータ型に基づいて決まります。 |
"CONTENT" | プロパティは、このクラスのプライマリ・コンテンツとして投影されます (つまり、プロパティのコンテンツは要素で囲まれることなく記述されます)。いずれのクラスでも、複数のプロパティにこの値を指定することはできません。 |
"NONE" | プロパティは、XML に投影されません。 |
XMLPROJECTION パラメータでは "COLLECTION" または "ELEMENTREF" の値も受け付けますが、お勧めはできないのでここでは説明しません。詳細は、%XML.PropertyParametersOpens in a new tab のクラス・ドキュメントを参照してください。
XMLPROJECTION の基本的なバリエーション
以下のクラスにより、"CONTENT" を除き、XMLPROJECTION のバリエーションをすべて使用する単純なプロパティを定義します。
Class xmlproj.SimpleProps Extends (%RegisteredObject, %XML.Adaptor)
{
Property Simple1 As %String (XMLPROJECTION="attribute");
Property Simple2 As %String (XMLPROJECTION="xmlattribute");
Property Simple3 As %String;
Property Simple4 As %String (XMLPROJECTION="element");
Property Simple5 As %String (XMLPROJECTION="wrapped");
Property Simple6 As %String (XMLPROJECTION="none");
}
以下は、このクラスのインスタンスの XML 表現の例です。
<SimpleProps Simple1="The quick" xml:Simple2="brown fox">
<Simple3>jumps</Simple3>
<Simple4>over</Simple4>
<Simple5>
<string>the lazy</string>
</Simple5>
</SimpleProps>
コンテンツとしてのプロパティの投影
"CONTENT" 値により、テキスト・コンテンツと属性はあるが下位要素はない単純な要素として、クラスを投影できます。
この値を使用するクラスの例を以下に示します。
Class xmlproj.SimpleContentProp Extends (%RegisteredObject, %XML.Adaptor)
{
Property Simple1 As %String(XMLPROJECTION = "content");
Property Simple2 As %String(XMLPROJECTION = "attribute");
Property Simple3 As %String(XMLPROJECTION = "element");
}
そのようなクラスのインスタンスをエクスポートすると、以下のようになります。
-
"CONTENT" とマークされたプロパティに値がある場合、この値はクラスのコンテンツとしてエクスポートされます。属性として投影されたプロパティもエクスポートされます。その他のプロパティは無視されます。以下はその例です。
<SimpleContentProp Simple2="other value">The quick brown fox jumps over the lazy dog</SimpleContentProp>
-
"CONTENT" とマークされたプロパティが NULL の場合、このプロパティは無視され、XMLPROJECTION の値で指定されたように、他のプロパティはすべてエクスポートされます。以下はその例です。
<SimpleContentProp Simple2="other value"> <Simple3>yet another value</Simple3> </SimpleContentProp>
いずれのクラスでも、複数のプロパティで XMLPROJECTION を "CONTENT" と指定することはできません。また、この値の使用対象にできるのは、単純でリテラル値があり、オブジェクトのタイプがコレクションなどではないプロパティのみです。
オブジェクト値プロパティのプロジェクションが持つ形式の制御
オブジェクト値プロパティごとに、そのオブジェクト・クラスにある XML プロジェクションのオプションで制御されるように、既定の XML プロジェクションは下位要素や属性のある XML 要素 (オブジェクト自体を表す) で構成され、そのオブジェクトのプロパティを表します。例は、"XML プロジェクションの例" を参照してください。
オブジェクト値プロパティのプロジェクションが持つ形式の指定
オブジェクト・プロパティの投影方法を制御するには、以下のように、そのプロパティの XMLPROJECTION パラメータを設定します。
XMLPROJECTION の値 | コレクション・プロパティへの影響 |
---|---|
"WRAPPED" | プロパティは、下位要素を持つ要素として投影されます。この要素は、オブジェクト・クラスに対応します。それぞれの下位要素は、そのクラスのプロパティに対応します。これは、オブジェクト・プロパティ (ストリーム以外) の既定値です。 |
"ELEMENT" | オブジェクト・クラスの各プロパティは要素として投影されます。親要素でラッピングされません。 |
"NONE" | プロパティは、XML に投影されません。 |
"ATTRIBUTE"、"XMLATTRIBUTE"、または "CONTENT" | コンパイル時エラー。 |
例えば、以下のクラスを考えてみます。
Class Basics.ObjectPropsDemo Extends (%RegisteredObject, %XML.Adaptor)
{
Property Object1 As SimpleObject(XMLPROJECTION = "wrapped");
Property Object2 As SimpleObject(XMLPROJECTION = "element");
}
以下は、このクラスのインスタンスの XML 表現の例です。
<ObjectPropsDemo>
<Object1>
<SimpleObject>
<MyProp>abcdef</MyProp>
<AnotherProp>qrstuv</AnotherProp>
</SimpleObject>
</Object1>
<Object2>
<MyProp>abcdef</MyProp>
<AnotherProp>qrstuv</AnotherProp>
</Object2>
</ObjectPropsDemo>
XMLSUMMARY の指定
クラスがプロパティとして使用される際に XML に投影するクラスのプロパティを簡単に指定できます。
-
そのクラスでは、クラス定義で指定されているように大文字と小文字を区別して、XML に投影するプロパティのコンマ区切りリストとして XMLSUMMARY クラス・パラメータを指定します。XMLSUMMARY には擬似プロパティの ID および OID を記述できません。
以下のパラメータのいずれかまたは両方とも指定しない限り、このパラメータの効果はありません。
-
同じクラスでは、オプションで XMLDEFAULTREFERENCE を "SUMMARY" または "COMPLETE" (既定) として指定します。これらの値では、大文字と小文字は区別されません。"SUMMARY" オプションは、このクラスがプロパティとして使用される際に、XMLSUMMARY にリストされたプロパティのみをプロジェクションで使用することを意味します。"SUMMARY" オプションは、XML プロジェクションのあるプロパティをすべて使用することを意味します。
これらの値では、大文字と小文字は区別されません。
-
このクラスをプロパティとして使用するクラスでは、オプションで XMLREFERENCE プロパティ・パラメータを "SUMMARY" または "COMPLETE" (既定) として指定します。これらの値では、大文字と小文字は区別されません。これは、XMLDEFAULTREFERENCE クラス・パラメータをオーバーライドします。
このプロパティ・パラメータを設定できるのは、プロパティがオブジェクト値を持つ場合のみです。
例えば、以下の Address クラスを考えてみます。
Class xmlsummary.Address Extends (%RegisteredObject, %XML.Adaptor)
{
Parameter XMLSUMMARY = "City,ZipCode";
Parameter XMLDEFAULTREFERENCE = "SUMMARY";
Property Street As %String;
Property City As %String;
Property State As %String;
Property ZipCode As %String;
}
以下は、このクラスのインスタンスの XML 表現の例です。
<Address>
<Street>47 Winding Way</Street>
<City>Middlebrook</City>
<State>GA</State>
<ZipCode>50291</ZipCode>
</Address>
すべてのプロパティが含まれていることに注意してください。
ここで、Address クラスをプロパティとして使用する別のクラスを考えてみます。
Class xmlsummary.Person Extends (%RegisteredObject, %XML.Adaptor)
{
Property Name As %String;
Property Address as Address;
}
以下は、このクラスのインスタンスの XML 表現の例です。
<Person>
<Name>Penelope Farnsworth</Name>
<Address>
<City>Middlebrook</City>
<ZipCode>50291</ZipCode>
</Address>
</Person>
ここでは、Address クラスはこのクラスのプロパティであるため、パラメータとして XMLSUMMARY と XMLDEFAULTREFERENCE が使用され、プロジェクションで使用されるのは XMLSUMMARY にリストされたクラス・プロパティのみです。
"COMPLETE" オプションを使用すると、オーバーライドを強制適用できます。例えば、以下のクラスでは Address クラスをプロパティとして使用しますが、XMLREFERENCE を "COMPLETE" と指定します。
Class xmlsummary.Employee Extends (%RegisteredObject, %XML.Adaptor)
{
Property Name As %String;
Property Address As Address(XMLREFERENCE = "COMPLETE");
}
以下は、このクラスのインスタンスの XML 表現の例です。
<Employee>
<Name>Malcom Winters</Name>
<Address>
<Street>770 Enders Lane</Street>
<City>Middlebrook</City>
<State>GA</State>
<ZipCode>50293</ZipCode>
</Address>
</Employee>
XML プロジェクションのあるすべてのプロパティが含まれます。この場合は、すべてのプロパティが含まれることを意味します。
オブジェクト識別子のみの投影
既定の方法でオブジェクト値プロパティを投影するのではなく、オブジェクトの識別子のみを投影できます。そのためには、XMLDEFAULTREFERENCE クラス・パラメータまたは XMLREFERENCE プロパティ・パラメータに、以下の値のいずれかを使用します。
-
"ID" オプションを指定すると、ディスクに保存されている、オブジェクトの内部 ID のみが投影されます。プロパティは、どれも投影されません。例えば、以下のクラスを考えてみます。
Class xmlidentifiers.Person Extends (%Persistent, %XML.Adaptor) { Property Name As %String; Property PrimaryCarePhysician As Person (XMLREFERENCE = "ID"); }
以下は、このクラスのインスタンスの XML 表現の例です。
<Person> <Name>Sam Smith</Name> <PrimaryCarePhysician>24</PrimaryCarePhysician> </Person>
-
"OID" オプションを指定すると、package.class,ID の形式でオブジェクトの OID のみが投影されます。プロパティは、どれも投影されません。PrimaryCarePhysician プロパティでこのオプションを使用すると、前述の Person オブジェクトは以下のように投影されます。
<Person> <Name>Sam Smith</Name> <PrimaryCarePhysician>xmlidentifiers.Person,24</PrimaryCarePhysician> </Person>
-
"GUID" オプションを指定すると、可能であれば、オブジェクトの GUID (グローバルに一意な ID) のみが投影されます。GUIDENABLED クラス・パラメータが 1 である場合を除いて、オブジェクトの GUIDは NULL になります。Person クラスを以下のように再定義するとします。
Class xmlidentifiers.Person Extends (%Persistent, %XML.Adaptor) { Parameter GUIDENABLED=1; Property Name as %String; Property PrimaryCarePhysician As Person (XMLREFERENCE = "GUID"); }
この場合、このクラスのインスタンスの XML 表現は以下のようになることがあります。
<Person> <Name>Sam Smith</Name> <PrimaryCarePhysician>D0F383EB-DB31-4C11-AD56-AA14EB37B734</PrimaryCarePhysician> </Person>
プロパティ・パラメータ XMLREFERENCE の場合、"ID"、"OID"、"GUID" の各オプションを使用できるのは、そのオブジェクト値が永続オブジェクトの場合のみです。それ場合以外は、コンパイル時エラーとなります。
同様に、クラス・パラメータ XMLDEFAULTREFERENCE を "ID"、"OID"、または "GUID" に設定したクラスに、永続オブジェクトではない値を持つプロパティがある場合は、それらのプロパティのプロパティ・パラメータ XMLREFERENCE を明示的に "COMPLETE" または "SUMMARY" に設定する必要があります。
コレクション・プロパティのプロジェクションが持つ形式の制御
コレクション・プロパティの XML プロジェクションが持つ形式を制御するには、そのプロパティの XMLPROJECTION パラメータを以下のように設定します。
XMLPROJECTION の値 | コレクション・プロパティへの影響 |
---|---|
"WRAPPED" | このプロパティは、下位要素を持つ要素として投影されます。各下位要素はコレクションの項目に対応します。これはコレクション・プロパティに対する既定の設定です。 |
"ELEMENT" | コレクションの各項目は要素として投影されます。親プロパティでラッピングされません。 |
"NONE" | プロパティは、XML に投影されません。 |
"ATTRIBUTE"、"XMLATTRIBUTE"、または "CONTENT" | コンパイル時エラー。 |
後続のセクションでは、データ型のリストまたは配列であるプロパティの例を紹介します。オブジェクトのコレクションでは、投影された要素には、それらのオブジェクトの XML プロジェクションに応じて、さらに構造体が再帰的に存在する場合があります。
リスト・プロパティのプロジェクションが持つ形式の指定
以下のクラスにより、"WRAPPED" と "ELEMENT" の値を使用するコレクション・プロパティを定義します。
Class xmlproj.DataTypeColls Extends (%RegisteredObject, %XML.Adaptor)
{
Property Collection1 As list Of %String;
Property Collection2 As list Of %String (XMLPROJECTION="wrapped");
Property Collection3 As list Of %String (XMLPROJECTION="element");
}
以下は、このクラスのインスタンスの XML 表現の例です。
<?xml version="1.0" encoding="UTF-8"?>
<DataTypeColls>
<Collection1>
<Collection1Item>list item 1</Collection1Item>
<Collection1Item>list item 2</Collection1Item>
</Collection1>
<Collection2>
<Collection2Item>list item 1</Collection2Item>
<Collection2Item>list item 2</Collection2Item>
</Collection2>
<Collection3>list item 1</Collection3>
<Collection3>list item 2</Collection3>
</DataTypeColls>
Collection3 プロパティでは "ELEMENT" が使用されますが、XML プロジェクションでは、プロパティがリストであることは無視され、各リスト項目がクラスの別プロパティとして扱われます。
配列プロパティのプロジェクションが持つ形式の指定
配列の場合、それぞれの配列項目には値とキーの両方があり、それらの情報は両方とも XML で表現されている必要があります。キーは常に、XML 属性として要素内に投影されます。以下のクラスを考えてみます。
Class xmlproj.DataTypeArray Extends (%RegisteredObject, %XML.Adaptor)
{
Property ArrayProp As array Of %String;
}
以下は、このクラスのインスタンスの既定の XML 表現の例です。
<?xml version="1.0" encoding="UTF-8"?>
<DataTypeArray>
<ArrayProp>
<ArrayPropItem ArrayPropKey="1">apples</ArrayPropItem>
<ArrayPropItem ArrayPropKey="2">bananas</ArrayPropItem>
<ArrayPropItem ArrayPropKey="3">chocolate</ArrayPropItem>
</ArrayProp>
</DataTypeArray>
XMLPROJECTION を "ELEMENT" に指定した場合、XML プロジェクションは代わりに以下のようになります。
<?xml version="1.0" encoding="UTF-8"?>
<DataTypeArray>
<ArrayProp ArrayPropKey="1">apples</ArrayProp>
<ArrayProp ArrayPropKey="2">bananas</ArrayProp>
<ArrayProp ArrayPropKey="3">chocolate</ArrayProp>
</DataTypeArray>
リレーションシップのプロジェクションが持つ形式の制御
リレーションシップは、使用されているコレクションの特性に応じて、他のプロパティと同じように XML に投影されます。
-
親子リレーションシップの場合 :
-
親オブジェクトのリレーションシップ・プロパティはコレクション・プロパティです。具体的にはオブジェクトのリストになります。"コレクション・プロパティのプロジェクションが持つ形式の制御" を参照してください。
-
子オブジェクトのリレーションシップ・プロパティはオブジェクト値プロパティです。
このリレーションシップは、既定では XML に投影されません。
-
-
一対多のリレーションシップの場合 :
-
単一オブジェクトのリレーションシップ・プロパティはコレクション・プロパティです。具体的にはオブジェクトのリストになります。
-
他のオブジェクトのリレーションシップ・プロパティはオブジェクト値プロパティです。
このリレーションシップは、既定では XML に投影されません。
-
どの時点でも、リレーションシップの片側のみを投影できます。そうしないと、無限ループが発生するからです。投影のやり方を逆にするには、XMLPROJECTION プロパティ・パラメータを使用します。
この原則は、例を使用してうまく説明できます。
リレーションシップの既定のプロジェクション
まず、以下の 2 つのクラスについて考えてみます。
クラス Parent はクラス Child の親です。
クラス Parent には、リレーションシップ・プロパティ (Children) に加えて、2 つのプロパティ (ParentPropA と ParentPropB) があります。
同様に、クラス Child には、リレーションシップ・プロパティ (MyParent) に加えて、2 つのプロパティ (ChildPropA と ChildPropB) があります。
これらのクラスを XML に投影すると、既定では以下の結果が得られます。
-
Parent の XML プロジェクションには、ParentPropA、ParentPropB、および Children の 3 つのプロパティのプロジェクションが含まれます。Children プロパティはその他のコレクションと同じように扱われます。つまり、既定では、入れ子にされた要素のセットとして投影されます。
以下はその例です。
<Parent> <ParentPropA>12345</ParentPropA> <ParentPropB>67890</ParentPropB> <Children> <Child> <ChildPropA>abc</ChildPropA> <ChildPropB>def</ChildPropB> </Child> <Child> <ChildPropA>ghi</ChildPropA> <ChildPropB>jkl</ChildPropB> </Child> </Children> </Parent>
-
Child の XML プロジェクションには、ChildPropA および ChildPropB の 2 つのプロパティのプロジェクションが含まれます。MyParent プロパティは無視されます。
以下はその例です。
<Child> <ChildPropA>abc</ChildPropA> <ChildPropB>def</ChildPropB> </Child>
一対多のリレーションシップでも同様です。具体的には、一側のオブジェクトには、リレーションシップ・プロパティのプロジェクションが含まれます。多側のオブジェクトには、リレーションシップ・プロパティのプロジェクションが含まれません。
代わりにリレーションシップの相手側を投影
両方のクラスのリレーションシップ・プロパティで XMLPROJECTION パラメータを指定することにより、代わりにリレーションシップの相手側を投影できます。次の例は、既定の例のバリエーションです。
Class Relationships2.Parent Extends (%Persistent, %XML.Adaptor)
{
Property ParentPropA As %String;
Property ParentPropB As %String;
Relationship Children As Child(XMLPROJECTION = "NONE") [ Cardinality = children, Inverse = MyParent ];
}
同様に、Child クラスは以下のようになります。
Class Relationships2.Child Extends (%Persistent, %XML.Adaptor)
{
Property ChildPropA As %String;
Property ChildPropB As %String;
Relationship MyParent As Parent (XMLPROJECTION="element") [ Cardinality = parent, Inverse = Children ];
}
これらのクラスを XML に投影すると、以下の結果が得られます。
-
Parent の XML プロジェクションでは、Children プロパティは無視されます。
<Parent> <ParentPropA>12345</ParentPropA> <ParentPropB>67890</ParentPropB> </Parent>
-
Child の XML プロジェクションには、そのすべてのプロパティのプロジェクションが含まれます。
<Child> <ChildPropA>abc</ChildPropA> <ChildPropB>def</ChildPropB> <MyParent> <ParentPropA>12345</ParentPropA> <ParentPropB>67890</ParentPropB> </MyParent> </Child>
ストリーム・プロパティのプロジェクションが持つ形式の制御
ストリーム・プロパティの場合、XMLPROJECTION のオプションは以下のようになります
XMLPROJECTION の値 | ストリーム・プロパティへの影響 |
---|---|
"ELEMENT" | ストリーム・コンテンツは要素に格納されます。 |
"WRAPPED" | "ELEMENT" と同じように扱われます。 |
"CONTENT" | ストリーム・コンテンツは、"コンテンツとしてのプロパティの投影" の説明のとおりに投影されます。その他のプロパティについて、XMLPROJECTION パラメータは "NONE" にする必要があります。 |
"NONE" | プロパティは、XML に投影されません。 |
"ATTRIBUTE" | プロパティは、属性として投影されます。 |
"XMLATTRIBUTE" | プロパティは、接頭語 xml を持つ属性として投影されます。 |
このセクションでは、ストリーム投影の例を示します。
例えば、以下のクラスを考えてみます。
Class Basics.StreamPropDemo Extends (%Persistent, %XML.Adaptor)
{
Property BinStream As %Library.GlobalBinaryStream;
Property CharStream As %Library.GlobalCharacterStream;
}
以下は、このクラスのインスタンスの XML 表現の例です。
<StreamPropDemo>
<BinStream>/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAUDBAQEAwUEBAQFBQUGBwwIBwcHBw8LCwkMEQ8SEhEP
ERETFhwXExQaFRERGCEYGh0dHx8fExciJCIeJBweHx7/2wBDAQUFBQcGBw4ICA4eFBEUHh4eHh4e
...
VcE/wkZ5wGJBH/joP50UVfQkqaS5dbi34EZtpJgPRlUkf1H402Fy9oIWHHlPj2K/Nn9cfhRRSGip
ZHzbmEPnEwZGGePu5/nj8qNJcpcrG4DxSuEkToDnPPtRRUyKGhPsuqlAxbypAhJ43A/y44q5HbNM
vmx3U9vuJDLG+ASCQW+pxRRSKP/Z</BinStream>
<CharStream>This is a sample file.
This is line 2.
This is line 3.
This is line 4.</CharStream>
</StreamPropDemo>
投影されるプロパティの可用性の制御
投影されたプロパティごとに、その使用をインポートのみ、エクスポートのみ、またはインポートとエクスポートの両方に指定できます。このためには、%XML.WriterOpens in a new tab クラスおよび %XML.ReaderOpens in a new tab クラスのエクスポートおよびインポートのメソッドによるプロパティ処理方法を制御する XMLIO パラメータを設定します。このパラメータには以下の値のいずれかを指定できます (大文字と小文字は区別されません)。
-
"INOUT" — このプロパティは、エクスポートとインポートの両方に使用します。これは投影されるプロパティに対する既定の設定です。
-
"IN" — このプロパティは、インポートに使用しますが、エクスポートでは無視されます。
-
"OUT" — このプロパティは、エクスポートに使用しますが、インポートではエラーの原因になります。このプロパティに対応する XML 要素が XML ドキュメントに存在する場合、インポートではエラーが返されます。
-
"CALC" — このプロパティは、エクスポートに使用しますが、インポートでは無視されます。このプロパティに対応する XML 要素が XML ドキュメントに存在する場合、インポートではそれが無視されます。一般的に、この値は、計算されたプロパティに使用されます (値が他のプロパティの値を基に計算されているもの)。このため、エクスポートではすべての値を記録し、インポートでは計算された値を無視できます。
XML に投影されていないプロパティに対して、このパラメータは何の効果もありません。
プロジェクションの無効化
何らかの理由によるテスト時などに、XML 対応クラスが投影されないようにするには、そのクラスのパラメータ XMLENABLED を 0 に設定します。このパラメータの既定値は 1 です。
XMLENABLED を使用して、あるクラスが投影されないようにする場合、このクラスは、XML に投影されるどのクラスでもプロパティとして使用することはできません。XMLENABLED を 0 に設定することは、%XML.AdaptorOpens in a new tab をスーパークラス・リストから削除することと同じです。
%XML.Adaptor のメソッド
%XML.AdaptorOpens in a new tab のメソッドはお勧めできないので、ほとんど説明していません。代わりに、%XML.WriterOpens in a new tab や %XML.SchemaOpens in a new tab の、ネームスペースに優れたサポートを提供するより強固なクラスを使用してください。詳細は、"XML ツールの使用法" を参照してください。