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 として使用できます。Node の namespaceURI が空の文字列である場合、直列化では namespaceURI を null として扱い、接頭辞を無視します (存在する場合)。

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

直列化される Document、DocumentFragment、または 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 に設定されていると、CDATAsection 内の表示できない文字は「well-formed」パラメータが true に設定されているときの「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.byteStream や LSOutput.systemId など) に対して生成されます。バイト順序記号が生成されない場合、警告「byte-order-mark-needed」が報告されます。エンコーディングが UTF-16BE または UTF-16LE の場合、出力はビッグエンディアン (UTF-16BE) またはリトルエンディアン (UTF-16LE) で、バイト順序記号は生成されません。どのケースも、エンコーディング宣言 (生成される場合) は、直列化の間に使用されるエンコーディングに対応します (たとえば、encoding="UTF-16" は、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」も参照してください。

メソッドの概要

DOMConfiguration	getDomConfig()
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) エンコーディングを指定せず、LSOutput.systemId を uri 引数に設定して、LSOutput で LSSerializer.write が呼び出されたかのように機能する簡易メソッドです。

メソッドの詳細

getDomConfig

DOMConfiguration getDomConfig()

getNewLine

String getNewLine()

書き出されている XML で使用される行末シーケンス文字です。任意の文字がサポートされますが、XML では特定の文字セットのシーケンスだけを行末として扱います (直列化されたコンテンツが XML 1.0 の場合は「XML 1.0」の「End-of-Line Handling」セクション 2.11 を参照。直列化されたコンテンツが XML 1.1 の場合は「XML 1.1」の「End-of-Line Handling」セクション 2.11 を参照)。推奨されていない文字シーケンスを使用すると、文書が直列化不可になったり、整形式にならなくなったりします。
取得時、この属性のデフォルト値は、実装固有のデフォルト行末シーケンスです。DOM 実装では、デフォルトの行末シーケンスを選択して、使用している環境のテキストファイルの通常の規則に合わせる必要があります。直列化されたコンテンツによっては、実装で、XML 1.0 または XML 1.1 によって許可されている行末シーケンスの 1 つに一致するデフォルトのシーケンスを選択する必要があります。この属性を null に設定すると、その値はデフォルト値にリセットされます。

setNewLine

void setNewLine(String newLine)

書き出されている XML で使用される行末シーケンス文字です。任意の文字がサポートされますが、XML では特定の文字セットのシーケンスだけを行末として扱います (直列化されたコンテンツが XML 1.0 の場合は「XML 1.0」の「End-of-Line Handling」セクション 2.11 を参照。直列化されたコンテンツが XML 1.1 の場合は「XML 1.1」の「End-of-Line Handling」セクション 2.11 を参照)。推奨されていない文字シーケンスを使用すると、文書が直列化不可になったり、整形式にならなくなったりします。
取得時、この属性のデフォルト値は、実装固有のデフォルト行末シーケンスです。DOM 実装では、デフォルトの行末シーケンスを選択して、使用している環境のテキストファイルの通常の規則に合わせる必要があります。直列化されたコンテンツによっては、実装で、XML 1.0 または XML 1.1 によって許可されている行末シーケンスの 1 つに一致するデフォルトのシーケンスを選択する必要があります。この属性を null に設定すると、その値はデフォルト値にリセットされます。

getFilter

LSSerializerFilter getFilter()

アプリケーションでフィルタが用意されていると、直列化処理は各ノードを直列化する前にフィルタを呼び出します。フィルタの実装では、ストリームからノードを削除したり、早期に直列化を終了するなどの選択ができます。
適用されている DOMConfiguration パラメータにより、要求された操作のあとにフィルタが呼び出されます。たとえば、CDATA セクションは、「cdata-sections」が false に設定されるとフィルタに渡されません。

setFilter

void setFilter(LSSerializerFilter filter)

アプリケーションでフィルタが用意されていると、直列化処理は各ノードを直列化する前にフィルタを呼び出します。フィルタの実装では、ストリームからノードを削除したり、早期に直列化を終了するなどの選択ができます。
適用されている DOMConfiguration パラメータにより、要求された操作のあとにフィルタが呼び出されます。たとえば、CDATA セクションは、「cdata-sections」が false に設定されるとフィルタに渡されません。

write

boolean write(Node nodeArg,
              LSOutput destination)
              throws LSException

LSSerializer インタフェースの一般的な説明で前述のように、指定されたノードを直列化します。出力は、指定した LSOutput に書き込まれます。
LSOutput への書き込み時、エンコーディングは、LSOutput や次の順に書き込まれるアイテム (またはアイテムの所有者文書) を通じてアクセス可能なエンコーディング情報を確認して見つけられます。

1. LSOutput.encoding
2. Document.inputEncoding
3. Document.xmlEncoding

前述のプロパティを通じてエンコーディングにアクセスできない場合は、「UTF-8」のデフォルトエンコーディングが使用されます。指定したエンコーディングがサポートされていない場合は、致命的なエラーの「unsupported-encoding」が返されます。
出力が LSOutput で指定されていない場合は、致命的なエラーの「no-output-specified」が返されます。
実装では、適切なメディアタイプを直列化されたデータに関連付ける必要があります。
HTTP URI に書き込むときは、HTTP PUT が実行されます。ほかの型の URI に書き込むとき、その URI にデータを書き込むメカニズムは実装によって異なります。

パラメータ:

nodeArg - 直列化するノード

destination - 直列化された DOM の宛先

戻り値:

node が正常に直列化された場合は true。通常の処理は停止されたものの、実装が文書を直列化し続けた場合は false を返す。そのあとの直列化の結果は実装によって異なる

例外:

LSException - SERIALIZE_ERR: LSSerializer がノードを直列化できなかった場合。DOM エラーに関する詳細を取得する場合、アプリケーションは「error-handler」パラメータを使用して DOMErrorHandler を接続する必要がある

writeToURI

boolean writeToURI(Node nodeArg,
                   String uri)
                   throws LSException

エンコーディングを指定せず、LSOutput.systemId を uri 引数に設定して、LSOutput で LSSerializer.write が呼び出されたかのように機能する簡易メソッドです。

パラメータ:

nodeArg - 直列化するノード

uri - 書き込み先の URI

戻り値:

node が正常に直列化された場合は true。通常の処理は停止されたものの、実装が文書を直列化し続けた場合は false を返す。そのあとの直列化の結果は実装によって異なる

例外:

LSException - SERIALIZE_ERR: LSSerializer がノードを直列化できなかった場合。DOM エラーに関する詳細を取得する場合、アプリケーションは「error-handler」パラメータを使用して DOMErrorHandler を接続する必要がある

writeToString

String writeToString(Node nodeArg)
                     throws DOMException,
                            LSException

LSSerializer インタフェースの一般的な説明で、前述のように指定されたノードを直列化します。出力は呼び出し側へ返される DOMString に書き込まれます。使用されるエンコーディングは UTF-16 などの DOMString 型のエンコーディングです。バイト順序記号は DOMString オブジェクトでは生成されません。

パラメータ:

nodeArg - 直列化するノード

戻り値:

直列化されたデータを返す

例外:

DOMException - DOMSTRING_SIZE_ERR: 結果の文字列が長すぎて DOMString 内に収まらない場合

LSException - SERIALIZE_ERR: LSSerializer がノードを直列化できなかった場合。DOM エラーに関する詳細を取得する場合、アプリケーションは「error-handler」パラメータを使用して DOMErrorHandler を接続する必要がある