net.sf.saxon.value
Class Value

java.lang.Object
  net.sf.saxon.value.Value

All Implemented Interfaces:

Expression, java.io.Serializable, ValueRepresentation

Direct Known Subclasses:

AtomicValue, Closure, EmptySequence, IntegerRange, SequenceExtent, ShareableSequence, SingletonNode

public abstract class Value

extends java.lang.Object

implements Expression, java.io.Serializable, 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.

See Also:

Serialized Form

Field Summary

static java.lang.Class[]

EMPTY_CLASS_ARRAY

Fields inherited from interface net.sf.saxon.expr.Expression

EVALUATE_METHOD, ITERATE_METHOD, PROCESS_METHOD

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

EMPTY_VALUE_ARRAY

Constructor Summary

Value()

Method Summary

static Item	asItem(ValueRepresentation value) Static method to make an Item from a Value
static SequenceIterator	asIterator(ValueRepresentation val, XPathContext context) 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 java.lang.CharSequence	collapseWhitespace(java.lang.CharSequence in) Collapse whitespace as defined in XML Schema
static java.lang.Object	convert(Item item) Internal method to convert an XPath value to a Java object.
static Value	convertJavaObjectToXPath(java.lang.Object object, SequenceType requiredType, Configuration config) Convert a Java object to an XPath value.
java.lang.Object	convertToJava(java.lang.Class target, XPathContext context) Convert to Java object (for passing to external functions)
void	display(int level, NamePool pool, java.io.PrintStream out) Diagnostic display of the expression
boolean	effectiveBooleanValue(XPathContext context) Get the effective boolean value of the expression.
boolean	equals(java.lang.Object obj) Compare two (sequence) values for equality.
java.lang.String	evaluateAsString(XPathContext context) Evaluate an expression as a String.
Item	evaluateItem(XPathContext context) Evaluate as a singleton item (or empty sequence).
int	getCardinality() Determine the cardinality
int	getDependencies() Determine which aspects of the context the expression depends on.
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
Container	getParentExpression() Get the expression that immediately contains this expression.
int	getSpecialProperties() Get the static properties of this expression (other than its type).
java.lang.String	getStringValue() Convert the value to a string, using the serialization rules.
int	hashCode() Return a hash code to support the equals() function
Item	itemAt(int n) Get the n'th item in the sequence (starting from 0).
java.util.Iterator	iterateSubExpressions() Get the sub-expressions of this expression.
static QNameValue	makeQNameValue(java.lang.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
static java.lang.CharSequence	normalizeWhitespace(java.lang.CharSequence in) Normalize whitespace as defined in XML Schema
Expression	optimize(Optimizer opt, StaticContext env, ItemType contextItemType) Optimize an expression
void	process(XPathContext context) Process the value as an instruction, without returning any tail calls
Expression	promote(PromotionOffer offer) Offer promotion for this subexpression.
Value	reduce() Reduce a value to its simplest form.
boolean	schemaEquals(Value obj) Compare two (sequence) values for equality.
Expression	simplify(StaticContext env) Simplify an expression
static double	stringToNumber(java.lang.CharSequence s) Static method to convert strings to numbers.
java.lang.String	toString() Convert to a string for diagnostic output
static java.lang.CharSequence	trimWhitespace(java.lang.CharSequence in) Remove leading and trailing whitespace.
Expression	typeCheck(StaticContext env, ItemType contextItemType) TypeCheck an expression

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.sf.saxon.expr.Expression

getImplementationMethod, iterate

Field Detail

EMPTY_CLASS_ARRAY

public static final java.lang.Class[] EMPTY_CLASS_ARRAY

Constructor Detail

Value

public Value()

Method Detail

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

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,
                                          XPathContext context)
                                   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.

context - The evaluation context. This may be null. It should always be possible to iterate over a value without supplying a context, but sometimes the context can provide access to better error information

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

Throws:

XPathException

stringToNumber

public static double stringToNumber(java.lang.CharSequence s)
                             throws java.lang.NumberFormatException

Static method to convert strings to numbers. Might as well go here as anywhere else.

Parameters:

s - the String to be converted

Returns:

a double representing the value of the String

Throws:

java.lang.NumberFormatException - if the value cannot be converted

normalizeWhitespace

