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

Behavior of PhantomReference.refersTo is not well documented

    XMLWordPrintable

    Details

    • Subcomponent:
    • CPU:
      generic
    • OS:
      generic

      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

          Activity

            People

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

              Dates

              Created:
              Updated: