net.sf.saxon.value
Class AtomicValue

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

All Implemented Interfaces:

Serializable, Comparable, SequenceIterable, Item, ValueRepresentation

Direct Known Subclasses:

Base64BinaryValue, BooleanValue, CalendarValue, DurationValue, HexBinaryValue, NumericValue, ObjectValue, QualifiedNameValue, StringValue

public abstract class AtomicValue
extends Value
implements Item

The AtomicValue class corresponds to the concept of an atomic value in the XPath 2.0 data model. Atomic values belong to one of the 19 primitive types defined in XML Schema; or they are of type xs:untypedAtomic; or they are "external objects", representing a Saxon extension to the XPath 2.0 type system.

The AtomicValue class contains some methods that are suitable for applications to use, and many others that are designed for internal use by Saxon itself. These have not been fully classified. At present, therefore, none of the methods on this class should be considered to be part of the public Saxon API.

Author:

Michael H. Kay

See Also:

Serialized Form

Field Summary

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

EMPTY_CLASS_ARRAY, INDETERMINATE_ORDERING

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

EMPTY_VALUE_ARRAY

Constructor Summary

AtomicValue()

Method Summary

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.
AtomicValue	convert(AtomicType targetType, XPathContext context, boolean validate) Convert the value to a given type.
AtomicValue	convert(BuiltInAtomicType schemaType, XPathContext context) Convert the value to a given type.
abstract AtomicValue	convertPrimitive(BuiltInAtomicType requiredType, boolean validate, XPathContext context) Convert a value to another primitive data type, with control over how validation is handled.
abstract AtomicValue	copy(AtomicType typeLabel) Create a copy of this atomic value, with a different type label
boolean	effectiveBooleanValue() Get the effective boolean value of the value
int	getCardinality() Determine the static cardinality
AtomicValue	getComponent(int component) Method to extract components of a value.
ItemType	getItemType(TypeHierarchy th) Determine the data type of the items in the expression, if possible
int	getLength() Get the length of the sequence
abstract BuiltInAtomicType	getPrimitiveType() Determine the primitive type of the value.
abstract String	getStringValue() Convert the value to a string, using the serialization rules.
CharSequence	getStringValueCS() Get the value of the item as a CharSequence.
SequenceIterator	getTypedValue() Get the typed value of this item
AtomicType	getTypeLabel() Determine the data type of the value.
Comparable	getXPathComparable() Get a Comparable value that implements the XPath ordering comparison semantics for this value.
boolean	hasBuiltInType() Test whether the type of this atomic value is a built-in type.
boolean	isMultiValued() Determine whether the value is multivalued, that is, whether it is a sequence that potentially contains more than one item
Item	itemAt(int n) Get the n'th item in the sequence (starting from 0).
SequenceIterator	iterate() Iterate over the (single) item in the sequence
void	process(XPathContext context) Process the instruction, without returning any tail calls
void	setTypeLabel(AtomicType type) Set the type label on this atomic value
String	toString() Get string value.

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

asItem, asItem, asIterator, asValue, compareTo, convert, convertJavaObjectToXPath, convertToJava, equals, fromItem, getCanonicalLexicalRepresentation, getIterator, getSchemaComparable, hashCode, iterate, makeQNameValue, reduce, stringToNumber

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

AtomicValue

public AtomicValue()

Method Detail

setTypeLabel

public void setTypeLabel(AtomicType type)

Set the type label on this atomic value

isMultiValued

public boolean isMultiValued()

Determine whether the value is multivalued, that is, whether it is a sequence that potentially contains more than one item

Specified by:

isMultiValued in class Value

Returns:

false for an atomic value

hasBuiltInType

public boolean hasBuiltInType()

Test whether the type of this atomic value is a built-in type.

getXPathComparable

public Comparable getXPathComparable()

Get a Comparable value that implements the XPath ordering comparison semantics for this value. Returns null if the value is not comparable according to XPath rules. The default implementation returns null. This is overridden for types that allow ordered comparisons in XPath: numeric, boolean, string, date, time, dateTime, yearMonthDuration, dayTimeDuration, and anyURI.

getStringValueCS

public CharSequence getStringValueCS()

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 Item

Specified by:

getStringValueCS in interface ValueRepresentation

Overrides:

getStringValueCS in class Value

Returns:

the string value of the item

See Also:

Item.getStringValue()

process

public void process(XPathContext context)
             throws XPathException

Process the instruction, without returning any tail calls

Overrides:

process in class Value

Parameters:

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

Throws:

XPathException

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)

Overrides:

itemAt in class Value

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.

Throws:

XPathException

getItemType

public ItemType getItemType(TypeHierarchy th)

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

Overrides:

getItemType in class Value

Parameters:

