Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Class java.lang.ref.Reference

java.lang.Object
    |
    +----java.lang.ref.Reference
Subclasses:
GuardedReference, PhantomReference, SoftReference, WeakReference

public abstract class Reference
extends Object
Abstract base class 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 garbage 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 primitive 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 mappings that do not prevent their keys (or values) from being reclaimed, and phantom references are for scheduling pre-mortem cleanup actions in a more flexible way than is possible with the Java finalization mechanism.

Soft references are a fourth type of reference object. Soft references are cleared automatically as the amount of memory available to the Java heap decreases. Because they are implemented in terms of guarded and weak references, soft references are not considered to be primitive.

Each reference-object type is implemented by a 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 and clearing the reference. Reference objects are otherwise immutable, so there is no modification operation. 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 creating a reference object that refers to that object and is registered 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 that point in time the reference will be considered to have been enqueued. The program may remove references from a queue either by polling or by blocking until a reference becomes available. Reference queues are implemented by the ReferenceQueue class.

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 a program using reference objects to ensure that the objects remain reachable for as long as the program is interested in their referents.

While some programs will choose to dedicate a thread to removing reference objects from one or more queues 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 map that uses weak references to implement weak keys could poll its reference queue each time the map is accessed. Because the poll method simply checks an internal data structure, this check will add little overhead to the map's access methods.

Automatically-cleared references

Weak and soft references are automatically cleared under appropriate conditions. Thus weak and soft references need not be registered with a queue in order to be useful, while guarded and phantom references do. An object that is reachable via guarded (or phantom) references will remain so until all such references are cleared 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:

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

Constructor Summary
 Reference(Object referent)
Create a new reference that refers to the given object.
 Reference(Object referent, ReferenceQueue queue)
Create a new reference that refers to the given object and is registered with the given reference queue.
 

Method Summary
void  clear()
Clear this reference object.
boolean  enqueue()
Add this reference to the queue with which it was registered.
Object  get()
Return the object to which this reference object refers.
boolean  isEnqueued()
Tell whether or not this reference object has been enqueued.
 
Methods inherited from class java.lang.Object
 clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Reference

protected Reference(Object referent)
Create a new reference that refers to the given object. The new reference is not registered with a queue.

Reference

protected Reference(Object referent,
                    ReferenceQueue queue)
Create a new reference that refers to the given object and is registered with the given reference queue.
Throws:
NullPointerException - If the queue argument is null
Method Detail

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.

clear

public void clear()
Clear this reference object. Future invocations of the get method will return null.

isEnqueued

public boolean isEnqueued()
Tell whether or not this reference object has been enqueued. If this reference object was not registered with a queue when it was created, then this method will always return false.

enqueue

public boolean enqueue()
Add this reference to the queue with which it was registered. Return true if this was done successfully; return false if the reference had already been enqueued, or if it was not registered with a queue.

Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Submit a bug or feature
Submit comments/suggestions about new javadoc look.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.