--- /dev/null 2015-07-01 10:11:09.377158340 +0200 +++ new/src/java.base/share/classes/java/lang/ref/Cleaner.java 2015-07-03 16:04:57.800716165 +0200 @@ -0,0 +1,53 @@ +package java.lang.ref; + +/** + * {@link Reference}(s) implementing this interface are automatically + * {@link #clean() cleaned} by reference handling thread(s) after their referents + * become appropriately (soft, weak or phantom) reachable. + *

+ * Such references can not be associated with a {@link ReferenceQueue}. Attempts + * to register a {@link SoftReference#SoftReference(Object, ReferenceQueue) soft}, + * {@link WeakReference#WeakReference(Object, ReferenceQueue) weak} or + * {@link PhantomReference#PhantomReference(Object, ReferenceQueue) phantom} + * reference implementing this interface with a non-null {@code ReferenceQueue} + * throw {@link IllegalArgumentException}. + * + * @since 1.9 + */ +public interface Cleaner { + + /** + * Invoked by one of the reference handling thread(s) some time after the + * referent of a {@link Reference} implementing this interface becomes + * appropriately (soft, weak or phantom) reachable and after the Reference + * is cleared by the garbage collector.

+ * Implementations should put the clean-up code into this method. + */ + void clean(); + + /** + * Always returns false. References implementing {@link Cleaner} + * interface are never associated with a {@link ReferenceQueue}. + * + * @return false; + */ + boolean isEnqueued(); + + /** + * Does nothing and returns false. References implementing {@link Cleaner} + * interface are never associated with a {@link ReferenceQueue}. + * + * @return false + */ + boolean enqueue(); + + /** + * Clears this Cleaner reference object. Invoking this method will not cause + * this object to be {@link #clean() cleaned}. It may prevent this object + * from being cleaned in the future if it has not been discovered as a pending + * reference by GC yet. + *

This method is invoked only by Java code; when the garbage collector + * clears references it does so directly, without invoking this method. + */ + void clear(); +}