KezvhLib/src-lib/net/kezvh/collections/DualMap/DualMap.java

   1 package net.kezvh.collections.DualMap;
   2
   3 import java.util.Collection;
   4 import java.util.Map;
   5 import java.util.Set;
   6
   7 import net.kezvh.collections.Pair;
   8
   9 /**
  10  * Renamed from Bimap because google's already using that for "Bijective Map".
  11  * Bastards.
  12  *
  13  * @author mjacob
  14  * @param <K1> first key type
  15  * @param <K2> second key type
  16  * @param <V> value type
  17  */
  18 public interface DualMap<K1, K2, V> extends Map<Pair<K1, K2>, V> {
  19         /**
  20          * Returns the number of key-value mappings in this map. If the map contains
  21          * more than <tt>Integer.MAX_VALUE</tt> elements, returns
  22          * <tt>Integer.MAX_VALUE</tt>.
  23          *
  24          * @return the number of key-value mappings in this map
  25          */
  26         int size();
  27
  28         /**
  29          * Returns <tt>true</tt> if this map contains no key-value mappings.
  30          *
  31          * @return <tt>true</tt> if this map contains no key-value mappings
  32          */
  33         boolean isEmpty();
  34
  35         /**
  36          * Returns <tt>true</tt> if this map contains a mapping for the specified
  37          * key. More formally, returns <tt>true</tt> if and only if this map
  38          * contains a mapping for a key <tt>k</tt> such that
  39          * <tt>(key==null ? k==null : key.equals(k))</tt>. (There can be at most one
  40          * such mapping.)
  41          *
  42          * @param key1 key whose presence in this map is to be tested
  43          * @param key2 key whose presence in this map is to be tested
  44          * @return <tt>true</tt> if this map contains a mapping for the specified
  45          *         key
  46          * @throws ClassCastException if the key is of an inappropriate type for
  47          *             this map (optional)
  48          * @throws NullPointerException if the specified key is null and this map
  49          *             does not permit null keys (optional)
  50          */
  51         boolean containsKey(K1 key1, K2 key2);
  52
  53         /**
  54          * @param key1
  55          * @return true if the map has any keys with key1 specified
  56          */
  57         boolean containsKey1(K1 key1);
  58
  59         /**
  60          * @param key2
  61          * @return true if the map has any keys with key2 specified
  62          */
  63         boolean containsKey2(K2 key2);
  64
  65         /**
  66          * Returns the value to which the specified key is mapped, or {@code null}
  67          * if this map contains no mapping for the key.
  68          * <p>
  69          * More formally, if this map contains a mapping from a key {@code k} to a
  70          * value {@code v} such that {@code (key==null ? k==null : key.equals(k))},
  71          * then this method returns {@code v}; otherwise it returns {@code null}.
  72          * (There can be at most one such mapping.)
  73          * <p>
  74          * If this map permits null values, then a return value of {@code null} does
  75          * not <i>necessarily</i> indicate that the map contains no mapping for the
  76          * key; it's also possible that the map explicitly maps the key to {@code
  77          * null}. The {@link #containsKey containsKey} operation may be used to
  78          * distinguish these two cases.
  79          *
  80          * @param key1 the key whose associated value is to be returned
  81          * @param key2 the key whose associated value is to be returned
  82          * @return the value to which the specified key is mapped, or {@code null}
  83          *         if this map contains no mapping for the key
  84          * @throws ClassCastException if the key is of an inappropriate type for
  85          *             this map (optional)
  86          * @throws NullPointerException if the specified key is null and this map
  87          *             does not permit null keys (optional)
  88          */
  89         V get(K1 key1, K2 key2);
  90
  91         /**
  92          * @param key1 COMMENT
  93          * @return COMMENT
  94          */
  95         Collection<Map.Entry<K2, V>> get1(K1 key1);
  96
  97         /**
  98          * @param key2 COMMENT
  99          * @return COMMENT
 100          */
 101         Collection<Map.Entry<K1, V>> get2(K2 key2);
 102
 103         // Modification Operations
 104
 105         /**
 106          * Associates the specified value with the specified key in this map
 107          * (optional operation). If the map previously contained a mapping for the
 108          * key, the old value is replaced by the specified value. (A map <tt>m</tt>
 109          * is said to contain a mapping for a key <tt>k</tt> if and only if
 110          * {@link #containsKey(Object, Object) m.containsKey(k)} would return
 111          * <tt>true</tt>.)
 112          *
 113          * @param key1 key with which the specified value is to be associated
 114          * @param key2 key with which the specified value is to be associated
 115          * @param value value to be associated with the specified key
 116          * @return the previous value associated with <tt>key</tt>, or <tt>null</tt>
 117          *         if there was no mapping for <tt>key</tt>. (A <tt>null</tt> return
 118          *         can also indicate that the map previously associated
 119          *         <tt>null</tt> with <tt>key</tt>, if the implementation supports
 120          *         <tt>null</tt> values.)
 121          * @throws UnsupportedOperationException if the <tt>put</tt> operation is
 122          *             not supported by this map
 123          * @throws ClassCastException if the class of the specified key or value
 124          *             prevents it from being stored in this map
 125          * @throws NullPointerException if the specified key or value is null and
 126          *             this map does not permit null keys or values
 127          * @throws IllegalArgumentException if some property of the specified key or
 128          *             value prevents it from being stored in this map
 129          */
 130         V put(K1 key1, K2 key2, V value);
 131
 132         /**
 133          * Removes the mapping for a key from this map if it is present (optional
 134          * operation). More formally, if this map contains a mapping from key
 135          * <tt>k</tt> to value <tt>v</tt> such that
 136          * <code>(key==null ?  k==null : key.equals(k))</code>, that mapping is
 137          * removed. (The map can contain at most one such mapping.)
 138          * <p>
 139          * Returns the value to which this map previously associated the key, or
 140          * <tt>null</tt> if the map contained no mapping for the key.
 141          * <p>
 142          * If this map permits null values, then a return value of <tt>null</tt>
 143          * does not <i>necessarily</i> indicate that the map contained no mapping
 144          * for the key; it's also possible that the map explicitly mapped the key to
 145          * <tt>null</tt>.
 146          * <p>
 147          * The map will not contain a mapping for the specified key once the call
 148          * returns.
 149          *
 150          * @param key1 key whose mapping is to be removed from the map
 151          * @param key2 key whose mapping is to be removed from the map
 152          * @return the previous value associated with <tt>key</tt>, or <tt>null</tt>
 153          *         if there was no mapping for <tt>key</tt>.
 154          * @throws UnsupportedOperationException if the <tt>remove</tt> operation is
 155          *             not supported by this map
 156          * @throws ClassCastException if the key is of an inappropriate type for
 157          *             this map (optional)
 158          * @throws NullPointerException if the specified key is null and this map
 159          *             does not permit null keys (optional)
 160          */
 161         V remove(K1 key1, K2 key2);
 162
 163         /**
 164          * @param key1 COMMENT
 165          * @return COMMENT
 166          */
 167         Collection<Map.Entry<K2, V>> remove1(K1 key1);
 168
 169         /**
 170          * @param key2 COMMENT
 171          * @return COMMENT
 172          */
 173         Collection<Map.Entry<K1, V>> remove2(K2 key2);
 174
 175         // Bulk Operations
 176
 177         /**
 178          * Copies all of the mappings from the specified map to this map (optional
 179          * operation). The effect of this call is equivalent to that of calling
 180          * {@link #put(Object,Object,Object) put(k, v)} on this map once for each
 181          * mapping from key <tt>k</tt> to value <tt>v</tt> in the specified map. The
 182          * behavior of this operation is undefined if the specified map is modified
 183          * while the operation is in progress.
 184          *
 185          * @param m mappings to be stored in this map
 186          * @throws UnsupportedOperationException if the <tt>putAll</tt> operation is
 187          *             not supported by this map
 188          * @throws ClassCastException if the class of a key or value in the
 189          *             specified map prevents it from being stored in this map
 190          * @throws NullPointerException if the specified map is null, or if this map
 191          *             does not permit null keys or values, and the specified map
 192          *             contains null keys or values
 193          * @throws IllegalArgumentException if some property of a key or value in
 194          *             the specified map prevents it from being stored in this map
 195          */
 196         void putAll(DualMap<? extends K1, ? extends K2, ? extends V> m);
 197
 198         /**
 199          * Removes all of the mappings from this map (optional operation). The map
 200          * will be empty after this call returns.
 201          *
 202          * @throws UnsupportedOperationException if the <tt>clear</tt> operation is
 203          *             not supported by this map
 204          */
 205         void clear();
 206
 207         // Views
 208
 209         /**
 210          * Returns a {@link Set} view of the keys contained in this map. The set is
 211          * backed by the map, so changes to the map are reflected in the set, and
 212          * vice-versa. If the map is modified while an iteration over the set is in
 213          * progress (except through the iterator's own <tt>remove</tt> operation),
 214          * the results of the iteration are undefined. The set supports element
 215          * removal, which removes the corresponding mapping from the map, via the
 216          * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>, <tt>removeAll</tt>,
 217          * <tt>retainAll</tt>, and <tt>clear</tt> operations. It does not support
 218          * the <tt>add</tt> or <tt>addAll</tt> operations.
 219          *
 220          * @return a set view of the keys contained in this map
 221          */
 222         Set<Pair<K1, K2>> keySet();
 223
 224         /**
 225          * @param key1
 226          * @return set of key2s for which there is a value associated with (key1,
 227          *         key2)
 228          */
 229         Set<K2> keySetOnKey1(K1 key1);
 230
 231         /**
 232          * @param key2
 233          * @return set of key1s for which there is a value associated with (key1,
 234          *         key2)
 235          */
 236         Set<K1> keySetOnKey2(K2 key2);
 237
 238         /**
 239          * Returns a {@link Collection} view of the values contained in this map.
 240          * The collection is backed by the map, so changes to the map are reflected
 241          * in the collection, and vice-versa. If the map is modified while an
 242          * iteration over the collection is in progress (except through the
 243          * iterator's own <tt>remove</tt> operation), the results of the iteration
 244          * are undefined. The collection supports element removal, which removes the
 245          * corresponding mapping from the map, via the <tt>Iterator.remove</tt>,
 246          * <tt>Collection.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and
 247          * <tt>clear</tt> operations. It does not support the <tt>add</tt> or
 248          * <tt>addAll</tt> operations.
 249          *
 250          * @return a collection view of the values contained in this map
 251          */
 252         Collection<V> values();
 253
 254         /**
 255          * Returns a {@link Collection} view of the values contained in this map.
 256          * The collection is backed by the map, so changes to the map are reflected
 257          * in the collection, and vice-versa. If the map is modified while an
 258          * iteration over the collection is in progress (except through the
 259          * iterator's own <tt>remove</tt> operation), the results of the iteration
 260          * are undefined. The collection supports element removal, which removes the
 261          * corresponding mapping from the map, via the <tt>Iterator.remove</tt>,
 262          * <tt>Collection.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and
 263          * <tt>clear</tt> operations. It does not support the <tt>add</tt> or
 264          * <tt>addAll</tt> operations.
 265          *
 266          * @param key1
 267          * @return values associated with given key1
 268          */
 269         Collection<V> valuesOnKey1(K1 key1);
 270
 271         /**
 272          * Returns a {@link Collection} view of the values contained in this map.
 273          * The collection is backed by the map, so changes to the map are reflected
 274          * in the collection, and vice-versa. If the map is modified while an
 275          * iteration over the collection is in progress (except through the
 276          * iterator's own <tt>remove</tt> operation), the results of the iteration
 277          * are undefined. The collection supports element removal, which removes the
 278          * corresponding mapping from the map, via the <tt>Iterator.remove</tt>,
 279          * <tt>Collection.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and
 280          * <tt>clear</tt> operations. It does not support the <tt>add</tt> or
 281          * <tt>addAll</tt> operations.
 282          *
 283          * @param key2
 284          * @return values associated with given key2
 285          */
 286         Collection<V> valuesOnKey2(K2 key2);
 287
 288         /**
 289          * Returns a {@link Set} view of the mappings contained in this map. The set
 290          * is backed by the map, so changes to the map are reflected in the set, and
 291          * vice-versa. If the map is modified while an iteration over the set is in
 292          * progress (except through the iterator's own <tt>remove</tt> operation, or
 293          * through the <tt>setValue</tt> operation on a map entry returned by the
 294          * iterator) the results of the iteration are undefined. The set supports
 295          * element removal, which removes the corresponding mapping from the map,
 296          * via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>, <tt>removeAll</tt>
 297          * , <tt>retainAll</tt> and <tt>clear</tt> operations. It does not support
 298          * the <tt>add</tt> or <tt>addAll</tt> operations.
 299          *
 300          * @return a set view of the mappings contained in this map
 301          */
 302         @Override
 303         Set<Map.Entry<Pair<K1, K2>, V>> entrySet();
 304
 305         /**
 306          * Returns a {@link Set} view of the mappings contained in this map. The set
 307          * is backed by the map, so changes to the map are reflected in the set, and
 308          * vice-versa. If the map is modified while an iteration over the set is in
 309          * progress (except through the iterator's own <tt>remove</tt> operation, or
 310          * through the <tt>setValue</tt> operation on a map entry returned by the
 311          * iterator) the results of the iteration are undefined. The set supports
 312          * element removal, which removes the corresponding mapping from the map,
 313          * via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>, <tt>removeAll</tt>
 314          * , <tt>retainAll</tt> and <tt>clear</tt> operations. It does not support
 315          * the <tt>add</tt> or <tt>addAll</tt> operations.
 316          *
 317          * @param key1
 318          * @return entries for which there is a value for (key1, key2)
 319          */
 320         Set<DualMap.Entry<K1, K2, V>> entrySetOnKey1(K1 key1);
 321
 322         /**
 323          * Returns a {@link Set} view of the mappings contained in this map. The set
 324          * is backed by the map, so changes to the map are reflected in the set, and
 325          * vice-versa. If the map is modified while an iteration over the set is in
 326          * progress (except through the iterator's own <tt>remove</tt> operation, or
 327          * through the <tt>setValue</tt> operation on a map entry returned by the
 328          * iterator) the results of the iteration are undefined. The set supports
 329          * element removal, which removes the corresponding mapping from the map,
 330          * via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>, <tt>removeAll</tt>
 331          * , <tt>retainAll</tt> and <tt>clear</tt> operations. It does not support
 332          * the <tt>add</tt> or <tt>addAll</tt> operations.
 333          *
 334          * @param key2
 335          * @return entries for which there is a value for (key1, key2)
 336          */
 337         Set<DualMap.Entry<K1, K2, V>> entrySetOnKey2(K2 key2);
 338
 339         /**
 340          * Returns a map m such that m(key2) == this(key1, key2). It is backed by
 341          * this map.
 342          *
 343          * @param key1
 344          * @return map
 345          */
 346         Map<K2, V> entryMapOnKey1(K1 key1);
 347
 348         /**
 349          * Returns a map m such that m(key1) == this(key1, key2). It is backed by
 350          * this map.
 351          *
 352          * @param key2
 353          * @return map
 354          */
 355         Map<K1, V> entryMapOnKey2(K2 key2);
 356
 357         /**
 358          * A map entry (key-value pair). The <tt>Map.entrySet</tt> method returns a
 359          * collection-view of the map, whose elements are of this class. The
 360          * <i>only</i> way to obtain a reference to a map entry is from the iterator
 361          * of this collection-view. These <tt>Map.Entry</tt> objects are valid
 362          * <i>only</i> for the duration of the iteration; more formally, the
 363          * behavior of a map entry is undefined if the backing map has been modified
 364          * after the entry was returned by the iterator, except through the
 365          * <tt>setValue</tt> operation on the map entry.
 366          *
 367          * @see DualMap#entrySet()
 368          * @author mjacob
 369          * @param <K1>
 370          * @param <K2>
 371          * @param <V>
 372          */
 373         interface Entry<K1, K2, V> extends Map.Entry<Pair<K1, K2>, V> {
 374                 /**
 375                  * Returns the key corresponding to this entry.
 376                  *
 377                  * @return the key corresponding to this entry
 378                  * @throws IllegalStateException implementations may, but are not
 379                  *             required to, throw this exception if the entry has been
 380                  *             removed from the backing map.
 381                  */
 382                 K1 getKey1();
 383
 384                 /**
 385                  * Returns the key corresponding to this entry.
 386                  *
 387                  * @return the key corresponding to this entry
 388                  * @throws IllegalStateException implementations may, but are not
 389                  *             required to, throw this exception if the entry has been
 390                  *             removed from the backing map.
 391                  */
 392                 K2 getKey2();
 393
 394                 /**
 395                  * Returns the value corresponding to this entry. If the mapping has
 396                  * been removed from the backing map (by the iterator's <tt>remove</tt>
 397                  * operation), the results of this call are undefined.
 398                  *
 399                  * @return the value corresponding to this entry
 400                  * @throws IllegalStateException implementations may, but are not
 401                  *             required to, throw this exception if the entry has been
 402                  *             removed from the backing map.
 403                  */
 404                 V getValue();
 405
 406                 /**
 407                  * Replaces the value corresponding to this entry with the specified
 408                  * value (optional operation). (Writes through to the map.) The behavior
 409                  * of this call is undefined if the mapping has already been removed
 410                  * from the map (by the iterator's <tt>remove</tt> operation).
 411                  *
 412                  * @param value new value to be stored in this entry
 413                  * @return old value corresponding to the entry
 414                  * @throws UnsupportedOperationException if the <tt>put</tt> operation
 415                  *             is not supported by the backing map
 416                  * @throws ClassCastException if the class of the specified value
 417                  *             prevents it from being stored in the backing map
 418                  * @throws NullPointerException if the backing map does not permit null
 419                  *             values, and the specified value is null
 420                  * @throws IllegalArgumentException if some property of this value
 421                  *             prevents it from being stored in the backing map
 422                  * @throws IllegalStateException implementations may, but are not
 423                  *             required to, throw this exception if the entry has been
 424                  *             removed from the backing map.
 425                  */
 426                 V setValue(V value);
 427
 428                 /**
 429                  * Compares the specified object with this entry for equality. Returns
 430                  * <tt>true</tt> if the given object is also a map entry and the two
 431                  * entries represent the same mapping. More formally, two entries
 432                  * <tt>e1</tt> and <tt>e2</tt> represent the same mapping if
 433                  *
 434                  * <pre>
 435                  * (e1.getKey() == null ? e2.getKey() == null : e1.getKey().equals(e2.getKey())) &amp;&amp; (e1.getValue() == null ? e2.getValue() == null : e1.getValue().equals(e2.getValue()))
 436                  * </pre>
 437                  *
 438                  * This ensures that the <tt>equals</tt> method works properly across
 439                  * different implementations of the <tt>Map.Entry</tt> interface.
 440                  *
 441                  * @param o object to be compared for equality with this map entry
 442                  * @return <tt>true</tt> if the specified object is equal to this map
 443                  *         entry
 444                  */
 445                 boolean equals(Object o);
 446
 447                 /**
 448                  * Returns the hash code value for this map entry. The hash code of a
 449                  * map entry <tt>e</tt> is defined to be:
 450                  *
 451                  * <pre>
 452                  * (e.getKey() == null ? 0 : e.getKey().hashCode()) &circ; (e.getValue() == null ? 0 : e.getValue().hashCode())
 453                  * </pre>
 454                  *
 455                  * This ensures that <tt>e1.equals(e2)</tt> implies that
 456                  * <tt>e1.hashCode()==e2.hashCode()</tt> for any two Entries <tt>e1</tt>
 457                  * and <tt>e2</tt>, as required by the general contract of
 458                  * <tt>Object.hashCode</tt>.
 459                  *
 460                  * @return the hash code value for this map entry
 461                  * @see Object#hashCode()
 462                  * @see Object#equals(Object)
 463                  * @see #equals(Object)
 464                  */
 465                 int hashCode();
 466         }
 467
 468         // Comparison and hashing
 469
 470         /**
 471          * Compares the specified object with this map for equality. Returns
 472          * <tt>true</tt> if the given object is also a map and the two maps
 473          * represent the same mappings. More formally, two maps <tt>m1</tt> and
 474          * <tt>m2</tt> represent the same mappings if
 475          * <tt>m1.entrySet().equals(m2.entrySet())</tt>. This ensures that the
 476          * <tt>equals</tt> method works properly across different implementations of
 477          * the <tt>Map</tt> interface.
 478          *
 479          * @param o object to be compared for equality with this map
 480          * @return <tt>true</tt> if the specified object is equal to this map
 481          */
 482         boolean equals(Object o);
 483
 484         /**
 485          * Returns the hash code value for this map. The hash code of a map is
 486          * defined to be the sum of the hash codes of each entry in the map's
 487          * <tt>entrySet()</tt> view. This ensures that <tt>m1.equals(m2)</tt>
 488          * implies that <tt>m1.hashCode()==m2.hashCode()</tt> for any two maps
 489          * <tt>m1</tt> and <tt>m2</tt>, as required by the general contract of
 490          * {@link Object#hashCode}.
 491          *
 492          * @return the hash code value for this map
 493          * @see Map.Entry#hashCode()
 494          * @see Object#equals(Object)
 495          * @see #equals(Object)
 496          */
 497         int hashCode();
 498
 499 }