public static java.lang.CharSequence normalizeWhitespace(java.lang.CharSequence in)

Normalize whitespace as defined in XML Schema

collapseWhitespace

public static java.lang.CharSequence collapseWhitespace(java.lang.CharSequence in)

Collapse whitespace as defined in XML Schema

trimWhitespace

public static java.lang.CharSequence trimWhitespace(java.lang.CharSequence in)

Remove leading and trailing whitespace. This has the same effect as collapseWhitespace, but is cheaper, for use by data types that do not allow internal whitespace.

Parameters:

in - the input string whose whitespace is to be removed

Returns:

the result of removing excess whitespace

getIterator

public static SequenceIterator getIterator(ValueRepresentation val)
                                    throws XPathException

Get a SequenceIterator over a ValueRepresentation

Throws:

XPathException

simplify

public final Expression simplify(StaticContext env)

Simplify an expression

Specified by:

simplify in interface Expression

Returns:

for a Value, this always returns the value unchanged

typeCheck

public final Expression typeCheck(StaticContext env,
                                  ItemType contextItemType)

TypeCheck an expression

Specified by:

typeCheck in interface Expression

Parameters:

env - the static context of the expression

contextItemType - the static type of "." at the point where this expression is invoked. The parameter is set to null if it is known statically that the context item will be undefined. If the type of the context item is not known statically, the argument is set to Type.ITEM_TYPE

Returns:

for a Value, this always returns the value unchanged

optimize

public final Expression optimize(Optimizer opt,
                                 StaticContext env,
                                 ItemType contextItemType)

Optimize an expression

Specified by:

optimize in interface Expression

Parameters:

opt - the optimizer in use. This provides access to supporting functions; it also allows different optimization strategies to be used in different circumstances.

env - the static context of the expression

contextItemType - the static type of "." at the point where this expression is invoked. The parameter is set to null if it is known statically that the context item will be undefined. If the type of the context item is not known statically, the argument is set to Type.ITEM_TYPE

Returns:

for a Value, this always returns the value unchanged

getItemType

public ItemType getItemType(TypeHierarchy th)

Determine the data type of the items in the expression, if possible

Specified by:

getItemType in interface Expression

Parameters:

th - The TypeHierarchy. Can be null if the target is an AtomicValue.

Returns:

for the default implementation: AnyItemType (not known)

getCardinality

public int getCardinality()

Determine the cardinality

Specified by:

getCardinality in interface Expression

Returns:

one of the values StaticProperty.ALLOWS_ONE, StaticProperty.ALLOWS_ZERO_OR_MORE, StaticProperty.ALLOWS_ZERO_OR_ONE, StaticProperty.ALLOWS_ONE_OR_MORE, StaticProperty.EMPTY. This default implementation returns ZERO_OR_MORE (which effectively gives no information).

iterateSubExpressions

public final java.util.Iterator iterateSubExpressions()

Get the sub-expressions of this expression.

Specified by:

iterateSubExpressions in interface Expression

Returns:

for a Value, this always returns an empty array

getParentExpression

public final Container getParentExpression()

Get the expression that immediately contains this expression. This method returns null for an outermost expression; it also return null in the case of literal values. For an XPath expression occurring within an XSLT stylesheet, this method returns the XSLT instruction containing the XPath expression.

Specified by:

getParentExpression in interface Expression

Returns:

the expression that contains this expression, if known; return null if there is no containing expression or if the containing expression is unknown.

getSpecialProperties

public int getSpecialProperties()

Get the static properties of this expression (other than its type). For a Value, the only special property is StaticProperty.NON_CREATIVE.

Specified by:

getSpecialProperties in interface Expression

Returns:

StaticProperty.NON_CREATIVE

promote

public final Expression promote(PromotionOffer offer)

Offer promotion for this subexpression. Values (constant expressions) are never promoted

Specified by:

promote in interface Expression

Parameters:

offer - details of the offer, for example the offer to move expressions that don't depend on the context to an outer level in the containing expression

Returns:

For a Value, this always returns the value unchanged

getDependencies

public final int getDependencies()

Determine which aspects of the context the expression depends on. The result is a bitwise-or'ed value composed from constants such as StaticProperty.VARIABLES and StaticProperty.CURRENT_NODE

Specified by:

getDependencies in interface Expression

