net.sf.saxon.s9api

Class XdmValue

java.lang.Object

net.sf.saxon.s9api.XdmValue

All Implemented Interfaces:

java.lang.Iterable<XdmItem>

Direct Known Subclasses:

XdmEmptySequence, XdmItem

public class XdmValue
extends java.lang.Object
implements java.lang.Iterable<XdmItem>

An value in the XDM data model. A value is a sequence of zero or more items, each item being either an atomic value or a node.

An XdmValue is immutable.

A sequence consisting of a single item may be represented as an instance of XdmItem, which is a subtype of XdmValue. However, there is no guarantee that a sequence of length one will always be an instance of XdmItem.

Similarly, a zero-length sequence may be represented as an instance of XdmEmptySequence, but there is no guarantee that every sequence of length zero will always be an instance of XdmEmptySequence.

Since:

9.0

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	XdmValue(GroundedValue value) Create an XdmValue that wraps a supplied GroundedValue.
	XdmValue(java.lang.Iterable<? extends XdmItem> items) Create an XdmValue as a sequence of XdmItem objects
	XdmValue(java.util.Iterator<? extends XdmItem> iterator) Create an XdmValue containing the items returned by an Iterator.
	XdmValue(java.util.stream.Stream<? extends XdmItem> stream) Create an XdmValue containing the results of reading a Stream

Method Summary

Modifier and Type	Method and Description
XdmValue	append(XdmValue otherValue) Create a new XdmValue by concatenating the contents of this XdmValue and another XdmValue into a single sequence.
XdmValue	documentOrder() Return a new XdmValue containing the nodes present in this XdmValue, with duplicates eliminated, and sorted into document order
GroundedValue	getUnderlyingValue() Get the underlying implementation object representing the value.
boolean	isEmpty() Ask whether the sequence is empty
XdmItem	itemAt(int n) Get the n'th item in the value, counting from zero.
XdmSequenceIterator<XdmItem>	iterator() Get an iterator over the items in this value.
static XdmValue	makeSequence(java.lang.Iterable<?> list) Make an XDM sequence from a Java Iterable.
static XdmValue	makeValue(java.lang.Object o) Make an XDM value from a Java object.
<T extends XdmItem> XdmStream<T>	select(Step<T> step) Get a stream of items by applying a Step to the items in this value.
int	size() Get the number of items in the sequence
XdmStream<? extends XdmItem>	stream() Get a stream comprising the items in this value
XdmValue	subsequence(int start, int length) Get a subsequence of the value
java.lang.String	toString() Create a string representation of the value.
static XdmValue	wrap(AtomicSequence value)
static XdmValue	wrap(Sequence value) Create an XdmValue that wraps an existing Saxon Sequence

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

XdmValue

protected XdmValue(GroundedValue value)

Create an XdmValue that wraps a supplied GroundedValue. This method is primarily for internal use, though it is also available to applications that manipulate data using lower-level Saxon interfaces.

Note that this constructor necessarily produces an XdmValue regardless of the supplied value. To construct instances of subclasses of XdmValue, such as XdmAtomicValue or XdmNode, use the wrap(net.sf.saxon.om.Sequence) method, or use the overriding constructor on the required subclass.

Parameters:

value - the value to be wrapped.

XdmValue

public XdmValue(java.lang.Iterable<? extends XdmItem> items)

Create an XdmValue as a sequence of XdmItem objects

Parameters:

items - a sequence of XdmItem objects. Note that if this is supplied as a list or similar collection, subsequent changes to the list/collection will have no effect on the XdmValue.

Since:

9.0.0.4

XdmValue

public XdmValue(java.util.Iterator<? extends XdmItem> iterator)
         throws SaxonApiException

Create an XdmValue containing the items returned by an Iterator.

Parameters:

iterator - the iterator that supplies the values

Throws:

SaxonApiException - if an error occurs reading values from the supplied iterator

Since:

9.6. Extended in 9.9 to take any Iterator, not just an XdmSequenceIterator.

XdmValue

