Package com.saxonica.xqj

## Class SaxonXQForwardSequence

- java.lang.Object
- - com.saxonica.xqj.Closable
  - - com.saxonica.xqj.SaxonXQForwardSequence

- All Implemented Interfaces:
    `XQItemAccessor`, `XQResultSequence`, `XQSequence`

      public class SaxonXQForwardSequence
      extends Closable
      implements 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

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `SaxonXQForwardSequence​(FocusTrackingIterator iterator, SaxonXQPreparedExpression expression)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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.
    `java.lang.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`.
    `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`.
    `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.
    `java.lang.String` | `getItemAsString​(java.util.Properties props)` | Serializes the current item according to the XSLT 2.0 and XQuery 1.0 serialization.
    `XQItemType` | `getItemType()` | Gets the type of the item.
    `long` | `getLong()` | Gets the current item as a `long`.
    `org.w3c.dom.Node` | `getNode()` | Gets the item as a DOM node.
    `java.net.URI` | `getNodeUri()` | Returns the URI for this item.
    `java.lang.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.
    `java.lang.String` | `getSequenceAsString​(java.util.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​(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​(java.io.OutputStream os, java.util.Properties props)` | Serializes the current item to a `Writer` according to XSLT 2.0 and XQuery 1.0 serialization.
    `void` | `writeItem​(java.io.Writer ow, java.util.Properties props)` | Serializes the current item to a `Writer` according to XSLT 2.0 and XQuery 1.0 serialization.
    `void` | `writeItemToResult​(javax.xml.transform.Result result)` | Writes the current item to a `Result`.
    `void` | `writeItemToSAX​(org.xml.sax.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​(java.io.OutputStream os, java.util.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​(java.io.Writer ow, java.util.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​(javax.xml.transform.Result result)` | Writes the entire sequence starting from the current position to a `Result`.
    `void` | `writeSequenceToSAX​(org.xml.sax.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 com.saxonica.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​(FocusTrackingIterator iterator,
                                           SaxonXQPreparedExpression expression)

  - ### Method Detail

    - #### getConnection

          public XQConnection getConnection()
                                     throws XQException

      Description copied from interface: `XQResultSequence`
      Gets the XQuery connection associated with this result sequence
      Specified by:
        `getConnection` in interface `XQResultSequence`
      Returns:
        the connection associated with this result sequence
      Throws:
        `XQException` - if the result sequence is in a closed state

    - #### getAtomicValue

          public java.lang.String getAtomicValue()
                                          throws XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        the string representation of the item
      Throws:
        `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 XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        a `boolean` representing the current item
      Throws:
        `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 XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        a `byte` representing the current item
      Throws:
        `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 XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        a `double` representing the current item
      Throws:
        `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 XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        a `float` representing the current item
      Throws:
        `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 XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        an `int` representing the current item
      Throws:
        `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 XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        an XML reader object as `XMLStreamReader`
      Throws:
        `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 java.lang.String getItemAsString​(java.util.Properties props)
                                           throws XQException

      Description copied from interface: `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 `XQItemAccessor`
      Parameters:
        `props` - specifies the serialization parameters, `null` is considered equivalent to an empty `Properties` object
      Returns:
        the serialized representation of the item
      Throws:
        `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 XQItemType getItemType()
                                 throws XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        the type of the item
      Throws:
        `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 XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        a `long` representing the current item
      Throws:
        `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 org.w3c.dom.Node getNode()
                                   throws XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        a DOM node representing the current item
      Throws:
        `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 java.net.URI getNodeUri()
                                  throws XQException

      Description copied from interface: `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 `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:
        `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 java.lang.Object getObject()
                                     throws XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        an object representing the current item
      Throws:
        `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 XQException

      Description copied from interface: `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 `XQItemAccessor`
      Returns:
        a `short` representing the current item
      Throws:
        `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​(XQItemType type)
                             throws XQException

      Description copied from interface: `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 `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:
        `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​(java.io.OutputStream os,
                                java.util.Properties props)
                         throws XQException

      Description copied from interface: `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 `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:
        `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​(java.io.Writer ow,
                                java.util.Properties props)
                         throws XQException

      Description copied from interface: `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 `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:
        `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​(javax.xml.transform.Result result)
                                 throws XQException

      Description copied from interface: `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:
      - `javax.xml.transform.dom.DOMResult`
      - `javax.xml.transform.sax.SAXResult`
      - `javax.xml.transform.stream.StreamResult`
      Specified by:
        `writeItemToResult` in interface `XQItemAccessor`
      Parameters:
        `result` - the result object into which the item is to be serialized
      Throws:
        `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​(org.xml.sax.ContentHandler saxHandler)
                              throws XQException

      Description copied from interface: `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 `XQItemAccessor`
      Parameters:
        `saxHandler` - the SAX content handler, optionally a lexical handler
      Throws:
        `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 XQException

      Description copied from interface: `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 `XQSequence`
      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

          public void afterLast()
                         throws XQException

      Description copied from interface: `XQSequence`
      Move to the position after the last item.
      Specified by:
        `afterLast` in interface `XQSequence`
      Throws:
        `XQException` - if (1) the sequence is forward only, or (2) the sequence is in a closed state

    - #### beforeFirst

          public void beforeFirst()
                           throws XQException

      Description copied from interface: `XQSequence`
      Moves to the position before the first item.
      Specified by:
        `beforeFirst` in interface `XQSequence`
      Throws:
        `XQException` - if (1) the sequence is forward only, or (2) the sequence is in a closed state

    - #### count

          public int count()
                    throws XQException

      Description copied from interface: `XQSequence`
      Returns a number indicating the number of items in the sequence.
      Specified by:
        `count` in interface `XQSequence`
      Returns:
        the number of items in this sequence
      Throws:
        `XQException` - if (1) the sequence is forward-only, or (2) the sequence is closed

    - #### first

          public boolean first()
                        throws XQException

      Description copied from interface: `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 `XQSequence`
      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

          public XQItem getItem()
                         throws XQException

      Description copied from interface: `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 `XQSequence`
      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.

    - #### getPosition

          public int getPosition()
                          throws XQException

      Description copied from interface: `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 `XQSequence`
      Throws:
        `XQException` - if (1) the sequence is forward-only, or (2) the sequence is closed

    - #### getSequenceAsStream

          public javax.xml.stream.XMLStreamReader getSequenceAsStream()
                                                               throws XQException

      Description copied from interface: `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 `XQSequence`
      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

          public java.lang.String getSequenceAsString​(java.util.Properties props)
                                               throws XQException

      Description copied from interface: `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 `XQSequence`
      Parameters:
        `props` - specifies the serialization parameters, `null` is considered equivalent to an empty `Properties` 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

          public boolean isAfterLast()
                              throws XQException

      Description copied from interface: `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 `XQSequence`
      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

          public boolean isBeforeFirst()
                                throws XQException

      Description copied from interface: `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 `XQSequence`
      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

          public boolean isFirst()
                          throws XQException

      Description copied from interface: `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 `XQSequence`
      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

          public boolean isLast()
                         throws XQException

      Description copied from interface: `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 `XQSequence`
      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

    - #### isOnItem

          public boolean isOnItem()
                           throws XQException

      Description copied from interface: `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 `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:
        `XQException` - if the sequence is in a closed state

    - #### isScrollable

          public boolean isScrollable()
                               throws XQException

      Description copied from interface: `XQSequence`
      Checks if the sequence is scrollable.
      Specified by:
        `isScrollable` in interface `XQSequence`
      Returns:
        `true` if the sequence can be scrolled backward or forward, `false` otherwise
      Throws:
        `XQException` - if the sequence is in a closed state

    - #### last

          public boolean last()
                       throws XQException

      Description copied from interface: `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 `XQSequence`
      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

          public boolean next()
                       throws XQException

      Description copied from interface: `XQSequence`
      Moves to the next item in the sequence. Calling this method on an empty sequence will return `false`.
      Specified by:
        `next` in interface `XQSequence`
      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

          public boolean previous()
                           throws XQException

      Description copied from interface: `XQSequence`
      Moves to the previous item in the sequence. Calling this method on an empty sequence will return `false`.
      Specified by:
        `previous` in interface `XQSequence`
      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

          public boolean relative​(int itempos)
                           throws XQException

      Description copied from interface: `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 `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:
        `XQException` - if (1) the sequence is forward only, or (2) the sequence is in a closed state.

    - #### writeSequence

          public void writeSequence​(java.io.OutputStream os,
                                    java.util.Properties props)
                             throws XQException

      Description copied from interface: `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 `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:
        `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​(java.io.Writer ow,
                                    java.util.Properties props)
                             throws XQException

      Description copied from interface: `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 `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:
        `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​(javax.xml.transform.Result result)
                                     throws XQException

      Description copied from interface: `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:
      - `javax.xml.transform.dom.DOMResult`
      - `javax.xml.transform.sax.SAXResult`
      - `javax.xml.transform.stream.StreamResult`
      Specified by:
        `writeSequenceToResult` in interface `XQSequence`
      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 the `Result` object, or (5) the `result` parameter is `null`

    - #### writeSequenceToSAX

          public void writeSequenceToSAX​(org.xml.sax.ContentHandler saxHandler)
                                  throws XQException

      Description copied from interface: `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 `XQSequence`
      Parameters:
        `saxHandler` - 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) the `saxhdlr` parameter is `null`