Chapter 13. The java.lang.ref Package

PhantomReference	Java 1.2
java.lang.ref

This class represents a reference to an object that does not prevent the referent object from being finalized by the garbage collector. When (or at some point after) the garbage collector determines that there are no more hard (direct) references to the referent object, that there are no SoftReference or WeakReference objects that refer to the referent, and that the referent has been finalized, it enqueues the PhantomReference object on the ReferenceQueue specified when the PhantomReference was created. This serves as notification that the object has been finalized and provides one last opportunity for any required cleanup code to be run.

To prevent a PhantomReference object from resurrecting its referent object, its get() method always returns null, both before and after the PhantomReference is enqueued. Nevertheless, a PhantomReference is not automatically cleared when it is enqueued, so when you remove a PhantomReference from a ReferenceQueue, you must call its clear() method or allow the PhantomReference object itself to be garbage-collected.

This class provides a more flexible mechanism for object cleanup than the finalize() method does. Note that in order to take advantage of it, it is necessary to subclass PhantomReference and define a method to perform the desired cleanup. Furthermore, since the get() method of a PhantomReference always returns null, such a subclass must also store whatever data is required for the cleanup operation.

Hierarchy: Object-->java.lang.ref.Reference-->PhantomReference

Reference	Java 1.2
java.lang.ref

This abstract class represents some type of indirect reference to a referent. get() returns the referent if the reference has not been explicitly cleared by the clear() method or implicitly cleared by the garbage collector. There are three concrete subclasses of Reference. The garbage collector handles these subclasses differently and clears their references under different circumstances.

Each of the subclasses of Reference defines a constructor that allows a ReferenceQueue to be associated with the Reference object. The garbage collector places Reference objects onto their associated ReferenceQueue objects to provide notification about the state of the referent object. isEnqueued() tests whether a Reference has been placed on the associated queue, and enqueue() explicitly places it on the queue. enqueue() returns false if the Reference object does not have an associated ReferenceQueue, or if it has already been enqueued.

Subclasses: PhantomReference, SoftReference, WeakReference

Returned By: ReferenceQueue.{poll(), remove()}

ReferenceQueue	Java 1.2
java.lang.ref

This class represents a queue (or linked list) of Reference objects that have been enqueued because the garbage collector has determined that the referent objects to which they refer are no longer adequately reachable. It serves as a notification system for object-reachability changes. Use poll() to return the first Reference object on the queue; the method returns null if the queue is empty. Use remove() to return the first element on the queue, or, if the queue is empty, to wait for a Reference object to be enqueued. You can create as many ReferenceQueue objects as needed. Specify a ReferenceQueue for a Reference object by passing it to the SoftReference(), WeakReference(), or PhantomReference() constructor.

A ReferenceQueue is required to use PhantomReference objects. It is optional with SoftReference and WeakReference objects; for these classes, the get() method returns null if the referent object is no longer adequately reachable.

Passed To: PhantomReference.PhantomReference(), SoftReference.SoftReference(), WeakReference.WeakReference()

SoftReference	Java 1.2
java.lang.ref

This class represents a soft reference to an object. A SoftReference is not cleared while there are any remaining hard (direct) references to the referent. Once the referent is no longer in use (i.e., there are no remaining hard references to it), the garbage collector may clear the SoftReference to the referent at any time. However, the garbage collector does not clear a SoftReference until it determines that system memory is running low. In particular, the Java VM never throws an OutOfMemoryError without first clearing all soft references and reclaiming the memory of the referents. The VM may (but is not required to) clear soft references according to a least-recently-used ordering.

If a SoftReference has an associated ReferenceQueue, the garbage collector enqueues the SoftReference at some time after it clears the reference.

SoftReference is particularly useful for implementing object-caching systems that do not have a fixed size, but grow and shrink as available memory allows.

Hierarchy: Object-->java.lang.ref.Reference-->SoftReference

WeakReference	Java 1.2
java.lang.ref

This class refers to an object in a way that does not prevent that referent object from being finalized and reclaimed by the garbage collector. When the garbage collector determines that there are no more hard (direct) references to the object, and that there are no SoftReference objects that refer to the object, it clears the WeakReference and marks the referent object for finalization. At some point after this, it also enqueues the WeakReference on its associated ReferenceQueue, if there is one, in order to provide notification that the referent has been reclaimed.

WeakReference is used by java.util.WeakHashMap to implement a hashtable that does not prevent the hashtable key object from being garbage-collected. WeakHashMap is useful when you want to associate auxiliary information with an object but do not want to prevent the object from being reclaimed.

Hierarchy: Object-->java.lang.ref.Reference-->WeakReference