net.sf.saxon.xqj
Class SaxonXQForwardSequence

java.lang.Object
  extended by net.sf.saxon.xqj.Closable
      extended by net.sf.saxon.xqj.SaxonXQForwardSequence
All Implemented Interfaces:
javax.xml.xquery.XQItemAccessor, javax.xml.xquery.XQResultSequence, javax.xml.xquery.XQSequence

public class SaxonXQForwardSequence
extends Closable
implements javax.xml.xquery.XQResultSequence

The class is a Saxon implementation of the XQJ interface XQResultSequence. This implementation is used to represent a sequence that can only be read in a forwards direction.


Constructor Summary
protected SaxonXQForwardSequence(SequenceIterator iterator, SaxonXQPreparedExpression expression)
           
 
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.
 int count()
          Returns a number indicating the number of items in the sequence.
 boolean first()
          Moves to the first item in the sequence.
 String getAtomicValue()
          Gets the current item as a Java String.
 boolean getBoolean()
          Gets the current item as a boolean.
 byte getByte()
          Gets the current item as a byte.
 javax.xml.xquery.XQConnection getConnection()
          Gets the XQuery connection associated with this result sequence
 double getDouble()
          Gets the current item as a double.
 float getFloat()
          Gets the current item as a float.
 int getInt()
          Gets the current item as an int.
 javax.xml.xquery.XQItem getItem()
          Get the current item as an immutable XQItem object.
 javax.xml.stream.XMLStreamReader getItemAsStream()
          Read the current item 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 getItemAsString(Properties props)
          Serializes the current item according to the XSLT 2.0 and XQuery 1.0 serialization.
 javax.xml.xquery.XQItemType getItemType()
          Gets the type of the item.
 long getLong()
          Gets the current item as a long.
 Node getNode()
          Gets the item as a DOM node.
 URI getNodeUri()
          Returns the URI for this item.
 Object getObject()
          Gets the current item as an Object.
 int getPosition()
          Gets the current cursor position.
 javax.xml.stream.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.
 short getShort()
          Gets the current item as a short.
 boolean instanceOf(javax.xml.xquery.XQItemType type)
          Checks if the item "matches" an item type, as defined in 2.5.4.2 Matching an Item Type and an Item, XQuery 1.0: An XML Query Language.
 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 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 writeItem(OutputStream os, Properties props)
          Serializes the current item to a Writer according to XSLT 2.0 and XQuery 1.0 serialization.
 void writeItem(Writer ow, Properties props)
          Serializes the current item to a Writer according to XSLT 2.0 and XQuery 1.0 serialization.
 void writeItemToResult(Result result)
          Writes the current item to a Result.
 void writeItemToSAX(ContentHandler saxHandler)
          Writes the current item to a SAX handler, as described in in Section 12.2 Serializing an XDM instance into a SAX event stream, XQuery API for Java (XQJ) 1.0.
 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 saxHandler)
          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 class net.sf.saxon.xqj.Closable
close, isClosed, setClosableContainer
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface javax.xml.xquery.XQSequence
close, isClosed
 

Constructor Detail

SaxonXQForwardSequence

protected SaxonXQForwardSequence(SequenceIterator iterator,
                                 SaxonXQPreparedExpression expression)
Method Detail

getConnection

public javax.xml.xquery.XQConnection getConnection()
                                            throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQResultSequence
Gets the XQuery connection associated with this result sequence

Specified by:
getConnection in interface javax.xml.xquery.XQResultSequence
Returns:
the connection associated with this result sequence
Throws:
javax.xml.xquery.XQException - if the result sequence is in a closed state

getAtomicValue

public String getAtomicValue()
                      throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Gets the current item as a Java String. The current item must be an atomic value. This function casts the current item to an xs:string value according to the casting rules defined in 17.1.2 Casting to xs:string and xs:untypedAtomic, XQuery 1.0 and XPath 2.0 Functions and Operators, and then returns the value as a Java String.

Specified by:
getAtomicValue in interface javax.xml.xquery.XQItemAccessor
Returns:
the string representation of the item
Throws:
javax.xml.xquery.XQException - if (1) there are errors accessing the item's value, (2) the item is not an atomic value, (3) there is an error when casting the item to a string representation, (4) the underlying sequence or item is in a closed state, or (5) in the case of forward only sequences, a get or write method was already invoked on the current item

getBoolean

public boolean getBoolean()
                   throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Gets the current item as a boolean. The current item must be an atomic value of type xs:boolean or a subtype.

Specified by:
getBoolean in interface javax.xml.xquery.XQItemAccessor
Returns:
a boolean representing the current item
Throws:
javax.xml.xquery.XQException - if (1) the conversion of the current item to a boolean fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getByte

public byte getByte()
             throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Gets the current item as a byte. The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of byte.

Specified by:
getByte in interface javax.xml.xquery.XQItemAccessor
Returns:
a byte representing the current item
Throws:
javax.xml.xquery.XQException - if (1) the conversion of the current item to a byte fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getDouble

public double getDouble()
                 throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Gets the current item as a double. The current item must be an atomic value of type xs:double or a subtype.

Specified by:
getDouble in interface javax.xml.xquery.XQItemAccessor
Returns:
a double representing the current item
Throws:
javax.xml.xquery.XQException - if (1) the conversion of the current item to a double fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getFloat

public float getFloat()
               throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Gets the current item as a float. The current item must be an atomic value of type xs:float or a subtype.

Specified by:
getFloat in interface javax.xml.xquery.XQItemAccessor
Returns:
a float representing the current item
Throws:
javax.xml.xquery.XQException - if (1) the conversion of the current item to a float fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getInt

public int getInt()
           throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Gets the current item as an int. The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of int.

Specified by:
getInt in interface javax.xml.xquery.XQItemAccessor
Returns:
an int representing the current item
Throws:
javax.xml.xquery.XQException - if (1) the conversion of the current item to a int fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getItemAsStream

public javax.xml.stream.XMLStreamReader getItemAsStream()
                                                 throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Read the current item 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. 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 underlying item or sequence. The operation on the stream is undefined if the underlying sequence is repositioned or the state of the underlying item or sequence is changed by concurrent operations.

Specified by:
getItemAsStream in interface javax.xml.xquery.XQItemAccessor
Returns:
an XML reader object as XMLStreamReader
Throws:
javax.xml.xquery.XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item 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 current item 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

getItemAsString

public String getItemAsString(Properties props)
                       throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Serializes the current item 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.

Specified by:
getItemAsString in interface javax.xml.xquery.XQItemAccessor
Parameters:
props - specifies the serialization parameters, null is considered equivalent to an empty Properties object
Returns:
the serialized representation of the item
Throws:
javax.xml.xquery.XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item 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) if there are errors during serialization

getItemType

public javax.xml.xquery.XQItemType getItemType()
                                        throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Gets the type of the item.
On a forward only sequence this method can be called independent of any other get or write method. It will not raise an error if such method has been called already, nor will it affect subsequent invocations of any other get or write method.

Specified by:
getItemType in interface javax.xml.xquery.XQItemAccessor
Returns:
the type of the item
Throws:
javax.xml.xquery.XQException - if (1) there are errors accessing the type of the item, or (2) the underlying sequence or item is in a closed state

getLong

public long getLong()
             throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Gets the current item as a long. The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of long.

Specified by:
getLong in interface javax.xml.xquery.XQItemAccessor
Returns:
a long representing the current item
Throws:
javax.xml.xquery.XQException - if (1) the conversion of the current item to a long fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getNode

public Node getNode()
             throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Gets the item as a DOM node. The current item must be a node. The type of the returned DOM node is governed by Table 7 - XQuery Node Types and Corresponding Java Object Types XQuery API for Java (XQJ) 1.0 The instance of the returned node is implementation dependent. The node may be a reference or a copy of the internal state of the item. It is advisable to make a copy of the node if the application plans to modify it.

Specified by:
getNode in interface javax.xml.xquery.XQItemAccessor
Returns:
a DOM node representing the current item
Throws:
javax.xml.xquery.XQException - if (1) if there are errors accessing the current item, (2) the current item is not a node, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

getNodeUri

public URI getNodeUri()
               throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Returns the URI for this item. If the item is a document node, then this method returns the absolute URI of the resource from which the document node was constructed. If the document URI is not available, then the empty string is returned. If the document URI is available, the returned value is the same as if fn:document-uri were evaluated on this document node. If the item is of a node kind other than document node, then the returned URI is implementation-defined.
On a forward only sequence this method can be called independent of any other get or write method. It will not raise an error if such method has been called already, nor will it affect subsequent invocations of any other get or write method on the current item.

Specified by:
getNodeUri in interface javax.xml.xquery.XQItemAccessor
Returns:
the document URI for this document node or the empty string if not available. For other node kinds, the result is implementation-defined
Throws:
javax.xml.xquery.XQException - if (1) if there are errors accessing the current item, (2) the current item is not a node, (3) if the underlying sequence or item is in a closed state

getObject

public Object getObject()
                 throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Gets the current item as an Object. The data type of the returned object will be the Java Object type as specified in 14.4 Mapping an XQuery Atomic Value to a Java Object Type and 14.5 Mapping an XQuery Node to a Java Object Type, XQuery API for Java (XQJ) 1.0.

Specified by:
getObject in interface javax.xml.xquery.XQItemAccessor
Returns:
an object representing the current item
Throws:
javax.xml.xquery.XQException - if (1) if there are errors accessing the current item, (2) if the underlying sequence or item is in a closed state, or (3) in the case of forward only sequences, a get or write method was already invoked on the current item

getShort

public short getShort()
               throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Gets the current item as a short. The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of short.

Specified by:
getShort in interface javax.xml.xquery.XQItemAccessor
Returns:
a short representing the current item
Throws:
javax.xml.xquery.XQException - if (1) the conversion of the current item to a short fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item

instanceOf

public boolean instanceOf(javax.xml.xquery.XQItemType type)
                   throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Checks if the item "matches" an item type, as defined in 2.5.4.2 Matching an Item Type and an Item, XQuery 1.0: An XML Query Language. You can use this method to first check the type of the result before calling the specific get methods.

Example -
  ...
  XQItemType strType = conn.createAtomicType(XQItemType.XQBASETYPE_STRING);
  XQItemType nodeType = conn.createNodeType();

  XQSequence result = preparedExpr.executeQuery();
  while (result.next())
  {
     // Generic check for node.. 
     if (result.instanceOf(nodeType))
        org.w3.dom.Node node = result.getNode();
     else if (result.instanceOf(strType))
        String str = result.getAtomicValue();
   }
 

If either the type of the XQItemAccessor or the input XQItemType is not a built-in type, then this method is allowed to raise exception if it can NOT determine the instanceOf relationship due to the lack of the access of the XML schema that defines the user defined schema types if the XQMetaData.isUserDefinedXMLSchemaTypeSupported() method returns false.
Otherwise, this method must determine if the type of the XQItemAccessor is an instance of the input XQItemType. Note even if isUserDefinedXMLSchemaTypeSupported() returns false, an XQJ implementation may still be able to determine the instanceOf relationship for certain cases involving user defined schema type. For example, if the type of an XQItemAccessor is of mySchema:hatSize sequence type and the input parameter XQItemType is of item() sequence type, the return value for instanceOf relationship should always be true even though the XQJ implementation does not know the precise type information of mySchema:hatSize type defined in XML schema 'mySchema'.

Specified by:
instanceOf in interface javax.xml.xquery.XQItemAccessor
Parameters:
type - item type to match
Returns:
true if this item matches the input item type as defined in 2.5.4.2 Matching an Item Type and an Item, XQuery 1.0: An XML Query Language, and false if it does not
Throws:
javax.xml.xquery.XQException - if (1) there are errors accessing the item's type, (2) if the underlying sequence or item is in a closed state, (3) if the implementation is unable to determine the schema definition of a user defined schema type, or (4) the type parameter is null

writeItem

public void writeItem(OutputStream os,
                      Properties props)
               throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Serializes the current item to a Writer according to 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.

