appserver.xml 詳細
イントロダクション
XMLフレームワークは2つの主なクラス - WOXMLCoder と WOXMLDecoder から形成され 、XMLとしてオブジェクトをコード化して解読することができます。これらのクラスはパース、又は( World Wide Web のような)外部ソースからXMLデータを生成すために使用できます。このような「外部からの」XMLで動作するとき、XMLエレメントと属性、そしてテキストエディタやXMLエディタで作成できるXML - フォーマット内で、オブジェクトにマップして「マッピング(地図)モデル」を記述します。
マッピング(地図)モデルは解読プロセスにおいて素晴らしい仕事をします。外部ソースから送受信するXMLをコード化して解読するときに使われます。WOXMLCoder と WOXMLDecoder が単にアーカイブメカニズムとして用いられる時、マッピング(地図)モデルは通常必要ではありません。マッピング(地図)モデル構想の詳細は "マッピング(地図)モデルのフォーマット" を参照して下さい。
マッピング(地図)モデルなしで WOXMLCoder と WOXMLDecoder クラスを使用しているカスタムオブジェクトをコード化して解読するとき、カスタムクラスに必要なことは:
- WOXMLCoding インタフェース内で宣言した encodeWithWOXMLCoder を実装(このメソッドの実装方法はカスタムクラスのインスタンス変数をコード化する場所です)
- WOXMLDecoder クラス記述内で宣言した単一引数の コンストラクチャ の実装
マッピング(地図)モデルとオブジェクトが下記のエンコードやデコードを使用した場合には上記記述方法が必要ありません:
- String, Number, Boolean と NSTimestamp のインスタンス。 このクラスのサブクラスはスーパークラスと同じ様に扱われます。ただし、WOXMLCoding インタフェースを実装する場合以外
- NSArray, NSDictionary と NSData のインスタンス。WebObject 5.1以前、これらの可変クラス( NSMutableArray 、 NSMutableDictionary と NSMutableData )が WOXMLCoder を使用してコード化される場合、無可変クラスと同じ様に書き出されることに注意して下さい。例えば、 NSMutableArray は NSArray として書き出されました。今、自分自身として書き出されます。結果として、 WOXMLDecoder が可変オブジェクトを解読するために使用される場合、可変フォームとして解読されます。
- EOEnterpriseObject のインスタンス(やサブクラスですべてのインスタンス変数がアトリビュートやリレーションシップの場合)
基礎的なSAXパーサーによって上げられた例外処理は、簡素化のために、コードを WOXMLException オブジェクト内でラッパーすることで必要な例外処理の数を減らすことができます。
マッピング(地図)モデルのフォーマット
マッピング(地図)モデルはテキストエディタまたはXMLエディタを使用して簡単に作成ができます。1つ又はそれ以上の <entity> エレメントから形成されるのはテキストファイルだけで、それぞれはゼロかそれ以上 <property> エレメント、単一ルート <model> エレメント内ですべて含んだものを囲めます。
下記は簡単なマッピング(地図)モデル:
<model>
<entity name="Command" xmlTag="command">
<property name="qty" xmlTag="quantity" attribute="YES"/>
<property name="movie" xmlTag="movie"/>
<property name="customer" xmlTag="customer"/>
</entity>
<entity name="MyMovie" xmlTag="movie">
<property name="title" xmlTag="name" attribute="YES"/>
<property name="dateReleased" xmlTag="date">
<property name="roles" xmlTag="role">
<property name="category" xmlTag="cat"/>
</entity>
<entity name="com.webobjects.eocontrol.EOGenericRecord" xmlTag="role">
<property name="roleName" xmlTag="name" attribute="YES"/>
</entity>
</model>
マッピング(地図)モデルを作成する場合に気をつけることは、解読時に指定されているプロパティがユニークである必要性があります。(同じプロパティのために2つのマップを持つことはできません)
エンコーディングしている時、XMLタグにも同じことが適用されます:同じXMLタグのために2つのマッピングを持つことができません。
<model> エレメント
<model> エレメントはマッピング(地図)ファイルのルートエレメントであり、マッピング・インフォメーションを含みます。それは属性を持ちません。
<model> エレメントは少なくとも1つ以上の <entity> エレメントを含んでいなくてはなりません。
<entity> エレメント
<entity> エレメントは生成されたXMLデータとエンコーディング・オブジェクト間のリレーションシップを記述します。最初の <entity> エレメントは生成されたXMLデータのルートエレメントを記述します。通常、次の <entity> エレメントはルートエレメントの記述を完了する必要があります。それは2つの必須属性と多数オプション属性を持ちます:
* name=property (必須) エンコーディングされているオブジェクトのタイプ名、例えば MyMovie クラス。通常、これはkey-valueコーディング上のプロパティ名です(クラス名、EOModel 内でエンタープライズオブジェクトの属性名、又はXMLデータがマップされるべきディクショナリキー)。
* xmlTag=tag (必須) 生成されたデータに現われるXMLタグ。このタグは現在記述されているエンティティーに対応します。
* ignoreUnmappedTags="YES" | "NO" (オプション) この属性はデコード時だけに有用です。 "NO" が WOXMLException を次の時に thrown します:unmappedTagsKey が指定されない場合や、エンティティーのためにXMLを解析する間に、XMLタグがマッピング(地図)モデル内に指定されたマップがない場合。"YES" が指定されるや、エンティティ・オブジェクトが NSDictionary としてデコードされている場合には例外処理が発生しません。デフォルトは "NO"。
* unmappedTagsKey=key (オプション) この属性はデコード時だけ有用です。エンティティーのXML解析時、 マッピング(地図)モデル内に特定のマップがないXMLタグと出会うと、key-valueコーディングのプロパティ名が使用されるべきです。key-valueコーディングのために与えられるべき値が NSDictionary で、例えば '{ quantity = "9"; }' 。開発者はこのように処理すべきです。
* contentsKey=key(オプション) この属性はデコード時だけ有用です。プロパティ名は <entity> タグで囲まれたテキストのために使用されます。 例えば、マッピング・モデルが次のことを含むなら:
...
<entity name="com.webobjects.foundation.NSMutableDictionary" xmlTag="text" contentsKey="contents" />
...
例えば、XMLパース中に次のコードがあるとします:
<text>Hello, <b>World!</b></text>
NSMutableDictionary オブジェクトは単一key-valueで作成されます:キー "contents" はその値として2つのエレメントを含む NSMutableArray を持ちます:String "Hello, " と単一key-valueの dictionary を持ちます:キーは "b" 、値は "World!" になるのです。
この属性が指定さた場合、この <entity> エレメントのために <property> エレメントを作成する必要はありません。使用されないからです。その代わりに、キーのためにkey-valueコーディングペアがあり、その値が NSMutableArrayとして処理されることを確認して下さい。
<property> エレメント
<entity> エレメント内では、ゼロ又はそれ以上の <property> エレメントを持つことができます。それはエンティティー・オブジェクトのプロパティとそのプロパティのために生成されるXMLデータの間のマッピングを記述します。各エンティティーオブジェクトのプロパティはその値がXMLデータとなるkey-valueコーディングペアです。それは2つの必須属性と多数オプション属性を持ちます:
* name=key (必須) プロパティを表しているkey-valueコーディングペアのキー名。
* xmlTag=tag (必須) 生成されたデータ内に現われるXMLタグ。このタグは現在記述されているプロパティに対応します。このプロパティタイプが実際にクラスであり、例えば MyMovie であるなら、 <entity> エレメントが完全な記述を完了するために後で定義されるべきです。<xmlTag> を使用してチェーンを完了します。上記のサンプルで、エンティティー Command はプロパティ movie を持ちます。movie は実際にクラス MyMovie のオブジェクトであるので、別の <entity> エレメントを使用して詳しく述べられます。
* attribute="YES" | "NO" (オプション) この属性はエンコード時だけ有用です。"YES" はこの属性を通常のサブエレメントの代わりに、 <entity> エレメントを囲んでいる 属性としてエンコードさせます。例えば、もし attribute="YES" が movie プロパティのために指定された場合、それはこのようにエンコードされるでしょう:
<command movie="someValue" ... </command>
そうしない場合:
<command>
...
<movie>someValue</movie>
...
</command>
デフォルトは "NO"。
* forceList="YES" | "NO" (オプション) この属性はデコード時だけ有用です。プロパティ値のためにパスしている時、囲んでいる単一値は適切なタイプのオブジェクトとして、または文字列として(値のためにそれ以上 <entity> エレメントをマッピングされてなければ)パスされます。これはデフォルトの行動です ( forceList = "NO" の場合)。"YES" は囲んでいる単一エレメントを適切なタイプの単一オブジェクトで NSMutableArray としてパスされます。 例えば、このように XML セグメントを持つなら:
<property_foo>
<type_bar>some_Value</type_bar>
</property_foo>
デフォルトでデコード時はキー property_foo でkey-valueコーディングコールとなり、タイプ type_bar のオブジェクトになります。forceList = "YES" はタイプ type_barの単一オブジェクトを含む NSMutableArrayになるインスタンスをもたらします。
以下のようなXMLストラクチャのデコードを注意:
<property_foo>
<type_bar>value1</type_bar>
<type_bar>value2</type_bar>
</property_foo>
常にキー property_foo でkey-valueコーディングコールとなり、2つの type_bar オブジェクトを含む NSMutableArray の値となります。
デフォルトは "NO"。
* codeBasedOn="TAG" (オプション) この属性はデコード時だけ有用です。WOXMLCoder は通常key-valueをコーディングしている間、プロパティ名属性の値をキーとして用います。カスタムクラス内でその名前の属性がインスタンス変数名を示すので、殆どの状態で望ましいと言えます。NSDictionary オブジェクトを使用する場合、 xmlTag 属性の値をキーとして用いることもあります。そのためには、属性のプロパティリスト内で codeBasedOn = "TAG" を指定してください。
* reportEmptyValues="YES" | "NO" (オプション) この属性はデコード時だけ有用です。XML デコード中に空のエレメントが遭遇した場合 (インスタンス, <myElement></myElement>)、WOXMLDecoder はデフォルトによって空の NSDictionary オブジェクトを作成します。reportEmptyValues を "NO" にセットすることでこの空のオブジェクトの作成を阻止します。 デフォルトは "YES"。
* outputTags="class" | "property" | "both" | "neither" (オプション) この属性はデコード時だけ有用です。マッピング・モデル内で指定されたXMLタグは与えられたプロパティのために出力されるべきです。デフォルトである "property"のXMLタグは出力されるべきです。"class" はプロパティの包囲クラスに関連するXMLタグが代りに出力されるべきであると指示します。 "both" の指示は 両方の "property" と "class" が出力されるべきです。"neither" は xmlTag を出力しまいことです。 outputTags属性の使用を例証するために、次のマッピング・モデルは NSMutableDictionary オブジェクトから HTML タグを作成するために使用可能です:
<model>
<entity name="com.webobjects.foundation.NSMutableDictionary" xmlTag="text">
<property name="p" xmlTag="ignore" outputTags="neither"/>
</entity>
<entity name="Paragraph" xmlTag="p">
<property name="text.contents" xmlTag="text" outputTags="class"/>
</entity>
<entity name="ItemList" xmlTag="ul">
<property name="contents" xmlTag="li" outputTags="both"/>
</entity>
<entity name="Item" xmlTag="item">
<property name="contents" xmlTag="ignore" outputTags="class"/>
</entity>
<entity name="LineBreak" xmlTag="br"/>
<entity name="ExternalLink" xmlTag="a">
<property name="url" xmlTag="href" attribute="YES"/>
<property name="anchorText" xmlTag="ignore" outputTags="neither"/>
</entity>
</model>