Abstract base class for reference objects.
Reference queues, to which registered reference objects are appended by the garbage collector after the appropriate reachability changes are detected.
Weak reference objects, which do not prevent their referents from being made finalizable, finalized, and then reclaimed.
An instance of a weak reference encapsulates a single reference to a
particular object, called the referent.
Every reference object provides methods for getting and
clearing the reference. Aside from the clearing operation reference objects
are otherwise immutable, so no
set operation is provided. A
program may further subclass these subclasses, adding whatever fields and
methods are required for its purposes, or it may use these subclasses without
A program may request to be notified of changes in an object's reachability by
registering an appropriate reference object with a reference
queue at the time the reference object is created. 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. Reference
queues are implemented by the
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.
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 hashtable that uses weak references to implement weak keys could poll its reference queue each time the table is accessed.
Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.