org.exist.xquery.value
Interface Sequence

All Known Subinterfaces:

ExtNodeSet, MemoryNodeSet, NodeSet, NodeValue

All Known Implementing Classes:

AbstractDateTimeValue, AbstractNodeSet, AbstractSequence, AnyURIValue, AtomicValue, AttributeImpl, AVLTreeNodeSet, Base64BinaryDocument, BinaryValue, BinaryValueFromBinaryString, BinaryValueFromFile, BinaryValueFromInputStream, BooleanValue, CDATASectionImpl, CommentImpl, ComputableValue, DateTimeValue, DateValue, DayTimeDurationValue, DecimalValue, DeferredFunctionCall, DocumentImpl, DoubleValue, DurationValue, ElementImpl, EmptyNodeSet, EmptySequence, ExtArrayNodeSet, FloatValue, FunctionReference, GDayValue, GMonthDayValue, GMonthValue, GroupedValueSequence, GYearMonthValue, GYearValue, InMemoryNodeSet, IntegerValue, JavaObjectValue, NamespaceNode, NewArrayNodeSet, NodeImpl, NodeProxy, NumericValue, OrderedValueSequence, PreorderedValueSequence, ProcessingInstructionImpl, QNameValue, RangeSequence, ReferenceNode, SortedNodeSet, StringValue, TextImpl, TimeValue, UntypedAtomicValue, ValueSequence, VirtualNodeSet, YearMonthDurationValue

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.
java.util.Iterator<Collection>	getCollectionIterator() Return an iterator on all collections referenced by documents contained in this sequence..
DocumentSet	getDocumentSet() Returns the set of documents from which the node items in this sequence have been selected.
int	getItemCount() Returns the number of items contained in the sequence.
int	getItemType() Return the primary type to which all items in this sequence belong.
int	getState()
java.lang.String	getStringValue() Convert the sequence to a string.
boolean	hasChanged(int previousState)
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	isCacheable()
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	nodeMoved(NodeId oldNodeId, StoredNode newNode) Node sets may implement this method to be informed of storage address and node id changes after updates.
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.
MemoryNodeSet	toMemNodeSet() Convert the sequence into an in-memory node set.
NodeSet	toNodeSet() Convert the sequence into a NodeSet.
SequenceIterator	unorderedIterator() Returns an iterator over all items in the sequence.

Field Detail

EMPTY_SEQUENCE

static final Sequence EMPTY_SEQUENCE

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

Method Detail

add

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

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

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

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

unorderedIterator

SequenceIterator unorderedIterator()
                                   throws XPathException

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

Throws:

XPathException

getItemCount

int getItemCount()

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

Returns:

The number of items in the sequence

isEmpty

boolean isEmpty()

Returns whether the sequence is empty or not.

Returns:

true is the sequence is empty

hasOne

boolean hasOne()

Returns whether the sequence has just one item or not.

Returns:

true is the sequence has just one item

hasMany

boolean hasMany()

Returns whether the sequence more than one item or not.

Returns:

true is the sequence more than one item

removeDuplicates

void removeDuplicates()

Explicitely remove all duplicate nodes from this sequence.

getCardinality

int getCardinality()

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

See Also:

Cardinality

itemAt

Item itemAt(int pos)

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

Parameters:

pos -

convertTo

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

java.lang.String getStringValue()
                                throws XPathException

Convert the sequence to a string.

Throws:

XPathException

effectiveBooleanValue

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

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.

toMemNodeSet

MemoryNodeSet toMemNodeSet()
                           throws XPathException

Convert the sequence into an in-memory node set. If the sequence contains items which are not nodes, an XPathException is thrown. For persistent node sets, this method will return null. Call isPersistentSet() to check if the sequence is a persistent node set.

Throws:

XPathException - if the sequence contains items which are not nodes or is a persistent node set

getDocumentSet

DocumentSet getDocumentSet()

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

getCollectionIterator

java.util.Iterator<Collection> getCollectionIterator()

Return an iterator on all collections referenced by documents contained in this sequence..

conversionPreference

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

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

boolean isCached()

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

setIsCached

void setIsCached(boolean cached)

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

Parameters:

cached -

clearContext

void clearContext(int contextId)
                  throws XPathException

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.

Throws:

XPathException

setSelfAsContext

void setSelfAsContext(int contextId)
                      throws XPathException

Throws:

XPathException

isPersistentSet

boolean isPersistentSet()

nodeMoved

void nodeMoved(NodeId oldNodeId,
               StoredNode newNode)

Node sets may implement this method to be informed of storage address and node id changes after updates.

Parameters:

oldNodeId -

newNode -

See Also:

UpdateListener

isCacheable

boolean isCacheable()

getState

int getState()

hasChanged

boolean hasChanged(int previousState)