|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
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 は次のように処理されます。
false に設定されていない場合) と DTD サブセットを含めて (DOM に存在する場合)、Document ノードが書き込まれる。Document ノードを書き込むと文書全体が直列化されるLSSerializer.write により直接書き込まれた場合、Entity ノードは実体拡張を出力するが、名前空間修正は行われない。結果の出力は外部実体として有効になるtrue に設定される場合、EntityReference ノードは「&entityName;」出力形式の実体参照として直列化される。実体参照の子ノード (展開) は無視される。「entities」パラメータが false に設定される場合は、実体参照の子だけが直列化される。子を持たない EntityReference ノード (対応する Entity ノードがないか、対応する Entity ノードが子を持たない) は常に直列化されるCDATAsections は、「split-cdata-sections」パラメータに従って処理される。パラメータが true に設定されていると、CDATAsections が分割され、表示できない文字は通常のコンテンツの数値参照として直列化される。正確な位置と分割数は指定されない。パラメータが false に設定されていると、CDATAsection 内の表示できない文字は「well-formed」パラメータが true に設定されているときの「wf-invalid-character」エラーとして報告される。代替文字が提供されず、直列化が続行されるのでエラーは回復できないDocumentFragment ノードは、ドキュメントフラグメントに現れる順序でドキュメントフラグメントの子を直列化することで直列化される注: Node の直列化は、必ずしも整形式の XML 文書を生成しません。つまり、LSParser は結果の直列化を解析しているときに致命的なエラーをスローする可能性があります。
文書 (マークアップの範囲外) の文字データ内では、直接表すことができないすべての文字は、文字参照に置き換えられます。出現する「<」と「&」は事前定義実体の「<」と「&」に置き換えられます。他の事前定義実体 (「>」、「'」、および「"」) は、必要な場合を除き使用できない可能性があります (例、「]]>」に「>」を使用するなど)。出力文字エンコーディングで直接表すことができないすべての文字は、数値参照として直列化されます。文字エンコーディング標準では、一般に文字の 16 進表現を使用するので、文字参照を直列化するとき、16 進表現を使用することをお勧めします。
単一引用符と二重引用符の両方を含む属性値を使用できるようにするには、アポストロフィまたは単一引用符文字 (') は「'」で、二重引用符文字 (") は「"」でそれぞれ表現できます。出力文字エンコーディングの属性値で直接表せない改行文字や他の文字は、数値参照として直列化されます。
出力文字エンコーディングで表せない文字がマークアップ内に、しかし属性の外に出現すると、致命的なエラー 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] 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 が呼び出されたかのように機能する簡易メソッドです。 |
| メソッドの詳細 |
|---|
DOMConfiguration getDomConfig()
LSSerializer が使用するDOMConfiguration オブジェクトです。LSSerializer の DOMConfiguration オブジェクトは、次のパラメータを追加または変更します。"canonical-form"truetrue に設定することによって「ormat-pretty-print」パラメータ、「discard-default-content」パラメータ、および「xml-declaration」パラメータが false に設定されます。それらのパラメータの 1 つを true に設定すると、このパラメータは false に設定されます。「canonical-form」が true の場合、XML 1.1 文書を直列化すると致命的なエラーが生成されます。 false"discard-default-content"trueAttr.specified 属性を使用して、どの属性を破棄する必要があるかを判定します。一部の実装では、このパラメータが true に設定されていると、実装で利用可能なあらゆる情報 (XML スキーマ、DTD、Attr.specified 属性など) を使用して、どの属性とコンテンツを破棄するかを判定する可能性があります。false"format-pretty-print"truefalse"ignore-unknown-character-denormalizations" true「unknown-character-denormalization」警告を出して、これらの文字で生じる可能性がある不完全な正規化を無視します。false"normalize-characters"DOMConfiguration で定義されているパラメータと同等です。コアのデフォルト値とは異なり、このパラメータのデフォルト値は true です。DOM 実装では、「XML 1.1」の付録 E に従って、文書に含まれる文字の完全な正規化をサポートする必要はありません。ただし、サポートされている場合は、デフォルトでこのパラメータを有効にする必要があります。 "xml-declaration"trueDocument、Element、あるいは Entity ノードを直列化する場合は、XML 宣言またはテキスト宣言を含める必要があります。バージョン (文書がレベル 3 文書であり、バージョンが null 以外である場合は Document.xmlVersion、そうでない場合は値「1.0」を使用) と出力エンコーディング (出力エンコーディングを確認する方法の詳細については、LSSerializer.write を参照) は直列化された XML 宣言で指定されます。 false「xml-declaration-needed」警告を通知します。
String getNewLine()
null に設定すると、その値はデフォルト値にリセットされます。
void setNewLine(String newLine)
null に設定すると、その値はデフォルト値にリセットされます。
LSSerializerFilter getFilter()
DOMConfiguration パラメータにより、要求された操作のあとにフィルタが呼び出されます。たとえば、CDATA セクションは、「cdata-sections」が false に設定されるとフィルタに渡されません。
void setFilter(LSSerializerFilter filter)
DOMConfiguration パラメータにより、要求された操作のあとにフィルタが呼び出されます。たとえば、CDATA セクションは、「cdata-sections」が false に設定されるとフィルタに渡されません。
boolean write(Node nodeArg,
LSOutput destination)
throws LSException
LSSerializer インタフェースの一般的な説明で前述のように、指定されたノードを直列化します。出力は、指定した LSOutput に書き込まれます。 LSOutput への書き込み時、エンコーディングは、LSOutput や次の順に書き込まれるアイテム (またはアイテムの所有者文書) を通じてアクセス可能なエンコーディング情報を確認して見つけられます。LSOutput.encodingDocument.inputEncodingDocument.xmlEncodingLSOutput で指定されていない場合は、致命的なエラーの「no-output-specified」が返されます。
nodeArg - 直列化するノードdestination - 直列化された DOM の宛先
node が正常に直列化された場合は true。通常の処理は停止されたものの、実装が文書を直列化し続けた場合は false を返す。そのあとの直列化の結果は実装によって異なる
LSException - SERIALIZE_ERR: LSSerializer がノードを直列化できなかった場合。DOM エラーに関する詳細を取得する場合、アプリケーションは「error-handler」パラメータを使用して DOMErrorHandler を接続する必要がある
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 を接続する必要がある
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 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。