Provides reference-object classes, which support a limited degree ofinteraction with the garbage collector. A program may use a reference objectto maintain a reference to some other object in such a way that the latterobject may still be reclaimed by the collector. A program may also arrange tobe notified some time after the collector has determined that the reachabilityof a given object has changed.

Package Specification

Areference object encapsulates a reference to some other object sothat the reference itself may be examined and manipulated like any otherobject. Three types of reference objects are provided, each weaker than thelast:soft,weak, andphantom. Each typecorresponds to a different level of reachability, as defined below. Softreferences are for implementing memory-sensitive caches, weak references arefor implementing canonicalizing mappings that do not prevent their keys (orvalues) from being reclaimed, and phantom references are for schedulingpre-mortem cleanup actions in a more flexible way than is possible with theJava finalization mechanism.

Each reference-object type is implemented by a subclass of the abstractbaseReference class. An instance of one ofthese subclasses encapsulates a single reference to a particular object, calledthereferent. Every reference object provides methods for getting andclearing the reference. Aside from the clearing operation reference objectsare otherwise immutable, so noset operation is provided. Aprogram may further subclass these subclasses, adding whatever fields andmethods are required for its purposes, or it may use these subclasses withoutchange.

Notification

A program may request to be notified of changes in an object's reachability byregistering an appropriate reference object with areferencequeue at the time the reference object is created. Some time after thegarbage collector determines that the reachability of the referent has changedto the value corresponding to the type of the reference, it will add thereference to the associated queue. At this point, the reference is consideredto beenqueued. The program may remove references from a queue eitherby polling or by blocking until a reference becomes available. Referencequeues are implemented by theReferenceQueueclass.

The relationship between a registered reference object and its queue isone-sided. That is, a queue does not keep track of the references that areregistered with it. If a registered reference becomes unreachable itself, thenit will never be enqueued. It is the responsibility of the program usingreference objects to ensure that the objects remain reachable for as long asthe program is interested in their referents.

While some programs will choose to dedicate a thread to removing referenceobjects from one or more queues and processing them, this is by no meansnecessary. A tactic that often works well is to examine a reference queue inthe course of performing some other fairly-frequent action. For example, ahashtable that uses weak references to implement weak keys could poll itsreference queue each time the table is accessed. This is how theWeakHashMap class works. Because theReferenceQueue.poll method simplychecks an internal data structure, this check will add little overhead to thehashtable access methods.

Automatically-cleared references

Soft and weak references are automatically cleared by the collector beforebeing added to the queues with which they are registered, if any. Thereforesoft and weak references need not be registered with a queue in order to beuseful, while phantom references do. An object that is reachable via phantomreferences will remain so until all such references are cleared or themselvesbecome unreachable.

Reachability

Going from strongest to weakest, the different levels of reachability reflectthe life cycle of an object. They are operationally defined as follows:

• An object isstrongly reachable if it can be reached by somethread without traversing any reference objects. A newly-created object isstrongly reachable by the thread that created it.
• An object issoftly reachable if it is not strongly reachable butcan be reached by traversing a soft reference.
• An object isweakly reachable if it is neither strongly norsoftly reachable but can be reached by traversing a weak reference. When theweak references to a weakly-reachable object are cleared, the object becomeseligible for finalization.
• An object isphantom reachable if it is neither strongly, softly,nor weakly reachable, it has been finalized, and some phantom reference refersto it.
• Finally, an object isunreachable, and therefore eligible forreclamation, when it is not reachable in any of the above ways.