/* * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ /** * Provides reference-object classes, which support a limited degree * of interaction with the garbage collector. A program may use a * reference object to maintain a reference to some other object in * such a way that the latter object may still be reclaimed by the * collector. A program may also arrange to be notified some time * after the collector has determined that the reachability of a given * object has changed. * *

Package Specification

* * A reference object encapsulates a reference to some other * object so that the reference itself may be examined and manipulated * like any other object. Three types of reference objects are * provided, each weaker than the last: soft, weak, * and phantom. Each type corresponds to a different level * of reachability, as defined below. Soft references are for * implementing memory-sensitive caches, weak references are for * implementing canonicalizing 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. * *

Each reference-object type is implemented by a subclass of the * abstract base {@link java.lang.ref.Reference} class. * An instance of one of these subclasses 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 {@code 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 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 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 {@link java.lang.ref.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 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. This is how the * {@link java.util.WeakHashMap} class works. Because * the {@link java.lang.ref.ReferenceQueue#poll * ReferenceQueue.poll} method simply checks an internal data * structure, this check will add little overhead to the hashtable * access methods. * *

Automatically-cleared references

* * Soft and weak references are automatically cleared by the collector * before being added to the queues with which they are registered, if * any. Therefore soft and weak references need not be registered * with a queue in order to be useful, while phantom references do. * An object that is reachable via 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: * * * * @author Mark Reinhold * @since 1.2 */ package java.lang.ref;