値の変換の制御

はじめに

XML 対応オブジェクトには一般的に、Caché データ型で定義されたプロパティがあります。それぞれのデータ型クラスでは、LogicalToXSD() メソッドと XSDToLogical() メソッドが定義されています。XML 出力がオブジェクトで要求されると、Caché XML ツールでは自動的に、プロパティごとに LogicalToXSD() メソッドを呼び出して、XML で使用できるようにデータを適切な形式に変換します。同様に、XML ドキュメントが入力として使用されると、Caché XML ツールでは XSDToLogical() メソッドを呼び出して、データを Caché 用の適切な形式に変換します。

例えば、%BinaryOpens in a new tab データ型クラスでは、LogicalToXSD() メソッドにより、$SYSTEM.Encryption.Base64Encode() メソッドを使用して発信値を変換します。同様に、XSDToLogical() メソッドにより、$SYSTEM.Encryption.Base64Decode() メソッドを使用して着信値を変換します。

Caché クラスにはストリーム値プロパティを含めることもできますが、ストリーム・クラスでは LogicalToXSD() メソッドも XSDToLogical() メソッドも定義しません。その代わり、XML 対応クラスのプロパティとして使用される場合、XML ツールではストリーム・クラスが特別に処理されます。具体的には以下の手順を実行します。

• 文字ストリームは、文字列と同じように扱われます。次のセクションで説明するように、XML 特殊文字が存在するために必要な変更は別にして、既定では変更されません。

• Caché で XML にエクスポートすると、バイナリ・ストリーム・プロパティが文字列に Base 64 エンコードで変換されます (つまり、データがその方法でエンコードされてからエクスポートされます)。Caché で XML からインポートすると、逆が実行されます。

XML 対応のオブジェクトを使用する際、XML に値を直接投影できないとか他の理由で値を変換するとかいった、特殊な場合の検討が必要になる場合があります。この章の残りの部分では、これらの場合について説明します。

XML 特殊文字の処理

コンテキストに応じて、Caché XML サポートでは、タイプ文字列または文字ストリームのプロパティ内にアンド記号 (&) やその他の特定の文字を検出すると、それらの文字をエスケープします。

それらの特殊文字では、CONTENT プロパティ・パラメータを設定することで、エスケープの実行方法を制御できます。以下に示すように、リテラル形式とエンコード形式では詳細が異なります。

* "ESCAPE-C14N" の場合、エスケープ処理は XML Canonicalization 規格に従って行われます。主な違いは、キャリッジ・リターンが 
 としてエスケープ処理されることです。

例

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

Class ResearchXForms.CONTENT Extends (%RegisteredObject, %XML.Adaptor)
{

Parameter XMLNAME = "Demo";

Property String1 As %String;

Property String2 As %String(CONTENT = "STRING");

Property String3 As %String(CONTENT = "ESCAPE");

Property String4 As %String(CONTENT = "MIXED");

}

String2 と String1 は、常に同様に処理されます。String2 では、CONTENT の既定値が使用されるからです。

このクラスのリテラル XML 出力は以下のようになります。

<?xml version="1.0" encoding="UTF-8"?>
<Demo>
  <String1>value 1 & value 2</String1>
  <String2>value 1 & value 2</String2>
  <String3>value 1 &amp; value 2</String3>
  <String4>value 1 & value 2</String4>
</Demo>

SOAP エンコードの XML 出力は以下のように変わります。

<?xml version="1.0" encoding="UTF-8"?>
<CONTENT xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:s="http://www.w3.org/2001/XMLSchema">
  <String1>value 1 & value 2</String1>
  <String2>value 1 & value 2</String2>
  <String3>value 1 &amp; value 2</String3>
  <String4>value 1 & value 2</String4>
</CONTENT>

UTC タイム・ゾーン・インジケータの処理

XML 対応クラスでは、XML ドキュメントからインポートする際に UTC タイム・ゾーン・インジケータを使用するかどうかを指定できます。同様に、エクスポート時に UTC タイム・ゾーン・インジケータを含めるかどうかを指定できます。

そのためには、XMLTIMEZONE パラメータを指定します。以下の値のいずれかを使用します。

• "UTC" — この場合、xsd:time または xsd:dateTime を含む要素をインポートすると、そのデータは UTC 時刻に変換されます。これが既定の動作です。

  XML スキーマの仕様に従い、Caché XML サポートではタイム・ゾーン・インジケータは純粋な期間として扱われ、EDT などの名前の付いたタイム・ゾーンはすべて無視されます。

• "IGNORE" — この場合、xsd:time または xsd:dateTime を含む要素をインポートすると、UTC タイム・ゾーン・インジケータは無視されます。

エクスポート時には、UTC 時刻が常に使用されます。XMLTIMEZONE パラメータにより、UTC タイム・ゾーン・インジケータが含まれるかどうかが制御されます。

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

Class ResearchXForms.UTC Extends (%Persistent, %XML.Adaptor)
{

Parameter XMLNAME = "Demo";

Property Time1 As %Time;

Property Time2 As %Time(XMLTIMEZONE = "IGNORE");

Property TimeStamp1 As %TimeStamp;

Property TimeStamp2 As %TimeStamp(XMLTIMEZONE = "IGNORE");

}

