Package net.sf.saxon.s9api
Class XdmMap
java.lang.Object
net.sf.saxon.s9api.XdmValue
net.sf.saxon.s9api.XdmItem
net.sf.saxon.s9api.XdmFunctionItem
net.sf.saxon.s9api.XdmMap
A map in the XDM data model. A map is a list of zero or more entries, each of which
is a pair comprising a key (which is an atomic value) and a value (which is an arbitrary value).
The map itself is an XDM item.
An XdmMap is immutable.
As originally issued in Saxon 9.8, this class implemented the Map
interface.
It no longer does so, because it was found that the methods XdmItem.size()
, put(XdmAtomicValue, XdmValue)
,
and remove(net.sf.saxon.s9api.XdmAtomicValue)
did not adhere to the semantic contract of that interface. Instead, it is now
possible to obtain a view of this object as an immutable Java Map
by calling the
method asImmutableMap()
. See bug 3824.
- Since:
- 9.8
-
Constructor Summary
ConstructorsConstructorDescriptionXdmMap()
Create an empty XdmMapXdmMap
(Map<? extends XdmAtomicValue, ? extends XdmValue> map) Create an XdmMap supplying the entries in the form of a Java Map, where the keys and values in the Java Map are XDM valuesCreate an XdmMap whose underlying value is a MapItem -
Method Summary
Modifier and TypeMethodDescriptionReturn this map as an immutable instance ofMap
asMap()
Return a mutable Java Map containing the same entries as this map.void
clear()
Removes all of the mappings from this map (optional operation).boolean
Returnstrue
if this map contains a mapping for the specified key.entrySet()
Returns aSet
of the key-value pairs contained in this map.get
(double key) Returns the value to which the specified double-valued key is mapped, ornull
if this map contains no mapping for the key.get
(long key) Returns the value to which the specified integer-valued key is mapped, ornull
if this map contains no mapping for the key.Returns the value to which the specified string-valued key is mapped, ornull
if this map contains no mapping for the key.get
(XdmAtomicValue key) Returns the value to which the specified key is mapped, ornull
if this map contains no mapping for the key.Get the underlying implementation object representing the value.boolean
isEmpty()
Returnstrue
if this map contains no key-value mappings.keySet()
Get the keys present in the map in the form of an unordered set.static <K,
V> XdmMap Static factory method to construct an XDM map by converting each entry in a supplied Java map.int
mapSize()
Get the number of entries in the mapput
(XdmAtomicValue key, XdmValue value) Create a new map containing an additional (key, value) pair.remove
(XdmAtomicValue key) Create a new map in which the entry for a given key has been removed.values()
Returns aCollection
containing the values found in this map, that is, the value parts of the key-value pairs.Methods inherited from class net.sf.saxon.s9api.XdmFunctionItem
asFunction, asStep, call, getArity, getName, getSystemFunction, isAtomicValue
Methods inherited from class net.sf.saxon.s9api.XdmItem
getStringValue, getUnicodeStringValue, isNode, matches, size, stream, wrapItem, wrapItem, wrapItem
Methods inherited from class net.sf.saxon.s9api.XdmValue
append, documentOrder, itemAt, iterator, makeSequence, makeValue, matches, select, subsequence, toString, where, wrap, wrap
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 Details
-
XdmMap
public XdmMap()Create an empty XdmMap -
XdmMap
Create an XdmMap whose underlying value is a MapItem- Parameters:
map
- the MapItem to be encapsulated
-
XdmMap
Create an XdmMap supplying the entries in the form of a Java Map, where the keys and values in the Java Map are XDM values- Parameters:
map
- a Java map whose entries are the (key, value) pairs- Since:
- 9.8
-
-
Method Details
-
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.- Overrides:
getUnderlyingValue
in classXdmItem
- Returns:
- the underlying implementation object representing the value
- Since:
- 9.8 (previously inherited from XdmValue which returns a Sequence)
-
mapSize
public int mapSize()Get the number of entries in the map- Returns:
- the number of entries in the map. (Note that the
XdmItem.size()
method returns 1 (one), because an XDM map is an item.)
-
put
Create a new map containing an additional (key, value) pair. If there is an existing entry with the same key, it is removed- Parameters:
key
- the keyvalue
- the value- Returns:
- a new map containing the additional entry. The original map is unchanged.
-
remove
Create a new map in which the entry for a given key has been removed. If there is no entry with the same key, the new map has the same content as the old (it may or may not be the same Java object)- Parameters:
key
- the key- Returns:
- a map without the specified entry. The original map is unchanged.
-
keySet
Get the keys present in the map in the form of an unordered set.- Returns:
- an unordered set of the keys present in this map, in arbitrary order.
-
asImmutableMap
Return this map as an immutable instance ofMap
- Returns:
- an immutable instance of
Map
backed by this map. Methods such asremove(net.sf.saxon.s9api.XdmAtomicValue)
andput(net.sf.saxon.s9api.XdmAtomicValue, net.sf.saxon.s9api.XdmValue)
applied to the result will always throwUnsupportedOperationException
.
-
asMap
Return a mutable Java Map containing the same entries as this map. -
clear
public void clear()Removes all of the mappings from this map (optional operation). The map will be empty after this call returns.- Throws:
UnsupportedOperationException
- if theclear
operation is not supported by this map
-
isEmpty
public boolean isEmpty()Returnstrue
if this map contains no key-value mappings. -
containsKey
Returnstrue
if this map contains a mapping for the specified key. More formally, returnstrue
if and only if this map contains a mapping for a keyk
such that(key==null ? k==null : key.equals(k))
. (There can be at most one such mapping.)- Parameters:
key
- key whose presence in this map is to be tested- Returns:
true
if this map contains a mapping for the specified key- Since:
- 9.8. Changed the method signature in 9.9.1.1 to match the implementation: see bug 3969.
-
get
Returns the value to which the specified key is mapped, ornull
if this map contains no mapping for the key.- Parameters:
key
- the key whose associated value is to be returned.- Returns:
- the value to which the specified key is mapped, or
null
if this map contains no mapping for the key - Throws:
ClassCastException
- if the supplied key cannot be converted to an XdmAtomicValueNullPointerException
- if the supplied key is null
-
get
Returns the value to which the specified string-valued key is mapped, ornull
if this map contains no mapping for the key. This is a convenience method to save the trouble of converting the String to anXdmAtomicValue
.- Parameters:
key
- the key whose associated value is to be returned. This is treated as an instance ofxs:string
(which will also match entries whose key isxs:untypedAtomic
orxs:anyURI
)- Returns:
- the value to which the specified key is mapped, or
null
if this map contains no mapping for the key - Throws:
NullPointerException
- if the supplied key is null
-
get
Returns the value to which the specified integer-valued key is mapped, ornull
if this map contains no mapping for the key. This is a convenience method to save the trouble of converting the integer to anXdmAtomicValue
.- Parameters:
key
- the key whose associated value is to be returned. This is treated as an instance ofxs:integer
(which will also match entries whose key belongs to another numeric type)- Returns:
- the value to which the specified key is mapped, or
null
if this map contains no mapping for the key - Throws:
NullPointerException
- if the supplied key is null
-
get
Returns the value to which the specified double-valued key is mapped, ornull
if this map contains no mapping for the key. This is a convenience method to save the trouble of converting the double to anXdmAtomicValue
.- Parameters:
key
- the key whose associated value is to be returned. This is treated as an instance ofxs:double
(which will also match entries whose key belongs to another numeric type)- Returns:
- the value to which the specified key is mapped, or
null
if this map contains no mapping for the key - Throws:
NullPointerException
- if the supplied key is null
-
values
Returns aCollection
containing the values found in this map, that is, the value parts of the key-value pairs.- Returns:
- a collection containing the values found in this map. The result may contain duplicates, and the ordering of the collection is unpredictable.
-
entrySet
Returns aSet
of the key-value pairs contained in this map.- Returns:
- a set of the mappings contained in this map
-
makeMap
Static factory method to construct an XDM map by converting each entry in a supplied Java map. The keys in the Java map must be convertible to XDM atomic values using theXdmAtomicValue.makeAtomicValue(Object)
method. The associated values must be convertible to XDM sequences using theXdmValue.makeValue(Object)
method.- Type Parameters:
K
- the type of the keysV
- the type of the values- Parameters:
input
- the supplied map- Returns:
- the resulting XdmMap
- Throws:
IllegalArgumentException
- if any value in the input map cannot be converted to a corresponding XDM value.
-