模块  java.xml
软件包  org.xml.sax

Interface ContentHandler

  • All Known Subinterfaces:
    TemplatesHandlerTransformerHandler
    所有已知实现类:
    DefaultHandlerDefaultHandler2ValidatorHandlerXMLFilterImplXMLReaderAdapter

    public interface ContentHandler
    接收文档逻辑内容的通知。
    This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

    这是大多数SAX应用程序实现的主要接口:如果需要通知应用程序基本解析事件,它会实现此接口并使用setContentHandler方法向SAX解析器注册实例。 解析器使用实例报告与文档相关的基本事件,如元素的开始和结束以及字符数据。

    此界面中的事件顺序非常重要,并且反映了文档本身中的信息顺序。 例如,元素的所有内容(字符数据,处理指令和/或子元素)将按顺序出现在startElement事件和相应的endElement事件之间。

    此接口类似于现已弃用的SAX 1.0 DocumentHandler接口,但它添加了对命名空间的支持以及报告跳过的实体(在非验证XML处理器中)。

    实施者应注意, java.net包中还有一个ContentHandler类; 这意味着这可能是一个坏主意

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

    实际上,“import ... *”通常是草率编程的标志,因此用户应该将此视为一个功能而不是错误。

    从以下版本开始:
    1.4,SAX 2.0
    另请参见:
    XMLReaderDTDHandlerErrorHandler
    • 方法详细信息

      • setDocumentLocator

        void setDocumentLocator​(Locator locator)
        接收用于查找SAX文档事件原点的对象。

        强烈建议SAX解析器(尽管不是绝对必需)提供定位器:如果它这样做,它必须通过在调用ContentHandler接口中的任何其他方法之前调用此方法来向应用程序提供定位器。

        定位器允许应用程序确定任何与文档相关的事件的结束位置,即使解析器没有报告错误。 通常,应用程序将使用此信息报告其自身的错误(例如与应用程序的业务规则不匹配的字符内容)。 定位器返回的信息可能不足以与搜索引擎一起使用。

        请注意,定位器将只后在调用SAX事件回调返回正确的信息startDocument回报和之前endDocument被调用。 应用程序不应尝试在任何其他时间使用它。

        参数
        locator - 可以返回任何SAX文档事件的位置的对象
        另请参见:
        Locator
      • startDocument

        void startDocument()            throws SAXException
        接收文档开头的通知。

        在任何其他事件回调之前,SAX解析器只会调用此方法一次( setDocumentLocator除外)。

        异常
        SAXException - 任何SAX异常,可能包装另一个异常
        另请参见:
        endDocument()
      • endDocument

        void endDocument()          throws SAXException
        接收文档结束的通知。

        该方法的文档与ErrorHandler.fatalError(org.xml.sax.SAXParseException)的文档之间存在明显的矛盾。 在将来的主要版本中解决这种歧义之前,客户端不应该假设当解析器报告fatalError()或抛出异常时是否将调用endDocument()。

        SAX解析器只会调用此方法一次,它将是解析期间调用的最后一个方法。 解析器在放弃解析(由于不可恢复的错误)或到达输入结束之前不应调用此方法。

        异常
        SAXException - 任何SAX异常,可能包含另一个异常
        另请参见:
        startDocument()
      • startPrefixMapping

        void startPrefixMapping​(String prefix,                        String uri)                 throws SAXException
        开始前缀-URI名称空间映射的范围。

        正常命名空间处理不需要此事件的信息:当http://xml.org/sax/features/namespaces功能为true (默认值)时,SAX XML阅读器将自动替换元素和属性名称的前缀。

        但是,有些情况下,应用程序需要在字符数据或属性值中使用前缀,而这些前缀无法安全地自动扩展; 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事件之前按顺序报告所有元素的内容。

        此事件最多允许每个元素使用三个名称组件:

        1. 名称空间URI;
        2. 当地名称;
        3. 合格(带前缀)名称。

        可以提供任何或所有这些,具体取决于http://xml.org/sax/features/namespaceshttp://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时,属性列表将包含用于名称空间声明(xmlns *属性)的属性(默认情况下为false,并且对true值的支持是可选的)。

        characters()一样,属性值可能包含需要多个char值的字符。

        参数
        uri - 名称空间URI,如果元素没有名称空间URI或者没有执行名称空间处理,则为空字符串
        localName - 本地名称(不带前缀),如果未执行名称空间处理,则为空字符串
        qName - 限定名称(带前缀),如果限定名称不可用,则为空字符串
        atts - 附加到元素的属性。 如果没有属性,则它应为空的Attributes对象。 startElement返回后此对象的值未定义
        异常
        SAXException - 任何SAX异常,可能包含另一个异常
        另请参见:
        endElement(java.lang.String, java.lang.String, java.lang.String)AttributesAttributesImpl
      • 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解析器可以在一个块中返回所有连续的字符数据,或者它们可以将它分成几个块; 但是,任何单个事件中的所有字符都必须来自同一个外部实体,以便Locator提供有用的信息。

        应用程序不得尝试从指定范围之外的数组中读取数据。

        单个字符可能包含多个Java char值。 发生这种情况有两个重要的情况,因为字符不能仅用16位表示。 在一种情况下,字符在代理对中表示,使用两个特殊的Unicode值。 这些字符位于所谓的“星体平面”中,代码点高于U + FFFF。 第二种情况涉及复合字符,例如与一个或多个重音字符组合的基本字符。

        您的代码不应该假设使用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解析器可以在一个块中返回所有连续的空格,或者它们可以将它分成几个块; 但是,任何单个事件中的所有字符都必须来自同一个外部实体,以便Locator提供有用的信息。

        应用程序不得尝试从指定范围之外的数组中读取数据。

        参数
        ch - XML文档中的字符
        start - 数组中的起始位置
        length - 从数组中读取的字符数
        异常
        SAXException - 任何SAX异常,可能包含另一个异常
        另请参见:
        characters(char[], int, int)
      • processingInstruction

        void processingInstruction​(String target,                           String data)                    throws SAXException
        接收处理指令的通知。

        对于发现的每个处理指令,解析器将调用此方法一次:请注意,处理指令可以在主文档元素之前或之后发生。

        SAX解析器绝不能使用此方法报告XML声明(XML 1.0,第2.8节)或文本声明(XML 1.0,第4.3.1节)。

        characters()类似 ,处理指令数据可能包含需要多个值的一个char

        参数
        target - 处理指令目标
        data - 处理指令数据,如果没有提供,则为null。 数据不包括将其与目标分开的任何空格
        异常
        SAXException - 任何SAX异常,可能包含另一个异常
      • skippedEntity

        void skippedEntity​(String name)            throws SAXException
        接收跳过的实体的通知。 这不会在标记构造中引用实体引用,例如元素开始标记或标记声明。 (XML建议要求报告跳过的外部实体.SAX还报告内部实体扩展/非扩展,标记结构除外。)

        每次跳过实体时,Parser都会调用此方法。 非验证处理器可以在没有看到声明的情况下跳过实体(例如,因为实体是在外部DTD子集中声明的)。 所有处理器都可以跳过外部实体,具体取决于http://xml.org/sax/features/external-general-entitieshttp://xml.org/sax/features/external-parameter-entities属性的值。

        参数
        name - 跳过的实体的名称。 如果它是参数实体,则名称将以'%'开头,如果它是外部DTD子集,则它将是字符串“[dtd]”
        异常
        SAXException - 任何SAX异常,可能包含另一个异常