com.tangosol.util
Class LiteSet

java.lang.Object
  java.util.AbstractCollection
      java.util.AbstractSet
          com.tangosol.util.LiteSet

All Implemented Interfaces:

ExternalizableLite, Externalizable, Serializable, Cloneable, Iterable, Collection, Set

public class LiteSet
extends AbstractSet
implements Cloneable, Externalizable, ExternalizableLite

An implementation of java.util.Set that is optimal (in terms of both size and speed) for very small sets of data but still works excellently with large sets of data. This implementation is not thread-safe.

The LiteSet implementation switches at runtime between several different sub-implementations for storing the set of objects, described here:

1. "empty set" - a set that contains no data;
2. "single entry" - a reference directly to an item is used to represent a set with exactly one item in it;
3. "Object[]" - a reference is held to an array of Objects that store the contents of the Set; the item limit for this implementation is determined by the THRESHOLD constant;
4. "delegation" - for more than THRESHOLD items, a set is created to delegate the set management to; sub-classes can override the default delegation class (java.util.HashSet) by overriding the factory method instantiateSet().

The LiteSet implementation supports the null value.

Author:

cp 06/02/99

Constructor Summary

LiteSet()
Construct a LiteSet

LiteSet(Collection collection)
Construct a LiteSet containing the elements of the passed Collection.

Method Summary

boolean	add(Object o) Ensures that this Set contains the specified element.
boolean	addAll(Collection collection) Adds all of the elements in the specified Collection to this Set if they are not already present.
protected void	checkShrinkFromOther() After a mutation operation has reduced the size of an underlying Set, check if the delegation model should be replaced with a more size- efficient storage approach, and switch accordingly.
void	clear() Removes all of the elements from this Set.
Object	clone() Create a clone of this Set.
boolean	contains(Object o) Returns true if this Set contains the specified element.
boolean	containsAll(Collection collection) Returns true if this Set contains all of the elements in the specified Collection.
Enumeration	elements() Returns an Enumerator over the elements in this Set.
protected void	initFromArray(Object[] ao, int c) Initialize the contents of this Set from the passed array ao containing c values.
protected Set	instantiateSet() (Factory pattern) Instantiate a Set object to store items in once the "lite" threshold has been exceeded.
boolean	isEmpty() Determine if this Set is empty.
Iterator	iterator() Returns an Iterator over the elements in this Set.
void	readExternal(DataInput in) Restore the contents of this object by loading the object's state from the passed DataInput object.
void	readExternal(ObjectInput in) Initialize this object from the data in the passed ObjectInput stream.
boolean	remove(Object o) Removes the specified element from this Set if it is present.
boolean	removeAll(Collection collection) Removes from this Set all of its elements that are contained in the specified Collection.
boolean	retainAll(Collection collection) Retains only the elements in this Set that are contained in the specified Collection.
int	size() Returns the number of elements in this Set (its cardinality).
Object[]	toArray() Returns an array containing all of the elements in this Set.
Object[]	toArray(Object[] aDest) Returns an array (whose runtime type is that of the specified array) containing all of the elements in this Set.
void	writeExternal(DataOutput out) Save the contents of this object by storing the object's state into the passed DataOutput object.
void	writeExternal(ObjectOutput out) Write this object's data to the passed ObjectOutput stream.

Methods inherited from class java.util.AbstractSet

equals, hashCode

Methods inherited from class java.util.AbstractCollection

toString

Constructor Detail

LiteSet

public LiteSet()

Construct a LiteSet

LiteSet

public LiteSet(Collection collection)

Construct a LiteSet containing the elements of the passed Collection.

Parameters:

collection - a Collection

Method Detail

isEmpty

public boolean isEmpty()

Determine if this Set is empty.

Specified by:

isEmpty in interface Collection

Specified by:

isEmpty in interface Set

Overrides:

isEmpty in class AbstractCollection

Returns:

true iff this Set is empty

size

public int size()

Returns the number of elements in this Set (its cardinality).

Specified by:

size in interface Collection

Specified by:

size in interface Set

Specified by:

size in class AbstractCollection

Returns:

the number of elements in this Set

contains

public boolean contains(Object o)

Returns true if this Set contains the specified element. More formally, returns true if and only if this Set contains an element e such that (o==null ? e==null : o.equals(e)).

Specified by:

contains in interface Collection

Specified by:

contains in interface Set

Overrides:

contains in class AbstractCollection

Parameters:

o - the object to check for

Returns:

true if this Set contains the specified element

iterator

public Iterator iterator()

Returns an Iterator over the elements in this Set. The elements are returned in an arbitrary order.

Specified by:

iterator in interface Iterable

Specified by:

iterator in interface Collection

Specified by:

iterator in interface Set

Specified by:

iterator in class AbstractCollection

Returns:

an iterator over the elements in this Set

elements

public Enumeration elements()

Returns an Enumerator over the elements in this Set. The elements are returned in an arbitrary order.

Returns:

an Enumerator over the elements in this Set

toArray

public Object[] toArray()

Returns an array containing all of the elements in this Set. Obeys the general contract of the Set.toArray method.

Specified by:

toArray in interface Collection

Specified by:

toArray in interface Set

Overrides:

toArray in class AbstractCollection

Returns:

an array containing all of the elements in this Set

toArray

public Object[] toArray(Object[] aDest)

