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

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