Returns:

for a Value, this always returns zero.

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)

Throws:

XPathException

getLength

public int getLength()
              throws XPathException

Get the length of the sequence

Throws:

XPathException

evaluateItem

public Item evaluateItem(XPathContext context)
                  throws XPathException

Evaluate as a singleton item (or empty sequence). Note: this implementation returns the first item in the sequence. The method should not be used unless appropriate type-checking has been done to ensure that the value will be a singleton.

Specified by:

evaluateItem in interface Expression

Parameters:

context - The context in which the expression is to be evaluated

Returns:

the node or atomic value that results from evaluating the expression; or null to indicate that the result is an empty sequence

Throws:

XPathException - if any dynamic error occurs evaluating the expression

process

public void process(XPathContext context)
             throws XPathException

Process the value as an instruction, without returning any tail calls

Specified by:

process in interface Expression

Parameters:

context - The dynamic context, giving access to the current node, the current variables, etc.

Throws:

XPathException

getStringValue

public java.lang.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.

evaluateAsString

public java.lang.String evaluateAsString(XPathContext context)
                                  throws XPathException

Evaluate an expression as a String. This function must only be called in contexts where it is known that the expression will return a single string (or where an empty sequence is to be treated as a zero-length string). Implementations should not attempt to convert the result to a string, other than converting () to "". This method is used mainly to evaluate expressions produced by compiling an attribute value template.

Specified by:

evaluateAsString in interface Expression

Parameters:

context - The context in which the expression is to be evaluated

Returns:

the value of the expression, evaluated in the current context. The expression must return a string or (); if the value of the expression is (), this method returns "".

Throws:

XPathException - if any dynamic error occurs evaluating the expression

java.lang.ClassCastException - if the result type of the expression is not xs:string?

effectiveBooleanValue

public boolean effectiveBooleanValue(XPathContext context)
                              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.

Specified by:

effectiveBooleanValue in interface Expression

Parameters:

context - The context in which the expression is to be evaluated

Returns:

the effective boolean value

Throws:

XPathException - if any dynamic error occurs evaluating the expression

equals

public boolean equals(java.lang.Object obj)

Compare two (sequence) values for equality. This supports identity constraints in XML Schema, which allow list-valued elements and attributes to participate in key and uniqueness constraints. This method returns false if any error occurs during the comparison, or if any of the items in either sequence is a node rather than an atomic value.

schemaEquals

public boolean schemaEquals(Value obj)

Compare two (sequence) values for equality. This supports identity constraints in XML Schema, which allow list-valued elements and attributes to participate in key and uniqueness constraints. This method returns false if any error occurs during the comparison, or if any of the items in either sequence is a node rather than an atomic value.

hashCode

public int hashCode()

Return a hash code to support the equals() function

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.

Specified by:

checkPermittedContents in interface Expression

Parameters:

parentType - The schema type

env - the static context

whole -

Throws:

XPathException - if the expression doesn't match the required content type

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

Throws:

XPathException

convertToJava

public java.lang.Object convertToJava(java.lang.Class target,
                                      XPathContext context)
                               throws XPathException

Convert to Java object (for passing to external functions)

Throws:

XPathException

display

public void display(int level,
                    NamePool pool,
                    java.io.PrintStream out)

Diagnostic display of the expression

Specified by:

display in interface Expression

Parameters:

level - indentation level for this expression

pool - NamePool used to expand any names appearing in the expression

out - Output destination

convertJavaObjectToXPath

public static Value convertJavaObjectToXPath(java.lang.Object object,
                                             SequenceType requiredType,
                                             Configuration config)
                                      throws XPathException

Convert a Java object to an XPath value. This method is called to handle the result of an external function call (but only if the required type is not known), 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)

config - The Configuration: may be null, in which case certain kinds of object (eg. DOM nodes) cannot be handled

Returns:

the result of converting the value. If the value is null, returns null.

Throws:

XPathException

makeQNameValue

public static QNameValue makeQNameValue(java.lang.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

Returns:

a corresponding Saxon QNameValue, or null if any error occurs performing the conversion

toString

public java.lang.String toString()

Convert to a string for diagnostic output

convert

public static java.lang.Object convert(Item item)
                                throws XPathException

Internal method to 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).

Throws:

XPathException