com.qizx.api
Interface XMLPullStream

public interface XMLPullStream

Streaming input of XML contents, working in 'pull' mode.

An object implementing this interface delivers the contents of an XML Node as a stream of "events", enumerated under control of the calling code (hence the term "pull mode"). An element appears as a pair of events ELEMENT_START, ELEMENT_END enclosing the events corresponding to the contents of the element. Atomic nodes (text, comment, PI) appear as a single event.

The stream is forward only. A method moveToNextEvent() both moves the stream to the next event and returns the type of this event (ELEMENT_START, TEXT, ELEMENT_END etc.). The current event type is also available through the method getCurrentEvent().

Other methods provide access to event-specific values such as element name, attributes, namespace declarations, textual contents.

Note: this interface is similar in essence to javax.xml.stream.XMLStreamReader, but simpler. The iteration style is slightly different since there is no hasNext() method.

Field Summary

static int	COMMENT Value returned by moveToNext and getEvent when a comment is reached.
static int	DOCUMENT_END Value returned by moveToNext and getEvent when the end of the document is reached.
static int	DOCUMENT_START Value returned by moveToNext and getEvent when the beginning of a document is reached.
static int	ELEMENT_END Value returned by moveToNext and getEvent when the end of an element is reached.
static int	ELEMENT_START Value returned by moveToNext and getEvent when the beginning of an element is reached.
static int	END Value returned by moveToNext and getEvent when the end of stream is reached.
static int	PROCESSING_INSTRUCTION Value returned by moveToNext and getEvent when a processing-instruction is reached.
static int	START Value returned by getEvent before the first call to moveToNext.
static int	TEXT Value returned by moveToNext and getEvent when a text node is reached.

Method Summary

int	getAttributeCount() On ELEMENT_START, returns the number of attributes of the element.
QName	getAttributeName(int index) On ELEMENT_START, returns the name of the N-th attribute of the element.
String	getAttributeValue(int index) On ELEMENT_START, returns the string-value of the N-th attribute of the element.
int	getCurrentEvent() Returns the same value as the latest moveToNextEvent.
String	getDTDName() Returns the declared DTD name of the document, if any.
String	getDTDPublicId() Returns the declared Public ID of the DTD, if any.
String	getDTDSystemId() Returns the declared System ID of the DTD, if any.
String	getEncoding() Returns the declared encoding of the document, if any.
String	getInternalSubset() Returns the source form of internal subset of the DTD, if any.
QName	getName() Returns the name of the current element node, or if the node is not an element, returns the name of the parent element.
int	getNamespaceCount() On ELEMENT_START, returns the number of namespace declarations of the element itself.
String	getNamespacePrefix(int index) On ELEMENT_START, returns the prefix of the N-th namespace declaration of the element.
String	getNamespaceURI(int index) On ELEMENT_START, returns the namespace URI of the N-th namespace declaration of the element.
String	getTarget() Returns the target name for a PROCESSING_INSTRUCTION.
String	getText() Returns the textual contents of an atomic node.
int	getTextLength() Returns the size of the textual contents of an atomic node.
int	moveToNextEvent() Moves the event stream one step forward.

Field Detail

END

public static final int END

Value returned by moveToNext and getEvent when the end of stream is reached.

See Also:

Constant Field Values

START

public static final int START

Value returned by getEvent before the first call to moveToNext.

See Also:

Constant Field Values

DOCUMENT_START

public static final int DOCUMENT_START

Value returned by moveToNext and getEvent when the beginning of a document is reached. From that point, the getEncoding() and getDTDxxx() methods return meaningful values. This event is not returned if the stream delivers the contents of a fragment of a document (element or atomic contents).

See Also:

Constant Field Values

DOCUMENT_END

public static final int DOCUMENT_END

Value returned by moveToNext and getEvent when the end of the document is reached. Always followed by END.

See Also:

Constant Field Values

ELEMENT_START

public static final int ELEMENT_START

Value returned by moveToNext and getEvent when the beginning of an element is reached. Attributes and namespace declarations are available on this event.

See Also:

Constant Field Values

ELEMENT_END

public static final int ELEMENT_END

Value returned by moveToNext and getEvent when the end of an element is reached. Attributes and namespace declarations are NOT available on this event.

