|
共通 DOM API | |||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
public interface LSSerializer
LSSerializer は、DOM ドキュメントを XML の中に直列化する (書き込む) ための API を提供します。XML データは文字列または出力ストリームに書き込まれます。直列化の間に行われる変更または修正は、直列化されたデータだけに影響を与えます。Document オブジェクトとその子は、直列化操作によって変更されることはありません。
XML データの直列化の間に、[DOM Level 3 Core] の付録 B で定義されている名前空間の修正が行われます。[DOM Level 2 Core] では、実際の名前空間 URI として空の文字列を許可しています。Node の namespaceURI が空の文字列の場合、直列化ではこれらの文字列を null として処理し、接頭辞があればそれを無視します。
LSSerializer は、直列化で任意のノード型を受け入れます。Document 型または Entity 型のノードでは、可能な場合、整形式の XML が生成されます (ドキュメントまたは実体が解析操作から得られ、作成後に変更されていない場合、整形式であることが保証される)。これらのノード型の直列化された出力は、それぞれ XML ドキュメントまたは外部 XML 実体として出力され、XML パーサの入力として受け入れ可能です。ほかのすべてのノード型の場合、直列化された形式は実装に依存します。
直列化されている Document、DocumentFragment、または Entity 内では、Nodes は次のように処理されます。
false に設定されている場合を除く) と DTD サブセットを含めて、Document ノードが書き込まれる。Document ノードを書き込むと、ドキュメント全体が直列化されるEntity ノードは、LSSerializer.write により直接書き込まれると、実体展開を出力するが、名前空間修正は行われない。結果の出力は外部実体として有効になるtrue に設定すると、EntityReference ノードは出力で &entityName; の形式の実体参照として直列化される。実体参照の子ノード (展開) は無視される。entities パラメータを false に設定すると、実体参照の子だけが直列化される。子を持たない (対応する Entity ノードを持たない、あるいは対応する Entity ノードが子を持たない) EntityReference ノードは常に直列化されるCDATAsections は split-cdata-sections パラメータに従って処理される。このパラメータを true に設定すると、CDATAsections は分割され、表現できない文字は通常の内容の数値文字参照として直列化される。分割の正確な位置と数は指定されない。このパラメータを false に設定すると、well-formed パラメータを true に設定した場合、CDATAsection の表現できない文字は「wf-invalid-character」エラーとして報告される。このエラーは回復できない。代替文字を供給する機構はなく、引き続き直列化が行われるDocumentFragment ノードは、ドキュメントフラグメントの子をドキュメントフラグメントに表れる順序で直列化することで直列化される 注: Node の直列化では、必ずしも常に整形式の XML ドキュメントが生成されるわけではありません。すなわち、LSParser が結果の直列化を解析するときに致命的エラーをスローする可能性があります。
ドキュメントの文字データ (マークアップの外部) 内では、直接表すことができない文字は文字参照に置換されます。< と & が存在すると、あらかじめ定義された実体の < と & に置き換えられます。その他のあらかじめ定義された実体 (>、'、および ") は必要な場合 (]]> に > を使用するなど) を除き使用されません。出力文字エンコーディングで直接表すことができない文字は、数値文字参照として直列化されます。また、文字エンコーディング標準は一般に文字の 16 進数表現を使用するので、文字参照を直列化するときは 16 進数表現を使用することをお勧めします。
属性値に一重引用符と二重引用符を含めることを許可するには、アポストロフィ記号または一重引用符 (') は、「'」として表し、二重引用符 (") は「"」として表すことができます。出力文字エンコーディングの属性値で直接表すことができない改行文字やほかの文字は、数値文字参照として直列化されます。
出力文字エンコーディングで表すことができない文字が、マークアップ内であるが属性の外部で検出されると、 DOMError 致命的エラーとして報告されます。一例として、要素 <LaCa?ada/> を encoding="us-ascii" を使って直列化する場合が挙げられます。この結果、DOMError "wf-invalid-character-in-node-name" (well-formed で提案されている) が生成されます。
LSSerializer の normalize-characters パラメータを true に設定して要求した場合、文字直列化は、[XML 1.1] の付録 E に含まれる完全に正規化された文字の定義に従って、マークアップと文字データについて、直列化されるすべてのデータで実行されます。文字正規化処理は、書き込まれているときのデータだけに影響を及ぼします。この処理は、直列化が完了したあとのドキュメントの DOM のビューを変更しません。
実装は、すべての XML パーサがサポートする必要があるすべてのエンコーディングでデータの直列化が可能であることを保証するために、UTF-8、UTF-16、UTF-16BE、および UTF-16LE エンコーディングをサポートする必要があります。エンコーディングが UTF-8 の場合、バイト順マークが直列化されるかどうか、あるいは出力がビッグエンディアンまたはリトルエンディアンであるかは実装に依存します。エンコーディングが UTF-16 の場合、出力がビッグエンディアンまたはリトルエンディアンであるかは実装に依存しますが、LSOutput.byteStream または LSOutput.systemId などの文字以外の出力に対してバイト順マークが生成される必要があります。バイト順マークが生成されない場合、byte-order-mark-needed 警告が報告されます。エンコーディングが UTF-16LE または UTF-16BE の場合、出力はビッグエンディアン (UTF-16BE) またはリトルエンディアン (UTF-16LE) であり、バイト順マークは生成されません。すべての場合において、エンコーディング宣言が生成された場合、エンコーディング宣言は直列化中に使用されるエンコーディングに対応しています (例、UTF-16 が要求された場合、encoding="UTF-16" が現れる)。
名前空間は直列化の間に修正されます。直列化処理は名前空間宣言、名前空間接頭辞、および要素に関連付けられた名前空間 URI、および属性が整合していることを検証します。不整合が見つかると、ドキュメントの直列化された形式は変更され、これらの不整合を削除します。ドキュメントの直列化中に名前空間の修正に使用されるメソッドは、 [DOM Level 3 Core] の付録 B.1、「Namespace normalization」で定義されたアルゴリズムです。
ドキュメントを直列化している間に、discard-default-content パラメータは指定されていないデータを直列化するかどうかを制御します。
直列化中、エラーと警告はエラーハンドラ (LSParser.domConfig の error-handler パラメータ) を通じてアプリケーションに報告されます。この仕様では、DOM ノードの直列化中に発生する可能性があるすべてのエラーと警告を定義しているのではなく、一部の一般的なエラーと警告のケースを定義しています。この仕様で定義されているエラーと警告の型 (DOMError.type) は次のとおりです。
"no-output-specified" [fatal]LSOutput への書き込み中に、LSOutput で出力が指定されていない場合に発生する"unbound-prefix-in-entity-reference" [fatal] true に設定し、バインドされていない名前空間接頭辞を置換テキストに含む実体が、名前空間接頭辞のバインディングがない位置で参照された場合に発生する"unsupported-encoding" [fatal]定義されたエラーと警告の発生に加えて、実装は IO エラー (ファイルが見つからない、アクセス権が拒否された) など実装固有のエラーと警告を発生することが想定されています。
「Document Object Model (DOM) Level 3 Load and Save Specification」も参照してください。
| メソッドの概要 | |
|---|---|
DOMConfiguration |
getDomConfig()
DOM ノードの直列化中に LSSerializer が使用する DOMConfiguration オブジェクト。 |
LSSerializerFilter |
getFilter()
アプリケーションがフィルタを提供する場合、シリアライザは各ノードを直列化する前にフィルタを呼び出します。 |
String |
getNewLine()
書き出し中の XML で使用される行末の文字シーケンス。 |
void |
setFilter(LSSerializerFilter filter)
アプリケーションがフィルタを提供する場合、シリアライザは各ノードを直列化する前にフィルタを呼び出します。 |
void |
setNewLine(String newLine)
書き出し中の XML で使用される行末の文字シーケンス。 |
boolean |
write(Node nodeArg,
LSOutput destination)
LSSerializer インタフェースの一般的な説明で前述したように、指定されたノードを直列化します。 |
String |
writeToString(Node nodeArg)
LSSerializer インタフェースの一般的な説明で述べられているように、指定されたノードを直列化します。 |
boolean |
writeToURI(Node nodeArg,
String uri)
LSSerializer.write が、エンコーディングが指定されておらず、LSOutput.systemId が uri 引数に設定されている LSOutput を使って呼び出された場合のように機能する簡易メソッドです。 |
| メソッドの詳細 |
|---|
DOMConfiguration getDomConfig()
LSSerializer が使用する DOMConfiguration オブジェクト。 LSSerializer の DOMConfiguration オブジェクトは次のパラメータを追加または変更します。"canonical-form"truetrue に設定すると、format-pretty-print、discard-default-content、および xml-declaration パラメータは false に設定されます。これらのパラメータのどれかを true に設定すると、このパラメータは false に設定されます。canonical-form が true のときに XML 1.1 ドキュメントを直列化すると、致命的エラーが発生します。false"discard-default-content"trueAttr.specified 属性を使って、破棄する属性を決定します。このパラメータを true に設定すると、実装によっては、実装に利用できる情報 (XML スキーマ、DTD、Attr.specified 属性など) をすべて使用して、破棄する属性と佩用を決定する場合があります。false"format-pretty-print"truefalse"ignore-unknown-character-denormalizations" trueunknown-character-denormalization」警告を発生し、これらの文字が原因で生じた可能性のある正規化されていないものを無視します。false"normalize-characters"DOMConfiguration により定義されているパラメータと同等です。Core の場合とは異なり、このパラメータのデフォルト値は true です。DOM 実装は [XML 1.1] の付録 E に従ってドキュメントの文字を完全に正規化された処理をサポートする必要はありませんが、サポートされている場合、このパラメータはデフォルトで起動されていなければなりません。"xml-declaration"trueDocument、Element、または Entity ノードを直列化する場合、XML 宣言またはテキスト宣言を含める必要があります。バージョン (ドキュメントが Level 3 ドキュメントであり、バージョンが null 以外の場合は Document.xmlVersion、そうでない場合は値 1.0 を使用)、および出力エンコーディング (出力エンコーディングを確認する方法については、LSSerializer.write を参照) は直列化された XML 宣言で指定されます。 falsexml-declaration-needed」警告を報告します。
String getNewLine()
null に設定すると、値はデフォルト値にリセットされます。
void setNewLine(String newLine)
null に設定すると、値はデフォルト値にリセットされます。
LSSerializerFilter getFilter()
DOMConfiguration パラメータが要求した操作が適用されたあとに呼び出されます。たとえば、cdata-sections を false に設定すると、CDATA セクションはフィルタに渡されません。
void setFilter(LSSerializerFilter filter)
DOMConfiguration パラメータが要求した操作が適用されたあとに呼び出されます。たとえば、cdata-sections を false に設定すると、CDATA セクションはフィルタに渡されません。
boolean write(Node nodeArg,
LSOutput destination)
throws LSException
LSSerializer インタフェースの一般的な説明で前述したように、指定されたノードを直列化します。出力は、供給された LSOutput に書き込まれます。 LSOutput への書き込み時、エンコーディングは LSOutput および書き込まれる項目 (または、項目の所有者ドキュメント) からアクセスできるエンコーディング情報を確認することで、次の順序で検出されます。LSOutput.encoding Document.inputEncoding Document.xmlEncoding LSOutput で出力が指定されない場合、no-output-specified 致命的エラーが発生します。
nodeArg - 直列化するノードdestination - 直列化された DOM の出力先
node が正常に直列化された場合は true。通常の処理は停止したが、実装がドキュメントの直列化を引き続き実行している場合は false。この場合、直列化の結果は実装に依存する
LSException - SERIALIZE_ERR: LSSerializer がノードを直列化できなかった場合に発生する。DOM アプリケーションは、エラーの詳細を取得する場合、error-handler パラメータを使って DOMErrorHandler に接続する必要がある
boolean writeToURI(Node nodeArg,
String uri)
throws LSException
LSSerializer.write が、エンコーディングが指定されておらず、LSOutput.systemId が uri 引数に設定されている LSOutput を使って呼び出された場合のように機能する簡易メソッドです。
nodeArg - 直列化するノードuri - 書き込み先の URI
node が正常に直列化された場合は true。通常の処理は停止したが、実装がドキュメントの直列化を引き続き実行している場合は false。この場合、直列化の結果は実装に依存する
LSException - SERIALIZE_ERR: LSSerializer がノードを直列化できなかった場合に発生する。DOM アプリケーションは、エラーの詳細を取得する場合、error-handler パラメータを使って DOMErrorHandler に接続する必要がある
String writeToString(Node nodeArg)
throws DOMException,
LSException
LSSerializer インタフェースの一般的な説明で述べられているように、指定されたノードを直列化します。出力は、呼び出し側に返された DOMString に書き込まれます。使用されるエンコーディングは、DOMString 型のエンコーディング、つまり UTF-16 です。バイト順マスクは DOMString オブジェクトで生成されません。
nodeArg - 直列化するノード
DOMException - DOMSTRING_SIZE_ERR: 結果の文字列が DOMString に合わせるには長すぎる場合に発生する
LSException - SERIALIZE_ERR: LSSerializer がノードを直列化できなかった場合に発生する。DOM アプリケーションは、エラーの詳細を取得する場合、error-handler パラメータを使って DOMErrorHandler に接続する必要がある
|
共通 DOM API | |||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||