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 が空の文字列である場合、直列化ではそれを 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" で <LaCanada/> 要素を直列化する場合が挙げられます。この結果、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) で、バイト順序記号は生成されません。いずれの場合も、エンコーディング宣言 (生成される場合) は直列化中に使用されるエンコーディングに対応します (たとえば、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」も参照してください。

メソッドのサマリー

メソッド

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

メソッドの詳細

getDomConfig

DOMConfiguration getDomConfig()

DOM ノードの直列化中に LSSerializer が使用する DOMConfiguration オブジェクト。
「DOM Level 3 Core」で定義されている DOMConfiguration インタフェースによって認識されるパラメータに加えて、LSSerializer の DOMConfiguration オブジェクトは次のパラメータを追加または変更します。

"canonical-form"

true

[オプション] 「正規 XML」で指定されている規則に従って文書を書き込みます。「DOM Level 3 Core」の「canonical-form」で説明されている動作に加えて、このパラメータを true に設定すると、「format-pretty-print」、「discard-default-content」、「xml-declaration」の各パラメータが false に設定されます。これらのパラメータのいずれかを true に設定すると、このパラメータが false に設定されます。「canonical-form」が true であるときに XML 1.1 文書を直列化すると、致命的エラーが生成します。

false

[必須] (デフォルト) 出力を正規化しません。

"discard-default-content"

true

[必須] (デフォルト) Attr.specified 属性を使用して、どのような属性を破棄するべきかを決定します。このパラメータが true に設定されている場合、一部の実装では、どのような属性およびコンテンツを破棄するかを決定するために、その実装で使用できるあらゆる情報 (つまり、XML スキーマ、DTD、Attr.specified 属性など) を使用する可能性があります。

false

[必須] すべての属性およびすべてのコンテンツを維持します。

"format-pretty-print"

true

[オプション] 空白文字を追加して出力を書式設定し、プリティープリント処理され、インデントされた読みやすい形式にします。この仕様では、変換の厳密な形式は指定されていません。プリティープリント処理により、文書のコンテンツが変更され、文書の有効性に影響が生じる可能性があります。実装の有効性を検証することにより有効性が保たれます。

false

[必須] (デフォルト) 結果をプリティープリント処理しません。

"ignore-unknown-character-denormalizations"

true

[必須] (デフォルト)「XML 1.1」がサポートされているときに完全な正規化を検証中に、正規化プロパティーを判定できない文字が検出された場合は、"unknown-character-denormalization" 警告を発生させ (このパラメータが設定されていない場合は、代わりにエラーを発生させる)、これらの文字によって引き起こされる可能性のある不完全な正規化をすべて無視します。

false

[オプション] プロセッサで正規化プロパティーを判定できない文字が検出された場合は、致命的エラーを報告します。

"normalize-characters"

このパラメータは、「DOM Level 3 Core」の DOMConfiguration で定義されているパラメータと同等です。コアの場合とは異なり、このパラメータのデフォルト値は true です。DOM 実装では、「XML 1.1」の付録 E に従って文書内の文字の完全な正規化をサポートする必要はありませんが、サポートする場合は、デフォルトでこのパラメータをアクティブにする必要があります。

"xml-declaration"

true

[必須] (デフォルト) Document、Element、または Entity ノードが直列化される場合は、XML 宣言またはテキスト宣言を含めるようにしてください。バージョン (文書がレベル 3 文書であり、バージョンが null 以外の場合は Document.xmlVersion、それ以外の場合は値「1.0」を使用する) および出力エンコーディング (出力エンコーディングを検索する方法の詳細は、LSSerializer.write を参照) は、直列化された XML 宣言で指定されます。

false

[必須] XML 宣言およびテキスト宣言を直列化しません。これにより問題が発生する (つまり、直列化されたデータの XML バージョンが「XML 1.0」以外であるか、または直列化されたデータを再解析できるようにするにはエンコーディングが必要になる) 場合は、"xml-declaration-needed" 警告を報告します。

getNewLine

String getNewLine()

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

setNewLine

void setNewLine(String newLine)

書き出されている XML で使用される行末シーケンス文字です。任意の文字列がサポートされますが、XML では文字シーケンスの特定のセットだけを行末として扱います (直列化されたコンテンツが XML 1.0 の場合は「XML 1.0」のセクション 2.11、「End-of-Line Handling」を参照。直列化されたコンテンツが XML 1.1 の場合は「XML 1.1」のセクション 2.11、「End-of-Line Handling」を参照)。推奨されていない文字シーケンスを使用すると、文書が直列化不可になったり、整形式にならなくなったりします。
取得時、この属性のデフォルト値は、実装固有のデフォルト行末シーケンスです。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 に書き込まれます。使用されるエンコーディングは、DOMString 型のエンコーディング、つまり UTF-16 です。DOMString オブジェクトでは、バイト順序記号が生成されません。

パラメータ:

nodeArg - 直列化するノード。

戻り値:

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

例外:

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

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