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.