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

All Implemented Interfaces:

java.lang.Iterable<XdmItem>

public class XdmMap
extends XdmFunctionItem

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

Constructors

Constructor and Description
XdmMap() Create an empty XdmMap
XdmMap(java.util.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 values
XdmMap(MapItem map) Create an XdmMap whose underlying value is a MapItem

Method Summary

Modifier and Type	Method and Description
java.util.Map<XdmAtomicValue,XdmValue>	asImmutableMap() Return this map as an immutable instance of Map
java.util.Map<XdmAtomicValue,XdmValue>	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	containsKey(XdmAtomicValue key) Returns true if this map contains a mapping for the specified key.
java.util.Set<java.util.Map.Entry<XdmAtomicValue,XdmValue>>	entrySet() Returns a Set of the key-value pairs contained in this map.
XdmValue	get(double key) Returns the value to which the specified double-valued key is mapped, or null if this map contains no mapping for the key.
XdmValue	get(long key) Returns the value to which the specified integer-valued key is mapped, or null if this map contains no mapping for the key.
XdmValue	get(java.lang.String key) Returns the value to which the specified string-valued key is mapped, or null if this map contains no mapping for the key.
XdmValue	get(XdmAtomicValue key) Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
MapItem	getUnderlyingValue() Get the underlying implementation object representing the value.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
java.util.Set<XdmAtomicValue>	keySet() Get the keys present in the map in the form of an unordered set.
static XdmMap	makeMap(java.util.Map input) 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 map
XdmMap	put(XdmAtomicValue key, XdmValue value) Create a new map containing an additional (key, value) pair.
XdmMap	remove(XdmAtomicValue key) Create a new map in which the entry for a given key has been removed.
java.util.Collection<XdmValue>	values() Returns a Collection 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, matches, size, stream, wrapItem, wrapItem, wrapItem

Methods inherited from class net.sf.saxon.s9api.XdmValue

append, documentOrder, fromGroundedValue, itemAt, iterator, makeSequence, makeValue, select, setValue, toString, 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 Detail

XdmMap

public XdmMap()

Create an empty XdmMap

XdmMap

public XdmMap(MapItem map)

Create an XdmMap whose underlying value is a MapItem

Parameters:

map - the MapItem to be encapsulated

XdmMap

public XdmMap(java.util.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 values

Parameters:

map - a Java map whose entries are the (key, value) pairs

Since:

9.8

Method Detail

getUnderlyingValue

public MapItem 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 class XdmItem

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

public XdmMap put(XdmAtomicValue key,
                  XdmValue value)

Create a new map containing an additional (key, value) pair. If there is an existing entry with the same key, it is removed

Returns:

a new map containing the additional entry. The original map is unchanged.

remove

public XdmMap remove(XdmAtomicValue key)

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)

Returns:

a map without the specified entry. The original map is unchanged.

keySet

public java.util.Set<XdmAtomicValue> 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

public java.util.Map<XdmAtomicValue,XdmValue> asImmutableMap()

Return this map as an immutable instance of Map

Returns:

an immutable instance of Map backed by this map. Methods such as remove(net.sf.saxon.s9api.XdmAtomicValue) and put(net.sf.saxon.s9api.XdmAtomicValue, net.sf.saxon.s9api.XdmValue) applied to the result will always throw UnsupportedOperationException.

asMap

public java.util.Map<XdmAtomicValue,XdmValue> asMap()

Return a mutable Java Map containing the same entries as this map.

Overrides:

asMap in class XdmItem

Returns:

a mutable Map from atomic values to (sequence) values, containing the same entries as this map

Since:

9.6.

clear

public void clear()

Removes all of the mappings from this map (optional operation). The map will be empty after this call returns.

Throws:

java.lang.UnsupportedOperationException - if the clear operation is not supported by this map

isEmpty

public boolean isEmpty()

Returns true if this map contains no key-value mappings.

Returns:

true if this map contains no key-value mappings

containsKey

public boolean containsKey(XdmAtomicValue key)

Returns true if this map contains a mapping for the specified key. More formally, returns true if and only if this map contains a mapping for a key k 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

public XdmValue get(XdmAtomicValue key)

Returns the value to which the specified key is mapped, or null 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:

java.lang.ClassCastException - if the supplied key cannot be converted to an XdmAtomicValue

java.lang.NullPointerException - if the supplied key is null

get

public XdmValue get(java.lang.String key)

Returns the value to which the specified string-valued key is mapped, or null if this map contains no mapping for the key. This is a convenience method to save the trouble of converting the String to an XdmAtomicValue.

Parameters:

key - the key whose associated value is to be returned. This is treated as an instance of xs:string (which will also match entries whose key is xs:untypedAtomic or xs:anyURI)

Returns:

the value to which the specified key is mapped, or null if this map contains no mapping for the key

Throws:

java.lang.NullPointerException - if the supplied key is null

get

public XdmValue get(long key)

Returns the value to which the specified integer-valued key is mapped, or null if this map contains no mapping for the key. This is a convenience method to save the trouble of converting the integer to an XdmAtomicValue.

Parameters:

key - the key whose associated value is to be returned. This is treated as an instance of xs: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:

java.lang.NullPointerException - if the supplied key is null

get

public XdmValue get(double key)

Returns the value to which the specified double-valued key is mapped, or null if this map contains no mapping for the key. This is a convenience method to save the trouble of converting the double to an XdmAtomicValue.

Parameters:

key - the key whose associated value is to be returned. This is treated as an instance of xs: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:

java.lang.NullPointerException - if the supplied key is null

values

public java.util.Collection<XdmValue> values()

Returns a Collection 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

public java.util.Set<java.util.Map.Entry<XdmAtomicValue,XdmValue>> entrySet()

Returns a Set of the key-value pairs contained in this map.

Returns:

a set of the mappings contained in this map

makeMap

public static XdmMap makeMap(java.util.Map input)
                      throws java.lang.IllegalArgumentException

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 the XdmAtomicValue.makeAtomicValue(Object) method. The associated values must be convertible to XDM sequences using the XdmValue.makeValue(Object) method.

Parameters:

input - the supplied map

Returns:

the resulting XdmMap

Throws:

java.lang.IllegalArgumentException - if any value in the input map cannot be converted to a corresponding XDM value.