Why are Phantom References not cleared as they are enqueued?

Question

We can see that "phantom reachable" is as unreachable as "unreachable": §

An object is phantom reachable if it is neither strongly, softly, nor weakly reachable, it has been finalized, and some phantom reference refers to it.

Finally, an object is unreachable, and therefore eligible for reclamation, when it is not reachable in any of the above ways.

Now, from: http://download.oracle.com/javase/6/docs/api/java/lang/ref/PhantomReference.html

Unlike soft and weak references, phantom references are not automatically cleared by the garbage collector as they are enqueued. An object that is reachable via phantom references will remain so until all such references are cleared or themselves become unreachable.

What's the underlying rationale? Is there even one?

Is this yet another typical case of Java API quirk?

Answer 1

Soft references are cleared when enqueued because the primary use of soft references are to allow caching of large objects, and clearing the soft references allows the large cached object to be garbage collected.

Weak references are cleared when enqueued because the primary use of weak references are to allow one to reference an object without preventing it from being garbage collected, so clearing the references as soon as the object is enqueued allows the object to be garbage collected.

Phantom references are not cleared when enqueued since one use case of phantom references is to allow performing cleanup before an object is garbage collected. By not clearing the references, the object remains phantomly reachable (and not eligible for garbage collected) until after the PhantomReference to that object is cleared by the user, or the PhantomReference is itself garbage collected.

This is explained here,

An object is phantom reachable if it is neither strongly, softly, nor weakly reachable, it has been finalized, and some phantom reference refers to it.

Finally, an object is unreachable, and therefore eligible for reclamation, when it is not reachable in any of the above ways.

Answer 2

This was changed in JDK 9. Now phantom references are cleared as soft and weak references do. And the corresponding paragraph was removed from the Javadoc.

Unlike soft and weak references, phantom references are not automatically cleared by the garbage collector as they are enqueued. An object that is reachable via phantom references will remain so until all such references are cleared or themselves become unreachable.