th - The TypeHierarchy. Can be null if the target is an AtomicValue, except in the case where it is an external ObjectValue.

Returns:

for the default implementation: AnyItemType (not known)

getTypeLabel

public AtomicType getTypeLabel()

Determine the data type of the value. This delivers the same answer as getItemType(net.sf.saxon.type.TypeHierarchy), except in the case of external objects (instances of ObjectValue, where the method may deliver a less specific type.

Returns:

for the default implementation: AnyItemType (not known)

getPrimitiveType

public abstract BuiltInAtomicType getPrimitiveType()

Determine the primitive type of the value. This delivers the same answer as getItemType().getPrimitiveItemType(). The primitive types are the 19 primitive types of XML Schema, plus xs:integer, xs:dayTimeDuration and xs:yearMonthDuration, and xs:untypedAtomic. For external objects, the result is AnyAtomicType.

getCardinality

public final int getCardinality()

Determine the static cardinality

Overrides:

getCardinality in class Value

Returns:

code identifying the cardinality

See Also:

Cardinality

convert

public final AtomicValue convert(BuiltInAtomicType schemaType,
                                 XPathContext context)
                          throws XPathException

Convert the value to a given type. The result of the conversion will be an atomic value of the required type. This method works only where the target type is a built-in type.

Parameters:

schemaType - the required atomic type

context -

Returns:

the result of the conversion, if conversion was possible. This will always be an instance of the class corresponding to the type of value requested

Throws:

XPathException - if conversion is not allowed for this required type, or if the particular value cannot be converted

convertPrimitive

public abstract AtomicValue convertPrimitive(BuiltInAtomicType requiredType,
                                             boolean validate,
                                             XPathContext context)

Convert a value to another primitive data type, with control over how validation is handled.

Parameters:

requiredType - type code of the required atomic type

validate - true if validation is required. If set to false, the caller guarantees that the value is valid for the target data type, and that further validation is therefore not required. Note that a validation failure may be reported even if validation was not requested.

context - The conversion context to be used. This is required at present only when converting to xs:Name or similar types: it determines the NameChecker to be used.

Returns:

the result of the conversion, if successful. If unsuccessful, the value returned will be a ValidationErrorValue. The caller must check for this condition. No exception is thrown, instead the exception will be encapsulated within the ValidationErrorValue.

convert

public AtomicValue convert(AtomicType targetType,
                           XPathContext context,
                           boolean validate)

Convert the value to a given type. The result of the conversion will be an atomic value of the required type. This method works where the target type is a built-in atomic type and also where it is a user-defined atomic type.

Parameters:

targetType - the type to which the value is to be converted

context - provides access to conversion context

validate - true if validation is required, false if the caller already knows that the value is valid

Returns:

the value after conversion if successful; or a ValidationErrorValue if conversion failed. The caller must check for this condition. Validation may fail even if validation was not requested.

copy

public abstract AtomicValue copy(AtomicType typeLabel)

Create a copy of this atomic value, with a different type label

Parameters:

typeLabel - the type label of the new copy. The caller is responsible for checking that the value actually conforms to this type.

getLength

public final int getLength()

Get the length of the sequence

Overrides:

getLength in class Value

Returns:

always 1 for an atomic value

iterate

public final SequenceIterator iterate()

Iterate over the (single) item in the sequence

Specified by:

iterate in class Value

Returns:

a SequenceIterator that iterates over the single item in this value

getStringValue

public abstract String getStringValue()

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. This method is refined for AtomicValues so that it never throws an Exception.

Specified by:

getStringValue in interface Item

Specified by:

getStringValue in interface ValueRepresentation

Overrides:

getStringValue in class Value

Returns:

the string value of the item

See Also:

Item.getStringValueCS()

getTypedValue

public final SequenceIterator getTypedValue()

Get the typed value of this item

Specified by:

getTypedValue in interface Item

Returns:

the typed value of the expression (which is this value)

effectiveBooleanValue

public boolean effectiveBooleanValue()
                              throws XPathException

Get the effective boolean value of the value

Overrides:

effectiveBooleanValue in class Value

Returns:

true, unless the value is boolean false, numeric zero, or zero-length string

Throws:

XPathException - if any dynamic error occurs evaluating the expression

getComponent

public AtomicValue getComponent(int component)
                         throws XPathException

Method to extract components of a value. Implemented by some subclasses, but defined at this level for convenience

Throws:

XPathException

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.

Overrides:

checkPermittedContents in class Value

Parameters:

parentType - The schema type

env - the static context

whole - true if this atomic value accounts for the entire content of the containing node

Throws:

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

toString

public String toString()

Get string value. In general toString() for an atomic value displays the value as it would be written in XPath: that is, as a literal if available, or as a call on a constructor function otherwise.

Overrides:

toString in class Value