Specified by:
writeItem in interface javax.xml.xquery.XQItemAccessor
Parameters:
os - the output stream into which the current item is to be serialized
props - specifies the serialization parameters, null is considered equivalent to an empty Properties object
Throws:
javax.xml.xquery.XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item 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) if there are errors during serialization, or (5) the os parameter is null

writeItem

public void writeItem(Writer ow,
                      Properties props)
               throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Serializes the current item to a Writer according to 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 a Writer, make sure the writer's encoding matches the encoding parameter if specified as a property or the default encoding.

Specified by:
writeItem in interface javax.xml.xquery.XQItemAccessor
Parameters:
ow - the writer object into which the current item is to be serialized
props - specifies the serialization parameters, null is considered equivalent to an empty Properties object
Throws:
javax.xml.xquery.XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item 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) if there are errors during serialization, or (5) the ow parameter is null

writeItemToResult

public void writeItemToResult(Result result)
                       throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Writes the current item to a Result. First the item is normalized as described in XSLT 2.0 and XQuery 1.0 serialization. Subsequently it is serialized to the Result 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:

Specified by:
writeItemToResult in interface javax.xml.xquery.XQItemAccessor
Parameters:
result - the result object into which the item is to be serialized
Throws:
javax.xml.xquery.XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item 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 current item into the Result object, or (5) the result parameter is null

writeItemToSAX

public void writeItemToSAX(ContentHandler saxHandler)
                    throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQItemAccessor
Writes the current item to a SAX handler, as described in 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. 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.

Specified by:
writeItemToSAX in interface javax.xml.xquery.XQItemAccessor
Parameters:
saxHandler - the SAX content handler, optionally a lexical handler
Throws:
javax.xml.xquery.XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item 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 XDM instance into a SAX event stream, or (5) the saxhdlr parameter is null

absolute

public boolean absolute(int itempos)
                 throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Moves the 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.

Specified by:
absolute in interface javax.xml.xquery.XQSequence
Parameters:
itempos - the item position to jump to
Returns:
true if the current position is within the sequence, false otherwise
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state

afterLast

public void afterLast()
               throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Move to the position after the last item.

Specified by:
afterLast in interface javax.xml.xquery.XQSequence
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state

beforeFirst

public void beforeFirst()
                 throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Moves to the position before the first item.

Specified by:
beforeFirst in interface javax.xml.xquery.XQSequence
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state

count

public int count()
          throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Returns a number indicating the number of items in the sequence.

Specified by:
count in interface javax.xml.xquery.XQSequence
Returns:
the number of items in this sequence
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward-only, or (2) the sequence is closed

first

public boolean first()
              throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Moves to the first item in the sequence. The method returns 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.

Specified by:
first in interface javax.xml.xquery.XQSequence
Returns:
true if the sequence was positioned on the first item, false otherwise
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state

getItem

public javax.xml.xquery.XQItem getItem()
                                throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Get the current item as an immutable 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.

Specified by:
getItem in interface javax.xml.xquery.XQSequence
Returns:
an XQItem object
Throws:
javax.xml.xquery.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.

getPosition

public int getPosition()
                throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
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 the isOnItem method to verify if the cursor is positioned on the item.

Calling this method on an empty sequence will return 0.

Specified by:
getPosition in interface javax.xml.xquery.XQSequence
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward-only, or (2) the sequence is closed

getSequenceAsStream

public javax.xml.stream.XMLStreamReader getSequenceAsStream()
                                                     throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
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. 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.

Specified by:
getSequenceAsStream in interface javax.xml.xquery.XQSequence
Returns:
an XML reader object as XMLStreamReader
Throws:
javax.xml.xquery.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

public String getSequenceAsString(Properties props)
                           throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
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.

Specified by:
getSequenceAsString in interface javax.xml.xquery.XQSequence
Parameters:
props - specifies the serialization parameters, null is considered equivalent to an empty Properties object
Returns:
the serialized representation of the sequence
Throws:
javax.xml.xquery.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

public boolean isAfterLast()
                    throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Checks if the current position is after the last item in the sequence. Calling this method on an empty sequence will return false.

Specified by:
isAfterLast in interface javax.xml.xquery.XQSequence
Returns:
true if the current position is after the last item, false otherwise
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state

isBeforeFirst

public boolean isBeforeFirst()
                      throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Checks if the current position before the first item in the sequence. Calling this method on an empty sequence will return false.

Specified by:
isBeforeFirst in interface javax.xml.xquery.XQSequence
Returns:
true if the current position is before the first item, false otherwise
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state

isFirst

public boolean isFirst()
                throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Checks if the current position at the first item in the sequence. Calling this method on an empty sequence will return false.

Specified by:
isFirst in interface javax.xml.xquery.XQSequence
Returns:
true if the current position is at the first item, false otherwise
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state

isLast

public boolean isLast()
               throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Checks if the current position at the last item in the sequence. Calling this method on an empty sequence will return false.

Specified by:
isLast in interface javax.xml.xquery.XQSequence
Returns:
true if the current position is at the last item, false otherwise
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state

isOnItem

public boolean isOnItem()
                 throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Check if the sequence is positioned on an item or not. Calling this method on an empty sequence will return false.

Specified by:
isOnItem in interface javax.xml.xquery.XQSequence
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:
javax.xml.xquery.XQException - if the sequence is in a closed state

isScrollable

public boolean isScrollable()
                     throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Checks if the sequence is scrollable.

Specified by:
isScrollable in interface javax.xml.xquery.XQSequence
Returns:
true if the sequence can be scrolled backward or forward, false otherwise
Throws:
javax.xml.xquery.XQException - if the sequence is in a closed state

last

public boolean last()
             throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Moves to the last item in the sequence. This method returns 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.

Specified by:
last in interface javax.xml.xquery.XQSequence
Returns:
true if the sequence was positioned on the last item, false otherwise
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state

next

public boolean next()
             throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Moves to the next item in the sequence. Calling this method on an empty sequence will return false.

Specified by:
next in interface javax.xml.xquery.XQSequence
Returns:
true if the new item is valid, false if there are no more items
Throws:
javax.xml.xquery.XQException - if the sequence is in a closed state

previous

public boolean previous()
                 throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Moves to the previous item in the sequence. Calling this method on an empty sequence will return false.

Specified by:
previous in interface javax.xml.xquery.XQSequence
Returns:
true if the new current position is within the sequence, (i.e., not before first); false otherwise.
Throws:
javax.xml.xquery.XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state.

relative

public boolean relative(int itempos)
                 throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
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. Calling 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.

Specified by:
relative in interface javax.xml.xquery.XQSequence
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:
javax.xml.xquery.XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state.

writeSequence

public void writeSequence(OutputStream os,
                          Properties props)
                   throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Serializes the sequence starting from the current position to an 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.

Specified by:
writeSequence in interface javax.xml.xquery.XQSequence
Parameters:
os - the output stream into which the sequence is to be serialized
props - specifies the serialization parameters, null is considered equivalent to an empty Properties object
Throws:
javax.xml.xquery.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

writeSequence

public void writeSequence(Writer ow,
                          Properties props)
                   throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
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 a Writer, 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.

Specified by:
writeSequence in interface javax.xml.xquery.XQSequence
Parameters:
ow - the writer object into which the sequence is to be serialized
props - specifies the serialization parameters, null is considered equivalent to an empty Properties object
Throws:
javax.xml.xquery.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

writeSequenceToResult

public void writeSequenceToResult(Result result)
                           throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
Writes the entire sequence starting from the current position to a 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.
Note that the normalization process can fail, in which case an XQException is thrown. An XQJ implementation must at least support the following implementations:

Specified by:
writeSequenceToResult in interface javax.xml.xquery.XQSequence
Parameters:
result - the result object into which the sequence is to be serialized
Throws:
javax.xml.xquery.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

writeSequenceToSAX

public void writeSequenceToSAX(ContentHandler saxHandler)
                        throws javax.xml.xquery.XQException
Description copied from interface: javax.xml.xquery.XQSequence
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 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.

Specified by:
writeSequenceToSAX in interface javax.xml.xquery.XQSequence
Parameters:
saxHandler - the SAX content handler, optionally a lexical handler
Throws:
javax.xml.xquery.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


Copyright (c) Saxonica Limited. All rights reserved.