public XdmValue(java.util.stream.Stream<? extends XdmItem> stream)
         throws SaxonApiException

Create an XdmValue containing the results of reading a Stream

Parameters:

stream - the stream to be read

Throws:

SaxonApiException - if an error occurs reading values from the supplied stream

Method Detail

wrap

public static XdmValue wrap(Sequence value)

Create an XdmValue that wraps an existing Saxon Sequence

Parameters:

value - the supplied Sequence (which may be a singleton Item),

Returns:

an XdmValue corresponding to the supplied Sequence. If the supplied value is null, an empty sequence is returned. If the supplied value is an atomic value, the result will be an instance of XdmAtomicValue.

• If the supplied value is a node, the result will be an instance of XdmNode.
• If the supplied value is a map, the result will be an instance of XdmMap.
• If the supplied value is an array, the result will be an instance of XdmArray.
• If the supplied value is a function item, the result will be an instance of XdmFunctionItem.

Throws:

SaxonApiUncheckedException - if the supplied Sequence is not yet fully evaluated, and evaluation of the underlying expression fails with a dynamic error.

Since:

9.5 (previously a protected method)

wrap

public static XdmValue wrap(AtomicSequence value)

append

public XdmValue append(XdmValue otherValue)

Create a new XdmValue by concatenating the contents of this XdmValue and another XdmValue into a single sequence. The two input XdmValue objects are unaffected by this operation.

Note: creating a sequence of N values by successive calls on this method takes time proportional to N-squared.

Parameters:

otherValue - the value to be appended

Returns:

a new XdmValue containing the concatenation of the two input XdmValue objects

Since:

9.2

size

public int size()

Get the number of items in the sequence

Returns:

the number of items in the value, considered as a sequence. Note that for arrays and maps, the answer will be 1 (one) since arrays and maps are items.

isEmpty

public boolean isEmpty()

Ask whether the sequence is empty

Returns:

true if the value is an empty sequence

Since:

10.1

itemAt

public XdmItem itemAt(int n)
               throws java.lang.IndexOutOfBoundsException,
                      SaxonApiUncheckedException

Get the n'th item in the value, counting from zero.

Parameters:

n - the item that is required, counting the first item in the sequence as item zero

Returns:

the n'th item in the sequence making up the value, counting from zero

Throws:

java.lang.IndexOutOfBoundsException - if n is less than zero or greater than or equal to the number of items in the value

SaxonApiUncheckedException - if the value is lazily evaluated and the delayed evaluation fails with a dynamic error.

subsequence

public XdmValue subsequence(int start,
                            int length)

Get a subsequence of the value

Parameters:

start - the index of the first item to be included in the result, counting from zero. A negative value is taken as zero. If the value is beyond the end of the sequence, an empty sequence is returned

length - the number of items to be included in the result. Specify Integer.MAX_VALUE to get the subsequence up to the end of the base sequence. If the value is negative, an empty sequence is returned. If the length goes off the end of the sequence, the result returns items up to the end of the sequence

Returns:

the required subsequence.

Since:

11

iterator

public XdmSequenceIterator<XdmItem> iterator()
                                      throws SaxonApiUncheckedException

Get an iterator over the items in this value.

Specified by:

iterator in interface java.lang.Iterable<XdmItem>

Returns:

an Iterator over the items in this value.

Throws:

SaxonApiUncheckedException - if the value is lazily evaluated and the delayed evaluation fails with a dynamic error.

getUnderlyingValue

public GroundedValue getUnderlyingValue()

Get the underlying implementation object representing the value. This method allows access to lower-level Saxon functionality, including classes and methods that offer no guarantee of stability across releases.

Returns:

the underlying implementation object representing the value

toString

public java.lang.String toString()

Create a string representation of the value. The is the result of serializing the value using the adaptive serialization method.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the value

makeSequence

public static XdmValue makeSequence(java.lang.Iterable<?> list)
                             throws java.lang.IllegalArgumentException

Make an XDM sequence from a Java Iterable. Each value delivered by the iterable is first converted to an XDM value using the makeValue(Object) method; if the result is anything other than a single XDM item, it is then wrapped in an XdmArray.

