|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface XQSequence
This interface represents a sequence of items as defined in the XDM. The sequence may be materialized or non-materialized.
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 | |
---|---|
boolean |
absolute(int itempos)
Moves the XQSequence 's position to the given item
number in this object. |
void |
afterLast()
Move to the position after the last item. |
void |
beforeFirst()
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. |
XQItem |
getItem()
Get the current item as an immutable XQItem object. |
int |
getPosition()
Gets the current cursor position. |
XMLStreamReader |
getSequenceAsStream()
Read the entire sequence starting from the current position as an XMLStreamReader object, as described in
Section 12.1 Serializing an XDM instance into a StAX event stream
(XMLStreamReader), XQuery API for Java (XQJ) 1.0. |
String |
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 |
isAfterLast()
Checks if the current position is after the last item in the sequence. |
boolean |
isBeforeFirst()
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 |
isScrollable()
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 an OutputStream 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 a Result . |
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 Detail |
---|
boolean absolute(int itempos) throws XQException
XQSequence
's position to the given item
number in this object. If the item number is positive, the
XQSequence
moves to the given item number with
respect to the beginning of the XQSequence
. 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 the XQSequence
on the last item;
calling the method absolute(-2)
moves the
XQSequence
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
.
itempos
- the item position to jump to
true
if the current position is
within the sequence, false
otherwise
XQException
- if (1) the sequence is forward only, or
(2) the sequence is in a closed statevoid afterLast() throws XQException
XQException
- if (1) the sequence is forward only,
or (2) the sequence is in a closed statevoid beforeFirst() throws XQException
XQException
- if (1) the sequence is forward only,
or (2) the sequence is in a closed statevoid close() throws XQException
XQSequence
object also implicitly closes all
XQItem
objects obtained from it.
All methods other than the isClosed
or close
method will raise exceptions when invoked
after closing the sequence.
Calling close
on an XQSequence
object
that is already closed has no effect.
XQException
- if there are errors during closing of
the sequenceboolean isClosed()
true
if the sequence is in
a closed state, false
otherwiseint count() throws XQException
XQException
- if (1) the sequence is forward-only, or (2)
the sequence is closedint getPosition() throws XQException
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 the isOnItem
method to verify if the cursor is positioned on the item.
Calling this method on an empty sequence
will return 0
.
XQException
- if (1) the sequence is forward-only, or (2)
the sequence is closedboolean isOnItem() throws XQException
false
.
true
if the sequence is currently
positioned on an item, false
if sequence
is positioned before the first item, or after the last
item
XQException
- if the sequence is in a closed stateboolean isScrollable() throws XQException
true
if the sequence can be scrolled
backward or forward, false
otherwise
XQException
- if the sequence is in a closed stateboolean first() throws XQException
true
, if it was able to move to the first item in the sequence
false
, otherwise. Calling this method on an empty sequence
will return false
.
true
if the sequence was positioned
on the first item, false
otherwise
XQException
- if (1) the sequence is forward only,
or (2) the sequence is in a closed stateXQItem getItem() throws XQException
XQItem
object.
In case of an XQResultSequence
, the item is an
XQResultItem
.
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 of XQSequence
lifetime. Thus, the XQSequence
is closed, this XQItem
object will be implicitly closed and it can no longer be used.
XQItem
object
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.XMLStreamReader getSequenceAsStream() throws XQException
XMLStreamReader
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.
XMLStreamReader
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.0String getSequenceAsString(Properties props) throws XQException
props
- specifies the serialization parameters,
null
is considered equivalent to an
empty Properties
object
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 itemboolean isAfterLast() throws XQException
false
.
true
if the current position is
after the last item, false
otherwise
XQException
- if (1) the sequence is forward only,
or (2) the sequence is in a closed stateboolean isBeforeFirst() throws XQException
false
.
true
if the current position is
before the first item, false
otherwise
XQException
- if (1) the sequence is forward only,
or (2) the sequence is in a closed stateboolean isFirst() throws XQException
false
.
true
if the current position is at
the first item, false
otherwise
XQException
- if (1) the sequence is forward only,
or (2) the sequence is in a closed stateboolean isLast() throws XQException
false
.
true
if the current position is at
the last item, false
otherwise
XQException
- if (1) the sequence is forward only,
or (2) the sequence is in a closed stateboolean last() throws XQException
true
, if it was able to move to the last item in the sequence
false
, otherwise. Calling this method on an empty sequence
will return false
.
true
if the sequence was positioned
on the last item, false
otherwise
XQException
- if (1) the sequence is forward only,
or (2) the sequence is in a closed stateboolean next() throws XQException
false
.
true
if the new item is valid,
false
if there are no more items
XQException
- if the sequence is in a closed stateboolean previous() throws XQException
false
.
true
if the new current position is
within the sequence, (i.e., not before first);
false
otherwise.
XQException
- if (1) the sequence is forward only, or
(2) the sequence is in a closed state.boolean relative(int itempos) throws XQException
relative(0)
is valid, but does not change the cursor position.
Note: Calling the method relative(1)
is identical to calling the method
next
and calling the method relative(-1)
is identical
to calling the method previous()
.
Calling this method on an empty sequence will return false
.
itempos
- the item position to jump to
true
if the new current position is within
the sequence (i.e., not before first or after last);
false
otherwise.
XQException
- if (1) the sequence is forward only, or
(2) the sequence is in a closed state.void writeSequence(OutputStream os, Properties props) throws XQException
OutputStream
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.
os
- the output stream into which the sequence is to be serializedprops
- specifies the serialization parameters,
null
is considered equivalent to an empty
Properties
object
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) the os
parameter is null
void writeSequence(Writer ow, Properties props) throws XQException
Writer
, make sure the writer's encoding
matches the encoding parameter if specified as a property or the default
encoding.
ow
- the writer object into which the sequence is to be serializedprops
- specifies the serialization parameters,
null
is considered equivalent to an empty
Properties
object
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) the ow
parameter is null
void writeSequenceToSAX(ContentHandler saxhdlr) throws XQException
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 the
org.xml.sax.LexicalHandler
interface. An implementation must check if the
specified ContentHandler
implements LexicalHandler
.
If the handler is a LexicalHandler
comment nodes are reported, otherwise
they will be silently ignored.
saxhdlr
- the SAX content handler, optionally a lexical handler
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) the saxhdlr
parameter is null
void writeSequenceToResult(Result result) throws XQException
Result
. First the sequence is normalized as described in
XSLT 2.0 and XQuery 1.0 serialization. Subsequently it is serialized
to the Result
object.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
result
- the result object into which the sequence
is to be serialized
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 the Result
object, or (5) the
result
parameter is null
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |