com.sleepycat.dbxml
Class XmlEventReader

java.lang.Object
  com.sleepycat.dbxml.XmlEventReader

public class XmlEventReader
extends Object

Used to read XML as events rather than serialized text. You can obtain an instance of this object using one of XmlDocument.getContentAsEventReader(),or XmlValue.asEventReader().
You use instances of this class with XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument), XmlDocument.setContentAsEventReader(com.sleepycat.dbxml.XmlEventReader), and XmlEventReaderToWriter.

This class implements an iterator-style interface, and you can manually retrieve its state using hasNext() and next(), along with accessor methods. When done with the object, its resources must be released using close().

The event types are declared as static int in this class

This class allows applications direct access to the content model of stored XML without the overhead of re-parsing the document text.

Field Summary

static int	CDATA CDATA event
static int	Characters Character (text) event
static int	Comment Comment event
static int	DTD DTD event
static int	EndDocument End document event
static int	EndElement End element event
static int	EndEntityReference End entity reference event
static int	ProcessingInstruction Processing instruction event
static int	StartDocument Start document event
static int	StartElement Start element event
static int	StartEntityReference Start entity reference event
static int	Whitespace Ignorable whitespace event

Constructor Summary

XmlEventReader()

Method Summary

void	close() Free the resources associated with this object.
boolean	encodingSet() Return whether the encoding is explicitly set in the XML declaration for the document.
int	getAttributeCount() Return the number of attributes for a StartElement event.
String	getAttributeLocalName(int index) Return the local name of the attribute specified by the index parameter.
String	getAttributeNamespaceURI(int index) Return the namespace URI of the attribute specified by the index parameter.
String	getAttributePrefix(int index) Return the prefix of the attribute specified by the index parameter.
String	getAttributeValue(int index) Return the text value of the attribute specified by the index parameter.
String	getEncoding() Return the character encoding.
int	getEventType() Return the event type of the current position.
boolean	getExpandEntities() Determine whether you will read events that are part of an expanded entity reference.
String	getLocalName() Return the local name of the event at the current position.
String	getNamespaceURI() Return the namespace URI of the event at the current position.
String	getPrefix() Return the namespace prefix of the event at the current position.
boolean	getReportEntityInfo() Determine whether you will read events indicating the start and end of entity references and expansion.
String	getSystemId() Return the system ID of the document, if available.
String	getValue() Return the text value of the current event.
String	getVersion() Return the XML version string.
boolean	hasEmptyElementInfo() Return whether the implementation keeps track of empty elements.
boolean	hasEntityEscapeInfo() Return whether the object is able to accurately determine if a given text value may require escaping of entities.
boolean	hasNext() Return true if there is another valid event remaining
boolean	isAttributeSpecified(int index) Return whether the attribute specified by the index is specified in the document (vs defaulted).
boolean	isEmptyElement() Return whether the current event is StartElement with an empty element.
boolean	isStandalone() Return whether the document is standalone.
boolean	isWhiteSpace() Return whether the current text value is entirely white space.
boolean	needsEntityEscape() Return whether the text value of the current event requires escaping.
boolean	needsEntityEscape(int index) Return whether the text value of the attribute specified by the index parameter requires escaping.
int	next() Move to the next event, returning its type.
int	nextTag() Move to the next event that is of type StartElement, EndElement, returning its type.
void	setExpandEntities(boolean value) Tell the object whether you want to read events that are part of an expanded entity reference.
void	setReportEntityInfo(boolean value) Tell the object whether you want to read events indicating the start and end of entity references and expansion.
boolean	standaloneSet() Return whether the standalone is set in the XML declaration for the document

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

StartElement

public static final int StartElement

Start element event

EndElement

public static final int EndElement

End element event

Characters

public static final int Characters

Character (text) event

CDATA

public static final int CDATA

CDATA event

Comment

public static final int Comment

Comment event

Whitespace

public static final int Whitespace

Ignorable whitespace event

StartDocument

public static final int StartDocument

Start document event

EndDocument

public static final int EndDocument

End document event

StartEntityReference

public static final int StartEntityReference

Start entity reference event

EndEntityReference

public static final int EndEntityReference

End entity reference event

ProcessingInstruction

