モジュール java.xml
パッケージ org.w3c.dom.ls

インタフェースLSSerializer


public interface LSSerializer
LSSerializerは、DOM文書をXMLに直列化する(書き込む)ためのAPIを提供します。 XMLデータは文字列または出力ストリームに書き込まれます。 直列化を実行する間にどのような変更や修正が行われても、影響があるのは直列化されたデータだけです。 Documentオブジェクトとその子が直列化操作によって変更されることはありません。

DOM Level 3 Core」、付録Bで定義されているように、XMLデータの直列化中に名前空間修正が行われます。「DOM Level 2 Core」では、実際の名前空間URIとして空の文字列が許可されます。 NodenamespaceURIが空の文字列である場合、直列化ではそれをnullとして処理し、接頭辞(存在する場合)を無視します。

LSSerializerは、直列化のために任意のノード型を受け入れます。 DocumentまたはEntity型のノードの場合は、可能であれば整形式のXMLが作成されます(文書またはエンティティが解析操作から得られ、作成されてから変更されていない場合は整形式が保証されます)。 これらのノード型の直列化出力は、それぞれXML文書または外部XMLエンティティとして出力され、XMLパーサーの受け入れ可能な入力となります。 ほかのすべてのノード型の直列化された形式は、実装によって決まります。

直列化されるDocumentDocumentFragment、またはEntity内では、Nodesは次のように処理されます。

  • XML宣言(「xml-declaration」パラメータがfalseに設定されてないかぎり)とDTDサブセット(DOM内に存在する場合)を含め、Documentノードが書き込まれます。 Documentノードを書き込むと、文書全体が直列化されます。
  • LSSerializer.writeによって直接書き込まれた場合、Entityノードはエンティティ拡張を出力しますが、名前空間修正は行われません。 結果として得られる出力は外部エンティティとして有効になります。
  • 出力にパラメータ" entities "trueに設定されている場合、EntityReferenceノードはフォームのエンティティ参照として直列化されます" &entityName; "がある場合。 エンティティ参照の子ノード(展開)は無視されます。 パラメータ" entities "がfalseに設定されている場合、エンティティ参照の子のみが直列化されます。 子を持たないEntityReferenceノード(対応するEntityノードがないか、または対応するEntityノードに子がない場合)は、常に直列化されます。
  • 指定された出力エンコーディングでは表現できないコンテンツ文字を含むCDATAsectionsは、split-cdata-sectionsパラメータに従って処理されます。 このパラメータがtrueに設定されている場合は、CDATAsectionsが分割され、表現できない文字は通常のコンテンツ内の数値文字参照として直列化されます。 正確な位置と分割数は指定されません。 パラメータがfalseに設定されている場合、パラメータ" well-formed "がtrueに設定されている場合、CDATAsection内の表現不可能な文字は"wf-invalid-character"エラーとして報告されます。 代替文字が提供されず、直列化が続行されるのでエラーは回復できません。
  • DocumentFragmentノードは、文書フラグメントの子を文書フラグメント内に現れる順序で直列化することによって直列化されます。
  • ほかのすべてのノード型(Element、Textなど)は、対応するXMLソース形式に直列化されます。

ノート: Nodeを直列化しても、必ずしも整形式のXML文書を生成しません。つまり、結果として得られる直列化の解析時に、LSParserによって致命的エラーがスローされる可能性があります。

文書(マークアップの範囲外)の文字データ内では、直接表すことができないすべての文字は、文字参照に置き換えられます。 「<」や「&」が現れると、事前定義済エンティティである&lt;や&amp;に置き換えられます。 その他の事前定義済エンティティ(&gt;、&apos;および&quot;)は、必要な場合(たとえば、「]]>」などで&gt;を使用している場合)を除き、使用されない可能性があります。 出力文字エンコーディングで直接表すことができないすべての文字は、数値参照として直列化されます。文字エンコーディング標準では、一般に文字の16進表現を使用するので、文字参照を直列化するときは、16進表現を使用することをお薦めします。