Returns an array (whose runtime type is that of the specified array) containing all of the elements in this Set. Obeys the general contract of the Set.toArray(Object[]) method.

Specified by:

toArray in interface Collection

Specified by:

toArray in interface Set

Overrides:

toArray in class AbstractCollection

Parameters:

aDest - the array into which the elements of this Set are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose

Returns:

an array containing the elements of this Set

Throws:

ArrayStoreException - if the component type of aDest is not a supertype of the type of every element in this Set

add

public boolean add(Object o)

Ensures that this Set contains the specified element. Returns true if the Set changed as a result of the call. (Returns false if this Set already contains the specified element.)

Specified by:

add in interface Collection

Specified by:

add in interface Set

Overrides:

add in class AbstractCollection

Parameters:

o - element to be added to this Set

Returns:

true if this Set did not already contain the specified element

remove

public boolean remove(Object o)

Removes the specified element from this Set if it is present. More formally, removes an element e such that (o==null ? e==null : o.equals(e)), if the Set contains such an element. Returns true if the Set contained the specified element (or equivalently, if the Set changed as a result of the call). The Set will not contain the specified element once the call returns.

Specified by:

remove in interface Collection

Specified by:

remove in interface Set

Overrides:

remove in class AbstractCollection

Parameters:

o - object to be removed from this Set, if present

Returns:

true if the Set contained the specified element

containsAll

public boolean containsAll(Collection collection)

Returns true if this Set contains all of the elements in the specified Collection.

Specified by:

containsAll in interface Collection

Specified by:

containsAll in interface Set

Overrides:

containsAll in class AbstractCollection

Parameters:

collection - Collection to be checked for containment in this Set

Returns:

true if this Set contains all of the elements in the specified Collection

addAll

public boolean addAll(Collection collection)

Adds all of the elements in the specified Collection to this Set if they are not already present. If the specified Collection is also a Set, the addAll operation effectively modifies this Set so that its value is the union of the two Sets.

Specified by:

addAll in interface Collection

Specified by:

addAll in interface Set

Overrides:

addAll in class AbstractCollection

Parameters:

collection - Collection whose elements are to be added to this Set

Returns:

true if this Set changed as a result of the call

retainAll

public boolean retainAll(Collection collection)

Retains only the elements in this Set that are contained in the specified Collection. In other words, removes from this Set all of its elements that are not contained in the specified Collection. If the specified Collection is also a Set, this operation effectively modifies this Set so that its value is the intersection of the two Sets.

Specified by:

retainAll in interface Collection

Specified by:

retainAll in interface Set

Overrides:

retainAll in class AbstractCollection

Parameters:

collection - collection that defines which elements this Set will retain

Returns:

true if this Set changed as a result of the call

removeAll

public boolean removeAll(Collection collection)

Removes from this Set all of its elements that are contained in the specified Collection. If the specified Collection is also a Set, this operation effectively modifies this Set so that its value is the asymmetric set difference of the two Sets.

Specified by:

removeAll in interface Collection

Specified by:

removeAll in interface Set

Overrides:

removeAll in class AbstractSet

Parameters:

collection - Collection that defines which elements will be removed from this Set

Returns:

true if this Set changed as a result of the call

clear

public void clear()

Removes all of the elements from this Set. This Set will be empty after this call returns.

Specified by:

clear in interface Collection

Specified by:

clear in interface Set

Overrides:

clear in class AbstractCollection

clone

public Object clone()

Create a clone of this Set.

Returns:

a clone of this Set

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Initialize this object from the data in the passed ObjectInput stream.

Specified by:

readExternal in interface Externalizable

Parameters:

in - the stream to read data from in order to restore the object

Throws:

IOException - if an I/O exception occurs

ClassNotFoundException

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Write this object's data to the passed ObjectOutput stream.

Specified by:

writeExternal in interface Externalizable

Parameters:

out - the stream to write the object to

Throws:

IOException - if an I/O exception occurs

readExternal

public void readExternal(DataInput in)
                  throws IOException

Restore the contents of this object by loading the object's state from the passed DataInput object.

Specified by:

readExternal in interface ExternalizableLite

Parameters:

in - the DataInput stream to read data from in order to restore the state of this object

Throws:

IOException - if an I/O exception occurs

NotActiveException - if the object is not in its initial state, and therefore cannot be deserialized into

writeExternal

public void writeExternal(DataOutput out)
                   throws IOException

Save the contents of this object by storing the object's state into the passed DataOutput object.

Specified by:

writeExternal in interface ExternalizableLite

Parameters:

out - the DataOutput stream to write the state of this object to

Throws:

IOException - if an I/O exception occurs

instantiateSet

protected Set instantiateSet()

(Factory pattern) Instantiate a Set object to store items in once the "lite" threshold has been exceeded. This method permits inheriting classes to easily override the choice of the Set object.

Returns:

an instance of Set

initFromArray

protected void initFromArray(Object[] ao,
                             int c)

Initialize the contents of this Set from the passed array ao containing c values.

Parameters:

ao - the array that contains the values to place in this Set

c - the number of values that will be placed into this Set

checkShrinkFromOther

protected void checkShrinkFromOther()

After a mutation operation has reduced the size of an underlying Set, check if the delegation model should be replaced with a more size- efficient storage approach, and switch accordingly.