public static final int ProcessingInstruction

Processing instruction event

DTD

public static final int DTD

DTD event

Constructor Detail

XmlEventReader

public XmlEventReader()

Method Detail

close

public void close()
           throws XmlException

Free the resources associated with this object. This call must be made when you are done with this object.

Throws:

XmlException

setReportEntityInfo

public void setReportEntityInfo(boolean value)
                         throws XmlException

Tell the object whether you want to read events indicating the start and end of entity references and expansion.

BDB XML maintains this information internally in order to provide more accurate round-tripping of documents with entities. By default, the start and end entity events are not reported. Not all implementations of XmlEventReader will support these events. Use getReportEntityInfo() to determine the actual state.

Parameters:

value - Set to true if you want to see StartEntityReference and EndEntityReference events.

Throws:

XmlException

getReportEntityInfo

public boolean getReportEntityInfo()
                            throws XmlException

Determine whether you will read events indicating the start and end of entity references and expansion.

BDB XML maintains this information internally in order to provide more accurate round-tripping of documents with entities. By default, the start and end entity events are not reported. Not all implementations of XmlEventReader will support these events. Use setReportEntityInfo(boolean) to change the state for those implementations that support it.

Throws:

XmlException

setExpandEntities

public void setExpandEntities(boolean value)
                       throws XmlException

Tell the object whether you want to read events that are part of an expanded entity reference. By default, this is true.

BDB XML maintains start and end of entity references internally in order to provide more accurate round-tripping of documents with entities. This interface controls whether you see the events from the expanded reference. For example, if you set this value to false, and set setReportEntityInfo(boolean) to true, you will see just the entity references themselves, and will suppress the expanded information. This can be useful for round-tripping of documents. Use getExpandEntities() to determine the actual state.

Parameters:

value - Set to true if you want to see events from expanded entities.

Throws:

XmlException

getExpandEntities

public boolean getExpandEntities()
                          throws XmlException

Determine whether you will read events that are part of an expanded entity reference. By default, this is true.

BDB XML maintains start and end of entity references internally in order to provide more accurate round-tripping of documents with entities. Use setExpandEntities(boolean) to change the state.

Throws:

XmlException

next

public int next()
         throws XmlException

Move to the next event, returning its type. Types are declared as static int in this class. If the current event is StartElement and the element is empty (isEmptyElement() returns true) the EndElement event is skipped.

This method will throw an exception if hasNext() is false.

Throws:

XmlException

nextTag

public int nextTag()
            throws XmlException

Move to the next event that is of type StartElement, EndElement, returning its type. If the current event is StartElement and the element is empty (isEmptyElement() returns true) the EndElement event is skipped.

This method will throw an exception if it does not find a StartElement or EndElement tag. It is best used when iterating through structured content, avoiding text and whitespace.

Throws:

XmlException

hasNext

public boolean hasNext()
                throws XmlException

Return true if there is another valid event remaining

Throws:

XmlException

getEventType

public int getEventType()
                 throws XmlException

Return the event type of the current position. Types are declared as static int in this class.

Throws:

XmlException

getNamespaceURI

public String getNamespaceURI()
                       throws XmlException

Return the namespace URI of the event at the current position. If the current event type is not StartElement or EndElement, null is returned.

Throws:

XmlException

getLocalName

public String getLocalName()
                    throws XmlException

Return the local name of the event at the current position. If the current event type is not StartElement, EndElement, or ProcessingInstruction, an exception is thrown.

If the current event is ProcessingInstruction, the target portion is returned. The data portion of a ProcessingInstruction event is returned using getValue().

Throws:

XmlException

getPrefix

public String getPrefix()
                 throws XmlException

Return the namespace prefix of the event at the current position. If the current event type is not StartElement or EndElement, an exception is thrown.

Throws:

XmlException

getValue

public String getValue()
                throws XmlException

Return the text value of the current event. The event must have a valid value. If this call is made on one of StartElement, EndElement, StartDocument, or EndDocument an exception is thrown.

If the current event is ProcessingInstruction, the data portion is returned using this interface. The target is returned using getLocalName().

Throws:

XmlException

getAttributeCount

public int getAttributeCount()
                      throws XmlException

