See this thread from Peter Levart on core-libs-dev:
Ripped javadoc from webrev.jdk.02:
`Ephemeron` objects are a special kind of `WeakReference` objects, which
hold two referents (a normal referent, also called a key referent, and a
value referent) and do not prevent their referents from being made
finalizable, finalized, and then reclaimed. In addition to the key
referent, which adheres to the referent behavior of a `WeakReference`,
an ephemeron also holds a value referent whose reachabiliy strength is
affected by the reachability strength of the key referent. The value
referent of an Ephemeron instance is considered:
- *strongly reachable* if the key referent of the same Ephemeron
object is strongly reachable, or if the value referent is otherwise
- *softly reachable* if it is not strongly reachable, and the key
referent of the same Ephemeron object is softly reachable, or if the
value referent is otherwise softly reachable.
- *weakly reachable* if it is neither strongly nor softly reachable,
and the key referent of the same Ephemeron object is weakly
reachable, or if the value referent is otherwise weakly reachable.
When the collector clears an Ephemeron object instance (according to the
rules expressed for clearing WeakReference object instances), the
Ephemeron instance's key referent and value referent are simultaneously
and atomically cleared.
By convenience, the Ephemeron's normal referent is also called the key
referent, and can be obtained either by invoking [`#get`] or [`#getKey`]
while the value referent can be obtained by invoking [`#getValue`]
### Reachability (should be moved to package-level docs)
Going from strongest to weakest, the different levels of reachability
reflect the life cycle of an object. They are operationally defined as
- An object is *strongly reachable* if it can be reached by some
thread without traversing any reference objects, or by traversing
the value of an Ephemeron whose key is strongly reachable. A
newly-created object is strongly reachable by the thread that
- An object is *softly reachable* if it is not strongly reachable but
can be reached by traversing a soft reference or by traversing the
value of an Ephemeron whose key is softly reachable.
- An object is *weakly reachable* if it is neither strongly nor softly
reachable but can be reached by traversing a weak reference or by
traversing the value of an ephemeron whose key is weakly reachable.
When the weak references to a weakly-reachable object are cleared,
the object becomes eligible for finalization.
- 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.