public interface LSSerializer
LSSerializer
は、DOM文書をXMLに直列化する(書き込む)ためのAPIを提供します。 XMLデータは文字列または出力ストリームに書き込まれます。 直列化を実行する間にどのような変更や修正が行われても、影響があるのは直列化されたデータだけです。 Document
オブジェクトとその子が直列化操作によって変更されることはありません。
「DOM Level 3 Core」、付録Bで定義されているように、XMLデータの直列化中に名前空間修正が行われます。「DOM Level 2 Core」では、実際の名前空間URIとして空の文字列が許可されます。 Node
のnamespaceURI
が空の文字列である場合、直列化ではそれをnull
として処理し、接頭辞(存在する場合)を無視します。
LSSerializer
は、直列化のために任意のノード型を受け入れます。 Document
またはEntity
型のノードの場合は、可能であれば整形式のXMLが作成されます(文書またはエンティティが解析操作から得られ、作成されてから変更されていない場合は整形式が保証されます)。 これらのノード型の直列化出力は、それぞれXML文書または外部XMLエンティティとして出力され、XMLパーサーの受け入れ可能な入力となります。 ほかのすべてのノード型の直列化された形式は、実装によって決まります。
直列化されるDocument
、DocumentFragment
、またはEntity
内では、Nodes
は次のように処理されます。
- XML宣言(「xml-declaration」パラメータが
false
に設定されてないかぎり)とDTDサブセット(DOM内に存在する場合)を含め、Document
ノードが書き込まれます。Document
ノードを書き込むと、文書全体が直列化されます。 -
LSSerializer.write
によって直接書き込まれた場合、Entity
ノードはエンティティ拡張を出力しますが、名前空間修正は行われません。 結果として得られる出力は外部エンティティとして有効になります。 - パラメータ"entitiesが"
true
に設定されている場合、EntityReference
ノードは、出力のフォーム"&entityName;
"のエンティティ参照として直列化されます。 エンティティ参照の子ノード(展開)は無視されます。 パラメータ "entities"がfalse
に設定されている場合、エンティティ参照の子のみが直列化されます。 子を持たないEntityReference
ノード(対応するEntity
ノードがないか、または対応するEntity
ノードに子がない場合)は、常に直列化されます。 -
指定された出力エンコーディングで表現できないコンテンツ文字を含む
CDATAsections
は、 "split-cdata-sections"パラメータに従って処理されます。 このパラメータがtrue
に設定されている場合は、CDATAsections
が分割され、表現できない文字は通常のコンテンツ内の数値文字参照として直列化されます。 正確な位置と分割数は指定されません。 パラメータがfalse
に設定されている場合、パラメータwell-formedがtrue
に設定されている場合、CDATAsection
の表現できない文字が"wf-invalid-character"
エラーとして報告されます。 代替文字が提供されず、直列化が続行されるのでエラーは回復できません。 -
DocumentFragment
ノードは、文書フラグメントの子を文書フラグメント内に現れる順序で直列化することによって直列化されます。 - ほかのすべてのノード型(Element、Textなど)は、対応するXMLソース形式に直列化されます。
注: 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)で、バイト順序記号は生成されません。 いずれの場合も、エンコーディング宣言(生成される場合)は直列化中に使用されるエンコーディングに対応します(たとえば、UTF-16が要求された場合はencoding="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」も参照してください。
- 導入されたバージョン:
- 1.5
-
メソッドのサマリー
修飾子と型 メソッド 説明 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
が呼び出されたかのように機能する簡易メソッドです。
-
メソッドの詳細
-
getDomConfig
DOMConfiguration getDomConfig()DOMノードの直列化中にLSSerializer
が使用するDOMConfiguration
オブジェクト。LSSerializer
のDOMConfiguration
オブジェクトは、[DOM Level 3 Core]で定義されたDOMConfigurationインタフェースで認識されるパラメータに加えて、次のパラメータを追加または変更します:"canonical-form"
-
true
- [オプション]「正規XML」で指定されている規則に従って文書を書き込みます。 canonical-form "[DOM Level 3 Core]に記述されている動作に加え、このパラメータを
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
で定義されているパラメータと同等です。 コアの場合とは異なり、このパラメータのデフォルト値はtrue
です。 DOM実装では、「XML 1.1」の付録Eに従って文書内の文字の完全な正規化をサポートする必要はありませんが、サポートする場合は、デフォルトでこのパラメータをアクティブにする必要があります。 -
"xml-declaration"
-
true
- [必須] (デフォルト)
Document
、Element
、またはEntity
ノードが直列化される場合は、XML宣言またはテキスト宣言を含めるようにしてください。 バージョン(文書がレベル3文書であり、バージョンがnull以外の場合はDocument.xmlVersion
、それ以外の場合は値「1.0」を使用する)および出力エンコーディング(出力エンコーディングを検索する方法の詳細は、LSSerializer.write
を参照)は、直列化されたXML宣言で指定されます。 -
false
- [必須] XML宣言およびテキスト宣言を直列化しません。 これにより問題が発生する(つまり、直列化されたデータのXMLバージョンが「XML 1.0」以外であるか、または直列化されたデータを再解析できるようにするにはエンコーディングが必要になる)場合は、
"xml-declaration-needed"
警告を報告します。
-
getNewLine
String getNewLine()書き出されているXMLで使用される行末シーケンス文字です。 任意の文字列がサポートされますが、XMLでは文字シーケンスの特定のセットのみを行末として扱います(直列化されたコンテンツがXML 1.0の場合は「XML 1.0」のセクション2.11、「End-of-Line Handling」を参照。直列化されたコンテンツがXML 1.1の場合は「XML 1.1」のセクション2.11、「End-of-Line Handling」を参照)。 推奨されていない文字シーケンスを使用すると、文書が直列化不可になったり、整形式にならなくなったりします。
取得時、この属性のデフォルト値は、実装固有のデフォルト行末シーケンスです。 DOM実装では、デフォルトの行末シーケンスを選択して、使用している環境のテキスト・ファイルの通常の規則に合わせる必要があります。 直列化されたコンテンツによっては、実装で、XML 1.0またはXML 1.1によって許可されている行末シーケンスの1つに一致するデフォルトのシーケンスを選択する必要があります。 この属性をnull
に設定すると、その値はデフォルト値にリセットされます。
-
setNewLine
void setNewLine(String newLine)書き出されているXMLで使用される行末シーケンス文字です。 任意の文字列がサポートされますが、XMLでは文字シーケンスの特定のセットのみを行末として扱います(直列化されたコンテンツがXML 1.0の場合は「XML 1.0」のセクション2.11、「End-of-Line Handling」を参照。直列化されたコンテンツがXML 1.1の場合は「XML 1.1」のセクション2.11、「End-of-Line Handling」を参照)。 推奨されていない文字シーケンスを使用すると、文書が直列化不可になったり、整形式にならなくなったりします。
取得時、この属性のデフォルト値は、実装固有のデフォルト行末シーケンスです。 DOM実装では、デフォルトの行末シーケンスを選択して、使用している環境のテキスト・ファイルの通常の規則に合わせる必要があります。 直列化されたコンテンツによっては、実装で、XML 1.0またはXML 1.1によって許可されている行末シーケンスの1つに一致するデフォルトのシーケンスを選択する必要があります。 この属性をnull
に設定すると、その値はデフォルト値にリセットされます。
-
getFilter
LSSerializerFilter getFilter()アプリケーションでフィルタが用意されていると、直列化処理は各ノードを直列化する前にフィルタを呼び出します。 フィルタの実装では、ストリームからノードを削除したり、早期に直列化を終了するなどの選択ができます。
フィルタは、DOMConfiguration
パラメータにより要求された操作が適用されたあとに呼び出されます。 たとえば、 "cdata-sections"がfalse
に設定されている場合、CDATAセクションはフィルタに渡されません。 -
setFilter
void setFilter(LSSerializerFilter filter)アプリケーションでフィルタが用意されていると、直列化処理は各ノードを直列化する前にフィルタを呼び出します。 フィルタの実装では、ストリームからノードを削除したり、早期に直列化を終了するなどの選択ができます。
フィルタは、DOMConfiguration
パラメータにより要求された操作が適用されたあとに呼び出されます。 たとえば、 "cdata-sections"がfalse
に設定されている場合、CDATAセクションはフィルタに渡されません。 -
write
boolean write(Node nodeArg, LSOutput destination) throws LSExceptionLSSerializer
インタフェースの一般的な説明で、前述のように指定されたノードを直列化します。 出力は、指定されたLSOutput
に書き込まれます。
LSOutput
への書込み時、エンコーディングは、LSOutput
および書き込まれる項目(または、その所有者文書)を通して到達できるエンコーディング情報を次の順序で検索することによって見つけられます。-
LSOutput.encoding
, -
Document.inputEncoding
, -
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.systemId
をuri
引数に設定して、LSOutput
でLSSerializer.write
が呼び出されたかのように機能する簡易メソッドです。- パラメータ:
nodeArg
- 直列化するノード。uri
- 書込み先のURI。- 戻り値:
node
が正常に直列化された場合はtrue
を返します。 通常の処理は停止したが、実装が文書の直列化を引き続き実行している場合はfalse
を返します。この場合、直列化の結果は実装に依存します。- 例外:
LSException
- SERIALIZE_ERR:LSSerializer
がノードを直列化できなかった場合に発生します。 DOMアプリケーションは、エラーの詳細を取得する場合は、パラメータerror-handlerを使用してDOMErrorHandler
を添付する必要があります。
-
writeToString
String writeToString(Node nodeArg) throws DOMException, LSExceptionLSSerializer
インタフェースの一般的な説明で、前述のように指定されたノードを直列化します。 出力は、呼出し側に返されるDOMString
に書き込まれます。 使用されるエンコーディングは、DOMString
型のエンコーディング、つまりUTF-16です。DOMString
オブジェクトでは、バイト順序記号が生成されません。- パラメータ:
nodeArg
- 直列化するノード。- 戻り値:
- 直列化されたデータを返す。
- 例外:
DOMException
- DOMSTRING_SIZE_ERR: 結果の文字列が長すぎてDOMString
内に収まらない場合に発生します。LSException
- SERIALIZE_ERR:LSSerializer
がノードを直列化できなかった場合に発生します。 DOMアプリケーションは、エラーの詳細を取得する場合は、パラメータerror-handlerを使用してDOMErrorHandler
を添付する必要があります。
-