From bf4ae1e29d4f40781557c10a400e5a461ce75e64 Mon Sep 17 00:00:00 2001
From: henryjen <unknown>
Date: Wed, 28 Aug 2013 14:13:03 -0700
Subject: [PATCH] 8022176: Weaken contract of java.lang.AutoCloseable
 Reviewed-by: alanb, martin, mduigou, psandoz Contributed-by:
 brian.goetz@oracle.com

---
 .../classes/java/lang/AutoCloseable.java      | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/share/classes/java/lang/AutoCloseable.java b/src/share/classes/java/lang/AutoCloseable.java
index ce0fffe59..be47cd083 100644
--- a/src/share/classes/java/lang/AutoCloseable.java
+++ b/src/share/classes/java/lang/AutoCloseable.java
@@ -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
-- 
GitLab