Interface XQSequence
- All Superinterfaces:
XQItemAccessor
- All Known Subinterfaces:
XQResultSequence
- All Known Implementing Classes:
SaxonXQForwardSequence
,SaxonXQSequence
The next
method is useful to position the
XQSequence
over the next item in the sequence.
If the scrollability is XQConstants.SCROLLTYPE_SCROLLABLE
,
then the previous
method can be called to move backwards.
In the case of a forward only sequence, the get methods may be only called
once per item. To perform multiple gets on an item, extract the item first
from the sequence using the getItem
method and
then operate on the XQItem
object.
XQPreparedExpression expr = conn.prepareExpression("for $i .."); XQSequence result = expr.executeQuery(); // create the ItemTypes for string and integer XQItemType strType = conn.createAtomicType(XQItemType.XQBASETYPE_STRING); XQItemType intType = conn.createAtomicType(XQItemType.XQBASETYPE_INT); // positioned before the first item while (result.next()) { XQItemType type = result.getItemType(); // If string, then get the string value out if (type.equals(strType)) String str = result.getAtomicValue(); else if (type.equals(intType)) // if it is an integer.. int intval = result.getInt(); ... }
In a sequence, the cursor may be positioned on an item, after the last item
or before the first item. The getPosition
method
returns the current position number. A value of 0 indicates
that it is positioned before the first item, a value of count() + 1
indicates that it is positioned after the last item, and any other value
indicates that it is positioned on the item at that position.
For example, a position value of 1 indicates that it is positioned on the item at position 1.
The isOnItem
method may be used to find out if the cursor
is positioned on the item. When the cursor is positioned on an item,
the next
method call will move the cursor to be on the next item.
See also: Section 12 Serialization, XQuery API for Java (XQJ) 1.0, which describes some general information applicable to various XQJ serialization methods.
-
Method Summary
Modifier and TypeMethodDescriptionboolean
absolute
(int itempos) Moves theXQSequence
's position to the given item number in this object.void
Move to the position after the last item.void
Moves to the position before the first item.void
close()
Closes the sequence and frees all resources associated with this sequence.int
count()
Returns a number indicating the number of items in the sequence.boolean
first()
Moves to the first item in the sequence.getItem()
Get the current item as an immutableXQItem
object.int
Gets the current cursor position.Read the entire sequence starting from the current position as anXMLStreamReader
object, as described in Section 12.1 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0.getSequenceAsString
(Properties props) Serializes the sequence starting from the current position to a String according to the XSLT 2.0 and XQuery 1.0 serialization.boolean
Checks if the current position is after the last item in the sequence.boolean
Checks if the current position before the first item in the sequence.boolean
isClosed()
Checks if the sequence is closed.boolean
isFirst()
Checks if the current position at the first item in the sequence.boolean
isLast()
Checks if the current position at the last item in the sequence.boolean
isOnItem()
Check if the sequence is positioned on an item or not.boolean
Checks if the sequence is scrollable.boolean
last()
Moves to the last item in the sequence.boolean
next()
Moves to the next item in the sequence.boolean
previous()
Moves to the previous item in the sequence.boolean
relative
(int itempos) Moves the cursor a relative number of items, either positive or negative.void
writeSequence
(OutputStream os, Properties props) Serializes the sequence starting from the current position to anOutputStream
according to the XSLT 2.0 and XQuery 1.0 serialization.void
writeSequence
(Writer ow, Properties props) Serializes the sequence starting from the current position to a Writer according to the XSLT 2.0 and XQuery 1.0 serialization.void
writeSequenceToResult
(Result result) Writes the entire sequence starting from the current position to aResult
.void
writeSequenceToSAX
(ContentHandler saxhdlr) Writes the entire sequence starting from the current position to a SAX handler, as described in Section 12.2 Serializing an XDM instance into a SAX event stream, XQuery API for Java (XQJ) 1.0.Methods inherited from interface javax.xml.xquery.XQItemAccessor
getAtomicValue, getBoolean, getByte, getDouble, getFloat, getInt, getItemAsStream, getItemAsString, getItemType, getLong, getNode, getNodeUri, getObject, getShort, instanceOf, writeItem, writeItem, writeItemToResult, writeItemToSAX
-
Method Details
-
absolute
Moves theXQSequence
's position to the given item number in this object. If the item number is positive, theXQSequence
moves to the given item number with respect to the beginning of theXQSequence
.The first item is item 1, the second is item 2, and so on.
If the given item number is negative, the
XQSequence
positions itself on an absolute item position with respect to the end of the sequence.For example, calling the method
absolute(-1)
positions theXQSequence
on the last item; calling the methodabsolute(-2)
moves theXQSequence
to the next-to-last item, and so on.absolute(0)
will position the sequence before the first item.An attempt to position the sequence beyond the first/last item set leaves the current position to be before the first item or after the last item.
Calling this method on an empty sequence will return
false
.- Parameters:
itempos
- the item position to jump to- Returns:
true
if the current position is within the sequence,false
otherwise- Throws:
XQException
- if (1) the sequence is forward only, or (2) the sequence is in a closed state
-
afterLast
Move to the position after the last item.- Throws:
XQException
- if (1) the sequence is forward only, or (2) the sequence is in a closed state
-
beforeFirst
Moves to the position before the first item.- Throws:
XQException
- if (1) the sequence is forward only, or (2) the sequence is in a closed state
-
close
Closes the sequence and frees all resources associated with this sequence.Closing an
XQSequence
object also implicitly closes allXQItem
objects obtained from it.All methods other than the
isClosed
orclose
method will raise exceptions when invoked after closing the sequence. Callingclose
on anXQSequence
object that is already closed has no effect.- Throws:
XQException
- if there are errors during closing of the sequence
-
isClosed
boolean isClosed()Checks if the sequence is closed.- Returns:
true
if the sequence is in a closed state,false
otherwise
-
count
Returns a number indicating the number of items in the sequence.- Returns:
- the number of items in this sequence
- Throws:
XQException
- if (1) the sequence is forward-only, or (2) the sequence is closed
-
getPosition
Gets the current cursor position.0 indicates that the position is before the first item and
count() + 1
indicates position after the last item. A specific position indicates that the cursor is positioned on the item at that position. Use theisOnItem
method to verify if the cursor is positioned on the item.Calling this method on an empty sequence will return
0
.- Throws:
XQException
- if (1) the sequence is forward-only, or (2) the sequence is closed
-
isOnItem
Check if the sequence is positioned on an item or not. Calling this method on an empty sequence will returnfalse
.- Returns:
true
if the sequence is currently positioned on an item,false
if sequence is positioned before the first item, or after the last item- Throws:
XQException
- if the sequence is in a closed state
-
isScrollable
Checks if the sequence is scrollable.- Returns:
true
if the sequence can be scrolled backward or forward,false
otherwise- Throws:
XQException
- if the sequence is in a closed state
-
first
Moves to the first item in the sequence. The method returnstrue
, if it was able to move to the first item in the sequencefalse
, otherwise. Calling this method on an empty sequence will returnfalse
.- Returns:
true
if the sequence was positioned on the first item,false
otherwise- Throws:
XQException
- if (1) the sequence is forward only, or (2) the sequence is in a closed state
-
getItem
Get the current item as an immutableXQItem
object. In case of anXQResultSequence
, the item is anXQResultItem
. In the case of forward only sequences, this method or any other get or write method may only be called once on the curent item.The
XQItem
object is dependent on the sequence from which it was created and is only valid for the duration ofXQSequence
lifetime. Thus, theXQSequence
is closed, thisXQItem
object will be implicitly closed and it can no longer be used.- Returns:
- an
XQItem
object - Throws:
XQException
- if (1) there are errors retrieving the item, or (2) in the case of a forward only sequence, a get or write method has already been invoked on the current item.
-
getSequenceAsStream
Read the entire sequence starting from the current position as anXMLStreamReader
object, as described in Section 12.1 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0.Note that the serialization process might fail, in which case a
XQException
is thrown.While the stream is being read, the application MUST NOT do any other concurrent operations on the sequence. The operation on the stream is undefined if the underlying sequence position or state is changed by concurrent operations.
After all items are written to the stream, the current position of the cursor is set to point after the last item.
Also, in the case of forward only sequences, this method may only be called if the current item has not yet been read through any of the get or write methods.
- Returns:
- an XML reader object as
XMLStreamReader
- Throws:
XQException
- if (1) there are errors accessing any of the items in the sequence, (2) the sequence is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (4) in case of an error during serialization of the sequence into a StAX event stream as defined in Section 12.1 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0
-
getSequenceAsString
Serializes the sequence starting from the current position to a String according to the XSLT 2.0 and XQuery 1.0 serialization.Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.
Reading the sequence during the serialization process performs implicit next operations to read the items.
After all items are written to the stream, the current position of the cursor is set to point after the last item.
Also, in the case of forward only sequences, this method may only be called if the current item has not yet been read through any of the get or write methods.
- Parameters:
props
- specifies the serialization parameters,null
is considered equivalent to an emptyProperties
object- Returns:
- the serialized representation of the sequence
- Throws:
XQException
- if (1) there are errors accessing the items in the sequence, (2) there are errors during serialization, (3) the sequence is in a closed state, or (4) in the case of a forward only sequence, a get or write method has already been invoked on the current item
-
isAfterLast
Checks if the current position is after the last item in the sequence. Calling this method on an empty sequence will returnfalse
.- Returns:
true
if the current position is after the last item,false
otherwise- Throws:
XQException
- if (1) the sequence is forward only, or (2) the sequence is in a closed state
-
isBeforeFirst
Checks if the current position before the first item in the sequence. Calling this method on an empty sequence will returnfalse
.- Returns:
true
if the current position is before the first item,false
otherwise- Throws:
XQException
- if (1) the sequence is forward only, or (2) the sequence is in a closed state
-
isFirst
Checks if the current position at the first item in the sequence. Calling this method on an empty sequence will returnfalse
.- Returns:
true
if the current position is at the first item,false
otherwise- Throws:
XQException
- if (1) the sequence is forward only, or (2) the sequence is in a closed state
-
isLast
Checks if the current position at the last item in the sequence. Calling this method on an empty sequence will returnfalse
.- Returns:
true
if the current position is at the last item,false
otherwise- Throws:
XQException
- if (1) the sequence is forward only, or (2) the sequence is in a closed state
-
last
Moves to the last item in the sequence. This method returnstrue
, if it was able to move to the last item in the sequencefalse
, otherwise. Calling this method on an empty sequence will returnfalse
.- Returns:
true
if the sequence was positioned on the last item,false
otherwise- Throws:
XQException
- if (1) the sequence is forward only, or (2) the sequence is in a closed state
-
next
Moves to the next item in the sequence. Calling this method on an empty sequence will returnfalse
.- Returns:
true
if the new item is valid,false
if there are no more items- Throws:
XQException
- if the sequence is in a closed state
-
previous
Moves to the previous item in the sequence. Calling this method on an empty sequence will returnfalse
.- Returns:
true
if the new current position is within the sequence, (i.e., not before first);false
otherwise.- Throws:
XQException
- if (1) the sequence is forward only, or (2) the sequence is in a closed state.
-
relative
Moves the cursor a relative number of items, either positive or negative. Attempting to move beyond the first/last item in the sequence positions the sequence before/after the the first/last item. Callingrelative(0)
is valid, but does not change the cursor position.Note: Calling the method
relative(1)
is identical to calling the methodnext
and calling the methodrelative(-1)
is identical to calling the methodprevious()
. Calling this method on an empty sequence will returnfalse
.- Parameters:
itempos
- the item position to jump to- Returns:
true
if the new current position is within the sequence (i.e., not before first or after last);false
otherwise.- Throws:
XQException
- if (1) the sequence is forward only, or (2) the sequence is in a closed state.
-
writeSequence
Serializes the sequence starting from the current position to anOutputStream
according to the XSLT 2.0 and XQuery 1.0 serialization.Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.
Reading the sequence during the serialization process performs implicit next operations to read the items.
After all items are written to the stream, the current position of the cursor is set to point after the last item.
Also, in the case of forward only sequences, this method may only be called if the current item has not yet been read through any of the get or write methods.
- Parameters:
os
- the output stream into which the sequence is to be serializedprops
- specifies the serialization parameters,null
is considered equivalent to an emptyProperties
object- Throws:
XQException
- if (1) there are errors accessing the items in the sequence, (2) there are errors during serialization, (3) the sequence is in a closed state, (4) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (5) theos
parameter isnull
-
writeSequence
Serializes the sequence starting from the current position to a Writer according to the XSLT 2.0 and XQuery 1.0 serialization.Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.
Warning: When outputting to aWriter
, make sure the writer's encoding matches the encoding parameter if specified as a property or the default encoding.
Reading the sequence during the serialization process performs implicit next operations to read the items.
After all items are written to the stream, the current position of the cursor is set to point after the last item.
Also, in the case of forward only sequences, this method may only be called if the current item has not yet been read through any of the get or write methods.
- Parameters:
ow
- the writer object into which the sequence is to be serializedprops
- specifies the serialization parameters,null
is considered equivalent to an emptyProperties
object- Throws:
XQException
- if (1) there are errors accessing the items in the sequence, (2) there are errors during serialization, (3) the sequence is in a closed state, (4) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (5) theow
parameter isnull
-
writeSequenceToSAX
Writes the entire sequence starting from the current position to a SAX handler, as described in Section 12.2 Serializing an XDM instance into a SAX event stream, XQuery API for Java (XQJ) 1.0.Note that the serialization process might fail, in which case a
XQException
is thrown.After all items are written to the stream, the current position of the cursor is set to point after the last item.
Also, in the case of forward only sequences, this method may only be called if the current item has not yet been read through any of the get or write methods.
The specified
org.xml.sax.ContentHandler
can optionally implement theorg.xml.sax.LexicalHandler
interface. An implementation must check if the specifiedContentHandler
implementsLexicalHandler
. If the handler is aLexicalHandler
comment nodes are reported, otherwise they will be silently ignored.- Parameters:
saxhdlr
- the SAX content handler, optionally a lexical handler- Throws:
XQException
- if (1) there are errors accessing any of the items in the sequence, (2) the sequence is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, (4) in case of an error during serializing the XDM instance into a SAX event stream, or (5) thesaxhdlr
parameter isnull
-
writeSequenceToResult
Writes the entire sequence starting from the current position to aResult
. First the sequence is normalized as described in XSLT 2.0 and XQuery 1.0 serialization. Subsequently it is serialized to theResult
object.
Note that the normalization process can fail, in which case an
XQException
is thrown.An XQJ implementation must at least support the following implementations:
javax.xml.transform.dom.DOMResult
javax.xml.transform.sax.SAXResult
javax.xml.transform.stream.StreamResult
- Parameters:
result
- the result object into which the sequence is to be serialized- Throws:
XQException
- if (1) there are errors accessing any of the items in the sequence, (2) the sequence is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, (4) in case of an error while serializing the sequence into theResult
object, or (5) theresult
parameter isnull
-