このクラスの XML 出力は以下のようになります。

<?xml version="1.0" encoding="UTF-8"?>
<Demo>
  <Time1>17:52:06Z</Time1>
  <Time2>17:52:06</Time2>
  <TimeStamp1>1976-02-18T17:52:06Z</TimeStamp1>
  <TimeStamp2>1976-02-18T17:52:06</TimeStamp2>
</Demo>

DISPLAYLIST での値の投影

%StringOpens in a new tab タイプ (またはサブクラス) のプロパティの場合、XML プロジェクションでは DISPLAYLIST プロパティを使用できます。

単純なプロパティにより、DISPLAYLIST パラメータと VALUELIST パラメータを指定できます。VALUELIST パラメータにより、プロパティに有効な値のリストを指定します。これによって列挙プロパティが定義されます。DISPLAYLIST パラメータも指定する場合があり、これによって、表示する対応値が指定されます。

既定では、XML プロジェクションではオブジェクトにある値が使用されます。その値は、VALUELIST で指定された値のいずれかです。%StringOpens in a new tab タイプのプロパティの場合、XMLLISTPARAMETER パラメータは、プロジェクションに使用する別の値のリストがどのパラメータに含まれるかを示すようになっています。通常、これは "DISPLAYLIST" に設定します。例えば、以下のデータ型クラスを考えてみます。

Class xmldisplaylist.MyEnumString Extends %String
{

Parameter VALUELIST = ",a,b,c";

Parameter DISPLAYLIST = ",apples,bananas,chocolate";

Parameter XMLLISTPARAMETER = "DISPLAYLIST";

}

また以下のクラスも考えてみます。ここでは、その前のデータ型クラスが使用されます。

Class xmldisplaylist.Demo Extends (%RegisteredObject, %XML.Adaptor)
{

Property Property1 As MyEnumString;

Property Property2 As MyEnumString(DISPLAYLIST = ",red,green,blue", VALUELIST = ",r,g,b");

}

以下は、このクラスのインスタンスの XML 表現の例です。

<Demo>
  <Property1>chocolate</Property1>
  <Property2>red</Property2>
</Demo>

一方、データ型クラスで XMLLISTPARAMETER パラメータを指定しない場合、XML 表現は以下のようになります。

<Demo>
  <Property1>c</Property1>
  <Property2>r</Property2>
</Demo>

インポートされたストリーム・プロパティの行末の制御

XML からインポートする際、文字ストリームの各プロパティで、ストリームの行末を制御できます。そのためには、XMLSTREAMMODE プロパティ・パラメータを設定します。このプロパティ・パラメータには、以下のいずれかの値を設定できます (大文字と小文字は区別されません)。

• XMLSTREAMMODE が "block" (既定) の場合、正規化された XML データが、変更されずにストリームにコピーされます。ストリームの LineTerminator プロパティが $CHAR(10) に設定され、インポートが従来の改行シーケンス ($CHAR(10)、$CHAR(13)、$CHAR(13,10)) と互換性を持つようになります。

• XMLSTREAMMODE が "line" の場合、XML データはストリームの LineTerminator プロパティで指定された文字で区切った行に分けられます。"%Library.AbstractStreamOpens in a new tab" を参照してください。

例えば、以下のデータがあるとします。

...
<Stream1>
this is a line
this is another line
this is another line

</Stream1>
...

このデータを %Stream.GlobalCharacterOpens in a new tab タイプの Stream1 プロパティを持つオブジェクトにインポートします。既定では、このプロパティでは XMLSTREAMMODE は "block" です。データをインポートした後、このプロパティは以下のデータを含みます。

this is a line
              this is another line
                                  this is another line

このプロパティで XMLSTREAMMODE を "line" に設定し、データを再インポートすると、このプロパティは以下のデータを含みます。

this is a line
this is another line
this is another line

この場合、行末はストリーム・クラスの LineTerminator プロパティによって決定されます。このプロパティは、%Stream.GlobalCharacterOpens in a new tab で $char(13,10) となります。

既定の日付/時刻値の指定

%TimeStampOpens in a new tab および %DateTimeOpens in a new tab データ型クラスでは、日付が $zdatetimeh による有効性チェックに失敗した場合、XMLDEFAULTVALUE パラメータによって使用する値が指定されます。そのような場合、既定では NULL 文字列が使用され、これにより、XMLImport() を介してデータをインポートするとエラーが発生します。クラスに対して有効な値を指定します。

例えば、%TimeStampOpens in a new tab や %DateTimeOpens in a new tab に対して、1841 年以降の日付を YYYY-MM-DD HH:MM:SS.nnnnnnnnn 形式で指定します。例: 01.01.41 00:00:00

XML への印字不能文字の投影

XML では、印字不能文字、特に ASCII 32 未満の文字は許可されません (キャリッジ・リターン、改行、およびタブは例外です)。

XML にプロパティを投影する必要があり、そのプロパティにこれら印字不能文字が含まれているとき、そのプロパティのタイプは %BinaryOpens in a new tab または (同等の) %xsd.base64BinaryOpens in a new tab とする必要があります。この値は、XML にエクスポートされるときに、Base 64 のエンコードに自動的に変換されます (またはインポートされるときに、Base 64 のエンコードから自動的に変換されます)。