1 files changed, 93 insertions, 0 deletions
diff --git a/scene-lib/src/annotations/util/coll/KeyedSet.java b/scene-lib/src/annotations/util/coll/KeyedSet.java
new file mode 100644
index 0000000..7da5ff7
--- /dev/null
+++ b/scene-lib/src/annotations/util/coll/KeyedSet.java
@@ -0,0 +1,93 @@
+package annotations.util.coll;
+
+import java.util.Set;
+
+/*>>>
+import org.checkerframework.checker.nullness.qual.*;
+*/
+
+/**
+ * A <code>KeyedSet</code> is a set whose members have distinct <em>keys</em>
+ * and can be looked up by key. A {@link Keyer} provides keys for the elements.
+ * It is forbidden for an element's key to change while the element is in the
+ * set.
+ */
+public interface KeyedSet<K, V> extends Set<V> {
+    /**
+     * Returns the <code>Keyer</code> that this <code>KeyedSet</code> uses
+     * to obtain keys for elements.
+     *
+     * @return the <code>Keyer</code> that this <code>KeyedSet</code> uses
+     *         to obtain keys for elements
+     */
+    public abstract Keyer<? extends K, ? super V> getKeyer();
+
+    /**
+     * Calls
+     *
+     * @{link #add(V, int, int) add(v, THROW_EXCEPTION, IGNORE)} and returns
+     *        true if <code>v</code> was added.
+     * @param v
+     *            the object to be added
+     * @return <code>true</code> if <code>v</code> was added
+     */
+    // public abstract boolean add(V v); // causes "ambiguities" for some
+    // strange reason
+    /**
+     * Conflict/equal behavior that does nothing.
+     */
+    public static final int IGNORE = -1;
+
+    /**
+     * Conflict/equal behavior that throws an {@link IllegalStateException}.
+     */
+    public static final int THROW_EXCEPTION = 0;
+
+    /**
+     * Conflict/equal behavior that removes the existing object and then adds
+     * the new object.
+     */
+    public static final int REPLACE = 1;
+
+    /**
+     * Adds <code>v</code> to this <code>KeyedSet</code>; this set's
+     * <code>Keyer</code> will be called once to fetch <code>v</code>'s
+     * key. If an object equal to <code>v</code> is already present in this
+     * <code>KeyedSet</code>, then this method carries out the
+     * <code>equalBehavior</code> and returns the existing object. Otherwise,
+     * if an object having a key equal to <code>v</code>'s is already present
+     * in this <code>KeyedSet</code>, then this method carries out the
+     * <code>conflictBehavior</code> and returns the existing object.
+     * Otherwise, this method adds <code>v</code> to this
+     * <code>KeyedSet</code> and returns null.
+     *
+     * @param v
+     *            the object to be added
+     * @param conflictBehavior
+     *            specifies what to do if <code>v</code>'s key equals an
+     *            existing object's key
+     * @param equalBehavior
+     *            specifies what to do if <code>v</code> equals an existing
+     *            object
+     * @return the existing object whose key matched <code>v</code>'s, if any
+     */
+    public abstract V add(V v, int conflictBehavior, int equalBehavior);
+
+    /**
+     * Adds <code>v</code> to this <code>KeyedSet</code>, replacing and
+     * returning an existing object with the same key as <code>v</code> (if
+     * any).  The existing object is replaced with <code>v</code> even if it
+     * equals <code>v</code>.  If no existing object is replaced, null is
+     * returned.
+     */
+    public abstract V replace(V v);
+
+    /**
+     * Looks for and returns an element with key <code>k</code>, or
+     * <code>null</code> if none.
+     *
+     * @return the element with key <code>k</code>, or <code>null</code> if
+     *         none
+     */
+    public abstract V lookup(K k);
+}