All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class java.lang.ref.Reference

java.lang.Object
    |
    +----java.lang.ref.Reference

public class Reference
extends Object

The Reference class contains the core abstractions for reference objects. Reference objects reify references in much the same way that Class objects reify Java classes. That is, a reference object encapsulates a reference to some other object so that the reference itself may be examined and manipulated like any other object.

The methods defined in this class allow a program to be notified some time after the collector detects a change in the reachability of a given object. They also allow a program to maintain a reference to an object that does not prevent the object from being considered for reclamation by the garbage collector.

Three types of reference objects are supported, each weaker than the last: guarded, weak, and phantom. Each type corresponds to a different level of reachability, as defined below. Guarded references are for implementing sophisticated caches, weak references are for implementing simple caches as well as mappings that do not prevent their keys (or values) from being reclaimed, and phantom references are for scheduling post-mortem cleanup actions in a more flexible way than is possible with the Java finalization mechanism.

Each reference-object type is implemented by subclass of the Reference class. An instance of one of these subclasses encapsulates a single reference to a particular object, called the referent. Each subclass provides methods for getting, setting, and clearing the reference. A program may further subclass these subclasses, adding whatever fields and methods are required for its purposes, or it may use these subclasses without change.

Notification

A program may request to be notified of changes in an object's reachability by registering an appropriate reference object with a reference queue. Some time after the garbage collector determines that the reachability of the referent has changed to the value corresponding to the type of the reference, it will add the reference to the associated queue. At this point, the reference is considered to be enqueued. The program may remove references from a queue either by polling or by blocking until a reference becomes available. When an enqueued reference is removed from its queue, it reverts to being unregistered. Reference queues are implemented by the ReferenceQueue class.

A reference object may be registered with only one queue at a time, and the relationship between a registered reference object and its queue is one-sided. That is, a queue does not keep track of the references that are registered with it. If a registered reference becomes unreachable itself, then it will never be enqueued. It is the responsibility of the program using reference objects to ensure that the objects remain reachable for as long as the program is interested in their referents.

An enqueued reference object may not be re-registered, unregistered, or modified to refer to some other object, although it may be cleared. Any attempt to perform one of the first three operations on an enqueued reference will cause an EnqueuedReferenceException to be thrown. This restriction ensures that when a program removes a reference from a queue it will see the referent for which the garbage collector detected a change in reachability, rather than some other object.

While some programs will choose to dedicate a thread to removing reference objects from a queue and processing them, this is by no means necessary. A tactic that often works well is to examine a reference queue in the course of performing some other fairly-frequent action. For example, a hashtable that uses weak references to implement weak keys could poll its reference queue each time the table is accessed. Because the one-argument remove method simply checks an internal data structure, and does so without acquiring any locks, this check will add little overhead to the hashtable access methods.

Weak references

A weak reference is automatically cleared by the collector at the same time it is added to the queue with which it is registered, if any. If there is more than one weak reference to an object, all such references will be cleared (and enqueued, if need be) simultaneously and atomically from the standpoint of the program. Thus weak references need not be registered with a queue in order to be useful, while guarded and phantom references do. Similarly, an object that is reachable via guarded (or phantom) references will remain so until all such references are cleared, are modified to refer to some other object, or themselves become unreachable.

Reachability

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

An object is strongly reachable if it can be reached by some thread without traversing any reference objects. A newly-created object is strongly reachable by the thread that created it.
An object is guardedly reachable if it is not strongly reachable but can be reached by traversing a guarded reference.
An object is weakly reachable if it is not guardedly reachable but can be reached by traversing a weak reference. When the weak references to a weakly-reachable object are cleared, the object becomes eligible for finalization.
Finally, an object is phantom reachable if it is not weakly reachable, it has been finalized, and some phantom reference refers to it. An object becomes unreachable, and eligible for reclamation, when the last phantom reference to it is cleared or becomes unreachable itself.

The CachedReference class defines a fifth type of reference object that is cleared only when the runtime system detects that memory is running low. Unlike the other reference-object types, the CachedReference class does not support notification via reference queues.

Since:: JDK1.2
See Also:: Runtime.MemoryAdvice, ReferenceQueue, GuardedReference, WeakReference, PhantomReference, CachedReference

clear(): Clear this reference object.
get(): Return the object to which this reference object refers.
isEnqueued(): Tell whether or not this reference object has been enqueued.
register(ReferenceQueue): Register this reference object with the given queue.
set(Object): Modify this reference object to refer to the given object.
unregister(): Cancel the registration of this reference object.

get

public Object get()

Return the object to which this reference object refers. If this reference has been cleared, either by the program or by the garbage collector, then return null.

set

public void set(Object referent) throws EnqueuedReferenceException

Modify this reference object to refer to the given object.

Throws: EnqueuedReferenceException: If this reference has been enqueued, in which case it must be removed from its queue before it can be modified

clear

public void clear()

Clear this reference object. Note that a reference may be cleared even if it has been enqueued.

isEnqueued

public boolean isEnqueued() throws UnsupportedOperationException

Tell whether or not this reference object has been enqueued. An enqueued reference object cannot be modified, registered, or unregistered.

Throws: UnsupportedOperationException: If this reference object does not support notification

register

public void register(ReferenceQueue queue) throws EnqueuedReferenceException

Register this reference object with the given queue. If this reference object is already registered with some queue, it will be unregistered and then re-registered with the given queue.

Throws: NullPointerException: If the queue argument is null
Throws: EnqueuedReferenceException: If this reference object has been enqueued, in which case it must be removed from its queue before it can be re-registered
Throws: UnsupportedOperationException: If this reference object does not support notification

unregister

public void unregister() throws EnqueuedReferenceException

Cancel the registration of this reference object. If this reference object is not registered, this method has no effect.

Throws: EnqueuedReferenceException: If this reference object has been enqueued; when it is removed from its queue, it will no longer be registered
Throws: UnsupportedOperationException: If this reference object does not support notification

All Packages  Class Hierarchy  This Package  Previous  Next  Index

Submit a bug or feature