emul/compact/src/main/java/java/lang/ref/package.html
changeset 772 d382dacfd73f
parent 771 4252bfc396fc
child 773 406faa8bc64f
     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>