Qizx fe-4.4p2 API

com.qizx.api
Interface XMLPullStream

All Known Subinterfaces:
FullTextPullStream
All Known Implementing Classes:
FullTextHighlighter, FullTextSnippetExtractor, com.qizx.xdm.XMLPullStreamBase

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 to javax.xml.stream.XMLStreamReader in essence, but it is fully compliant with the XQuery/XPath2 Data Model and it is 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.
 Node getCurrentNode()
          Returns the current node, if the implementation of this object is able to.
 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

static final int END
Value returned by moveToNext and getEvent when the end of stream is reached.

See Also:
Constant Field Values

START

static final int START
Value returned by getEvent before the first call to moveToNext.

See Also:
Constant Field Values

DOCUMENT_START

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

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

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

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

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

static final int COMMENT
Value returned by moveToNext and getEvent when a comment is reached.

See Also:
Constant Field Values

PROCESSING_INSTRUCTION

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

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

int getCurrentEvent()
Returns the same value as the latest moveToNextEvent.

Returns:
an event code like in moveToNextEvent

getEncoding

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

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

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

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

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

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

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

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

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

int getNamespaceCount()
On ELEMENT_START, returns the number of namespace declarations of the element itself. Otherwise returns -1.

Returns:
number of namespace declarations

getNamespacePrefix

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

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

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

int getTextLength()
Returns the size of the textual contents of an atomic node.

Returns:
the number of characters
See Also:
getText()

getTarget

String getTarget()
Returns the target name for a PROCESSING_INSTRUCTION.

Returns:
a String which is the target name of the PI

getCurrentNode

Node getCurrentNode()
Returns the current node, if the implementation of this object is able to. Otherwise the null value is returned.


© 2010 Axyana Software