Mercurial > hg > openjdk > aarch64-port > jdk
changeset 8020:77a8c4ad516c
8022176: Weaken contract of java.lang.AutoCloseable
Reviewed-by: alanb, martin, mduigou, psandoz
Contributed-by: brian.goetz@oracle.com
author | henryjen |
---|---|
date | Wed, 28 Aug 2013 14:13:03 -0700 |
parents | 4bdbe25b1e04 |
children | 3db3ae4e0853 |
files | src/share/classes/java/lang/AutoCloseable.java |
diffstat | 1 files changed, 18 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/src/share/classes/java/lang/AutoCloseable.java Tue Sep 03 11:29:12 2013 -0700 +++ b/src/share/classes/java/lang/AutoCloseable.java Wed Aug 28 14:13:03 2013 -0700 @@ -26,7 +26,24 @@ package java.lang; /** - * A resource that must be closed when it is no longer needed. + * 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