net.sf.saxon.value

Class Value

Implemented Interfaces:
Serializable, SequenceIterable, ValueRepresentation
Known Direct Subclasses:
AtomicValue, Closure, EmptySequence, IntegerRange, SequenceExtent, ShareableSequence, SingletonNode

public abstract class Value
extends java.lang.Object
implements Serializable, SequenceIterable, ValueRepresentation

A value is the result of an expression but it is also an expression in its own right. Note that every value can be regarded as a sequence - in many cases, a sequence of length one.

Field Summary

static Class[]
EMPTY_CLASS_ARRAY
static int
INDETERMINATE_ORDERING
Constant returned by compareTo() method to indicate an indeterminate ordering between two values

Fields inherited from interface net.sf.saxon.om.ValueRepresentation

EMPTY_VALUE_ARRAY

Method Summary

Item
asItem()
Return the value in the form of an Item
static Item
asItem(ValueRepresentation value)
Static method to make an Item from a Value
static SequenceIterator
asIterator(ValueRepresentation val)
Static method to get an Iterator over any ValueRepresentation (which may be either a Value or a NodeInfo
static Value
asValue(ValueRepresentation val)
Static method to make a Value from a given Item (which may be either an AtomicValue or a NodeInfo
void
checkPermittedContents(SchemaType parentType, StaticContext env, boolean whole)
Check statically that the results of the expression are capable of constructing the content of a given schema type.
static Value
convertJavaObjectToXPath(Object object, SequenceType requiredType, XPathContext context)
Convert a Java object to an XPath value.
Object
convertToJava(Class target, XPathContext context)
Convert to Java object (for passing to external functions)
static Object
convertToJava(Item item)
Convert an XPath value to a Java object.
boolean
effectiveBooleanValue()
Get the effective boolean value of the expression.
boolean
equals(Object obj)
Compare two (sequence) values for equality.
static Value
fromItem(Item item)
Static method to get a Value from an Item
CharSequence
getCanonicalLexicalRepresentation()
Get the canonical lexical representation as defined in XML Schema.
int
getCardinality()
Determine the cardinality
ItemType
getItemType(TypeHierarchy th)
Determine the data type of the items in the expression, if possible
static SequenceIterator
getIterator(ValueRepresentation val)
Get a SequenceIterator over a ValueRepresentation
int
getLength()
Get the length of the sequence
Comparable
getSchemaComparable()
Get a Comparable value that implements the XML Schema ordering comparison semantics for this value.
String
getStringValue()
Convert the value to a string, using the serialization rules.
CharSequence
getStringValueCS()
Get the value of the item as a CharSequence.
Item
itemAt(int n)
Get the n'th item in the sequence (starting from 0).
abstract SequenceIterator
iterate()
Iterate over the items contained in this value.
SequenceIterator
iterate(XPathContext context)
Return an iterator over the results of evaluating an expression
static QNameValue
makeQNameValue(Object object, Configuration config)
Temporary method to make a QNameValue from a JAXP 1.3 QName, without creating a compile-time link to the JDK 1.5 QName class
void
process(XPathContext context)
Process the value as an instruction, without returning any tail calls
Value
reduce()
Reduce a value to its simplest form.
static double
stringToNumber(CharSequence s)
Static method to convert strings to doubles.
String
toString()
Convert to a string for diagnostic output

Field Details

EMPTY_CLASS_ARRAY

public static final Class[] EMPTY_CLASS_ARRAY

INDETERMINATE_ORDERING

public static final int INDETERMINATE_ORDERING
Constant returned by compareTo() method to indicate an indeterminate ordering between two values

Method Details

asItem

public Item asItem()
            throws XPathException
Return the value in the form of an Item
Returns:
the value in the form of an Item

asItem

public static Item asItem(ValueRepresentation value)
            throws XPathException
Static method to make an Item from a Value
Parameters:
value - the value to be converted
Returns:
null if the value is an empty sequence; or the only item in the value if it is a singleton sequence
Throws:
XPathException - if the Value contains multiple items

asIterator

public static SequenceIterator asIterator(ValueRepresentation val)
            throws XPathException
Static method to get an Iterator over any ValueRepresentation (which may be either a Value or a NodeInfo
Parameters:
val - The supplied value, or null, indicating the empty sequence.
Returns:
The supplied value, if it is a value, or a SingletonNode that wraps the item, if it is a node. If the supplied value was null, return an EmptySequence

asValue

public static Value asValue(ValueRepresentation val)
Static method to make a Value from a given Item (which may be either an AtomicValue or a NodeInfo
Parameters:
val - The supplied value, or null, indicating the empty sequence.
Returns:
The supplied value, if it is a value, or a SingletonNode that wraps the item, if it is a node. If the supplied value was null, return an EmptySequence

checkPermittedContents

public void checkPermittedContents(SchemaType parentType,
                                   StaticContext env,
                                   boolean whole)
            throws XPathException
Check statically that the results of the expression are capable of constructing the content of a given schema type.
Parameters:
parentType - The schema type
env - the static context
whole - true if this value accounts for the entire content of the containing node
Throws:
XPathException - if the expression doesn't match the required content type

convertJavaObjectToXPath

public static Value convertJavaObjectToXPath(Object object,
                                             SequenceType requiredType,
                                             XPathContext context)
            throws XPathException
Convert a Java object to an XPath value. This method is called to handle the result of an external function call, and also to process global parameters passed to the stylesheet or query.
Parameters:
object - The Java object to be converted
requiredType - The required type of the result (if known)
context - The XPath dynamic context
Returns:
the result of converting the value. If the value is null, returns null.

convertToJava

public Object convertToJava(Class target,
                            XPathContext context)
            throws XPathException
Convert to Java object (for passing to external functions)
Parameters:
target - the required target class
context - the XPath dynamic evaluation context
Returns:
the (boxed) Java object that best represents the XPath value

convertToJava

public static Object convertToJava(Item item)
            throws XPathException
Convert an XPath value to a Java object. An atomic value is returned as an instance of the best available Java class. If the item is a node, the node is "unwrapped", to return the underlying node in the original model (which might be, for example, a DOM or JDOM node).
Parameters:
item - the item to be converted
Returns:
the value after conversion

effectiveBooleanValue

public boolean effectiveBooleanValue()
            throws XPathException
Get the effective boolean value of the expression. This returns false if the value is the empty sequence, a zero-length string, a number equal to zero, or the boolean false. Otherwise it returns true.
Returns:
the effective boolean value
Throws:
XPathException - if any dynamic error occurs evaluating the expression

equals

public boolean equals(Object obj)
Compare two (sequence) values for equality. This method implements the XPath eq operator, for cases where it is defined. For values containing nodes, nodes are compared for identity. In cases where eq is not defined, it throws ClassCastException. In cases where the result of eq is an empty sequence, this function returns false, except that two empty sequences compare equal. The method also returns a ClassCastException if any failure occurs evaluating either of the values.

fromItem

public static Value fromItem(Item item)
Static method to get a Value from an Item
Parameters:
item - the supplied item
Returns:
the item expressed as a Value

getCanonicalLexicalRepresentation

public CharSequence getCanonicalLexicalRepresentation()
Get the canonical lexical representation as defined in XML Schema. This is not always the same as the result of casting to a string according to the XPath rules.
Returns:
the canonical lexical representation if defined in XML Schema; otherwise, the result of casting to string according to the XPath 2.0 rules

getCardinality

public int getCardinality()
Determine the cardinality
Returns:
the cardinality

getItemType

public ItemType getItemType(TypeHierarchy th)
Determine the data type of the items in the expression, if possible
Parameters:
th - The TypeHierarchy. Can be null if the target is an AtomicValue.
Returns:
for the default implementation: AnyItemType (not known)

getIterator

public static SequenceIterator getIterator(ValueRepresentation val)
            throws XPathException
Get a SequenceIterator over a ValueRepresentation
Parameters:
val - the value to iterate over
Returns:
the iterator

getLength

public int getLength()
            throws XPathException
Get the length of the sequence
Returns:
the number of items in the sequence

getSchemaComparable

public Comparable getSchemaComparable()
Returns:
a Comparable that follows XML Schema comparison rules

getStringValue

public String getStringValue()
            throws XPathException
Convert the value to a string, using the serialization rules. For atomic values this is the same as a cast; for sequence values it gives a space-separated list.
Specified by:
getStringValue in interface ValueRepresentation
Throws:
XPathException - The method can fail if evaluation of the value has been deferred, and if a failure occurs during the deferred evaluation. No failure is possible in the case of an AtomicValue.

getStringValueCS

public CharSequence getStringValueCS()
            throws XPathException
Get the value of the item as a CharSequence. This is in some cases more efficient than the version of the method that returns a String.
Specified by:
getStringValueCS in interface ValueRepresentation

itemAt

public Item itemAt(int n)
            throws XPathException
Get the n'th item in the sequence (starting from 0). This is defined for all Values, but its real benefits come for a sequence Value stored extensionally (or for a MemoClosure, once all the values have been read)
Parameters:
n - position of the required item, counting from zero.
Returns:
the n'th item in the sequence, where the first item in the sequence is numbered zero. If n is negative or >= the length of the sequence, returns null.

iterate

public abstract SequenceIterator iterate()
            throws XPathException
Iterate over the items contained in this value.
Returns:
an iterator over the sequence of items
Throws:
XPathException - if a dynamic error occurs. This is possible only in the case of values that are materialized lazily, that is, where the iterate() method leads to computation of an expression that delivers the values.

iterate

public final SequenceIterator iterate(XPathContext context)
            throws XPathException
Return an iterator over the results of evaluating an expression
Specified by:
iterate in interface SequenceIterable
Parameters:
context - the dynamic evaluation context (not used in this implementation)
Returns:
an iterator over the items delivered by the expression

makeQNameValue

public static QNameValue makeQNameValue(Object object,
                                        Configuration config)
Temporary method to make a QNameValue from a JAXP 1.3 QName, without creating a compile-time link to the JDK 1.5 QName class
Parameters:
object - an instance of javax.xml.namespace.QName
config - the Saxon configuration (used for dynamic loading)
Returns:
a corresponding Saxon QNameValue, or null if any error occurs performing the conversion

process

public void process(XPathContext context)
            throws XPathException
Process the value as an instruction, without returning any tail calls
Parameters:
context - The dynamic context, giving access to the current node, the current variables, etc.

reduce

public Value reduce()
            throws XPathException
Reduce a value to its simplest form. If the value is a closure or some other form of deferred value such as a FunctionCallPackage, then it is reduced to a SequenceExtent. If it is a SequenceExtent containing a single item, then it is reduced to that item. One consequence that is exploited by class FilterExpression is that if the value is a singleton numeric value, then the result will be an instance of NumericValue
Returns:
the value in simplified form

stringToNumber

public static double stringToNumber(CharSequence s)
            throws NumberFormatException
Static method to convert strings to doubles.
Parameters:
s - the String to be converted
Returns:
a double representing the value of the String

toString

public String toString()
Convert to a string for diagnostic output