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.
 * <p>
 * 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.<p>
     * 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.
     * <p>This method is invoked only by Java code; when the garbage collector
     * clears references it does so directly, without invoking this method.
     */
    void clear();
}