Package net.sf.saxon.value

Class SingletonClosure

java.lang.Object

net.sf.saxon.value.Closure

net.sf.saxon.value.SingletonClosure

All Implemented Interfaces:

ContextOriginator, Sequence

public class SingletonClosure
extends Closure
implements Sequence

A SingletonClosure represents a value that has not yet been evaluated: the value is represented by an expression, together with saved values of all the context variables that the expression depends on. The value of a SingletonClosure is always either a single item or an empty sequence.

The expression may depend on local variables and on the context item; these values are held in the saved XPathContext object that is kept as part of the Closure, and they will always be read from that object. The expression may also depend on global variables; these are unchanging, so they can be read from the Bindery in the normal way. Expressions that depend on other contextual information, for example the values of position(), last(), current(), current-group(), should not be evaluated using this mechanism: they should always be evaluated eagerly. This means that the Closure does not need to keep a copy of these context variables.

Field Summary

Fields inherited from class net.sf.saxon.value.Closure

depth, expression, inputEvaluator, inputIterator, learningEvaluator, savedXPathContext, serialNumber

Constructor Summary

Constructors

Constructor	Description
SingletonClosure(Expression exp, PullEvaluator inputEvaluator, XPathContext context)	Constructor should not be called directly, instances should be made using the make() method.

Method Summary

Modifier and Type	Method	Description
Item	asItem()	Return the value in the form of an Item
int	getLength()	Get the length of the sequence
Item	head()	Get the first item in the sequence.
boolean	isBuilt()
Item	itemAt(int n)	Get the n'th item in the sequence (starting from 0).
SequenceIterator	iterate()	Evaluate the expression in a given context to return an iterator over a sequence
SingletonClosure	makeRepeatable()	Ensure that the sequence is in a form where it can be evaluated more than once.
GroundedValue	materialize()	Return a value containing all the items in the sequence returned by this SequenceIterator

Methods inherited from class net.sf.saxon.value.Closure

getExpression, getSavedXPathContext, reduce, saveContext, setInputEvaluator, setLearningEvaluator, setSavedXPathContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SingletonClosure

public SingletonClosure(Expression exp,
                        PullEvaluator inputEvaluator,
                        XPathContext context)
                 throws XPathException

Constructor should not be called directly, instances should be made using the make() method.

Parameters:

exp - the expression to be lazily evaluated

context - the context in which the expression should be evaluated

Throws:

XPathException - if an error occurs saving the dynamic context

Method Detail

iterate

public SequenceIterator iterate()

Evaluate the expression in a given context to return an iterator over a sequence

Specified by:

iterate in interface Sequence

Specified by:

iterate in class Closure

Returns:

an iterator (specifically, a Saxon SequenceIterator, which is not a Iterator) over all the items

head

public Item head()
          throws XPathException

Get the first item in the sequence.

Specified by:

head in interface Sequence

Overrides:

head in class Closure

Returns:

the first item in the sequence if there is one, or null if the sequence is empty

Throws:

XPathException - in the situation where the sequence is evaluated lazily, and evaluation of the first item causes a dynamic error.

asItem

public Item asItem()
            throws XPathException

Return the value in the form of an Item

Returns:

the value in the form of an Item

Throws:

XPathException - if an error is detected

itemAt

public Item itemAt(int n)
            throws XPathException

Get the n'th item in the sequence (starting from 0). This is defined for all SequenceValues, but its real benefits come for a SequenceValue stored extensionally.

Parameters:

n - the index of the requested item

Returns:

the n'th item in the sequence

Throws:

XPathException - if an error is detected

getLength

public int getLength()
              throws XPathException

Get the length of the sequence

Returns:

the length of the sequence

Throws:

XPathException - if an error is detected

materialize

public GroundedValue materialize()
                          throws XPathException

Return a value containing all the items in the sequence returned by this SequenceIterator

Specified by:

materialize in interface Sequence

Returns:

the corresponding value

Throws:

XPathException - if evaluating the contents of the sequence (lazily) fails with a dynamic error.

makeRepeatable

public SingletonClosure makeRepeatable()

Description copied from interface: Sequence

Ensure that the sequence is in a form where it can be evaluated more than once. Some sequences (for example LazySequence and Closure can only be evaluated once, and this operation causes these to be grounded. However, making it repeatable is not the same as making it grounded; it does not flush out all errors. Indeed, lazy evaluation relies on this property, because an expression that has been lifted out of a loop must not be evaluated unless the loop is executed at least once, to prevent spurious errors.

Specified by:

makeRepeatable in interface Sequence

Overrides:

makeRepeatable in class Closure

Returns:

An equivalent sequence that can be repeatedly evaluated

isBuilt

public boolean isBuilt()