Parameters:

list - the Java iterable

Returns:

the result of the conversion if successful

Throws:

java.lang.IllegalArgumentException - if conversion is not possible

makeValue

public static XdmValue makeValue(java.lang.Object o)
                          throws java.lang.IllegalArgumentException

Make an XDM value from a Java object. The supplied object may be any of the following:

• An instance of XdmValue (for example, an XdmNode or XdmAtomicValue or XdmArray or XdmMap), which is returned unchanged
• An instance of Sequence (for example, a NodeInfo or AtomicValue), which is wrapped as an XdmValue
• An instance of Map, which is converted to an XDM Map using the XdmMap.makeMap(java.util.Map<K, V>) method
• A Java array, of any type, which is converted to an XDM Array using the XdmArray.makeArray(java.lang.Object[]) method
• A Java collection, more specifically Iterable, which is converted to an XDM sequence using the makeSequence(Iterable) method
• Any object that is convertible to an XDM atomic value using the method XdmAtomicValue.makeAtomicValue(Object)

Parameters:

o - the Java object

Returns:

the result of the conversion if successful

Throws:

java.lang.IllegalArgumentException - if conversion is not possible

documentOrder

public XdmValue documentOrder()
                       throws SaxonApiException

Return a new XdmValue containing the nodes present in this XdmValue, with duplicates eliminated, and sorted into document order

Returns:

the same nodes, sorted into document order, with duplicates eliminated

Throws:

SaxonApiException - if anything goes wrong (typically during delayed evaluation of the input sequence)

java.lang.ClassCastException - if the sequence contains items that are not nodes

Since:

9.9

stream

public XdmStream<? extends XdmItem> stream()

Get a stream comprising the items in this value

Returns:

a Stream over the items in this value

Since:

9.9

select

public <T extends XdmItem> XdmStream<T> select(Step<T> step)

Get a stream of items by applying a Step to the items in this value. This operation is analogous to the Stream.flatMap operation in Java, or to the "!" operator in XPath.

The following examples assume a static import declaration of the standard Steps: import static net.sf.saxon.s9api.streams.Steps.*;

• select(child()) returns a stream containing all children
• select(child("*")) returns a stream containing all element children
• select(child("author")) returns a stream containing all element children with local name "author" (regardless of namespace)
• select(child("http://my.ns/", "author")) returns a stream containing all element children with local name "author" and namespace "http://my.ns/"
• select(descendant("author")) returns a stream containing all element descendants with local name "author" (regardless of namespace)
• select(descendant("author").then(attribute("name")) returns a stream containing the "name" attributes of "author" descendants
• select(path("//", "author", "@name")) returns a stream containing the "name" attributes of "author" descendants
• select(child("author").where(attributeEq("firstName", "Jane")) returns a stream containing all the "author" children having a "firstName" attribute whose value is "Jane"
• select(child("author").first()) returns a stream containing the first "author" child (if there is one)
• select(child("author").where(attributeEq("firstName", "Jane").last()) returns a stream containing the last "author" child having a "firstName" attribute whose value is "Jane" (if there is one)

In each of the above examples, the selected nodes are returned as an XdmStream<XdmNode>; this class extends Stream<XdmNode>, so all the standard operations on streams are available, together with some additional operations specific to node streams.

The select method thus has comparable power to simple XPath expressions; but unlike XPath expressions, there is no run-time overhead in parsing the XPath expression and developing an execution plan.

Type Parameters:

T - the type of items to be returned by the step (often XdmNode)

Parameters:

step - the Step to be applied to the items in this value. This will often be one of the standard steps returned by the static methods of the Steps class, such as Steps.child(), or by instance methods (such as Step.where(java.util.function.Predicate<? super T>), Step.cat(net.sf.saxon.s9api.streams.Step<T>), or Step.first()) but it is also possible to create user-defined steps.

Returns:

a Stream of items obtained by replacing each item X in this value by the items obtained by applying the Step function to X.

Since:

9.9