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>
A value in the XDM data model. A value is a sequence of zero or more items, each item being an atomic value, a node, or a function item.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 Description XdmValue(java.lang.Iterable<? extends XdmItem> items)
Create an XdmValue as a sequence of XdmItem objectsXdmValue(java.util.Iterator<? extends XdmItem> iterator)
Create an XdmValue containing the items returned by anIterator
.XdmValue(java.util.stream.Stream<? extends XdmItem> stream)
Create an XdmValue containing the results of reading a Streamprotected
XdmValue(GroundedValue value)
Create an XdmValue that wraps a suppliedGroundedValue
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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 orderGroundedValue
getUnderlyingValue()
Get the underlying implementation object representing the value.boolean
isEmpty()
Ask whether the sequence is emptyXdmItem
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 JavaIterable
.static XdmValue
makeValue(java.lang.Object o)
Make an XDM value from a Java object.boolean
matches(SequenceType type)
Test whether the value matches a supplied SequenceType<T extends XdmItem>
XdmStream<T>select(Step<T> step)
Get a stream of items by applying aStep
to the items in this value.int
size()
Get the number of items in the sequenceXdmStream<? extends XdmItem>
stream()
Get a stream comprising the items in this valueXdmValue
subsequence(int start, int length)
Get a subsequence of the valuejava.lang.String
toString()
Create a string representation of the value.XdmValue
where(java.util.function.Predicate<? super XdmItem> predicate)
Filter the value on a supplied predicatestatic XdmValue
wrap(AtomicSequence value)
static XdmValue
wrap(Sequence value)
Create an XdmValue that wraps an existing Saxon Sequence
-
-
-
Constructor Detail
-
XdmValue
protected XdmValue(GroundedValue value)
Create an XdmValue that wraps a suppliedGroundedValue
. 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 ofXdmValue
, such asXdmAtomicValue
orXdmNode
, use thewrap(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 anIterator
.- 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 valueSaxonApiUncheckedException
- 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 returnedlength
- 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 interfacejava.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, with the optionsindent="yes"
andomit-xml-declaration="yes"
. Theitem-separator
if there are multiple items is a newline. Any trailing newline in the result is removed.Note that this method does not return the same result as the XPath
fn:string()
function: it corresponds more closely to thefn:serialize()
function.If the
XdmValue
is an element node, the result will be a well-formed XML document serialized as defined in the W3C XSLT/XQuery serialization specification, using options method="xml", indent="yes", omit-xml-declaration="yes".In the case of a document node, the result will be a well-formed XML document provided that the document node contains exactly one element child, and no text node children.
In the case of an attribute node, the output is a string in the form
name="value"
. The name will use the original namespace prefix.In the case of a namespace node, the output is a string in the form of a namespace declaration, that is
xmlns="uri"
orxmlns:pre="uri"
.Other nodes, such as text nodes, comments, and processing instructions, are represented as they would appear in lexical XML. Note: this means that in the case of text nodes, special characters such as
&
and<
are output in escaped form. To get the unescaped string value of a text node, useXdmItem.getStringValue()
instead.Atomic values are serialized according to the rules of the adaptive output method, for example
true()
,"blue"
,42
, orxs:date("2023-01-31")
.A sequence of items is formatted by serializing the individual items, separated by newlines.
- Overrides:
toString
in classjava.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 JavaIterable
. Each value delivered by the iterable is first converted to an XDM value using themakeValue(Object)
method; if the result is anything other than a single XDM item, it is then wrapped in anXdmArray
.- 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, anXdmNode
orXdmAtomicValue
orXdmArray
orXdmMap
), which is returned unchanged - An instance of
Sequence
(for example, aNodeInfo
orAtomicValue
), which is wrapped as anXdmValue
- An instance of
Map
, which is converted to an XDM Map using theXdmMap.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 themakeSequence(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
- An instance of
-
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 aStep
to the items in this value. This operation is analogous to theStream.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 childrenselect(child("*"))
returns a stream containing all element childrenselect(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" descendantsselect(path("//", "author", "@name"))
returns a stream containing the "name" attributes of "author" descendantsselect(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 extendsStream
<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 (oftenXdmNode
)- Parameters:
step
- theStep
to be applied to the items in this value. This will often be one of the standard steps returned by the static methods of theSteps
class, such asSteps.child()
, or by instance methods (such asStep.where(java.util.function.Predicate<? super T>)
,Step.cat(net.sf.saxon.s9api.streams.Step<T>)
, orStep.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
-
where
public XdmValue where(java.util.function.Predicate<? super XdmItem> predicate)
Filter the value on a supplied predicate- Parameters:
predicate
- the predicate to be applied. Note that anItemType
is a predicate, so this method can be used to select those items that match a supplied item type. For example,where(ItemType.INTEGER)
will select the items in the sequence that are instances ofxs:integer
.- Returns:
- a new
XdmValue
comprising those items in thisXdmValue
that match the given predicate. - Since:
- 12.0
-
matches
public boolean matches(SequenceType type)
Test whether the value matches a supplied SequenceType- Parameters:
type
- the SequenceType that we are testing against- Returns:
- true if this value matches the sequence type, false otherwise.
- Since:
- 12.0
-
-