com.phoenixst.collections

Class ReapableCollection

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 and retainAll 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
booleanadd(Object object)
Adds the specified element to this collection, wrapping the element with a Reference created by the Reaper used to construct this collection.
booleanaddAll(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.
voidclear()
booleancontains(Object object)
Returns true if this collection contains a Reference for the specified object.
booleancontainsAll(Collection collection)
Returns true if this collection contains References for all of the elements in the specified collection.
booleanisEmpty()
Returns true if this collection contains no elements; a false return value doesn't signify anything meaningful.
Iteratoriterator()
Returns an Iterator over the elements in this collection, which are the referents of uncleared References.
voidreap()
booleanremove(Object object)
If this collection contains a Reference for the specified object, the first such Reference found is cleared and true is returned.
booleanremoveAll(Collection collection)
Removes all this collection's elements that are also contained in the specified collection.
booleanretainAll(Collection collection)
Retains only this collection's elements that are also contained in the specified collection.
intsize()
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.
StringtoString()

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

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.

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.

clear

public void clear()

contains

public boolean contains(Object object)
Returns true if this collection contains a Reference for the specified object.

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.

isEmpty

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

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!

reap

public void reap()

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.

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.

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.

size

public int size()
Returns at most the number of uncleared References currently in this 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.

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.

toString

public String toString()
See the Plexus project home, hosted by SourceForge.
Copyright B) 1994-2006, by Phoenix Software Technologists, Inc. and others. All Rights Reserved. Use is subject to license terms.