com.phoenixst.collections
Interface Reaper

All Known Implementing Classes:

RunnableReaper

public interface Reaper

The interface defining an object which reaps Reapables. This interface, along with the ReapableCollection class, is intended to be used to solve the problem presented by the following requirements:

• A resource produces objects (let's call them Foos) that are given to clients.
• The resource needs to track all Foos that it has produced that are still in use.
• Either it is not possible, or it is undesirable, for there to be an explicit way for a client to dispose of a Foo.
• However, when a client is no longer using a Foo (when its reference falls out of scope, for example), it should be reclaimed.

A typical example would be a more robust Iterator which can actually deal with changes to the underlying data structure while iteration is in progress.

However, this is not the only use-case. A Reaper can also be used when there is no need to keep track of the currently reachable referents. A Reapable instance could be created specific to each referent, to perform specific cleanup actions. This would work as long as the referent is not reachable from the Reapable.

Since:

1.0

Version:

$Revision: 1.12 $

Author:

Ray A. Conner

Method Summary

Reference

createReference(Reapable reapable, Object referent) Creates and returns a Reference for the given arguments.

Method Detail

createReference

Reference createReference(Reapable reapable,
                          Object referent)

Creates and returns a Reference for the given arguments. Sometime after the Reference is reclaimed by the garbage collector, the argument's Reapable.reap() method will be called. Please note that there is typically no guarantee that this method will ever be called, so this mechanism should not be relied upon as a replacement for a try/finally block.

Implementations should never return PhantomReferences if the referent needs to be retrievable while it is still referencable through other paths, or if the Reference.clear() is not guaranteed to be called.