com.phoenixst.collections
Class ReapableCollection

java.lang.Object
  com.phoenixst.collections.ReapableCollection

All Implemented Interfaces:

Reapable, Iterable, Collection

public class ReapableCollection
extends Object
implements Collection, Reapable

A reapable Collection. At any time, elements of an instance of this class may be removed if there are no longer any references to them outside of the instance. In particular, many methods like size() and isEmpty() may not give accurate answers, and that information is immediately out of date. Instances of this class are synchronized where necessary, but the user is required to synchronize externally during any iteration.

This Collection does not permit null elements, nor will it allow itself to be added.

Most of the methods in this class use reference equality rather than .equals(), given that the intent of this class is to track actual Object instances. However, the methods removeAll(Collection) and retainAll(Collection) use the contains() method of the argument Collection.

Since:

1.0

Version:

$Revision: 1.14 $

Author:

Ray A. Conner

Constructor Summary

ReapableCollection()
Creates a new ReapableCollection using the default Reaper.

ReapableCollection(Reaper reaper)
Creates a new ReapableCollection with the specified Reaper.

Method Summary

boolean	add(Object object) Adds the specified element to this collection, wrapping the element with a Reference created by the Reaper used to construct this collection.
boolean	addAll(Collection collection) Adds all of the elements in the specified collection to this collection, wrapping each element with a Reference created by the Reaper used to construct this collection.
void	clear()
boolean	contains(Object object) Returns true if this collection contains a Reference for the specified object.
boolean	containsAll(Collection collection) Returns true if this collection contains References for all of the elements in the specified collection.
boolean	isEmpty() Returns true if this collection contains no elements; a false return value doesn't signify anything meaningful.
Iterator	iterator() Returns an Iterator over the elements in this collection, which are the referents of uncleared References.
void	reap() Informs this Reapable that it has at least one reference which has been reclaimed.
boolean	remove(Object object) If this collection contains a Reference for the specified object, the first such Reference found is cleared and true is returned.
boolean	removeAll(Collection collection) Removes all this collection's elements that are also contained in the specified collection.
boolean	retainAll(Collection collection) Retains only this collection's elements that are also contained in the specified collection.
int	size() Returns at most the number of uncleared References currently in this collection.
Object[]	toArray() Returns an array containing all of the elements in this collection.
Object[]	toArray(Object[] array) Returns an array containing all of the elements in this collection.
String	toString()

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Collection

equals, hashCode

Constructor Detail

ReapableCollection

public ReapableCollection()

Creates a new ReapableCollection using the default Reaper.

ReapableCollection

public ReapableCollection(Reaper reaper)

Creates a new ReapableCollection with the specified Reaper. The Reaper must not create PhantomReferences.

Method Detail

size

public int size()

Returns at most the number of uncleared References currently in this collection.

Specified by:

size in interface Collection

isEmpty

public boolean isEmpty()

Returns true if this collection contains no elements; a false return value doesn't signify anything meaningful.

Specified by:

isEmpty in interface Collection

add

public boolean add(Object object)

Adds the specified element to this collection, wrapping the element with a Reference created by the Reaper used to construct this collection. This Collection does not permit null elements, nor will it allow itself to be added.

Specified by:

add in interface Collection

remove

public boolean remove(Object object)

If this collection contains a Reference for the specified object, the first such Reference found is cleared and true is returned.

Specified by:

remove in interface Collection

contains

public boolean contains(Object object)

Returns true if this collection contains a Reference for the specified object.

Specified by:

contains in interface Collection

iterator

public Iterator iterator()

Returns an Iterator over the elements in this collection, which are the referents of uncleared References. The user must externally synchronize the Iterator returned by this method!

Specified by:

iterator in interface Iterable

Specified by:

iterator in interface Collection

clear

public void clear()

Specified by:

clear in interface Collection

addAll

public boolean addAll(Collection collection)

Adds all of the elements in the specified collection to this collection, wrapping each element with a Reference created by the Reaper used to construct this collection. This Collection does not permit null elements, nor will it allow itself to be added. If the argument collection is this collection, nothing happens and false is returned.

Specified by:

addAll in interface Collection

removeAll

public boolean removeAll(Collection collection)

Removes all this collection's elements that are also contained in the specified collection. Unlike most other methods in this class, this method uses the definition of element equality defined by the argument collection. This implementation is O(n*m), where n is the size of this collection and m is the cost of executing the contains() method of the argument collection.

Specified by:

removeAll in interface Collection

retainAll

public boolean retainAll(Collection collection)

Retains only this collection's elements that are also contained in the specified collection. Unlike most other methods in this class, this method uses the definition of element equality defined by the argument collection. This implementation is O(n*m), where n is the size of this collection and m is the cost of executing the contains() method of the argument collection.

Specified by:

retainAll in interface Collection

containsAll

public boolean containsAll(Collection collection)

Returns true if this collection contains References for all of the elements in the specified collection. This implementation is O(n*m), where n is the size of this collection and m is the cost of iterating over the argument collection.

Specified by:

containsAll in interface Collection

toArray

public Object[] toArray()

Returns an array containing all of the elements in this collection. Note that this creates strong references to all elements, and will therefore prevent them from being garbage collected.

Specified by:

toArray in interface Collection

toArray

public Object[] toArray(Object[] array)

Returns an array containing all of the elements in this collection. Note that this creates strong references to all elements, and will therefore prevent them from being garbage collected.

Specified by:

toArray in interface Collection

toString

public String toString()

Overrides:

toString in class Object

reap

public void reap()

Description copied from interface: Reapable

Informs this Reapable that it has at least one reference which has been reclaimed.

Specified by:

reap in interface Reapable