See Also:

Constant Field Values

TEXT

public static final int TEXT

Value returned by moveToNext and getEvent when a text node is reached. Adjacent text nodes are always coalesced.

See Also:

Constant Field Values

COMMENT

public static final int COMMENT

Value returned by moveToNext and getEvent when a comment is reached.

See Also:

Constant Field Values

PROCESSING_INSTRUCTION

public static final int PROCESSING_INSTRUCTION

Value returned by moveToNext and getEvent when a processing-instruction is reached.

See Also:

Constant Field Values

Method Detail

moveToNextEvent

public int moveToNextEvent()
                    throws DataModelException

Moves the event stream one step forward.

Returns:

the next event. If the stream has reached its end, returns END.

Throws:

DataModelException - may be thrown by the stream implementation in case access to data is impossible (deleted document, closed Library).

getCurrentEvent

public int getCurrentEvent()

Returns the same value as the latest moveToNextEvent.

Returns:

an event code like in moveToNextEvent

getEncoding

public String getEncoding()

Returns the declared encoding of the document, if any. Valid from the moment a DOCUMENT_START event is encountered.

Returns:

the declared encoding, or null

getDTDName

public String getDTDName()

Returns the declared DTD name of the document, if any. Valid from the moment a DOCUMENT_START event is encountered.

Returns:

the declared DTD name, or null

getDTDPublicId

public String getDTDPublicId()

Returns the declared Public ID of the DTD, if any. Valid from the moment a DOCUMENT_START event is encountered.

Returns:

the declared DTD public id, or null

getDTDSystemId

public String getDTDSystemId()

Returns the declared System ID of the DTD, if any. Valid from the moment a DOCUMENT_START event is encountered.

Returns:

the declared DTD system id, or null

getInternalSubset

public String getInternalSubset()

Returns the source form of internal subset of the DTD, if any. Valid from the moment a DOCUMENT_START event is encountered.

Returns:

the internal subset, or null

getName

public QName getName()

Returns the name of the current element node, or if the node is not an element, returns the name of the parent element.

Returns:

the latest element name

getAttributeCount

public int getAttributeCount()

On ELEMENT_START, returns the number of attributes of the element. Otherwise returns -1.

Returns:

the number of attributes of the current element, else -1

getAttributeName

public QName getAttributeName(int index)

On ELEMENT_START, returns the name of the N-th attribute of the element.

Parameters:

index - of the attribute (starting from 0)

Returns:

name of the N-th attribute of the current element

Throws:

IndexOutOfBoundsException - if not on an element start, of the index is invalid.

getAttributeValue

public String getAttributeValue(int index)

On ELEMENT_START, returns the string-value of the N-th attribute of the element.

Parameters:

index - of the attribute (starting from 0)

Returns:

value of the N-th attribute of the current element

Throws:

IndexOutOfBoundsException - if not on an element start, of the index is invalid.

getNamespaceCount

public int getNamespaceCount()

On ELEMENT_START, returns the number of namespace declarations of the element itself. Otherwise returns -1.

Returns:

number of namespace declarations

getNamespacePrefix

public String getNamespacePrefix(int index)

On ELEMENT_START, returns the prefix of the N-th namespace declaration of the element.

Parameters:

index - of the namespace declaration (starting from 0)

Returns:

prefix of the N-th namespace of the current element

Throws:

IndexOutOfBoundsException - if not on an element start, of the index is invalid.

getNamespaceURI

public String getNamespaceURI(int index)

On ELEMENT_START, returns the namespace URI of the N-th namespace declaration of the element.

Parameters:

index - of the namespace declaration (starting from 0)

Returns:

URI of the N-th namespace of the current element

Throws:

IndexOutOfBoundsException - if not on an element start, of the index is invalid.

getText

public String getText()

Returns the textual contents of an atomic node. On PROCESSING_INSTRUCTION, returns the contents without the target name. On element and document events, return null.

Returns:

a String for the direct contents of the current leaf node

getTextLength

public int getTextLength()

Returns the size of the textual contents of an atomic node.

Returns:

the number of characters

See Also:

getText()

getTarget

public String getTarget()

Returns the target name for a PROCESSING_INSTRUCTION.

Returns:

a String which is the target name of the PI