所有类
|
|||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
org.xml.sax
接口 ContentHandler
- 所有已知子接口:
- TemplatesHandler, TransformerHandler
-
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 ...*" 通常标志不简洁的编程,因此,用户应该将此作为一种功能而不是错误。
- 从以下版本开始:
- 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
-
接收文档的开始的通知。
在其他任何事件回调(不包括
setDocumentLocator
)之前,SAX 解析器仅调用此方法一次。 -
- 抛出:
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 属性的值:
- 当名称空间属性为 true(默认)时,名称空间 URI 和本地名称是必需项,当名称空间属性为 false 时,则为可选项(如果指定一个值,两个都必须指定);
- 当名称空间前缀属性为 true 时,限定名是必需项,当名称空间前缀属性为 false(默认值)时,则为可选项。
注意,所提供的属性列表仅包括具有显式值(指定的或默认的)的属性:将忽略 #IMPLIED 属性。仅在
http://xml.org/sax/features/namespace-prefixes
属性为 true (默认情况下为 false,并且对 true 值的支持是可选项)时属性列表才包括用于名称空间声明(xmlns* 属性)的属性。与
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 异常,可能包装另外的异常