ReapableCollection (Plexus v0.13.1 API Specification)

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

Constructors 

Constructor and Description


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



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










Method Summary

Methods 

Modifier and Type
Method and Description


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

Modifier and Type	Method and Description
`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()`

Class ReapableCollection

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Collection

Constructor Detail

ReapableCollection

ReapableCollection

Method Detail

size

isEmpty

add

remove

contains

iterator

clear

addAll

removeAll

retainAll

containsAll

toArray

toArray

toString

reap