Chapter 13. The java.lang.ref Package

The java.lang.ref package defines classes that allow Java programs to interact with the Java garbage collector. A Reference represents an indirect reference to an arbitrary object, known as the referent. SoftReference, WeakReference, and PhantomReference are three concrete subclasses of Reference that interact with the garbage collector in different ways, as explained in the individual class descriptions that follow. ReferenceQueue represents a linked list of Reference objects. Any Reference object may have a ReferenceQueue associated with it. A Reference object is enqueued on its ReferenceQueue at some point after the garbage collector determines that the referent object has become appropriately unreachable. (The exact level of unreachability depends on the type of Reference being used.) An application can monitor a ReferenceQueue to determine when referent objects enter a new reachability status. Figure 13-1 shows the hierarchy of this package, which is new as of Java 1.2.

Figure 13-1. The java.lang.ref package

Using the mechanisms defined in this package, you can implement a cache that grows and shrinks in size according to the amount of available system memory. Or, you can implement a hashtable that associates auxiliary information with arbitrary objects, but does not prevent those objects from being garbage-collected if they are otherwise unused. The mechanisms provided by this package are low-level ones, however, and typical applications do not use java.lang.ref directly. Instead, they rely on higher-level utilities built on top of the package. See java.util.WeakHashMap for one example.

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.

public class PhantomReference extends java.lang.ref.Reference {
//	Public Constructors
	public PhantomReference (Object referent, ReferenceQueue q);
//	Public Methods Overriding Reference
	public Object get ();	constant
}

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.

public abstract class Reference {
//	No Constructor
//	Public Instance Methods
	public void clear ();
	public boolean enqueue ();
	public Object get ();
	public boolean isEnqueued ();
}

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.

public class ReferenceQueue {
//	Public Constructors
	public ReferenceQueue ();
//	Public Instance Methods
	public java.lang.ref.Reference poll ();
	public java.lang.ref.Reference remove () throws InterruptedException;
	public java.lang.ref.Reference remove (long timeout) throws IllegalArgumentExceptionInterruptedException;
}

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.

public class SoftReference extends java.lang.ref.Reference {
//	Public Constructors
	public SoftReference (Object referent);
	public SoftReference (Object referent, ReferenceQueue q);
//	Public Methods Overriding Reference
	public Object get ();
}

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.

public class WeakReference extends java.lang.ref.Reference {
//	Public Constructors
	public WeakReference (Object referent);
	public WeakReference (Object referent, ReferenceQueue q);
}

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