1 package annotations.util.coll; 2 3 import java.util.Set; 4 5 /*>>> 6 import org.checkerframework.checker.nullness.qual.*; 7 */ 8 9 /** 10 * A <code>KeyedSet</code> is a set whose members have distinct <em>keys</em> 11 * and can be looked up by key. A {@link Keyer} provides keys for the elements. 12 * It is forbidden for an element's key to change while the element is in the 13 * set. 14 */ 15 public interface KeyedSet<K, V> extends Set<V> { 16 /** 17 * Returns the <code>Keyer</code> that this <code>KeyedSet</code> uses 18 * to obtain keys for elements. 19 * 20 * @return the <code>Keyer</code> that this <code>KeyedSet</code> uses 21 * to obtain keys for elements 22 */ 23 public abstract Keyer<? extends K, ? super V> getKeyer(); 24 25 /** 26 * Calls 27 * 28 * @{link #add(V, int, int) add(v, THROW_EXCEPTION, IGNORE)} and returns 29 * true if <code>v</code> was added. 30 * @param v 31 * the object to be added 32 * @return <code>true</code> if <code>v</code> was added 33 */ 34 // public abstract boolean add(V v); // causes "ambiguities" for some 35 // strange reason 36 /** 37 * Conflict/equal behavior that does nothing. 38 */ 39 public static final int IGNORE = -1; 40 41 /** 42 * Conflict/equal behavior that throws an {@link IllegalStateException}. 43 */ 44 public static final int THROW_EXCEPTION = 0; 45 46 /** 47 * Conflict/equal behavior that removes the existing object and then adds 48 * the new object. 49 */ 50 public static final int REPLACE = 1; 51 52 /** 53 * Adds <code>v</code> to this <code>KeyedSet</code>; this set's 54 * <code>Keyer</code> will be called once to fetch <code>v</code>'s 55 * key. If an object equal to <code>v</code> is already present in this 56 * <code>KeyedSet</code>, then this method carries out the 57 * <code>equalBehavior</code> and returns the existing object. Otherwise, 58 * if an object having a key equal to <code>v</code>'s is already present 59 * in this <code>KeyedSet</code>, then this method carries out the 60 * <code>conflictBehavior</code> and returns the existing object. 61 * Otherwise, this method adds <code>v</code> to this 62 * <code>KeyedSet</code> and returns null. 63 * 64 * @param v 65 * the object to be added 66 * @param conflictBehavior 67 * specifies what to do if <code>v</code>'s key equals an 68 * existing object's key 69 * @param equalBehavior 70 * specifies what to do if <code>v</code> equals an existing 71 * object 72 * @return the existing object whose key matched <code>v</code>'s, if any 73 */ 74 public abstract V add(V v, int conflictBehavior, int equalBehavior); 75 76 /** 77 * Adds <code>v</code> to this <code>KeyedSet</code>, replacing and 78 * returning an existing object with the same key as <code>v</code> (if 79 * any). The existing object is replaced with <code>v</code> even if it 80 * equals <code>v</code>. If no existing object is replaced, null is 81 * returned. 82 */ 83 public abstract V replace(V v); 84 85 /** 86 * Looks for and returns an element with key <code>k</code>, or 87 * <code>null</code> if none. 88 * 89 * @return the element with key <code>k</code>, or <code>null</code> if 90 * none 91 */ 92 public abstract V lookup(K k); 93 } 94
