Chapter 10. XmlEventReader

Chapter 10. XmlEventReader
Prev		Next

#include <DbXml.hpp>

virtual XmlEventReader::~XmlEventReader()

The XmlEventReader class enables applications to read document content via a pull interface without materializing XML as text. This can be efficient and allow closer integration of XML processing in an application.

The XmlEventReader acts as an iterator, where XmlEventReader::hasNext indicates the presence of additional events, and XmlEventReader::next moves the current location, returning the event type of the next event. At any given location, various methods on the object allow the application to retrieve the current state, such as element name and attributes. Character state (names, text values, etc) are returned in NULL-terminated const unsigned char * strings, encoded in UTF-8. Their values are valid only until another call is made on the XmlEventReader object. When processing of the object is completed, the XmlEventReader::close method must be called to release resources. Some interfaces implicitly assume ownership of the object -- for example XmlDocument::setContentAsEventReader.

XmlEventReader does not include events for attributes. Attributes are retrieved via interfaces such as XmlEventReader::getAttributeLocalName when the event type is StartElement.

XmlEventReader skips the EndElement event for empty elements (where XmlEventReader::isEmptyElement returns true).

Event types are defined at global scope, and include:

XmlEventReader::StartElement
The current event is the start of an element.
XmlEventReader::EndElement
The current event is the end of an element.
XmlEventReader::Characters
The current event is text characters.
XmlEventReader::CDATA
The current event is CDATA text.
XmlEventReader::Comment
The current event is comment text.
XmlEventReader::Whitespace
The current event is ignorable whitespace.
XmlEventReader::StartDocument
The current event is the start of the document.
XmlEventReader::EndDocument
The current event is the end of the document.
XmlEventReader::StartEntityReference
The current event marks the start of expanded entity text.
XmlEventReader::EndEntityReference
The current event marks the end of expanded entity text.
XmlEventReader::ProcessingInstruction
The current event is a processing instruction.
XmlEventReader::DTD
The current event is the text of a DTD.

Many of the class methods are context-dependent, as they are meaningful only within the context of a given event. See the documentation for the individual methods for details.

An XmlEventReader object may be obtained via XmlDocument::getContentAsEventReader or XmlValue::asEventReader or from an application-written class derived from XmlEventReader. This object is not thread-safe, and can only be safely used by one thread at a time in an application.

XmlEventReader Methods

XmlEventReader Methods	Description
XmlEventReader::close	Release resources for reader.
XmlEventReader::encodingSet	Checks if the encoding of the document is set.
XmlEventReader::getAttributeCount	Return the number of attributes for an element event.
XmlEventReader::getAttributeLocalName	Get attribute's local name.
XmlEventReader::getAttributeNamespaceURI	Get attribute's namespace URI.
XmlEventReader::getAttributePrefix	Get attribute's namespace prefix.
XmlEventReader::getAttributeValue	Get attribute's value.
XmlEventReader::getEncoding	Return the encoding of the document.
XmlEventReader::getEventType	Return the type of the current event.
XmlEventReader::getExpandEntities	Get whether to expand entities.
XmlEventReader::getLocalName	Return the name of the current element event.
XmlEventReader::getNamespaceURI	Return the namespace URI of the current element event.
XmlEventReader::getPrefix	Return the namespace prefix for the current element event.
XmlEventReader::getReportEntityInfo	Get whether to report entity information.
XmlEventReader::getSystemId	Return the System ID for for the document.
XmlEventReader::getValue	Return the value of the current event.
XmlEventReader::getVersion	Return the XML version string for the document.
XmlEventReader::hasEmptyElementInfo	Check if object will return empty element state.
XmlEventReader::hasEntityEscapeInfo	Check if object has information about entities.
XmlEventReader::hasNext	Check if there are more events.
XmlEventReader::isAttributeSpecified	Check if an attribute is specified.
XmlEventReader::isEmptyElement	Check current element is empty.
XmlEventReader::isStandalone	Check if document is standalone XML.
XmlEventReader::isWhiteSpace	Check if current text value is white space.
XmlEventReader::needsEntityEscape	Check if text or attribute value needs escaping.
XmlEventReader::next	Move to the next event.
XmlEventReader::nextTag	Move to the next StartElement or EndElement event.
XmlEventReader::setExpandEntities	Set whether to expand entities.
XmlEventReader::setReportEntityInfo	Set whether to report entity information.
XmlEventReader::standaloneSet	Check if the standalone attribute is set.