1.1 --- a/emul/compact/src/main/java/java/lang/ref/package.html Tue Feb 26 14:55:55 2013 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,147 +0,0 @@
1.4 -<!--
1.5 - Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved.
1.6 - DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 -
1.8 - This code is free software; you can redistribute it and/or modify it
1.9 - under the terms of the GNU General Public License version 2 only, as
1.10 - published by the Free Software Foundation. Oracle designates this
1.11 - particular file as subject to the "Classpath" exception as provided
1.12 - by Oracle in the LICENSE file that accompanied this code.
1.13 -
1.14 - This code is distributed in the hope that it will be useful, but WITHOUT
1.15 - ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 - FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 - version 2 for more details (a copy is included in the LICENSE file that
1.18 - accompanied this code).
1.19 -
1.20 - You should have received a copy of the GNU General Public License version
1.21 - 2 along with this work; if not, write to the Free Software Foundation,
1.22 - Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 -
1.24 - Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 - or visit www.oracle.com if you need additional information or have any
1.26 - questions.
1.27 --->
1.28 -
1.29 -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1.30 -<html>
1.31 -<body bgcolor="white">
1.32 -
1.33 -
1.34 -Provides reference-object classes, which support a limited degree of
1.35 -interaction with the garbage collector. A program may use a reference object
1.36 -to maintain a reference to some other object in such a way that the latter
1.37 -object may still be reclaimed by the collector. A program may also arrange to
1.38 -be notified some time after the collector has determined that the reachability
1.39 -of a given object has changed.
1.40 -
1.41 -
1.42 -<h2>Package Specification</h2>
1.43 -
1.44 -A <em>reference object</em> encapsulates a reference to some other object so
1.45 -that the reference itself may be examined and manipulated like any other
1.46 -object. Three types of reference objects are provided, each weaker than the
1.47 -last: <em>soft</em>, <em>weak</em>, and <em>phantom</em>. Each type
1.48 -corresponds to a different level of reachability, as defined below. Soft
1.49 -references are for implementing memory-sensitive caches, weak references are
1.50 -for implementing canonicalizing mappings that do not prevent their keys (or
1.51 -values) from being reclaimed, and phantom references are for scheduling
1.52 -pre-mortem cleanup actions in a more flexible way than is possible with the
1.53 -Java finalization mechanism.
1.54 -
1.55 -<p> Each reference-object type is implemented by a subclass of the abstract
1.56 -base <code>{@link java.lang.ref.Reference}</code> class. An instance of one of
1.57 -these subclasses encapsulates a single reference to a particular object, called
1.58 -the <em>referent</em>. Every reference object provides methods for getting and
1.59 -clearing the reference. Aside from the clearing operation reference objects
1.60 -are otherwise immutable, so no <code>set</code> operation is provided. A
1.61 -program may further subclass these subclasses, adding whatever fields and
1.62 -methods are required for its purposes, or it may use these subclasses without
1.63 -change.
1.64 -
1.65 -
1.66 -<h3>Notification</h3>
1.67 -
1.68 -A program may request to be notified of changes in an object's reachability by
1.69 -<em>registering</em> an appropriate reference object with a <em>reference
1.70 -queue</em> at the time the reference object is created. Some time after the
1.71 -garbage collector determines that the reachability of the referent has changed
1.72 -to the value corresponding to the type of the reference, it will add the
1.73 -reference to the associated queue. At this point, the reference is considered
1.74 -to be <em>enqueued</em>. The program may remove references from a queue either
1.75 -by polling or by blocking until a reference becomes available. Reference
1.76 -queues are implemented by the <code>{@link java.lang.ref.ReferenceQueue}</code>
1.77 -class.
1.78 -
1.79 -<p> The relationship between a registered reference object and its queue is
1.80 -one-sided. That is, a queue does not keep track of the references that are
1.81 -registered with it. If a registered reference becomes unreachable itself, then
1.82 -it will never be enqueued. It is the responsibility of the program using
1.83 -reference objects to ensure that the objects remain reachable for as long as
1.84 -the program is interested in their referents.
1.85 -
1.86 -<p> While some programs will choose to dedicate a thread to removing reference
1.87 -objects from one or more queues and processing them, this is by no means
1.88 -necessary. A tactic that often works well is to examine a reference queue in
1.89 -the course of performing some other fairly-frequent action. For example, a
1.90 -hashtable that uses weak references to implement weak keys could poll its
1.91 -reference queue each time the table is accessed. This is how the <code>{@link
1.92 -java.util.WeakHashMap}</code> class works. Because the <code>{@link
1.93 -java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll}</code> method simply
1.94 -checks an internal data structure, this check will add little overhead to the
1.95 -hashtable access methods.
1.96 -
1.97 -
1.98 -<h3>Automatically-cleared references</h3>
1.99 -
1.100 -Soft and weak references are automatically cleared by the collector before
1.101 -being added to the queues with which they are registered, if any. Therefore
1.102 -soft and weak references need not be registered with a queue in order to be
1.103 -useful, while phantom references do. An object that is reachable via phantom
1.104 -references will remain so until all such references are cleared or themselves
1.105 -become unreachable.
1.106 -
1.107 -
1.108 -<a name="reachability"></a>
1.109 -<h3>Reachability</h3>
1.110 -
1.111 -Going from strongest to weakest, the different levels of reachability reflect
1.112 -the life cycle of an object. They are operationally defined as follows:
1.113 -
1.114 -<ul>
1.115 -
1.116 -<li> An object is <em>strongly reachable</em> if it can be reached by some
1.117 -thread without traversing any reference objects. A newly-created object is
1.118 -strongly reachable by the thread that created it.
1.119 -
1.120 -<li> An object is <em>softly reachable</em> if it is not strongly reachable but
1.121 -can be reached by traversing a soft reference.
1.122 -
1.123 -<li> An object is <em>weakly reachable</em> if it is neither strongly nor
1.124 -softly reachable but can be reached by traversing a weak reference. When the
1.125 -weak references to a weakly-reachable object are cleared, the object becomes
1.126 -eligible for finalization.
1.127 -
1.128 -<li> An object is <em>phantom reachable</em> if it is neither strongly, softly,
1.129 -nor weakly reachable, it has been finalized, and some phantom reference refers
1.130 -to it.
1.131 -
1.132 -<li> Finally, an object is <em>unreachable</em>, and therefore eligible for
1.133 -reclamation, when it is not reachable in any of the above ways.
1.134 -
1.135 -</ul>
1.136 -
1.137 -
1.138 -@author Mark Reinhold
1.139 -@since 1.2
1.140 -
1.141 -<!--
1.142 -<h2>Related Documentation</h2>
1.143 -
1.144 -For overviews, tutorials, examples, guides, and tool documentation, please see:
1.145 -<ul>
1.146 - <li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
1.147 -</ul>
1.148 --->
1.149 -</body>
1.150 -</html>