uk.ac.starlink.util

## Class MapGroup<K,V>

- java.lang.Object
- - uk.ac.starlink.util.MapGroup<K,V>

-     public class MapGroup<K,V>
      extends java.lang.Object

  Represents an ordered list of `Map`s containing related data. The same keys may crop up in the maps comprising the groups, and are taken to have the same meaning, so that all the values associated with a given key in any of the maps in the group are taken to be a related set. There is no requirement however that a key which appears in one of the maps has to appear in any or all of the others. A single list of the union of all the keys which appear in any of the maps in the group can be obtained. An ordering may be imposed on this list.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `MapGroup()` Constructs a new `MapGroup`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addMap(java.util.Map<K,V> map)` Adds a new Map to the end of this group.
    `java.util.List<K>` | `getKeyOrder()` Returns the list which defines ordering for any keys which crop up.
    `java.util.List<K>` | `getKnownKeys()` Returns a list of all the keys which appear in any of the metadata sets.
    `java.util.List<java.util.Map<K,V>>` | `getMaps()` Returns an unmodifiable list of all the maps in this group.
    `void` | `removeKey(K key)` Removes all entries with a given key for every map in this group.
    `void` | `removeKeys(java.util.Collection<K> keys)` Removes all entries which have a key in a given collection for every map in this group.
    `void` | `retainKeys(java.util.Collection<K> keys)` Removes all entries except those with keys in a given collection for every map in this group.
    `void` | `setKeyOrder(java.util.List<K> ordering)` Mandates an ordering to be imposed on the map keys.
    `void` | `setKnownKeys(java.util.List<K> keys)` Sets the list of known keys.
    `int` | `size()` Returns the number of maps in this group.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### MapGroup

          public MapGroup()

      Constructs a new `MapGroup`.

  - ### Method Detail

    - #### addMap

          public void addMap(java.util.Map<K,V> map)

      Adds a new Map to the end of this group.
      Parameters:
        `map` - the map to add

    - #### getMaps

          public java.util.List<java.util.Map<K,V>> getMaps()

      Returns an unmodifiable list of all the maps in this group. It is unmodifiable so that you can't put anything in it which is not a `Map`.
      Returns:
        a list of the maps

    - #### size

          public int size()

      Returns the number of maps in this group.
      Returns:
        map count

    - #### setKeyOrder

          public void setKeyOrder(java.util.List<K> ordering)

      Mandates an ordering to be imposed on the map keys. The effect of this call is to influence the order of the list returned by subsequent calls of `getKnownKeys()`.

      The supplied argument `ordering` is a list of objects; an object which appears earlier in this list is considered to be earlier in the list of `MapGroup` keys. Any which do not appear in this list will be ranked in an unspecified order at the end (their natural comparison order will be used if both objects implement `Comparable`).

      Parameters:
        `ordering` - a list of objects which may appear in this group's map keys

    - #### getKeyOrder

          public java.util.List<K> getKeyOrder()

      Returns the list which defines ordering for any keys which crop up.
      Returns:
        current key ordering

    - #### removeKeys

          public void removeKeys(java.util.Collection<K> keys)

      Removes all entries which have a key in a given collection for every map in this group.
      Parameters:
        `keys` - the set of key values whose entries must be removed

    - #### removeKey

          public void removeKey(K key)

      Removes all entries with a given key for every map in this group.
      Parameters:
        `key` - the key whose entries must be removed

    - #### retainKeys

          public void retainKeys(java.util.Collection<K> keys)

      Removes all entries except those with keys in a given collection for every map in this group.
      Parameters:
        `keys` - the keys whose entries must be retained

    - #### setKnownKeys

          public void setKnownKeys(java.util.List<K> keys)

      Sets the list of known keys. This list, if not null, will be returned by subsequent calls of `getKnownKeys()`.
      Parameters:
        `keys` - collection of keys

    - #### getKnownKeys

          public java.util.List<K> getKnownKeys()

      Returns a list of all the keys which appear in any of the metadata sets. The order is determined by the most recent call of `setKeyOrder(java.util.List<K>)`. If it has never been called they will be returned in an arbitrary order. If `setKnownKeys(java.util.List<K>)` has been called with a non-null argument, that list will be returned instead.
      Returns:
        the list of map keys