共通 DOM API

org.w3c.dom.ls
インタフェース LSSerializer


public interface LSSerializer

LSSerializer は、DOM ドキュメントを XML の中に直列化する (書き込む) ための API を提供します。XML データは文字列または出力ストリームに書き込まれます。直列化の間に行われる変更または修正は、直列化されたデータだけに影響を与えます。Document オブジェクトとその子は、直列化操作によって変更されることはありません。

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

LSSerializer は、直列化で任意のノード型を受け入れます。Document 型または Entity 型のノードでは、可能な場合、整形式の XML が生成されます (ドキュメントまたは実体が解析操作から得られ、作成後に変更されていない場合、整形式であることが保証される)。これらのノード型の直列化された出力は、それぞれ XML ドキュメントまたは外部 XML 実体として出力され、XML パーサの入力として受け入れ可能です。ほかのすべてのノード型の場合、直列化された形式は実装に依存します。

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

注: Node の直列化では、必ずしも常に整形式の XML ドキュメントが生成されるわけではありません。すなわち、LSParser が結果の直列化を解析するときに致命的エラーをスローする可能性があります。

ドキュメントの文字データ (マークアップの外部) 内では、直接表すことができない文字は文字参照に置換されます。< と & が存在すると、あらかじめ定義された実体の &lt; と &amp; に置き換えられます。その他のあらかじめ定義された実体 (&gt;、&apos;、および &quot;) は必要な場合 (]]> に &gt; を使用するなど) を除き使用されません。出力文字エンコーディングで直接表すことができない文字は、数値文字参照として直列化されます。また、文字エンコーディング標準は一般に文字の 16 進数表現を使用するので、文字参照を直列化するときは 16 進数表現を使用することをお勧めします。

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

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

LSSerializernormalize-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.domConfigerror-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)
          LSSerializer.write が、エンコーディングが指定されておらず、LSOutput.systemIduri 引数に設定されている LSOutput を使って呼び出された場合のように機能する簡易メソッドです。
 

メソッドの詳細

getDomConfig

DOMConfiguration getDomConfig()
DOM ノードの直列化中に LSSerializer が使用する DOMConfiguration オブジェクト。
[DOM Level 3 Core] で定義済みの DOMConfiguration インタフェースで認識されるパラメータに加えて、LSSerializerDOMConfiguration オブジェクトは次のパラメータを追加または変更します。
"canonical-form"
true
[オプション] [Canonical 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 により定義されているパラメータと同等です。Core の場合とは異なり、このパラメータのデフォルト値は true です。DOM 実装は [XML 1.1] の付録 E に従ってドキュメントの文字を完全に正規化された処理をサポートする必要はありませんが、サポートされている場合、このパラメータはデフォルトで起動されていなければなりません。
"xml-declaration"
true
[必須] (デフォルト) DocumentElement、または Entity ノードを直列化する場合、XML 宣言またはテキスト宣言を含める必要があります。バージョン (ドキュメントが Level 3 ドキュメントであり、バージョンが null 以外の場合は Document.xmlVersion、そうでない場合は値 1.0 を使用)、および出力エンコーディング (出力エンコーディングを確認する方法については、LSSerializer.write を参照) は直列化された XML 宣言で指定されます。
false
[必須] XML 宣言とテキスト宣言を直列化しません。これにより問題が発生する場合 (つまり、直列化されたデータが[XML 1.0] 以外の XML バージョンのデータである、またはエンコーディングが直列化されたデータを再解析できる必要がある場合)、「xml-declaration-needed」警告を報告します。


getNewLine

String getNewLine()
書き出し中の XML で使用される行末の文字シーケンス。任意の文字列がサポートされますが、XML は特定の文字シーケンスのセットだけを行末として処理します。直列化された内容が XML 1.0 の場合は、[XML 1.0] の 2.1.1 項の「End-of-Line Handling」を参照し、直列化された内容が XML 1.1 の場合は、[XML 1.1] の 2.1.1 項の「End-of-Line Handling」を参照してください。推奨されている文字シーケンス以外の文字シーケンスを使用すると、直列化されていないまたは整形式ではないドキュメントが生成される可能性があります。
取得時、この属性のデフォルト値は実装固有のデフォルトの行末シーケンスです。DOM 実装は、デフォルト値を選択して、使用されている環境のテキストファイルの表記規則に合わせる必要があります。実装は、直列化された内容に応じて、XML 1.0 または XML 1.1 で許可されているシーケンスのどれかに一致するデフォルトのシーケンスを選択しなければなりません。この属性を null に設定すると、値はデフォルト値にリセットされます。


setNewLine

void setNewLine(String newLine)
書き出し中の XML で使用される行末の文字シーケンス。任意の文字列がサポートされますが、XML は特定の文字シーケンスのセットだけを行末として処理します。直列化された内容が XML 1.0 の場合は、[XML 1.0] の 2.1.1 項の「End-of-Line Handling」を参照し、直列化された内容が XML 1.1 の場合は、[XML 1.1] の 2.1.1 項の「End-of-Line Handling」を参照してください。推奨されている文字シーケンス以外の文字シーケンスを使用すると、直列化されていないまたは整形式ではないドキュメントが生成される可能性があります。
取得時、この属性のデフォルト値は実装固有のデフォルトの行末シーケンスです。DOM 実装は、デフォルト値を選択して、使用されている環境のテキストファイルの表記規則に合わせる必要があります。実装は、直列化された内容に応じて、XML 1.0 または XML 1.1 で許可されているシーケンスのどれかに一致するデフォルトのシーケンスを選択しなければなりません。この属性を null に設定すると、値はデフォルト値にリセットされます。


getFilter

LSSerializerFilter getFilter()
アプリケーションがフィルタを提供する場合、シリアライザは各ノードを直列化する前にフィルタを呼び出します。フィルタの実装では、ストリームからノードを削除したり、直列化を早期に終了したりすることを選択できます。
フィルタは、DOMConfiguration パラメータが要求した操作が適用されたあとに呼び出されます。たとえば、cdata-sectionsfalse に設定すると、CDATA セクションはフィルタに渡されません。


setFilter

void setFilter(LSSerializerFilter filter)
アプリケーションがフィルタを提供する場合、シリアライザは各ノードを直列化する前にフィルタを呼び出します。フィルタの実装では、ストリームからノードを削除したり、直列化を早期に終了したりすることを選択できます。
フィルタは、DOMConfiguration パラメータが要求した操作が適用されたあとに呼び出されます。たとえば、cdata-sectionsfalse に設定すると、CDATA セクションはフィルタに渡されません。


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
LSSerializer.write が、エンコーディングが指定されておらず、LSOutput.systemIduri 引数に設定されている LSOutput を使って呼び出された場合のように機能する簡易メソッドです。

パラメータ:
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 に接続する必要がある

共通 DOM API

バグや機能要求の報告
Java は、米国およびその他の国における米国 Sun Microsystems, Inc. の商標もしくは登録商標です。
Copyright 2004 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.