Editing Java Platform, Standard Edition (section)

==== java.lang.ref ====
The {{Javadoc:SE|package=java.lang.ref|java/lang/ref}} package provides more flexible types of [[Reference (computer science)|references]] than are otherwise available, permitting limited interaction between the application and the [[Java virtual machine|Java Virtual Machine]] (JVM) [[garbage collection (computer science)|garbage collector]].  It is an important package, central enough to the language for the language designers to give it a name that starts with "java.lang", but it is somewhat special-purpose and not used by a lot of developers.  This package was added in J2SE 1.2.

Java has an expressive system of references and allows for special behavior for garbage collection. A normal reference in Java is known as a "strong reference". The <code>java.lang.ref</code> package defines three other types of references—soft, [[weak reference|weak]], and phantom references. Each type of reference is designed for a specific use.

* A {{Javadoc:SE|java/lang/ref|SoftReference}} can be used to implement a [[cache (computing)|cache]].  An object that is not reachable by a strong reference (that is, not strongly reachable), but is referenced by a soft reference is called "softly reachable". A softly reachable object may be garbage collected at the discretion of the garbage collector. This generally means that softly reachable objects are only garbage collected when free memory is low—but again, this is at the garbage collector's discretion. Semantically, a soft reference means, "Keep this object when nothing else references it, unless the memory is needed."
* A {{Javadoc:SE|java/lang/ref|WeakReference}} is used to implement weak maps.  An object that is not strongly or softly reachable, but is referenced by a weak reference is called "[[weakly reachable]]".  A weakly reachable object is garbage collected in the next collection cycle. This behavior is used in the class {{Javadoc:SE|package=java.util|java/util|WeakHashMap}}.  A weak map allows the programmer to put key/value pairs in the map and not worry about the objects taking up memory when the key is no longer reachable anywhere else.  Another possible application of weak references is the [[string intern pool]].  Semantically, a weak reference means "get rid of this object when nothing else references it at the next garbage collection."
* A {{Javadoc:SE|java/lang/ref|PhantomReference}} is used to reference objects that have been marked for garbage collection and have been [[finalizer|finalized]], but have not yet been reclaimed. An object that is not strongly, softly or weakly reachable, but is referenced by a phantom reference is called "phantom reachable." This allows for more flexible cleanup than is possible with the finalization mechanism alone.  Semantically, a phantom reference means "this object is no longer needed and has been finalized in preparation for being collected."

Each of these reference types extends the {{Javadoc:SE|java/lang/ref|Reference}} class, which provides the {{Javadoc:SE|name=get()|java/lang/ref|Reference|get()}} [[method (computer science)|method]] to return a strong reference to the referent object (or <code>null</code> if the reference has been cleared or if the reference type is phantom), and the {{Javadoc:SE|name=clear()|java/lang/ref|Reference|clear()}} method to clear the reference.

The <code>java.lang.ref</code> also defines the class {{Javadoc:SE|java/lang/ref|ReferenceQueue}}, which can be used in each of the applications discussed above to keep track of objects that have changed reference type.  When a <code>Reference</code> is created it is optionally registered with a reference queue.  The application polls the reference queue to get references that have changed reachability state.