streaming api_XML的Streaming API简介（StAX）

StAX概述

自成立以来，用于XML处理的Java API（JAXP）提供了两种处理XML的方法-文档对象模型（DOM）方法（使用标准对象模型表示XML文档）和XML简单API（SAX）方法，该方法使用应用程序提供的事件处理程序来处理XML。在JSR-173：XML的流API（StAX）中提出了这些方法的流替代方法。它的最终版本于2004年3月发布，并成为JAXP 1.4的一部分（将包含在即将发布的Java 6版本中）。

顾名思义，StAX注重流媒体。实际上，StAX与其他方法的不同之处在于应用程序将XML作为事件流进行处理的能力。将XML作为一组事件进行处理的想法并不是全新的（实际上，它已经存在于SAX中）。但是，不同之处在于StAX允许应用程序代码一个接一个地拉出这些事件，而不必提供在解析器方便时从解析器接收事件的处理程序。

StAX实际上由两组XML处理API组成，每组提供不同的抽象级别。基于游标的API允许应用程序将XML作为令牌（或事件）流使用。应用程序可以检查解析器的状态并获取有关最后解析的令牌的信息，然后前进到下一个令牌，依此类推。这是一个相当底层的API。尽管效率很高，但它没有提供底层XML结构的抽象。基于高级迭代器的API允许应用程序将XML作为一系列事件对象进行处理，每个事件对象都将XML结构的一部分传达给应用程序。应用程序所需要做的就是确定已解析事件的类型，将其转换为相应的具体类型，并使用其方法来获取与该事件有关的信息。

基础

为了使用这两个API，应用程序必须首先获得一个具体的XMLInputFactory 。在经典的JAXP风格中，这是使用Abstract Factory模式完成的。 XMLInputFactory类提供静态的newInstance方法，这些方法用于定位和实例化具体工厂。要配置此实例，可以设置自定义或预定义的属性（其名称在类XMLInputFactory中定义）。最后，为了使用基于游标的API，应用程序通过调用createXMLStreamReader方法之一来获取XMLStreamReader 。另外，为了使用基于事件迭代器的API，应用程序将调用createXMLEventReader方法之一来获取XMLEventReader （请参见清单1）。

清单1.获取和配置默认的`XMLInputFactory`

// get the default factory instance
XMLInputFactory factory = XMLInputFactory.newInstance();
// configure it to create readers that coalesce adjacent character sections
factory.setProperty(XMLInputFactory.IS_COALESCING, Boolean.TRUE);
XMLStreamReader r = factory.createXMLStreamReader(input);
// ...

XMLStreamReader和XMLEventReader允许应用程序自行遍历基础XML流。两种方法之间的区别在于它们如何显示已解析的XML InfoSet的片段。 XMLStreamReader充当游标，其指向刚超出最近解析的XML令牌之外的位置，并提供获取有关此令牌的更多信息的方法。这种方法非常节省内存，因为它不会创建任何新对象。但是，业务应用程序开发人员可能会发现XMLEventReader稍微更直观，因为它实际上是将XML转换为事件对象流的标准Java迭代器。每个事件对象依次封装与其表示的特定XML结构有关的信息。本系列的第2部分将详细介绍基于事件迭代器的API。

至于使用哪种API样式取决于情况。与基于游标的API相比，基于事件迭代器的API代表了一种更加面向对象的方法。这样，由于当前解析器的状态反映在事件对象中，因此更容易应用于模块化体系结构。因此，应用程序组件在处理事件时不需要访问解析器/读取器。此外，可以使用XMLInputFactory的createXMLEventReader(XMLStreamReader)方法从XMLStreamReader创建XMLEventReader 。

StAX还定义了序列化API，这是Java的标准XML处理支持中非常缺少的功能。与其解析对象一样，它也是一种流API，有两种形式：用于令牌的较低级XMLStreamWriter和用于事件对象的较高级XMLEventWriter 。 XMLStreamWriter提供了用于编写单个XML令牌（例如，打开和关闭标签或元素属性）的方法，而无需检查其格式是否正确。另一方面， XMLEventWriter允许应用程序将完整的XML事件对象添加到输出中。在第3部分中，您将详细探讨StAX序列化API。

为什么要使用StAX？

在致力于学习新的XML处理API之前，您可能想知道是否值得这样做。实际上，StAX采用的基于拉的方法相对于其他方法具有几个重要的优点。首先，无论使用哪种API样式，都是由应用程序调用读取器（解析器），而不是相反。通过保留对解析过程的控制，您可以简化调用代码以精确处理其期望的内容，并选择在遇到意外情况时仅停止解析。此外，由于此方法不是基于处理程序回调，因此应用程序不需要像使用SAX时那样需要维护模拟的解析器状态。

StAX还保留了SAX通过DOM提供的优势。通过将焦点从结果对象模型转移到已解析的流本身，应用程序可以处理理论上无限的XML流，因为事件本质上是瞬态的，不需要在内存中累积。对于使用XML作为消息传递协议而不是表示文档内容的一类应用程序，例如Web服务或即时消息传递应用程序，这尤其重要。例如，如果将传递给DOM的Web服务路由器servlet所做的只是将其转换为特定于应用程序的对象模型，然后简单地将其丢弃，则几乎没有用。使用StAX直接进入应用程序模型更为有效。对于可扩展消息和状态协议（XMPP）客户端，使用DOM是绝对不可能的-XMPP客户端/服务器流是根据用户输入的消息实时递增生成的。等待流的结束标记（以最终完成DOM的构建）意味着等待直到对话结束。通过将XML处理为一系列事件，应用程序可以以最合适的方式对每个事件做出React（例如，显示传入的即时消息等）。

由于其双向特性，StAX还非常好地支持链式处理，尤其是在事件级别。接受事件（来自任何来源）的能力封装在XMLEventConsumer接口中，该接口由XMLEventWriter扩展。因此，您可以模块化地编写应用程序，以从XMLEventReader（它也是一个普通的Iterator，可以将其视为此类）读取XML事件，对其进行处理，然后将其传递给事件使用者（如果可以，则进一步扩展处理链）需要）。正如您将在第2部分中学习的那样，还可以通过使用应用程序提供的过滤器（实现EventFilter接口的类）或使用EventReaderDelegate装饰现有的XMLEventReader来定制XMLEventReader。

总而言之，StAX使应用程序比DOM或SAX更接近底层XML。通过使用StAX，应用程序不仅可以建立所需的对象模型（而不必处理标准DOM），而且还可以方便地做到这一点，而不是仅在从解析器获得回调之后才可以这样做。

下一节将详细研究基于游标的API以及如何使用它来有效处理XML流。

基于游标的API

使用基于游标的API时，应用程序通过在XML令牌流上推进逻辑游标来处理XML。基于游标的解析器实质上是一种状态机，由于事件而从一种状态良好的状态转换为另一种状态。在这种情况下，触发事件是XML令牌，当应用程序使用适当的方法沿令牌流推进解析器时，将对其进行解析。在每种状态下，您可以使用一组方法来获取有关最新事件的信息。通常，并非所有方法都适用于所有状态。

要使用基于游标的方法，应用程序必须首先通过调用XMLInputFactory的createXMLStreamReader方法之一从XMLInputFactory获得XMLStreamReader 。此方法有多个版本，每个版本支持不同类型的输入。例如，可以创建XMLStreamReader来解析plain java.io.InputStream ， java.io.Reader ，还可以解析JAXP Source（ javax.xml.transform.Source ）。从理论上讲，最后一个选项应该使与其他JAXP技术（例如SAX和DOM）的交互更加容易。

清单2.创建一个`XMLStreamReader`来解析`InputStream`

URL url = new URL(uri);
InputStream input = url.openStream();
XMLInputFactory factory = XMLInputFactory.newInstance();
XMLStreamReader r = factory.createXMLStreamReader(uri, input);
// process the stream
// ...
r.close();
input.close();

XMLStreamReader接口实质上定义了基于游标的API（尽管令牌常量是在其超类型接口XMLStreamConstants中定义的）。之所以称为基于游标，是因为读取器充当基础令牌流上的游标。应用程序可以使光标沿着令牌流向前移动，并在光标位置检查令牌。

XMLStreamReader提供了几种导航令牌流的方法。为了确定光标当前指向的令牌（或事件）的类型，应用程序可以调用getEventType() 。此方法返回接口XMLStreamConstants定义的标记常量之一。要移至下一个令牌，应用程序可以调用next() 。此方法还返回已解析标记的类型-与后续调用getEventType()所返回的值相同。只要方法hasNext()返回true（即，有更多要解析的标记），就只能调用此方法（以及其他推进读者的方法）。

清单3.使用`XMLStreamReader`处理XML的常用模式

