Caché オブジェクトの 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 対応サブクラスの作成は不要です。

詳細は、"Caché での Web サービスおよび Web クライアントの作成" を参照してください。

配列のリストで定義されるプロパティ

Property PropName As List of classname 構文や Property PropName As Array of classname 構文で定義されているプロパティごとに、以下の手順を実行します。

• Classname がオブジェクト・クラスである場合、クラスを XML 対応にします。つまり、classname のスーパークラス・リストに %XML.AdaptorOpens in a new tab を追加します。

• classname がデータ型クラスの場合、必要な作業はありません。

• classname がストリーム・クラスであり、プロパティがリストの場合は、必要な作業はありません。ストリームは、文字列として XML に投影されます。

以下はその例です。

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 に投影されません。

• プライベート・プロパティ

• 多次元プロパティ

• XMLPROJECTION パラメータを "NONE" として指定したプロパティ

"ELEMENT" などの適切な値に XMLPROJECTION プロパティ・パラメータを設定すると、プライベート・プロパティを投影できます。これについてはこの章で後述します。同じことが多次元プロパティに適用されます。また、多次元プロパティは、最上位ノードに値がある場合にのみ投影できます。プロジェクションに含まれるのは最上位ノードのみです。

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>

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" と指定することはできません。また、この値の使用対象にできるのは、単純でリテラル値があり、オブジェクトのタイプがコレクションなどではないプロパティのみです。

オブジェクト値プロパティのプロジェクションが持つ形式の指定

オブジェクト・プロパティの投影方法を制御するには、以下のように、そのプロパティの XMLPROJECTION パラメータを設定します。

例えば、以下のクラスを考えてみます。

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 クラス・パラメータを指定します。

  以下のパラメータのいずれかまたは両方とも指定しない限り、このパラメータの効果はありません。

• 同じクラスでは、オプションで 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>

  

リスト・プロパティのプロジェクションが持つ形式の指定

以下のクラスにより、"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>

リレーションシップの既定のプロジェクション

まず、以下の 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>