/* * 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 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;