属性値に単一引用符と二重引用符の両方を含めることを可能にするために、アポストロフィまたは単一引用符文字(')を「&apos;」として、また二重引用符文字(")を「&quot;」として表すことができます。 出力文字エンコーディングの属性値で直接表せない改行文字やほかの文字は、数値参照として直列化されます。

出力文字エンコーディングで表せない文字が、マークアップ内ではあるが、属性の外部に現れた場合は、すべて致命的エラーDOMErrorとして報告されます。 例として、encoding="us-ascii"で<LaCañada/>要素を直列化する場合があげられます。 この結果、DOMError "wf-invalid-character-in-node-name" (" well-formed "で提案されているように)が生成されます。

LSSerializerのパラメータ" normalize-characters "をtrueに設定してリクエストすると、マークアップ・データと文字データの両方で、直列化されるすべてのデータについて、[XML 1.1]の付録E に含まれる「完全に正規化された」文字の定義に従って文字正規化が実行されます。 文字の正規化処理は、書込み中のデータのみに影響を与えます。直列化の完了後、処理により文書のDOMのビューが変化することはありません。

実装では、「UTF-8」、「UTF-16」、「UTF-16BE」、および「UTF-16LE」エンコーディングをサポートして、すべてのXMLパーサーによってサポートされる必要があるすべてのエンコーディングで、データが直列化されることを保証する必要があります。 エンコーディングがUTF-8の場合、バイト順序記号が直列化されるかどうか、または出力がビッグ・エンディアンかリトル・エンディアンのどちらなのかは、実装に依存します。 エンコーディングがUTF-16である場合、出力がビッグ・エンディアンまたはリトル・エンディアンのどちらになるかは実装に依存しますが、LSOutput.byteStreamLSOutput.systemIdなどの非文字出力に対してバイト順序記号が生成されます。 バイト順序記号が生成されない場合、警告「byte-order-mark-needed」が報告されます。 エンコーディングがUTF-16BEまたはUTF-16LEの場合、出力はビッグ・エンディアン(UTF-16BE)またはリトル・エンディアン(UTF-16LE)で、バイト順序記号は生成されません。 いずれの場合も、エンコーディング宣言(生成される場合)は直列化中に使用されるエンコーディングに対応します(たとえば、UTF-16が要求された場合はencoding="UTF-16"が表示されます)。

名前空間は直列化中に修正され、直列化処理では名前空間宣言、名前空間接頭辞、および要素と属性に関連付けられた名前空間URIが一貫していることが確認されます。 矛盾が検出された場合、文書の直列化された形式は変更され、矛盾を削除します。 文書の直列化中に名前空間修正の実行に使用されるメソッドは、「DOM Level 3 Core」の付録B.1「名前空間の正規化」で定義されているアルゴリズムです。

文書を直列化中に、指定以外のデータが直列化されるかどうかは「discard-default-content」パラメータにより制御されます。

直列化中にエラーと警告がエラー・ハンドラ(LSSerializer.domConfigの" error-handler "パラメータ)を介してアプリケーションに報告されます。 この仕様では、DOMノードを直列化中に発生する可能性があるすべてのエラーと警告は定義されていませんが、一般的なエラーと警告のケースの一部を定義しています。 この仕様で定義されているエラーと警告の種類(DOMError.type)は次のとおりです。

"no-output-specified" [fatal]
LSOutputへの書込み中に、LSOutputで出力が指定されていない場合に返されます。
"unbound-prefix-in-entity-reference" [fatal]
構成パラメータ" namespaces "がtrueに設定されており、置換テキストにバインドされていないネームスペース・プレフィクスが含まれるエンティティが、ネームスペース・プレフィクスのバインディングがないロケーションで参照されている場合に発生します。
"unsupported-encoding" [fatal]
サポートされていないエンコーディングが検出された場合に返されます。

定義済みのエラーや警告を返すのに加えて、実装では、IOエラー(「ファイルが見つかりません、アクセス権は拒否されました...」)などを招くほかのエラーや警告について実装固有のエラーを返します。

Document Object Model (DOM) Level 3 Load and Save Specification」も参照してください。

導入されたバージョン:
1.5