Package com.tangosol.util

Class LiteSet<E>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractSet<E>

com.tangosol.util.LiteSet<E>

All Implemented Interfaces:

ExternalizableLite, Externalizable, Serializable, Cloneable, Iterable<E>, Collection<E>, Set<E>

public class LiteSet<E>
extends AbstractSet<E>
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

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor	Description
LiteSet()	Construct a LiteSet
LiteSet(Collection<? extends E> collection)	Construct a LiteSet containing the elements of the passed Collection.

Method Summary

Modifier and Type	Method	Description
boolean	add(E o)	Ensures that this Set contains the specified element.
boolean	addAll(Collection<? extends E> 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<E>	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<E>	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<E>	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

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.Set

spliterator

Constructor Detail

LiteSet

public LiteSet()

Construct a LiteSet

LiteSet

public LiteSet(Collection<? extends E> 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<E>

Specified by:

isEmpty in interface Set<E>

Overrides:

isEmpty in class AbstractCollection<E>

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<E>

Specified by:

size in interface Set<E>

Specified by:

size in class AbstractCollection<E>

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<E>

Specified by:

contains in interface Set<E>

Overrides:

contains in class AbstractCollection<E>

Parameters:

o - the object to check for

Returns:

true if this Set contains the specified element

iterator

public Iterator<E> iterator()

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

Specified by:

iterator in interface Collection<E>

Specified by:

iterator in interface Iterable<E>

Specified by:

iterator in interface Set<E>

Specified by:

iterator in class AbstractCollection<E>

Returns:

an iterator over the elements in this Set

elements

public Enumeration<E> 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<E>

Specified by:

toArray in interface Set<E>

Overrides:

toArray in class AbstractCollection<E>

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<E>

Specified by:

toArray in interface Set<E>

Overrides:

toArray in class AbstractCollection<E>

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(E 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<E>

Specified by:

add in interface Set<E>

Overrides:

add in class AbstractCollection<E>

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<E>

Specified by:

remove in interface Set<E>

Overrides:

remove in class AbstractCollection<E>

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<E>

Specified by:

containsAll in interface Set<E>

Overrides:

containsAll in class AbstractCollection<E>

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<? extends E> 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<E>

Specified by:

addAll in interface Set<E>

Overrides:

addAll in class AbstractCollection<E>

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<E>

Specified by:

retainAll in interface Set<E>

Overrides:

retainAll in class AbstractCollection<E>

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<E>

Specified by:

removeAll in interface Set<E>

Overrides:

removeAll in class AbstractSet<E>

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<E>

Specified by:

clear in interface Set<E>

Overrides:

clear in class AbstractCollection<E>

clone

public Object clone()

Create a clone of this Set.

Overrides:

clone in class Object

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<E> 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.