net.sf.saxon.value

Class ObjectValue<T>

java.lang.Object

net.sf.saxon.value.ObjectValue<T>

All Implemented Interfaces:

Iterable<MapItem>, GroundedValue<MapItem>, Item<MapItem>, Sequence<MapItem>, ExternalObject<T>

Direct Known Subclasses:

Bindery.FailureValue, Tuple

public class ObjectValue<T>
extends Object
implements ExternalObject<T>

An XPath value that encapsulates a Java object. Such a value can only be constructed from Java code either in a Java extension function, or in the calling application.

Until Saxon 9.4, ObjectValue was a subclass of AtomicValue, and external Java objects were considered to be atomic. From 9.5, this has been changed so that an ObjectValue is another kind of Item: a fourth kind, at the same level as nodes, atomic values, and function items.

In the same way as ObjectValue is a wrapper around a Java instance object, the type of the value is a wrapper around the corresponding Java class. These types have subtype-supertype relationships that correspond to the Java class hierarchy. The top type in this branch of the class hierarchy, which wraps the Java class "Object", has item() as its superclass. These types can be referred to in the SequenceType syntax using QNames of the form jt:full.package.name.ClassName, where the conventional prefix jt maps to the namespace URI http://saxon.sf.net/java-type.

An ObjectValue is no longer permitted to wrap a Java null. An empty sequence should be used in this situation.

The effective boolean value of a wrapped Java object, like that of a node, is always true.

Atomizing a wrapped Java object, or applying the fn:string() function, returns an xs:string whose value is the result of calling toString() on the wrapped Java object.

Constructor Summary

Constructors

Constructor and Description
ObjectValue(T object) Constructor

Method Summary

Modifier and Type	Method and Description
StringValue	atomize() Atomize the item.
static String	displayTypeName(Object value) Display the type name for use in error messages
boolean	effectiveBooleanValue() Get the effective boolean value of the value
boolean	equals(Object other) Determine if two ObjectValues are equal
Genre	getGenre() Get the genre of this item
ItemType	getItemType(TypeHierarchy th) Determine the data type of the items in the expression, if possible
T	getObject() Get the encapsulated object
String	getStringValue() Get the value of the item as a string.
CharSequence	getStringValueCS() Get the string value of the item as a CharSequence.
int	hashCode()
String	toShortString() Provide a short string showing the contents of the item, suitable for use in error messages

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.saxon.om.Item

getLength, head, isStreamed, itemAt, iterate, iterator, reduce, subsequence, toGroundedValue

Methods inherited from interface net.sf.saxon.om.GroundedValue

asIterable, materialize

Methods inherited from interface net.sf.saxon.om.Sequence

makeRepeatable

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

ObjectValue

public ObjectValue(T object)

Constructor

Parameters:

object - the object to be encapsulated

Method Detail

getGenre

public Genre getGenre()

Get the genre of this item

Specified by:

getGenre in interface Item<MapItem>

Returns:

the genre

getStringValue

public String getStringValue()

Get the value of the item as a string. For nodes, this is the string value of the node as defined in the XPath 2.0 data model, except that all nodes are treated as being untyped: it is not an error to get the string value of a node with a complex type. For atomic values, the method returns the result of casting the atomic value to a string.

If the calling code can handle any CharSequence, the method getStringValueCS() should be used. If the caller requires a string, this method is preferred.

Specified by:

getStringValue in interface GroundedValue<MapItem>

Specified by:

getStringValue in interface Item<MapItem>

Returns:

the string value of the item

Throws:

UnsupportedOperationException - if the item is a function item (an unchecked exception is used here to avoid introducing exception handling to a large number of paths where it is not needed)

Since:

8.4

See Also:

getStringValueCS()

getStringValueCS

public CharSequence getStringValueCS()

Get the string value of the item as a CharSequence. This is in some cases more efficient than the version of the method that returns a String. The method satisfies the rule that X.getStringValueCS().toString() returns a string that is equal to X.getStringValue().

Note that two CharSequence values of different types should not be compared using equals(), and for the same reason they should not be used as a key in a hash table.

If the calling code can handle any CharSequence, this method should be used. If the caller requires a string, the getStringValue() method is preferred.

Specified by:

getStringValueCS in interface GroundedValue<MapItem>

Specified by:

getStringValueCS in interface Item<MapItem>

Returns:

the string value of the item

Throws:

UnsupportedOperationException - if the item is a function item (an unchecked exception is used here to avoid introducing exception handling to a large number of paths where it is not needed)

Since:

8.4

See Also:

getStringValue()

atomize

public StringValue atomize()

Atomize the item.

Specified by:

atomize in interface Item<MapItem>

Returns:

the result of atomization. For an external object this is defined to be the result of the toString() method, as an xs:string value.

getItemType

public ItemType getItemType(TypeHierarchy th)

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

Specified by:

getItemType in interface ExternalObject<T>

Parameters:

th - The TypeHierarchy.

Returns:

for the default implementation: AnyItemType (not known)

displayTypeName

public static String displayTypeName(Object value)

Display the type name for use in error messages

Returns:

the type name. This will be in the form "java-type:" followed by the full class name of the wrapped Java object.

effectiveBooleanValue

public boolean effectiveBooleanValue()

Get the effective boolean value of the value

Specified by:

effectiveBooleanValue in interface GroundedValue<MapItem>

Returns:

true (always)

getObject

public T getObject()

Get the encapsulated object

Specified by:

getObject in interface ExternalObject<T>

Returns:

the Java object that this external object wraps

equals

public boolean equals(Object other)

Determine if two ObjectValues are equal

Overrides:

equals in class Object

Returns:

true if the other object is also a wrapped Java object and if the two wrapped objects compare equal using the Java equals() method.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toShortString

public String toShortString()

Description copied from interface: Item

Provide a short string showing the contents of the item, suitable for use in error messages

Specified by:

toShortString in interface GroundedValue<MapItem>

Specified by:

toShortString in interface Item<MapItem>

Returns:

a depiction of the item suitable for use in error messages