|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
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()
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 が呼び出されたかのように機能する簡易メソッドです。 |
| メソッドの詳細 |
|---|
DOMConfiguration getDomConfig()
LSSerializer が使用する DOMConfiguration オブジェクト。LSSerializer の DOMConfiguration オブジェクトは次のパラメータを追加または変更します。
"canonical-form"truetrue に設定すると、「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"trueAttr.specified 属性を使用して、どの属性を破棄するかを決定します。このパラメータが true に設定されている場合、実装によっては、破棄する属性とコンテンツを決定する際に、実装で使用可能なあらゆる情報 (XML スキーマ、DTD、Attr.specified 属性など) を使用する可能性があります。 false"format-pretty-print"truefalse"ignore-unknown-character-denormalizations" trueunknown-character-denormalization」警告 (このパラメータが設定されていない場合は警告ではなくエラー) を出して、これらの文字によって生じる可能性がある不完全な正規化を無視します。 false"normalize-characters"DOMConfiguration で定義されているパラメータと同等です。コアとは異なり、このパラメータのデフォルト値は true です。DOM 実装では「XML 1.1」の「付録 E」に従って文書に含まれる文字の完全な正規化をサポートする必要はありませんが、サポートする場合は、デフォルトでこのパラメータを有効にする必要があります。 "xml-declaration"trueDocument ノード、Element ノード、または Entity ノードが直列化されている場合は、XML 宣言またはテキスト宣言を含める必要があります。バージョン (文書が Level 3 文書であり、バージョンが null でない場合は Document.xmlVersion、それ以外の場合は値「1.0」) および出力エンコーディング (出力エンコーディングの見分け方については LSSerializer.write を参照) は、直列化された XML 宣言で指定されます。 falsexml-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.encoding
Document.inputEncoding
Document.xmlEncoding
LSOutput で指定されていない場合は、致命的なエラーの「no-output-specified」が返されます。
nodeArg - 直列化するノードdestination - 直列化された DOM の宛先
node が正常に直列化された場合は true。通常の処理は停止したが、実装がドキュメントの直列化を引き続き実行している場合は false。 この場合、直列化の結果は実装に依存する
LSException - SERIALIZE_ERR:LSSerializer がノードを直列化できなかった場合に発生する。DOM エラーに関する詳細を取得する場合、 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 エラーに関する詳細を取得する場合、 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 エラーに関する詳細を取得する場合、 DOM アプリケーションは「error-handler」パラメータを使用して DOMErrorHandler を接続する必要がある
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。