ContentHandler (Java Platform SE 8 )

All Known Subinterfaces:

TemplatesHandler ， TransformerHandler ， UnmarshallerHandler

所有已知实现类：

DefaultHandler ， DefaultHandler2 ， ValidatorHandler ， XMLFilterImpl ， XMLReaderAdapter
```
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 ... *”通常是一个乱码编程的标志，所以用户应该考虑这个功能，而不是一个bug。
从以下版本开始：

SAX 2.0

另请参见：

XMLReader ， DTDHandler ， ErrorHandler

方法摘要

所有方法接口方法抽象方法
Modifier and Type	Method and Description
`void`	`characters(char[] ch, int start, int length)` 接收字符数据通知。
`void`	`endDocument()` 接收文件结束的通知。
`void`	`endElement(String uri, String localName, String qName)` 接收元素结尾的通知。
`void`	`endPrefixMapping(String prefix)` 结束前缀URI映射的范围。
`void`	`ignorableWhitespace(char[] ch, int start, int length)` 在元素内容中接收到可忽略的空白的通知。
`void`	`processingInstruction(String target, String data)` 接收处理指令的通知。
`void`	`setDocumentLocator(Locator locator)` 接收一个查找SAX文档事件的起源的对象。
`void`	`skippedEntity(String name)` 接收跳过实体的通知。
`void`	`startDocument()` 接收文件开头的通知。
`void`	`startElement(String uri, String localName, String qName, Attributes atts)` 接收元素开头的通知。
`void`	`startPrefixMapping(String prefix, String uri)` 开始一个prefix-URI命名空间映射的范围。

- 方法详细信息
  - 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
```
    开始一个prefix-URI命名空间映射的范围。
    来自此事件的信息对于正常的命名空间处理来说不是必需的：当http://xml.org/sax/features/namespaces功能为真 （默认值）时，SAX XML阅读器将自动替换元素和属性名称的前缀。
    
    然而，有些情况下，当应用程序需要在字符数据或属性值中使用前缀时，无法自动扩展它们; start / endPrefixMapping事件将信息提供给应用程序，以在必要时在这些上下文中扩展前缀。
    
    请注意，start / endPrefixMapping事件不能保证相对于彼此正确嵌套：所有startPrefixMapping事件将在相应的startElement事件之前立即发生，并且所有endPrefixMapping事件将在相应的endElement事件之后立即发生，但其命令不另行保证。
    
    不应该为“xml”前缀启动/ endPrefixMapping事件，因为它是预先声明的和不可变的。
    
    参数
    
    prefix - 声明的命名空间前缀。空字符串用于默认元素命名空间，它没有前缀。
    
    uri - 前缀映射到的命名空间URI
    
    异常
    
    SAXException - 客户端可能会在处理过程中抛出异常
    
    另请参见：
    
    endPrefixMapping(java.lang.String) ， startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)
  - endPrefixMapping
```
void endPrefixMapping(String prefix)
               throws SAXException
```
    结束前缀URI映射的范围。
    详见startPrefixMapping 。这些事件将会立即发生，相应的后endElement事件，但顺序endPrefixMapping个事件是不是另有保证。
    
    参数
    
    prefix - 正在映射的前缀。当默认映射范围结束时，这是空字符串。
    
    异常
    
    SAXException - 客户端可能会在处理过程中抛出异常
    
    另请参见：
    
    startPrefixMapping(java.lang.String, java.lang.String) ， endElement(java.lang.String, java.lang.String, java.lang.String)
  - 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/namespaces和http://xml.org/sax/features/namespace-prefixes属性的值，可以提供任何或全部这些内容：
    - 命名空间URI和本地名称在namespaces属性为true （默认值）时是必需的，并且在命名空间属性为false时 （如果指定，都必须）为可选参数;
    - 当namespace-prefixes属性为true时，必需的限定名称，并且当namespace-prefixes属性为false （默认值）时是可选的。
    请注意，提供的属性列表将仅包含具有显式值（指定或默认值）的属性：#IMPLIED属性将被省略。只有当http://xml.org/sax/features/namespace-prefixes属性为true时，属性列表才会包含用于命名空间声明（xmlns * attributes）的属性（默认情况下为false，并且对真值支持是可选的）。
    
    像characters()一样，属性值可能具有需要多于一个char值的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
```
    接收字符数据通知。
    Parser将调用此方法来报告每个字符数据块。 SAX解析器可以在单个块中返回所有连续的字符数据，或者它们可以将其分割成多个块; 然而，任何单个事件中的所有字符必须来自相同的外部实体，以便定位器提供有用的信息。
    
    应用程序不得尝试从指定范围之外的数组读取。
    
    单个字符可能包含多个Java char值。有两个重要的情况发生，因为字符不能仅在十六位中表示。在一种情况下，字符在代理对中表示 ，使用两个特殊的Unicode值。这些字符在所谓的“星云飞行”中，代码点高于U + FFFF。第二种情况涉及复合字符，例如与一个或多个重音字符组合的基本字符。
    
    您的代码不应该假设使用char的一次性成语将以字符单位工作; 在某些情况下，他们会拆分字符。这在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
```
    接收处理指令的通知。
    解析器将为发现的每个处理指令调用此方法一次：请注意，处理指令可能发生在主文档元素之前或之后。
    
    SAX解析器不得使用此方法报告XML声明（XML 1.0，第2.8节）或文本声明（XML 1.0，第4.3.1节）。
    
    像characters()一样，处理指令数据可能具有需要多于一个char值的char 。
    
    参数
    
    target - 处理指令目标
    
    data - 处理指令数据，如果没有提供，则返回null。数据不包括将其与目标分离的任何空格
    
    异常
    
    SAXException - 任何SAX异常，可能包装另一个异常
  - skippedEntity
```
void skippedEntity(String name)
            throws SAXException
```
    接收跳过实体的通知。这不是在标记结构中的实体引用（如元素起始标记或标记声明）中调用的。（XML建议需要报告跳过的外部实体，SAX还报告内部实体扩展/非扩展，除了标记结构之外）
    每次跳过实体时，Parser将调用此方法。如果没有看到声明，则非验证处理器可能会跳过实体（例如，实体在外部DTD子集中声明）。所有处理器可能会跳过外部实体，具体取决于http://xml.org/sax/features/external-general-entities和http://xml.org/sax/features/external-parameter-entities属性的值。
    
    参数
    
    name - 跳过的实体的名称。如果它是一个参数实体，名称将以'％'开头，如果是外部DTD子集，它将是字符串“[dtd]”
    
    异常
    
    SAXException - 任何SAX异常，可能包装另一个异常

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.

Interface ContentHandler

方法摘要

方法详细信息

setDocumentLocator

startDocument

endDocument

startPrefixMapping

endPrefixMapping

startElement

endElement

characters

ignorableWhitespace

processingInstruction

skippedEntity