モジュール java.xml
パッケージ org.xml.sax

インタフェースContentHandler

  • 既知のすべてのサブインタフェース:
    TemplatesHandler, TransformerHandler
    既知のすべての実装クラス:
    DefaultHandler, DefaultHandler2, ValidatorHandler, XMLFilterImpl, XMLReaderAdapter
    public interface ContentHandler
    文書の論理コンテンツの通知を受け取ります。
    このモジュールは、ソース・コード、文書ともに公開ドメインに置かれています。したがって、内容に関する保証は一切提供されません。 詳細については、http://www.saxproject.orgを参照してください。

    ほとんどのSAXアプリケーションが、このインタフェースを実装しています。標準の構文解析イベントの通知を受ける必要がある場合、アプリケーションはこのインタフェースを実装し、setContentHandlerメソッドを使用してインスタンスをSAXパーサーに登録します。 パーサーはこのインスタンスを使用して、要素や文字データの開始、終了といった標準の文書関連イベントを報告します。

    このインタフェース内のイベントの順序は、文書自体に含まれる情報の順序をミラー化したものであり、非常に重要です。 たとえば、ある要素の全コンテンツ(文字データ、処理命令、サブ要素など)は、startElementイベントとこれに対応するendElementイベントの間に順番に並べられます。

    このインタフェースは、現在では非推奨に指定されているSAX 1.0のDocumentHandlerインタフェースと似ていますが、新たに名前空間のサポートと、妥当性を検証しないXMLプロセッサでスキップされたエンティティの報告のサポートが追加されています。

    実装者は、java.netパッケージにContentHandlerクラスが含まれている点を考慮して、次のような処理は避けてください

    import java.net.*;
 import org.xml.sax.*;

    通常、「import...*」を使用したプログラムは、ずさんな(sloppy)プログラムと見なされます。ユーザーは、バグよりもこの点に注意を払う必要があります。

    導入されたバージョン:
    1.4, SAX 2.0
    関連項目:
    XMLReader, DTDHandler, ErrorHandler

    • メソッドの詳細

      • setDocumentLocator

        void setDocumentLocator​(Locator locator)
        SAX文書イベントの発生元を特定するオブジェクトを受け取ります。

        ロケータが必要な場合は、必須条件ではありませんが、SAXパーサーを使用することを強くお勧めします。SAXパーサーは、ContentHandlerインタフェース内のどのメソッドよりも先にこのメソッドを呼び出し、アプリケーションにロケータを提供します。

        アプリケーションは、ロケータを利用して、パーサーがエラーを報告しない場合でも文書関連イベントの終了位置を特定できます。 通常、アプリケーションはこの情報を使って固有のエラー(文字コンテンツがアプリケーションの機能規則に沿っていないなど)を報告します。 一般に、ロケータから返される情報は不十分であり、検索エンジンでの使用に適していません。

        ロケータは、startDocumentが戻ったあと、endDocumentが呼び出される前の呼び出しSAXイベント・コールバック中にかぎり適正な情報を返します。 それ以外のとき、アプリケーションでロケータの情報を利用するべきではありません。

        パラメータ:
        locator - SAX文書イベントの位置を返すオブジェクト
        関連項目:
        Locator

      • startDocument

        void startDocument()
            throws SAXException
        文書の開始通知を受け取ります。

        SAXパーサーは、ほかのイベントがコールバックされる前に1回だけこのメソッドを呼び出します(setDocumentLocator以外)。

        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある
        関連項目:
        endDocument()

      • endDocument

        void endDocument()
          throws SAXException
        文書の終了通知を受け取ります。

        このメソッドのマニュアルとErrorHandler.fatalError(org.xml.sax.SAXParseException)のマニュアルとの間には明らかに矛盾があります。 クライアントは、今後のメジャー・リリースでこのあいまいさが解決されないかぎり、パーサーがfatalError()を報告したり例外をスローしたときにendDocument()が呼び出されるかどうかを仮定しないようにする必要があります。

        SAXパーサーは、このメソッドを構文解析の最後に1回だけ呼び出します。 回復不可能なエラーによって構文解析が途中で破棄されるか、入力が終了するまで、このメソッドは呼び出されません。

        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある
        関連項目:
        startDocument()

      • startPrefixMapping

        void startPrefixMapping​(String prefix,
                        String uri)
                 throws SAXException
        前置修飾子とURI名前空間マッピングのスコープを開始します。

        通常の名前空間処理はイベントから提供される情報を必要としません。SAXのXMLリーダーは、http: //xml.org/sax/features/namespaces機能がtrue (デフォルト)に設定されていると、要素および属性名の接頭辞を自動的に置き換えます。

        しかし、アプリケーションによって文字データや属性値の中で使用される場合、接頭辞を安全に展開できません。こうしたアプリケーションには、必要に応じて、start/endPrefixMappingイベントにより、接頭辞をアプリケーション・コンテキスト内で拡張するために必要な情報が提供されます。

        start/endPrefixMappingイベントがそれぞれ正しくネストされるかどうかは保証されません。すべてのstartPrefixMappingイベントは対応するstartElementイベントの直前に発生し、すべてのendPrefixMappingイベントは対応するendElementイベントの直後に発生しますが、それ以外にイベントの順番は保証されていません。

        「xml」接頭辞は事前に宣言される不変の修飾子なので、そのstart/endPrefixMappingイベントは存在しません。

        パラメータ:
        prefix - 宣言される名前空間接頭辞。 デフォルトによる要素の名前空間に使用する空文字列(接頭辞なし)。
        uri - 接頭辞のマップ先の名前空間URI
        例外:
        SAXException - 処理中にクライアントが例外をスローすることがある
        関連項目:
        endPrefixMapping(java.lang.String), startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

      • startElement

        void startElement​(String uri,
                  String localName,
                  String qName,
                  Attributes atts)
           throws SAXException
        要素の開始通知を受け取ります。

        パーサーはXML文書内の各要素の前でこのメソッドを呼び出します。各startElementイベントには対応するendElementイベントがあります。これは、要素が空である場合も変わりません。 対応するendElementイベントの前に、要素のコンテンツ全部が順番に報告されます。

        このイベントでは、各要素に最大3つの名前コンポーネントを許可します。

        1. 名前空間URI
        2. ローカル名
        3. 前置修飾子付きの修飾名。

        http://xml.org/sax/features/namespacesプロパティおよびhttp://xml.org/sax/features/namespace-prefixesプロパティの値により、これらのいずれか、または全部が提供されます。

        • 名前空間URIとローカル名は、namespacesプロパティがtrue (デフォルト)である場合は必須。namespacesプロパティがfalseである場合はオプション(一方が指定されていれば両方が必要)。
        • 修飾名は、namespace-prefixesプロパティがtrueである場合は必須。namespace-prefixesプロパティがfalse (デフォルト)である場合はオプション。

        提供される属性リストには、明示的な値(指定された値またはデフォルト値)を持つ属性のみが含まれます。#IMPLIED属性は含まれません。 この属性リストには、http://xml.org/sax/features/namespace-prefixesプロパティがtrue (デフォルトの設定はfalse。trueのサポートはオプション)である場合にかぎり、名前空間宣言(xmlns*属性)に使用される属性が含まれます。

        属性値は、characters()のように2つ以上のchar値を必要とする文字を持つ場合があります。

        パラメータ:
        uri - 名前空間URI。要素が名前空間URIを持たない場合、または名前空間処理が行われない場合は空文字列
        localName - 接頭辞なしのローカル名。名前空間処理が行われない場合は空文字列
        qName - 接頭辞付きの修飾名。修飾名を使用できない場合は空文字列
        atts - 要素に付加された属性。 属性が存在しない場合、空のAttributesオブジェクト。 startElementが返されたあとのこのオブジェクトの値は定義されない
        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある
        関連項目:
        endElement(java.lang.String, java.lang.String, java.lang.String), Attributes, AttributesImpl

      • endElement

        void endElement​(String uri,
                String localName,
                String qName)
         throws SAXException
        要素の終了通知を受け取ります。

        SAXパーサーは、XML文書内の各要素の終わりにこのメソッドを呼び出します。各endElementイベントには対応するstartElementイベントがあります。これは、要素が空である場合も変わりません。

        名前については、startElementを参照してください。

        パラメータ:
        uri - 名前空間URI。要素が名前空間URIを持たない場合、または名前空間処理が行われない場合は空文字列
        localName - 接頭辞なしのローカル名。名前空間処理が行われない場合は空文字列
        qName - 接頭辞付きのXML修飾名。修飾名を使用できない場合は空文字列
        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある

      • characters

        void characters​(char[] ch,
                int start,
                int length)
         throws SAXException
        文字データの通知を受け取ります。

        パーサーは、このメソッドを呼び出して、各文字データ・チャンクを報告します。 SAXパーサーは、連続する文字データを単一のチャンクとして、またはいくつかのチャンクに分割して返します。ただし、ロケータから有益な情報を得るためには、単一のイベントに含まれる文字がすべて同じ外部エンティティのものでなければいけません。

        アプリケーションは、指定された範囲外の配列を読み取ることはできません。

        個々の文字は2つ以上のJava char値で構成される場合があります。 文字列を16ビット以内で表示することはできないため、2つの重要なケースが発生します。 1つは、文字が2つの特殊Unicode値を使用してサロゲート・ペアで表されることです。 このような文字列は「Astral Planes」と呼ばれ、U+FFFFより大きいコード・ポイントを持ちます。 もう1つは、1つ以上のアクセント文字に結合しているベース文字列などの合成文字列になることです。

        char-at-a-time慣用法を使用するアルゴリズムは文字を分割する場合もあるので、文字単位で処理していると想定してはいけません。 これは、XMLが属性値、処理命令データ、コメントなどの任意の文字列や、このメソッドから報告されたデータ内にある任意の文字列を許可する場所に関連します。 また、一般的にはJavaコードが国際化されたテキストを操作する場所に関連しますが、発行はXMLに一意のものではありません。

        一部のパーサーは、このメソッドではなくignorableWhitespaceメソッドを使用して、要素コンテンツに含まれる空白文字を報告します。これは、妥当性を検証するパーサーに必須の機能です。

        パラメータ:
        ch - XML文書の文字
        start - 配列内の開始位置
        length - 配列から読み取られる文字数
        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある
        関連項目:
        ignorableWhitespace(char[], int, int), Locator

      • ignorableWhitespace

        void ignorableWhitespace​(char[] ch,
                         int start,
                         int length)
                  throws SAXException
        要素コンテンツに含まれる無視できる空白文字の通知を受け取ります。

        妥当性を検証するパーサーは、このメソッドを使用して、要素コンテンツに含まれる空白文字のチャンクを報告する必要があります(W3C XML 1.0勧告セクション2.10を参照)。妥当性を検査しないパーサーも、コンテンツ・モデルの構文解析および利用が可能である場合は、このメソッドを使用する場合があります。

        SAXパーサーは、連続するすべての空白文字を単一のチャンクとして、または複数のチャンクに分割して返します。ただし、ロケータから有益な情報を得るためには、単一のイベントに含まれる文字がすべて同じ外部エンティティのものである必要があります。

        アプリケーションは、指定された範囲外の配列を読み取ることはできません。

        パラメータ:
        ch - XML文書の文字
        start - 配列内の開始位置
        length - 配列から読み取られる文字数
        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある
        関連項目:
        characters(char[], int, int)

      • processingInstruction

        void processingInstruction​(String target,
                           String data)
                    throws SAXException
        処理命令の通知を受け取ります。

        パーサーは、処理命令を検出するたびに1回ずつこのメソッドを呼び出します。処理命令は、メインの文書要素の前後に存在する可能性があります。

        SAXパーサーが、このメソッドを使用してXML宣言を報告することはありません(XML 1.0、セクション2.8)。また、テキスト宣言を報告することもありません(XML 1.0、セクション4.3.1)。

        処理命令データは、characters()のように2つ以上のchar値を必要とする文字を持つ場合があります。

        パラメータ:
        target - 処理命令のターゲット
        data - 処理命令データ。データが提供されなかった場合はnull。 データには、ターゲットと自身を区別するための空白文字は含まれない
        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある

      • skippedEntity

        void skippedEntity​(String name)
            throws SAXException
        スキップされたエンティティの通知を受け取ります。 これは、要素開始タグやマークアップ宣言などのマークアップ構造内のエンティティ参照に対しては呼び出されません。 XML勧告ではスキップされた外部エンティティの報告が必要です。 また、SAXもマークアップ構造内を除く内部エンティティの拡張の有無を報告します。

        パーサーは、エンティティがスキップされるたびに1回ずつこのメソッドを呼び出します。 妥当性を検証しないプロセッサは、(エンティティが外部DTDサブセット内に定義されているなどの理由で)宣言が検出されないとエンティティをスキップします。 すべてのプロセッサは、http://xml.org/sax/features/external-general-entitiesプロパティとhttp://xml.org/sax/features/external-parameter-entitiesプロパティの値により、外部エンティティをスキップする可能性があります。

        パラメータ:
        name - スキップされたエンティティの名前。 パラメータ・エンティティの場合、この名前は「%」で始まる。外部DTDサブセットの場合は、文字列「[dtd]」となる
        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある