模块 java.xml

软件包 org.xml.sax

Interface ContentHandler

All Known Subinterfaces:

TemplatesHandler ， TransformerHandler

所有已知实现类：

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 ... *”通常是草率编程的标志，因此用户应该将此视为一个功能而不是错误。

从以下版本开始：

1.4，SAX 2.0

另请参见：

XMLReader ， DTDHandler ， ErrorHandler

方法摘要

变量和类型	方法	描述
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)	开始前缀-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

开始前缀-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)

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 （默认值）时是必需的，并且在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) ， 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解析器可以在一个块中返回所有连续的字符数据，或者它们可以将它分成几个块; 但是，任何单个事件中的所有字符都必须来自同一个外部实体，以便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-entities和http://xml.org/sax/features/external-parameter-entities属性的值。

参数

name - 跳过的实体的名称。 如果它是参数实体，则名称将以'％'开头，如果它是外部DTD子集，则它将是字符串“[dtd]”

异常

SAXException - 任何SAX异常，可能包含另一个异常