モジュール java.xml
パッケージ 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として空の文字列が許可されます。 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によって致命的エラーがスローされる可能性があります。

    文書(マークアップの範囲外)の文字データ内では、直接表すことができないすべての文字は、文字参照に置き換えられます。 「<」や「&」が現れると、事前定義済エンティティである&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.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 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.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,
                     LSException
        LSSerializerインタフェースの一般的な説明で、前述のように指定されたノードを直列化します。 出力は、呼出し側に返されるDOMStringに書き込まれます。 使用されるエンコーディングは、DOMString型のエンコーディング、つまりUTF-16です。 DOMStringオブジェクトでは、バイト順序記号が生成されません。
        パラメータ:
        nodeArg - 直列化するノード。
        戻り値:
        直列化されたデータを返す。
        例外:
        DOMException - DOMSTRING_SIZE_ERR: 結果の文字列が長すぎてDOMString内に収まらない場合に発生します。
        LSException - SERIALIZE_ERR: LSSerializerがノードを直列化できなかった場合に発生します。 DOMアプリケーションは、エラーの詳細を取得する場合は、パラメータerror-handlerを使用してDOMErrorHandlerを添付する必要があります。