Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8262841

Clarify the behavior of PhantomReference::refersTo

XMLWordPrintable

    • b30
    • generic
    • generic

        A DESCRIPTION OF THE PROBLEM :
        When JDK-8188055 added Reference.refersTo, there were some concerns regarding how PhantomReference should behave. In the end it appears PhantomReference.refersTo got the functionality to check whether the reference still refers to an object (at least latest jdk.java.net builds do):
        ```
        Object o = new Object();
        PhantomReference<Object> ref = new PhantomReference<>(o, null);
        ref.refersTo(null); // false
        ref.refersTo(o); // true
        ```

        However the current documentation for PhantomReference does not make this obvious, especially since the documentation for `Reference.get()` says that instead of `get() == ...` one should use `refersTo(...)`, but `PhantomReference.get()` is documented as always returning `null`.

        Therefore it would be good to adjust the PhantomReference documentation in the following ways:
        - Class documentation section with "The {@code get} method of a phantom reference always returns {@code null}" should mention that `refersTo` can be used.
        - Constructor documentation should be rephrased. It might now be a legit use-case to use `null` as queue and call `refersTo` (at least it is not "completely useless" anymore)
        - `refersTo` should be overridden to allow mentioning in documentation that this method works for PhantomReference






              mchung Mandy Chung (Inactive)
              webbuggrp Webbug Group
              Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

                Created:
                Updated:
                Resolved: