## org.exist.xquery.value
Interface Sequence

All Known Subinterfaces:
  NodeSet, NodeValue

All Known Implementing Classes:
  AbstractNodeSet, AbstractSequence, AtomicValue, DeferredFunctionCall, NodeImpl, NodeProxy

public interface Sequence

This interface represents a sequence as defined in the XPath 2.0 specification. A sequence is a sequence of items. Each item is either an atomic value or a node. A single item is also a sequence, containing only the item. The base classes for `atomic values` and `nodes` thus implement the Sequence interface. Also, a `node set` is a special type of sequence, where all items are of type node.

Field Summary
`static Sequence` `EMPTY_SEQUENCE` Constant representing an empty sequence, i.e.

Method Summary
`void` `add(Item item)` Add an item to the current sequence.
`void` `addAll(Sequence other)` Add all items of the other sequence to this item.
`void` `clearContext(int contextId)` For every item in the sequence, clear any context-dependant information that is stored during query processing.
`int` `conversionPreference(java.lang.Class javaClass)` Returns a preference indicator, indicating the preference of a value to be converted into the given Java class.
`AtomicValue` `convertTo(int requiredType)` Try to convert the sequence into an atomic value.
`boolean` `effectiveBooleanValue()` Get the effective boolean value of this sequence.
`int` `getCardinality()` Returns the cardinality of this sequence.
`DocumentSet` `getDocumentSet()` Returns the set of documents from which the node items in this sequence have been selected.
`int` `getItemType()` Return the primary type to which all items in this sequence belong.
`int` `getLength()` Returns the number of items contained in the sequence.
`java.lang.String` `getStringValue()` Convert the sequence to a string.
`boolean` `hasMany()` Returns whether the sequence more than one item or not.
`boolean` `hasOne()` Returns whether the sequence has just one item or not.
`boolean` `isCached()` Returns true if the sequence is the result of a previous operation and has been cached.
`boolean` `isEmpty()` Returns whether the sequence is empty or not.
`boolean` `isPersistentSet()`
`Item` `itemAt(int pos)` Returns the item located at the specified position within this sequence.
`SequenceIterator` `iterate()` Returns an iterator over all items in the sequence.
`void` `removeDuplicates()` Explicitely remove all duplicate nodes from this sequence.
`void` `setIsCached(boolean cached)` Indicates that the sequence is the result of a previous operation and has not been recomputed.
`void` `setSelfAsContext(int contextId)`
`java.lang.Object` `toJavaObject(java.lang.Class target)` Convert the value into an instance of the specified Java class.
`NodeSet` `toNodeSet()` Convert the sequence into a NodeSet.
`SequenceIterator` `unorderedIterator()` Returns an iterator over all items in the sequence.

Field Detail

### EMPTY_SEQUENCE

    public static final Sequence EMPTY_SEQUENCE

  Constant representing an empty sequence, i.e. a sequence with no item.

Method Detail

### add

    public void add(Item item)
             throws XPathException

  Add an item to the current sequence. An `XPathException` may be thrown if the item's type is incompatible with this type of sequence (e.g. if the sequence is a node set). The sequence may or may not allow duplicate values.

  Parameters:
    `item` -
  Throws:
    `XPathException`

### addAll

    public void addAll(Sequence other)
                throws XPathException

  Add all items of the other sequence to this item. An `XPathException` may be thrown if the type of the items in the other sequence is incompatible with the primary type of this sequence.

  Parameters:
    `other` -
  Throws:
    `XPathException`

### getItemType

    public int getItemType()

  Return the primary type to which all items in this sequence belong. This is `Type.NODE` for node sets, `Type.ITEM` for other sequences with mixed items.

  Returns:
    the primary type of the items in this sequence.

### iterate

    public SequenceIterator iterate()
                             throws XPathException

  Returns an iterator over all items in the sequence. The items are returned in document order where applicable.

  Throws:
    `XPathException` - TODO
    `XPathException` - TODO

### unorderedIterator

    public SequenceIterator unorderedIterator()

  Returns an iterator over all items in the sequence. The returned items may - but need not - to be in document order.

### getLength

    public int getLength()

  Returns the number of items contained in the sequence. Call this method only when necessary, since it can be resource consuming.

  Returns:
    The sequence's length

### isEmpty

    public boolean isEmpty()

  Returns whether the sequence is empty or not.

  Returns:
    `true` is the sequence is empty

### hasOne

    public boolean hasOne()

  Returns whether the sequence has just one item or not.

  Returns:
    `true` is the sequence has just one item

### hasMany

    public boolean hasMany()

  Returns whether the sequence more than one item or not.

  Returns:
    `true` is the sequence more than one item

### removeDuplicates

    public void removeDuplicates()

  Explicitely remove all duplicate nodes from this sequence.

### getCardinality

    public int getCardinality()

  Returns the cardinality of this sequence. The returned value is a combination of flags as defined in `Cardinality`.

  See Also:
    `Cardinality`

### itemAt

    public Item itemAt(int pos)

  Returns the item located at the specified position within this sequence. Items are counted beginning at 0.

  Parameters:
    `pos` -

### convertTo

    public AtomicValue convertTo(int requiredType)
                          throws XPathException

  Try to convert the sequence into an atomic value. The target type should be specified by using one of the constants defined in class `Type`. An `XPathException` is thrown if the conversion is impossible.

  Parameters:
    `requiredType` - one of the type constants defined in class `Type`
  Throws:
    `XPathException`

### getStringValue

    public java.lang.String getStringValue()
                                    throws XPathException

  Convert the sequence to a string.

  Throws:
    `XPathException`

### effectiveBooleanValue

    public boolean effectiveBooleanValue()
                                  throws XPathException

  Get the effective boolean value of this sequence. Will be false if the sequence is empty, true otherwise.

  Throws:
    `XPathException`

### toNodeSet

    public NodeSet toNodeSet()
                      throws XPathException

  Convert the sequence into a NodeSet. If the sequence contains items which are not nodes, an XPathException is thrown.

  Throws:
    `XPathException` - if the sequence contains items which are not nodes.

### getDocumentSet

    public DocumentSet getDocumentSet()

  Returns the set of documents from which the node items in this sequence have been selected. This is for internal use only.

### conversionPreference

    public int conversionPreference(java.lang.Class javaClass)

  Returns a preference indicator, indicating the preference of a value to be converted into the given Java class. Low numbers mean that the value can be easily converted into the given class.

  Parameters:
    `javaClass` -

### toJavaObject

    public java.lang.Object toJavaObject(java.lang.Class target)
                                  throws XPathException

  Convert the value into an instance of the specified Java class.

  Parameters:
    `target` -
  Throws:
    `XPathException`

### isCached

    public boolean isCached()

  Returns true if the sequence is the result of a previous operation and has been cached.

### setIsCached

    public void setIsCached(boolean cached)

  Indicates that the sequence is the result of a previous operation and has not been recomputed.

  Parameters:
    `cached` -

### clearContext

    public void clearContext(int contextId)

  For every item in the sequence, clear any context-dependant information that is stored during query processing. This feature is used for node sets, which may store information about their context node.

### setSelfAsContext

    public void setSelfAsContext(int contextId)

### isPersistentSet

    public boolean isPersistentSet()

Copyright (C) Wolfgang Meier. All rights reserved.