changeset 8109: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