diff --git a/src/java/com/threerings/presents/dobj/DSet.java b/src/java/com/threerings/presents/dobj/DSet.java index d518bf43f..07b2b8fc7 100644 --- a/src/java/com/threerings/presents/dobj/DSet.java +++ b/src/java/com/threerings/presents/dobj/DSet.java @@ -37,22 +37,18 @@ import com.threerings.io.Streamable; import com.threerings.presents.Log; /** - * The distributed set class provides a means by which an unordered set of - * objects can be maintained as a distributed object field. Entries can be - * added to and removed from the set, requests for which will generate - * events much like other distributed object fields. + * The distributed set class provides a means by which an unordered set of objects can be + * maintained as a distributed object field. Entries can be added to and removed from the set, + * requests for which will generate events much like other distributed object fields. * - *
Classes that wish to act as set entries must implement the {@link - * Entry} interface which extends {@link Streamable} and adds the - * requirement that the object provide a key which will be used to - * identify entry equality. Thus an entry is declared to be in a set of - * the object returned by that entry's {@link Entry#getKey} method is - * equal (using {@link Object#equals}) to the entry returned by the {@link - * Entry#getKey} method of some other entry in the set. Additionally, in - * the case of entry removal, only the key for the entry to be removed - * will be transmitted with the removal event to save network - * bandwidth. Lastly, the object returned by {@link Entry#getKey} must be - * a {@link Streamable} type. + *
Classes that wish to act as set entries must implement the {@link Entry} interface which
+ * extends {@link Streamable} and adds the requirement that the object provide a key which will be
+ * used to identify entry equality. Thus an entry is declared to be in a set of the object returned
+ * by that entry's {@link Entry#getKey} method is equal (using {@link Object#equals}) to the entry
+ * returned by the {@link Entry#getKey} method of some other entry in the set. Additionally, in the
+ * case of entry removal, only the key for the entry to be removed will be transmitted with the
+ * removal event to save network bandwidth. Lastly, the object returned by {@link Entry#getKey}
+ * must be a {@link Streamable} type.
*/
public class DSetgetKey() method returns a key that
- * equals() the key returned by getKey() of
- * the supplied entry. Returns false otherwise.
+ * Returns true if the set contains an entry whose getKey() method returns a key
+ * that equals() the key returned by getKey() of the supplied
+ * entry. Returns false otherwise.
*/
public boolean contains (E elem)
{
@@ -135,8 +141,8 @@ public class DSetequals() the supplied key. Returns false otherwise.
+ * Returns true if an entry in the set has a key that equals() the supplied
+ * key. Returns false otherwise.
*/
public boolean containsKey (Comparable key)
{
@@ -144,23 +150,20 @@ public class DSetgetKey().equals(key))
- * the specified key or null if no entry could be found that matches
- * the key.
+ * Returns the entry that matches (getKey().equals(key)) the specified key or null
+ * if no entry could be found that matches the key.
*/
public E get (Comparable key)
{
// determine where we'll be adding the new element
- int eidx = ArrayUtil.binarySearch(
- _entries, 0, _size, key, ENTRY_COMP);
+ int eidx = ArrayUtil.binarySearch(_entries, 0, _size, key, ENTRY_COMP);
return (eidx < 0) ? null : _entries[eidx];
}
/**
- * Returns an iterator over the entries of this set. It does not
- * support modification (nor iteration while modifications are being
- * made to the set). It should not be kept around as it can quickly
- * become out of date.
+ * Returns an iterator over the entries of this set. It does not support modification (nor
+ * iteration while modifications are being made to the set). It should not be kept around as it
+ * can quickly become out of date.
*
* @deprecated
*/
@@ -171,10 +174,9 @@ public class DSetarray argument is null, an object array of sufficient
- * size to contain all of the elements of this set will be created and
- * returned.
+ * Copies the elements of this distributed set into the supplied array. If the array is not
+ * large enough to hold all of the elements, as many as fit into the array will be copied. If
+ * the array argument is null, an object array of sufficient size to contain all
+ * of the elements of this set will be created and returned.
*/
public E[] toArray (E[] array)
{
@@ -245,24 +244,20 @@ public class DSetaddTo{Set}() method
- * should be called on the distributed object that contains the set in
- * question.
+ * Adds the specified entry to the set. This should not be called directly, instead the
+ * associated addTo{Set}() method should be called on the distributed object that
+ * contains the set in question.
*
- * @return true if the entry was added, false if it was already in
- * the set.
+ * @return true if the entry was added, false if it was already in the set.
*/
protected boolean add (E elem)
{
// determine where we'll be adding the new element
- int eidx = ArrayUtil.binarySearch(
- _entries, 0, _size, elem, ENTRY_COMP);
+ int eidx = ArrayUtil.binarySearch(_entries, 0, _size, elem, ENTRY_COMP);
// if the element is already in the set, bail now
if (eidx >= 0) {
- Log.warning("Refusing to add duplicate entry [entry=" + elem +
- ", set=" + this + "].");
+ Log.warning("Refusing to add duplicate entry [entry=" + elem + ", set=" + this + "].");
return false;
}
@@ -274,20 +269,17 @@ public class DSetremoveFrom{Set}()
- * method should be called on the distributed object that contains the
- * set in question.
+ * Removes the specified entry from the set. This should not be called directly, instead the
+ * associated removeFrom{Set}() method should be called on the distributed object
+ * that contains the set in question.
*
- * @return true if the entry was removed, false if it was not in the
- * set.
+ * @return true if the entry was removed, false if it was not in the set.
*/
protected boolean remove (E elem)
{
@@ -315,13 +305,11 @@ public class DSetremoveFrom{Set}() method should be called on the
- * distributed object that contains the set in question.
+ * Removes from the set the entry whose key matches the supplied key. This should not be called
+ * directly, instead the associated removeFrom{Set}() method should be called on
+ * the distributed object that contains the set in question.
*
- * @return the old matching entry if found and removed, null if not
- * found.
+ * @return the old matching entry if found and removed, null if not found.
*/
protected E removeKey (Comparable key)
{
@@ -333,19 +321,16 @@ public class DSetupdate{Set}() method should be called on the
- * distributed object that contains the set in question.
+ * Updates the specified entry by locating an entry whose key matches the key of the supplied
+ * entry and overwriting it. This should not be called directly, instead the associated
+ * update{Set}() method should be called on the distributed object that contains
+ * the set in question.
*
- * @return the old entry that was replaced, or null if it was not
- * found (in which case nothing is updated).
+ * @return the old entry that was replaced, or null if it was not found (in which case nothing
+ * is updated).
*/
protected E update (E elem)
{
// look up this entry's position in our set
- int eidx = ArrayUtil.binarySearch(
- _entries, 0, _size, elem, ENTRY_COMP);
+ int eidx = ArrayUtil.binarySearch(_entries, 0, _size, elem, ENTRY_COMP);
// if we found it, update it
if (eidx >= 0) {
@@ -396,10 +379,8 @@ public class DSet