com.h3c.util

## Class SafeMap<K,V>

- java.lang.Object
- - com.h3c.util.SafeMap<K,V>

- Type Parameters:
    `K` - the type of keys maintained by this safe map
    `V` - the type of mapped values

      public class SafeMap<K,V>
      extends Object

  This class facilitates the creation of mappings that, once built, are immutable. It is designated a "safe" map, because a (possibly default) value will always be returned, regardless of whether the specified key is null, or has not been mapped.

  Reverse lookups are also possible. Given a value, one can retrieve either the `first key` that maps to the value, or, in the case where no such mapping exists, the default key (which may be null), or `a set of all keys` that map to the value, or, in the case where no such mapping exists, an empty set.

  For example, suppose you have two enumerations:

       public enum Roman { I, II, III, IV, V, XX }
       public enum Greek { ALPHA, BETA, GAMMA }

  And you want to create the following mapping:

         I   -->  ALPHA
         II  -->  ALPHA
         III -->  ALPHA
         IV  -->  BETA
         V   -->  GAMMA
         (default: ALPHA)

  This is done by employing the `Builder` inner-class as an intermediary, as follows:

       private static final SafeMap<Roman,Greek> map =
           new SafeMap.Builder<Roman,Greek>(Greek.ALPHA)
               .add(Roman.I, Greek.ALPHA)
               .add(Roman.II, Greek.ALPHA)
               .add(Roman.III, Greek.ALPHA)
               .add(Roman.IV, Greek.BETA)
               .add(Roman.V, Greek.GAMMA)
               .build();

  Note that the default value is specified as a paramter to the builder constructor and that all required mappings are added in a chained expression, ending with the `build()` call to create the map instance.

  Now we can look up values:

       map.get(Roman.I);                // returns Greek.ALPHA
       map.get(Roman.IV);               // returns Greek.BETA
       map.get(Roman.XX);               // returns Greek.ALPHA
       map.get(null);                   // returns Greek.ALPHA
       map.getFirstKey(Greek.ALPHA)     // returns Roman.I
       map.getAllKeys(Greek.ALPHA)      // returns Set<Roman> containing I, II, III

  Under the hood, this class uses a `TreeMap` so that entries are kept sorted by their keys. Thus, when using `getFirstKey(V)` one should expect the key that comes earliest in the sort order (declaration order for enumeration constants).

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `SafeMap.Builder<K,V>` SafeMap builder class.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `V` | `get(K key)` Returns the value mapped to the given key, or the default value if this map contains no mapping for the key.
    `Set<K>` | `getAllKeys(V value)` Return all keys that are mapped to the given value, or an empty set if no such mapping exists.
    `K` | `getDefaultKey()` Returns the default key for this map.
    `V` | `getDefaultValue()` Returns the default value for this map.
    `K` | `getFirstKey(V value)` Return the first key that is mapped to the given value, or the default key if no such mapping exists.
    `int` | `size()` Returns the number of elements in the map.
    `String` | `toString()`

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

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

- - ### Method Detail

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### get

          public V get(K key)

      Returns the value mapped to the given key, or the default value if this map contains no mapping for the key. The default value is also returned if `null` is specified as the key.
      Parameters:
        `key` - the key
      Returns:
        the mapped value

    - #### getFirstKey

          public K getFirstKey(V value)

      Return the first key that is mapped to the given value, or the default key if no such mapping exists.
      Parameters:
        `value` - the value
      Returns:
        the first key mapped to that value

    - #### getAllKeys

          public Set<K> getAllKeys(V value)

      Return all keys that are mapped to the given value, or an empty set if no such mapping exists.
      Parameters:
        `value` - the value
      Returns:
        the set of keys that map to this value

    - #### getDefaultValue

          public V getDefaultValue()

      Returns the default value for this map.
      Returns:
        the default value

    - #### getDefaultKey

          public K getDefaultKey()

      Returns the default key for this map.
      Returns:
        the default key

    - #### size

          public int size()

      Returns the number of elements in the map.
      Returns:
        the size of the map

Copyright © 2014. All Rights Reserved.