com.threerings.presents.dobj
Class DSet<E extends DSet.Entry>

java.lang.Object
  com.threerings.presents.dobj.DSet<E>

Type Parameters:

E - the type of entry stored in this set.

All Implemented Interfaces:

Streamable, Cloneable, Iterable<E>

public class DSet<E extends DSet.Entry>
extends Object
implements Iterable<E>, Streamable, Cloneable

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 DSet.Entry interface which extends 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 DSet.Entry.getKey() method is equal (using Object.equals(java.lang.Object)) to the entry returned by the DSet.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 DSet.Entry.getKey() must be a Streamable type.

Nested Class Summary

static interface

DSet.Entry Entries of the set must implement this interface.

Field Summary

protected E[]	_entries The entries of the set (in a sparse array).
protected int	_modCount Used to check for concurrent modification.
protected int	_size The number of entries in this set.
protected static Comparator<DSet.Entry>	ENTRY_COMP Used for lookups and to keep the set contents sorted on insertions.
protected static int	INITIAL_CAPACITY The default capacity of a set instance.

Constructor Summary

DSet()
Constructs an empty distributed set.

DSet(E[] source)
Creates a distributed set and populates it with values from the supplied array.

DSet(Iterable<E> source)
Creates a distributed set and populates it with values from the supplied iterator.

DSet(Iterator<E> source)
Creates a distributed set and populates it with values from the supplied iterator.

Method Summary

protected boolean	add(E elem) Adds the specified entry to the set.
Set<E>	asSet() Creates an immutable view of this distributed set as a Java set.
DSet<E>	clone() Generates a shallow copy of this object.
static int	compare(Comparable<?> c1, Comparable<?> c2) Compares the first comparable to the second.
boolean	contains(E elem) 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.
boolean	containsKey(Comparable<?> key) Returns true if an entry in the set has a key that equals() the supplied key.
Iterator<E>	entries() Deprecated.
E	get(Comparable<?> key) Returns the entry that matches (getKey().equals(key)) the specified key or null if no entry could be found that matches the key.
protected int	getWarningSize() Returns the minimum size where we should warn that we're getting a bit large.
Iterator<E>	iterator() Returns an iterator over the entries of this set.
static <E extends DSet.Entry> DSet<E>	newDSet() Creates a new DSet of the appropriate generic type.
static <E extends DSet.Entry> DSet<E>	newDSet(Iterable<E> source) Creates a new DSet of the appropriate generic type.
void	readObject(ObjectInputStream in) Custom reader method.
protected boolean	remove(E elem) Removes the specified entry from the set.
protected E	removeKey(Comparable<?> key) Removes from the set the entry whose key matches the supplied key.
int	size() Returns the number of entries in this set.
E[]	toArray(E[] array) Copies the elements of this distributed set into the supplied array.
Object[]	toArray(Object[] array) Deprecated. use toArray(Entry[]).
String	toString()
DSet<E>	typedClone() Deprecated. clone() works just fine now.
protected E	update(E elem) Updates the specified entry by locating an entry whose key matches the key of the supplied entry and overwriting it.
void	writeObject(ObjectOutputStream out) Custom writer method.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_entries

protected E extends DSet.Entry[] _entries

The entries of the set (in a sparse array).

_size

protected int _size

The number of entries in this set.

_modCount

protected transient int _modCount

Used to check for concurrent modification.

INITIAL_CAPACITY

protected static final int INITIAL_CAPACITY

The default capacity of a set instance.

See Also:

Constant Field Values

ENTRY_COMP

protected static Comparator<DSet.Entry> ENTRY_COMP

Used for lookups and to keep the set contents sorted on insertions.

Constructor Detail

DSet

public DSet(Iterable<E> source)

Creates a distributed set and populates it with values from the supplied iterator. This should be done before the set is unleashed into the wild distributed object world because no associated entry added events will be generated. Additionally, this operation does not check for duplicates when adding entries, so one should be sure that the iterator contains only unique entries.

Parameters:

source - an iterator from which we will initially populate the set.

DSet

public DSet(Iterator<E> source)

Creates a distributed set and populates it with values from the supplied iterator. This should be done before the set is unleashed into the wild distributed object world because no associated entry added events will be generated. Additionally, this operation does not check for duplicates when adding entries, so one should be sure that the iterator contains only unique entries.

Parameters:

source - an iterator from which we will initially populate the set.

DSet

public DSet(E[] source)

Creates a distributed set and populates it with values from the supplied array. This should be done before the set is unleashed into the wild distributed object world because no associated entry added events will be generated. Additionally, this operation does not check for duplicates when adding entries, so one should be sure that the iterator contains only unique entries.

Parameters:

source - an array from which we will initially populate the set.

DSet

public DSet()

Constructs an empty distributed set.

Method Detail

newDSet

public static <E extends DSet.Entry> DSet<E> newDSet()

Creates a new DSet of the appropriate generic type.

newDSet

public static <E extends DSet.Entry> DSet<E> newDSet(Iterable<E> source)

Creates a new DSet of the appropriate generic type.

compare

public static int compare(Comparable<?> c1,
                          Comparable<?> c2)

Compares the first comparable to the second. This is useful to avoid type safety warnings when dealing with the keys of DSet.Entry values.

size

public int size()

Returns the number of entries in this set.

contains

public boolean contains(E elem)

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.

containsKey

public boolean containsKey(Comparable<?> key)

Returns true if an entry in the set has a key that equals() the supplied key. Returns false otherwise.

get

public E get(Comparable<?> key)

Returns the entry that matches (getKey().equals(key)) the specified key or null if no entry could be found that matches the key.

entries

@Deprecated
public Iterator<E> entries()

Deprecated.

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.

iterator

public Iterator<E> iterator()

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.

Specified by:

iterator in interface Iterable<E extends DSet.Entry>

toArray

public E[] toArray(E[] array)

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.

asSet

public Set<E> asSet()

Creates an immutable view of this distributed set as a Java set.

toArray

@Deprecated
public Object[] toArray(Object[] array)

Deprecated. use toArray(Entry[]).

add

protected boolean add(E elem)

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.

Returns:

true if the entry was added, false if it was already in the set.

remove

protected boolean remove(E elem)

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.

Returns:

true if the entry was removed, false if it was not in the set.

removeKey

protected E removeKey(Comparable<?> key)

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.

Returns:

the old matching entry if found and removed, null if not found.

update

protected E update(E elem)

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.

Returns:

the old entry that was replaced, or null if it was not found (in which case nothing is updated).

getWarningSize

protected int getWarningSize()

Returns the minimum size where we should warn that we're getting a bit large.

typedClone

@Deprecated
public DSet<E> typedClone()

Deprecated. clone() works just fine now.

Generates a shallow copy of this object in a type safe manner.

clone

public DSet<E> clone()

Generates a shallow copy of this object.

Overrides:

clone in class Object

toString

public String toString()

Overrides:

toString in class Object

writeObject

public void writeObject(ObjectOutputStream out)
                 throws IOException

Custom writer method. @see Streamable.

Throws:

IOException

readObject

public void readObject(ObjectInputStream in)
                throws IOException,
                       ClassNotFoundException

Custom reader method. @see Streamable.

Throws:

IOException

ClassNotFoundException