JavaTM 2 Platform
Standard Ed. 5.0

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()
           
 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 で定義されている規則に従って書き込みます。「canonical-form」「DOM Level 3 Core」で説明されている動作に加え、このパラメータを true に設定することによって「ormat-pretty-print」パラメータ、「discard-default-content」パラメータ、および「xml-declaration」パラメータが false に設定されます。それらのパラメータの 1 つを 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
「必須」(デフォルト) DocumentElement、あるいは Entity ノードを直列化する場合は、XML 宣言またはテキスト宣言を含める必要があります。バージョン (文書がレベル 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 エラーに関する詳細を取得する場合、アプリケーションは「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 エラーに関する詳細を取得する場合、アプリケーションは「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 を接続する必要がある

JavaTM 2 Platform
Standard Ed. 5.0

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java 2 SDK SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。