共通 DOM API

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

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

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

注: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) で、バイト順序記号は生成されません。どのケースも、エンコーディング宣言 (生成される場合) は、直列化の間に使用されるエンコーディングに対応します (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()
          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.systemIduri 引数に設定して、LSOutputLSSerializer.write が呼び出されたかのように機能する簡易メソッドです。
 

メソッドの詳細

getDomConfig

DOMConfiguration getDomConfig()
DOM ノードの直列化中に LSSerializer が使用する DOMConfiguration オブジェクト。
「DOM Level 3 Core」で定義された DOMConfiguration インタフェースによって認識されるパラメータに加えて、LSSerializerDOMConfiguration オブジェクトは次のパラメータを追加または変更します。
"canonical-form"
true
[オプション] 「正規 XML」で指定されている規則に従って文書に書き込みます。このパラメータを true に設定すると、「DOM Level 3 Core」「canonical-form」に記述されている動作に加えて、「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 宣言またはテキスト宣言を含める必要があります。バージョン (文書が 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」の「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 エラーに関する詳細を取得する場合、 DOM アプリケーションは「error-handler」パラメータを使用して DOMErrorHandler を接続する必要がある

writeToURI

boolean writeToURI(Node nodeArg,
                   String uri)
                   throws LSException
エンコーディングを指定せず、LSOutput.systemIduri 引数に設定して、LSOutputLSSerializer.write が呼び出されたかのように機能する簡易メソッドです。

パラメータ:
nodeArg - 直列化するノード
uri - 書き込み先の URI
戻り値:
node が正常に直列化された場合は true。通常の処理は停止されたものの、 実装が文書を直列化し続けた場合は false。そのあとの直列化の結果は 実装によって異なる
例外:
LSException - SERIALIZE_ERR:LSSerializer がノードを直列化 できなかった場合。DOM エラーに関する詳細を取得する場合、 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 エラーに関する詳細を取得する場合、 DOM アプリケーションは「error-handler」パラメータを使用して DOMErrorHandler を接続する必要がある

共通 DOM API

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