to top
Android APIs
Since: API Level 1
package

java.lang.ref

Provides the system's ReferenceQueue implementation as well as different forms of reference objects which impose special behavior on the garbage collector. The behavior depends on the type of Reference being used. Three different type of references exist, each being weaker than the preceding one: SoftReference, WeakReference, and PhantomReference. "Weakness" here means that less restrictions are being imposed on the garbage collector as to when it is allowed to actually garbage-collect the referenced object.

In order to use reference objects properly it is important to understand the different types of reachability that trigger their clearing and enqueueing. The following table lists these, from strongest to weakest. For each row, an object is said to have the reachability on the left side if (and only if) it fulfills all of the requirements on the right side. In all rows, consider the root set to be a set of references that are "resistant" to garbage collection (that is, running threads, method parameters, local variables, static fields and the like).

Strongly reachable
  • There exists at least one path from the root set to the object that does not traverse any instance of a Reference subclass.
Softly reachable
Weakly reachable
  • The object is neither strongly nor softly reachable.
  • There exists at least one path from the root set to the object that does traverse a WeakReference instance, but no PhantomReference instances.
Phantom-reachable
  • The object is neither strongly, softly nor weakly reachable.
  • The object is referenced by a PhantomReference instance.
  • The object has already been finalized.

Classes

PhantomReference<T> Implements a phantom reference, which is the weakest of the three types of references. 
Reference<T> Provides an abstract class which describes behavior common to all reference objects. 
ReferenceQueue<T> The ReferenceQueue is the container on which reference objects are enqueued when the garbage collector detects the reachability type specified for the referent. 
SoftReference<T> A reference that is cleared when its referent is not strongly reachable and there is memory pressure. 
WeakReference<T> Implements a weak reference, which is the middle of the three types of references.