Bug ID: JDK-7027362 Project Coin: warn of throwing InterruptedException in AutoCloseable.close javadoc

Type: Bug
Component: core-libs
Sub-Component: java.lang
Affected Version: 7

Priority: P3
Status: Closed
Resolution: Fixed
OS: generic
CPU: generic

Submitted: 2011-03-14
Updated: 2021-06-15
Resolved: 2011-05-18

JDK 7
7 b136Fixed

From http://mail.openjdk.java.net/pipermail/coin-dev/2011-March/003161.html

"After due consideration and after consulting with the concurrency mavens 
on the JSR 166 expert group, the JSR 334 expert group has decided it is 
sufficient for the specification of the AutoCloseable type to strongly 
warn against having AutoCloseable.close throw InterruptedException at 
runtime.  Additionally, javac and other compilers may warn against 
declaring an AutoCloseable.close method which throws InterruptedException."

SUGGESTED FIX # HG changeset patch # User darcy # Date 1300128321 25200 # Node ID 1924a21184a629e214eed61b1a08255731af547a # Parent 2e473067520f7be2bfbb598750f5a6567e44d5b2 7027362: Project Coin: warn of throwing InterruptedException in AutoCloseable.close javadoc Reviewed-by: jjb --- a/src/share/classes/java/lang/AutoCloseable.java Mon Mar 14 18:13:32 2011 +0000 +++ b/src/share/classes/java/lang/AutoCloseable.java Mon Mar 14 11:45:21 2011 -0700 @@ -34,12 +34,27 @@ public interface AutoCloseable { public interface AutoCloseable { /** * Closes this resource, relinquishing any underlying resources. - * This method is invoked automatically by the {@code - * try}-with-resources statement. + * This method is invoked automatically on objects managed by the + * {@code try}-with-resources statement. * - * Classes implementing this method are strongly encouraged to - * be declared to throw more specific exceptions (or no exception - * at all, if the close cannot fail). + * While this interface method is declared to throw {@code + * Exception}, implementers are strongly 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. + * + * Implementers of this interface are also strongly advised + * to not have the {@code close} method throw {@link + * 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}. + * + * More generally, if it would cause problems for an + * exception to be suppressed, the {@code AutoCloseable.close} + * method should not throw it. * * Note that unlike the {@link java.io.Closeable#close close} * method of {@link java.io.Closeable}, this {@code close} method @@ -48,9 +63,8 @@ public interface AutoCloseable { * visible side effect, unlike {@code Closeable.close} which is * required to have no effect if called more than once. * - * However, while not required to be idempotent, implementers of - * this interface are strongly encouraged to make their {@code - * close} methods idempotent. + * However, implementers of this interface are strongly encouraged + * to make their {@code close} methods idempotent. * * @throws Exception if this resource cannot be closed */

14-03-2011

EVALUATION Yes.

14-03-2011

PUBLIC COMMENTS See http://hg.openjdk.java.net/jdk7/tl/jdk/rev/1924a21184a6

14-03-2011

Relates :	JDK-8268736 - Use apiNote in AutoCloseable.close javadoc
Relates :	JDK-7012279 - Project Coin: Clarify AutoCloseable and Throwable javadoc
Relates :	JDK-7031273 - Project Coin: Sync with JSR 334 PR
Relates :	JDK-8155591 - Misleading warning when not overriding close method in interface extending AutoCloseable
Relates :	JDK-7027157 - Project Coin: javac warnings for AutoCloseable.close throwing InterruptedException