THE Java™ Programming Language, Fourth Edition

Creates a new reference object with the given referent and registered with the

given queue.

Both weak and soft references are enqueued at some point after the garbage collector determines that their
referent has entered that particular reachability state, and in both cases they are cleared before being
enqueued. Phantom references are also enqueued at some point after the garbage collector determines the
referent is phantom reachable, but they are not cleared. Once a reference object has been queued by the
garbage collector, it is guaranteed that get will return null, and so the object cannot be resurrected.

Registering a reference object with a reference queue does not create a reference between the queue and the
reference object. If your reference object itself becomes unreachable, then it will never be enqueued. So your
application needs to keep a strong reference to all reference objects.

The ReferenceQueue class provides three methods for removing references from the queue:

public Reference<? extends T>poll()

Removes and returns the next reference object from this queue, or null if

the queue is empty.

public Reference<? extends T>remove()tHRows

InterruptedException

Removes and returns the next reference object from this queue. This method

blocks indefinitely until a reference object is available from the queue.

public Reference<? extends T>remove(long timeout)throws

InterruptedException

Removes and returns the next reference object from this queue. This method

blocks until a reference object is available from the queue or the specified

time-out period elapses. If the time-out expires, null is returned. A time-out

of zero means wait indefinitely.

The poll method allows a thread to query the existence of a reference in a queue, taking action only if one is
present, as in the example. The remove methods are intended for more complex (and rare) situations in
which a dedicated thread is responsible for removing references from the queue and taking the appropriate
actionthe blocking behavior of these methods is the same as that defined by Object.wait (as discussed
from page 354). You can ask whether a particular reference is in a queue via its isEnqueued method. You
can force a reference into its queue by calling its enqueue method, but usually this is done by the garbage
collector.

Reference queues are used with phantom references to determine when an object is about to be reclaimed. A
phantom reference never lets you reach the object, even when it is otherwise reachable: Its get method
always returns null. In effect it is the safest way to find out about a collected objecta weak or soft reference
will be enqueued after an object is finalizable; a phantom reference is enqueued after the referent has been
finalized and, therefore only after the last possible time that the object can do something. If you can, you
should generally use a phantom reference because the other references still allow the possibility that a
finalize method will use the object.

Consider a resource manager that controls access to some set of external resources. Objects can request access
to a resource and use it until they are done, after which they should return the resource back to the resource
manager. If the resource is shared, and use of it is passed from object to object, perhaps even across multiple
threads, then it can be difficult to determine which use of the resource is the last use. That makes it difficult to