/** * 保持资源(文件或者socket)直到它关闭的类.{@code AutoCloseable} 的 {@link #close()}方法 * 在退出 {@code try}-with-resources 块时自动被调用.指令应该保证资源被立即释放, * 避免资源超出限制导致错误. * * @apiNote * <p>实际上,并不需要子类都实现自动释放资源,由基类来实现释放资源也是可行的,通常推荐使用 * {@code try}-with-resources 块处理资源.然而,因为{@link java.util.stream.Stream} * 支持基于I/O和非I/O俩种形式,因此{@code try}-with-resources 块通常在非I/O形式时没有必要使用. * @since 1.7 */ /** * An object that may hold resources (such as file or socket handles) * until it is closed. The {@link #close()} method of an {@code AutoCloseable} * object is called automatically when exiting a {@code * try}-with-resources block for which the object has been declared in * the resource specification header. This construction ensures prompt * release, avoiding resource exhaustion exceptions and errors that * may otherwise occur. * * @apiNote * <p>It is possible, and in fact common, for a base class to * implement AutoCloseable even though not all of its subclasses or * instances will hold releasable resources. For code that must operate * in complete generality, or when it is known that the {@code AutoCloseable} * instance requires resource release, it is recommended to use {@code * try}-with-resources constructions. However, when using facilities such as * {@link java.util.stream.Stream} that support both I/O-based and * non-I/O-based forms, {@code try}-with-resources blocks are in * general unnecessary when using non-I/O-based forms. * * @author Josh Bloch * @since 1.7 */ public interface AutoCloseable { /** * 关闭资源,放弃任何底层资源.在 {@code try}-with-resources中此方法被自动使用. * <p> 此方法被声明成抛出{@code Exception},强烈建议抛出自己专用异常, * 或者如果操纵不允许失败,不抛出异常. * * <p> 实现的closeclose会失败时需要特别小心,强烈建议放弃底层资源并且将内部资源标记为已经closed, * 然后再抛出异常.{@code close}方法调用次数不会超过一次,所以确保资源能够 * 及时释放.此外,它还减少了资源包裹容易出现的问题. * * <p> 强烈建议实现类不要抛出{@link InterruptedException} */ /** * 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> Cases where the close operation may fail require careful * attention by implementers. It is strongly advised to relinquish * the underlying resources and to internally <em>mark</em> the * resource as closed, prior to throwing the exception. The {@code * close} method is unlikely to be invoked more than once and so * this ensures that the resources are released in a timely manner. * Furthermore it reduces problems that could arise when the resource * wraps, or is wrapped, by another resource. * * <p><em>Implementers of this interface are also strongly advised * to not have the {@code close} method throw {@link * InterruptedException}.</em> * * 此异常与线程状态交互,如果{@linkplain Throwable#addSuppressed 禁止} * @{code InterruptedException}可能会导致非预期运行时行为 * * This exception interacts with a thread's interrupted status, * and runtime misbehavior is likely to occur if an {@code * InterruptedException} is {@linkplain Throwable#addSuppressed * suppressed}. * * 更普遍来说,如果异常应该被禁止,{@code AutoCloseable.close}就不应该抛出它. * * More generally, if it would cause problems for an * exception to be suppressed, the {@code AutoCloseable.close} * method should not throw it. * * 注意:与{@link java.io.Closeable#close close}不同,{@code close}不要求是幂等. * 换句话来说,调用此方法超过一次可能会导致副作用.而{@code Closeable.close}可以多次调用. * * 但是,强烈将此方法实现成幂等操作. * * <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; }