// create an XMLStreamReader
XMLStreamReader r = ...;
try {int event = r.getEventType();while (true) {switch (event) {case XMLStreamConstants.START_DOCUMENT:// add cases for each event of interest// ...}if (!r.hasNext())break;event = r.next();}
} finally {r.close();
}

其他一些方法可能会使reader前进。方法nextTag()将跳过任何空格，注释或处理指令，直到到达START_ELEMENT或END_ELEMENT 。当解析纯元素内容时，此方法很有用。如果在找到标签之前（注释或处理指令除外）遇到非空白文本，则会引发异常。方法getElementText()将返回元素的开始和结束标记之间（即START_ELEMENT和END_ELEMENT之间getElementText()所有文本内容。如果找到任何嵌套的元素，它将引发异常。

您会注意到，在此上下文中，术语“令牌”和“事件”可互换使用。虽然基于游标的API的文档讨论事件，但将输入源视为令牌流更容易。由于还有其他基于事件的API样式（事件是适当的对象），因此它也不太混乱。但是， XMLStreamReader的事件本身并不是全部标记。例如， START_DOCUMENT和END_DOCUMENT事件不需要匹配的令牌。前一个事件在解析开始之前发生，而后一个事件在无法进行进一步解析之后发生（例如，在解析了最后一个元素的结束标记之后，读取器处于END_ELEMENT状态；但是，在尝试解析更多令牌并没有找到任何令牌之后，阅读器将转换为END_DOCUMENT状态）。

处理XML文档

在每个解析器状态下，应用程序都可以使用适用的方法来获取有关它的信息。例如，方法getNamespaceContext()和getNamespaceURI()可以分别获取当前名称空间上下文和当前有效的名称空间URI，而与当前事件类型无关。同样， getLocation()可以获取有关当前事件位置的信息。方法hasName()和hasText()可以分别确定当前事件是否具有名称（例如元素或属性）或文本（例如字符，注释或CDATA）。方法isStartElement() ， isEndElement() ， isCharacters()和isWhiteSpace()是确定当前事件性质的便捷快捷方式。最后，方法require（ int ， String ， String ）可以声明预期的解析器状态；除非当前事件是指定的类型，并且本地名称和名称空间（如果指定）与当前事件匹配，则它将引发异常。

清单4.使用当前事件为`START_ELEMENT`时可用的属性相关方法

if (reader.getEventType() == XMLStreamConstants.START_ELEMENT) {System.out.println("Start Element: " + reader.getName());for(int i = 0, n = reader.getAttributeCount(); i < n; ++i) {QName name = reader.getAttributeName(i);String value = reader.getAttributeValue(i);System.out.println("Attribute: " + name + "=" + value);}
}

XMLStreamReader创建后，立即以START_DOCUMENT状态启动（即， getEventType()将返回START_DOCUMENT ）。处理令牌时，请考虑到这一点。与迭代器不同，游标无需先前进（使用next() ）即可进入有效状态。同样，在读者转换到其最终状态END_DOCUMENT之后，应用程序不应尝试前进。一旦处于此状态，方法hasNext()将返回false。

START_DOCUMENT事件提供了获取有关文档本身的信息的方法，例如getEncoding() ， getVersion()和isStandalone() 。应用程序还可以通过调用getProperty(String)获得命名的属性值；但是，某些属性仅在特定状态下定义（例如，如果当前事件为DTD，则属性javax.xml.stream.notations和javax.xml.stream.entities返回任何符号和实体声明）。

在START_ELEMENT和END_ELEMENT ，可以使用与元素名称和名称空间相关的方法（例如getName() ， getLocalName() ， getPrefix()和getNamespaceXXX() ）；与属性相关的方法（ getAttributeXXX() ）也可以在START_ELEMENT 。

ATTRIBUTE和NAMESPACE也被视为独立事件，尽管在解析典型的XML文档时不会遇到它们。但是，由于XPath查询而返回ATTRIBUTE或NAMESPACE节点时，可能会遇到它们。

在基于文本的事件（例如CHARACTERS ， CDATA ， COMMENT和SPACE ）中，请使用各种getTextXXX()方法获取文本。您可以分别使用getPITarget()和getPIData()来检索PROCESSING_INSTRUCTION的目标和数据。 ENTITY_REFERENCE和DTD也支持getText() ; ENTITY_REFERENCE也getLocalName() 。

解析完成后，应用程序将关闭阅读器以释放其在此过程中获取的任何资源。请注意，这不会关闭基础输入源。

清单5提供了使用基于游标的API处理XML文档的完整示例。首先，获取XMLInputFactory的默认实例，并创建一个XMLStreamReader来解析给定的输入流。接下来，迭代检查读者的状态，并根据当前事件类型，报告特定信息（例如，如果处于START_ELEMENT状态，则为元素名称及其属性）。最后，到达END_DOCUMENT时关闭阅读器。

清单5.使用`XMLStreamReader`解析XML文档的完整示例

XMLInputFactory factory = XMLInputFactory.newInstance();
XMLStreamReader r = factory.createXMLStreamReader(input);
try {int event = r.getEventType();while (true) {switch (event) {case XMLStreamConstants.START_DOCUMENT:out.println("Start Document.");break;case XMLStreamConstants.START_ELEMENT:out.println("Start Element: " + r.getName());for(int i = 0, n = r.getAttributeCount(); i < n; ++i)out.println("Attribute: " + r.getAttributeName(i) + "=" + r.getAttributeValue(i));break;case XMLStreamConstants.CHARACTERS:if (r.isWhiteSpace())break;out.println("Text: " + r.getText());break;case XMLStreamConstants.END_ELEMENT:out.println("End Element:" + r.getName());break;case XMLStreamConstants.END_DOCUMENT:out.println("End Document.");break;}if (!r.hasNext())break;event = r.next();}
} finally {r.close();
}

`XMLStreamReader`高级用法

也可以通过使用基本阅读器和应用程序定义的过滤器（即，实现StreamFilter的类的实例）调用XMLInputFactory的createFilteredReader方法来创建过滤的XMLStreamReader 。在浏览过滤的阅读器时，只要基本阅读器前进到下一个标记，便会查询过滤器。如果过滤器批准当前事件，则将其暴露给过滤后的阅读器。如果不是，则跳过令牌并测试下一个令牌，依此类推。这种方法允许开发人员创建基于游标的XML处理器，以处理解析后的内容的简化子集，并将其与各种扩展内容模型的过滤器结合使用。

要执行更复杂的流操作，请子类StreamReaderDelegate并重写适当的方法。然后可以使用此子类的实例包装基本XMLStreamReader ，从而为应用程序提供基本XML流的修改视图。使用此技术可以对XML流执行简单的转换，例如过滤或替换某些令牌，甚至用新的令牌扩充该流。

在清单6中，使用自定义StreamReaderDelegate包装了一个基本XMLStreamReader ，并重写了它的next()方法以跳过COMMENT和PROCESSING_INSTRUCTION事件。使用生成的阅读器时，应用程序不必担心会遇到这些类型的令牌。

清单6.使用定制的`StreamReaderDelegate`过滤掉注释和处理指令

URL url = new URL(uri);
InputStream input = url.openStream();XMLInputFactory f = XMLInputFactory.newInstance();
XMLStreamReader r = f.createXMLStreamReader(uri, input);
XMLStreamReader fr = new StreamReaderDelegate(r) {public int next() throws XMLStreamException {while (true) {int event = super.next();switch (event) {case XMLStreamConstants.COMMENT:case XMLStreamConstants.PROCESSING_INSTRUCTION:continue;default:return event;}}}
};try {int event = fr.getEventType();while (true) {switch (event) {case XMLStreamConstants.COMMENT:case XMLStreamConstants.PROCESSING_INSTRUCTION:// this should never happenthrow new IllegalStateException("Filter failed!");default:// process XML normally}if (!fr.hasNext())break;event = fr.next();}
} finally {fr.close();
}input.close();

超越基于游标的处理

如您所见，基于游标的API完全是关于效率的。所有状态信息都可以直接从流读取器中获得，并且不会创建额外的对象。这在性能和低内存占用非常重要的应用中特别有用。

基于拉式XML解析的好处已经有一段时间了。实际上，StAX本身是从一种称为XML Pull Parsing的方法派生的。 XML Pull Parser API与StAX提供的基于光标的API相似。可以检查解析器状态以获取有关上一个已解析事件的信息，然后前进到下一个事件，依此类推。没有提供基于事件迭代器的替代API。这种方法非常轻巧，特别适合于资源受限的环境，例如J2ME。但是，很少有实现提供诸如验证之类的企业级功能，因此XML Pull在企业Java开发人员中从未流行。

基于以前的拉式解析器实现的经验，StAX的创建者选择包括基于对象的替代基于游标的API。即使XMLEventReader接口在表面上看似简单，但基于事件迭代器的方法仍比基于游标的方法具有重要的优势。通过将解析器事件转换为一流的对象，它允许应用程序以面向对象的方式处理它们。这样可以在多个应用程序组件之间实现更好的模块化和代码重用。

清单7.使用StAX `XMLEventReader`解析XML

XMLInputFactory inputFactory = XMLInputFactory.newInstance();
XMLEventReader reader = inputFactory.createXMLEventReader(input);
try {while (reader.hasNext()) {XMLEvent e = reader.nextEvent();if (e.isCharacters() && ((Characters) e).isWhiteSpace())continue;out.println(e);}
} finally {reader.close();
}

摘要

在本文中，向您介绍了StAX及其较低级别的基于游标的API。第2部分将对事件迭代器API进行更深入的研究。

翻译自: https://www.ibm.com/developerworks/java/library/x-stax1/index.html