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

Clarify the behavior of PhantomReference::refersTo

    XMLWordPrintable

    Details

    • Subcomponent:
    • Resolved In Build:
      b30
    • CPU:
      generic
    • OS:
      generic

      Backports

        Description

        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






          Attachments

            Issue Links

              Activity

                People

                Assignee:
                mchung Mandy Chung
                Reporter:
                webbuggrp Webbug Group
                Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                  Dates

                  Created:
                  Updated:
                  Resolved: