-
- 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事件之前按顺序报告所有元素的内容。此事件最多允许每个元素使用三个名称组件:
- 名称空间URI;
- 当地名称; 和
- 合格(带前缀)名称。
可以提供任何或所有这些,具体取决于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异常,可能包含另一个异常
-
-