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

- 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 | 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

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | 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, isNode, 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 a copy of the entries in this map. Changes to the returned map have no effect on the original `XdmMap`.
      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.
      Overrides:
        `isEmpty` in class `XdmValue`
      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.