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>, java.util.Map<XdmAtomicValue,XdmValue>

public class XdmMap
extends XdmFunctionItem
implements java.util.Map<XdmAtomicValue,XdmValue>

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, and is also an implementation of a Java Map.

An XdmMap is immutable.

Since:

9.8

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

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>	asMap() Return a corresponding Java Map.
void	clear() Removes all of the mappings from this map (optional operation).
boolean	containsKey(java.lang.Object key) Returns true if this map contains a mapping for the specified key.
boolean	containsValue(java.lang.Object value) Returns true if this map maps one or more keys to the specified value.
java.util.Set<java.util.Map.Entry<XdmAtomicValue,XdmValue>>	entrySet() Returns a Set view of the mappings contained in this map.
XdmValue	get(java.lang.Object 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 a list.
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.
void	putAll(java.util.Map<? extends XdmAtomicValue,? extends XdmValue> m) Copies all of the mappings from the specified map to this map (optional operation).
XdmValue	remove(java.lang.Object key) Removes the mapping for a key from this map if it is present (optional operation).
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 view of the values contained in this map.

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

call, getArity, getName, getSystemFunction, isAtomicValue

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

getStringValue, size, wrapItem

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

append, itemAt, iterator, makeSequence, makeValue, setValue, toString, wrap

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, equals, forEach, getOrDefault, hashCode, merge, putIfAbsent, remove, replace, replace, replaceAll, size

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

Specified by:

put in interface java.util.Map<XdmAtomicValue,XdmValue>

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 a list.

Specified by:

keySet in interface java.util.Map<XdmAtomicValue,XdmValue>

Returns:

a list of the keys present in this map, in arbitrary order.

asMap

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

Return a corresponding Java 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.

Specified by:

clear in interface java.util.Map<XdmAtomicValue,XdmValue>

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.

Specified by:

isEmpty in interface java.util.Map<XdmAtomicValue,XdmValue>

Returns:

true if this map contains no key-value mappings

containsKey

public boolean containsKey(java.lang.Object 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.)

Specified by:

containsKey in interface java.util.Map<XdmAtomicValue,XdmValue>

Parameters:

key - key whose presence in this map is to be tested

Returns:

true if this map contains a mapping for the specified key

Throws:

java.lang.ClassCastException - if the key is of an inappropriate type for this map (optional)

java.lang.NullPointerException - if the specified key is null and this map does not permit null keys (optional)

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this map maps one or more keys to the specified value. More formally, returns true if and only if this map contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)). This operation will probably require time linear in the map size for most implementations of the Map interface.

This implementation always throws UnsupportedOperationException.

Specified by:

containsValue in interface java.util.Map<XdmAtomicValue,XdmValue>

Parameters:

value - value whose presence in this map is to be tested

Returns:

true if this map maps one or more keys to the specified value

Throws:

java.lang.ClassCastException - if the value is of an inappropriate type for this map (optional)

java.lang.NullPointerException - if the specified value is null and this map does not permit null values (optional)

get

public XdmValue get(java.lang.Object key)

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

Specified by:

get in interface java.util.Map<XdmAtomicValue,XdmValue>

Parameters:

key - the key whose associated value is to be returned. If this is not an XdmAtomicValue, the method attempts to construct an XdmAtomicValue using the method XdmAtomicValue.makeAtomicValue(Object); it is therefore possible to pass a simple key such as a string or integer.

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 key is of an inappropriate type for this map (in this case, XdmAtomicValue) (optional)

java.lang.NullPointerException - if the specified key is null (optional)

remove

public XdmValue remove(java.lang.Object key)

Removes the mapping for a key from this map if it is present (optional operation). More formally, if this map contains a mapping from key k to value v such that (key==null ? k==null : key.equals(k)), that mapping is removed. (The map can contain at most one such mapping.)

Returns the value to which this map previously associated the key, or null if the map contained no mapping for the key.

If this map permits null values, then a return value of null does not necessarily indicate that the map contained no mapping for the key; it's also possible that the map explicitly mapped the key to null.

The map will not contain a mapping for the specified key once the call returns.

Specified by:

remove in interface java.util.Map<XdmAtomicValue,XdmValue>

Parameters:

key - key whose mapping is to be removed from the map

Returns:

the previous value associated with key, or null if there was no mapping for key.

Throws:

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

java.lang.ClassCastException - if the key is of an inappropriate type for this map (optional)

java.lang.NullPointerException - if the specified key is null and this map does not permit null keys (optional)

putAll

public void putAll(java.util.Map<? extends XdmAtomicValue,? extends XdmValue> m)

Copies all of the mappings from the specified map to this map (optional operation). The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress.

Specified by:

putAll in interface java.util.Map<XdmAtomicValue,XdmValue>

Parameters:

m - mappings to be stored in this map

Throws:

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

java.lang.ClassCastException - if the class of a key or value in the specified map prevents it from being stored in this map

java.lang.NullPointerException - if the specified map is null, or if this map does not permit null keys or values, and the specified map contains null keys or values

java.lang.IllegalArgumentException - if some property of a key or value in the specified map prevents it from being stored in this map

values

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

Returns a Collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Specified by:

values in interface java.util.Map<XdmAtomicValue,XdmValue>

Returns:

a collection view of the values contained in this map

entrySet

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

Returns a Set view of the mappings contained in this map.

Specified by:

entrySet in interface java.util.Map<XdmAtomicValue,XdmValue>

Returns:

a set view 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.