src/java.base/share/classes/java/lang/ref/package-info.java

rev 13309 : imported patch spec
rev 13310 : imported patch inc1

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2015, 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

@@ -41,12 +41,11 @@
  * and <em>phantom</em>.  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.
+ * scheduling post-mortem cleanup actions.
  *
  * <p> 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 <em>referent</em>.

@@ -62,13 +61,13 @@
  * A program may request to be notified of changes in an object's
  * reachability by <em>registering</em> an appropriate reference
  * object with a <em>reference queue</em> 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 <em>enqueued</em>.  The program may remove
+ * value corresponding to the type of the reference, it will clear the
+ * reference and add it to the associated queue.  At this point, the
+ * reference is considered to be <em>enqueued</em>.  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.
  *
  * <p> The relationship between a registered reference object and its

@@ -90,20 +89,10 @@
  * 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.
  *
- * <h3>Automatically-cleared references</h3>
- *
- * 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.
- *
  * <a name="reachability"></a>
  * <h3>Reachability</h3>
  *
  * Going from strongest to weakest, the different levels of
  * reachability reflect the life cycle of an object.  They are