package java.lang;

/**
 * A resource that must be closed when it is no longer needed.
 */
public interface AutoCloseable {
	/**
	 * Closes this resource, relinquishing any underlying resources. This method is invoked
	 * automatically on objects managed by the {@code try}-with-resources statement.
	 *
	 * <p>
	 * While this interface method is declared to throw {@code Exception}, implementers are
	 * <em>strongly</em> encouraged to declare concrete implementations of the {@code close} method to
	 * throw more specific exceptions, or to throw no exception at all if the close operation cannot
	 * fail.
	 *
	 * <p>
	 * <em>Implementers of this interface are also strongly advised to not have the {@code close} method
	 * throw {@link InterruptedException}.</em>
	 *
	 * This exception interacts with a thread's interrupted status.
	 *
	 * <p>
	 * Note that unlike the {@link java.io.Closeable#close close} method of {@link java.io.Closeable},
	 * this {@code close} method is <em>not</em> required to be idempotent. In other words, calling this
	 * {@code close} method more than once may have some visible side effect, unlike
	 * {@code Closeable.close} which is required to have no effect if called more than once.
	 *
	 * However, implementers of this interface are strongly encouraged to make their {@code close}
	 * methods idempotent.
	 *
	 * @throws Exception
	 *         if this resource cannot be closed
	 */
	void close() throws Exception;
}