Return the number of attributes for a StartElement event. If the current event is not StartElement, an exception is thrown.

Throws:

XmlException

isAttributeSpecified

public boolean isAttributeSpecified(int index)
                             throws XmlException

Return whether the attribute specified by the index is specified in the document (vs defaulted). If the current event is not StartElement, or the index is out of the valid range for the number of attributes, an exception is thrown.

Parameters:

index - The index of the attribute in the current element's attribute list

Throws:

XmlException

getAttributeLocalName

public String getAttributeLocalName(int index)
                             throws XmlException

Return the local name of the attribute specified by the index parameter. If the current event is not StartElement, or the index is out of the valid range for the number of attributes, an exception is thrown.

Parameters:

index - The index of the attribute in the current element's attribute list

Throws:

XmlException

getAttributeNamespaceURI

public String getAttributeNamespaceURI(int index)
                                throws XmlException

Return the namespace URI of the attribute specified by the index parameter. If the current event is not StartElement, or the index is out of the valid range for the number of attributes, an exception is thrown.

Parameters:

index - The index of the attribute in the current element's attribute list

Throws:

XmlException

getAttributePrefix

public String getAttributePrefix(int index)
                          throws XmlException

Return the prefix of the attribute specified by the index parameter. If the current event is not StartElement, or the index is out of the valid range for the number of attributes, an exception is thrown.

Parameters:

index - The index of the attribute in the current element's attribute list

Throws:

XmlException

getAttributeValue

public String getAttributeValue(int index)
                         throws XmlException

Return the text value of the attribute specified by the index parameter. If the current event is not StartElement, or the index is out of the valid range for the number of attributes, an exception is thrown.

Parameters:

index - The index of the attribute in the current element's attribute list

Throws:

XmlException

getEncoding

public String getEncoding()
                   throws XmlException

Return the character encoding.

Throws:

XmlException

getVersion

public String getVersion()
                  throws XmlException

Return the XML version string. This will be typically "1.0" or "1.1"

Throws:

XmlException

getSystemId

public String getSystemId()
                   throws XmlException

Return the system ID of the document, if available. Note: if the document comes from BDB XML, this will always be null.

Throws:

XmlException

isStandalone

public boolean isStandalone()
                     throws XmlException

Return whether the document is standalone.

Throws:

XmlException

standaloneSet

public boolean standaloneSet()
                      throws XmlException

Return whether the standalone is set in the XML declaration for the document

Throws:

XmlException

encodingSet

public boolean encodingSet()
                    throws XmlException

Return whether the encoding is explicitly set in the XML declaration for the document.

Throws:

XmlException

hasEntityEscapeInfo

public boolean hasEntityEscapeInfo()
                            throws XmlException

Return whether the object is able to accurately determine if a given text value may require escaping of entities. BDB XML maintains this information internally, and it can be used to avoid expensive string parsing, looking for entities to escape.

Throws:

XmlException

needsEntityEscape

public boolean needsEntityEscape(int index)
                          throws XmlException

Return whether the text value of the attribute specified by the index parameter requires escaping. If the return value is false, there are no entities to escape. If the current event is not StartElement, or the index is out of the valid range for the number of attributes, an exception is thrown.

Parameters:

index - The index of the attribute in the current element's attribute list

Throws:

XmlException

needsEntityEscape

public boolean needsEntityEscape()
                          throws XmlException

Return whether the text value of the current event requires escaping. If the return value is false, there are no entities to escape. If the current event does not have a valid text value, an exception is thrown.

Throws:

XmlException

hasEmptyElementInfo

public boolean hasEmptyElementInfo()
                            throws XmlException

Return whether the implementation keeps track of empty elements. If true, empty elements will have no EndElement event.

Throws:

XmlException

isEmptyElement

public boolean isEmptyElement()
                       throws XmlException

Return whether the current event is StartElement with an empty element. If the current event is not StartElement an exception is thrown. If the element is empty the corresponding EndElement event is skipped.

Throws:

XmlException

isWhiteSpace

public boolean isWhiteSpace()
                     throws XmlException

Return whether the current text value is entirely white space. The current event must be Whitespace, Characters, or CDATA, or an exception is thrown. White space is carriage return, line feed, tab, or space.

Throws:

XmlException