JDK-7012279 : Project Coin: Clarify AutoCloseable and Throwable javadoc
  • Type: Bug
  • Component: core-libs
  • Sub-Component: java.lang
  • Affected Version: 7
  • Priority: P4
  • Status: Closed
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2011-01-13
  • Updated: 2011-05-17
  • Resolved: 2011-05-17
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 7
7 b128Fixed
Related Reports
Relates :  
JDK-7027362 - Project Coin: warn of throwing InterruptedException in AutoCloseable.close javadoc
Relates :  
JDK-7031371 - Clarify javadoc of Throwable, including addSuppressed
Description
Feedback leading up to the JSR 334 EDR revealed a few suggestions for clarifications to the AutoCloseable and Throwable javadoc; these clarifications should be made.
Comments
PUBLIC COMMENTS See http://hg.openjdk.java.net/jdk7/tl/jdk/rev/59e352561146
14-01-2011
SUGGESTED FIX # HG changeset patch # User darcy # Date 1294986118 28800 # Node ID 59e352561146dd531f380b909f7d82f5cd7ea4aa # Parent 29f2e311cce7fd2b439238af470b400e97623208 7012279: Project Coin: Clarify AutoCloseable and Throwable javadoc Reviewed-by: jjb --- a/src/share/classes/java/lang/AutoCloseable.java Thu Jan 13 20:32:12 2011 -0800 +++ b/src/share/classes/java/lang/AutoCloseable.java Thu Jan 13 22:21:58 2011 -0800 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -33,7 +33,7 @@ package java.lang; */ public interface AutoCloseable { /** - * Close this resource, relinquishing any underlying resources. + * Closes this resource, relinquishing any underlying resources. * This method is invoked automatically by the {@code * try}-with-resources statement. * @@ -48,6 +48,10 @@ 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. + * * @throws Exception if this resource cannot be closed */ void close() throws Exception; --- a/src/share/classes/java/lang/Throwable.java Thu Jan 13 20:32:12 2011 -0800 +++ b/src/share/classes/java/lang/Throwable.java Thu Jan 13 22:21:58 2011 -0800 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -809,7 +809,7 @@ public class Throwable implements Serial native StackTraceElement getStackTraceElement(int index); /** - * Read a {@code Throwable} from a stream, enforcing + * Reads a {@code Throwable} from a stream, enforcing * well-formedness constraints on fields. Null entries and * self-pointers are not allowed in the list of {@code * suppressedExceptions}. Null entries are not allowed for stack @@ -865,9 +865,10 @@ public class Throwable implements Serial } /** - * Adds the specified exception to the list of exceptions that - * were suppressed, typically by the {@code try}-with-resources - * statement, in order to deliver this exception. + * Appends the specified exception to the exceptions that were + * suppressed in order to deliver this exception. This method is + * typically called (automatically and implicitly) by the {@code + * try}-with-resources statement. * * If the first exception to be suppressed is {@code null}, that * indicates suppressed exception information will <em>not</em> be
14-01-2011
EVALUATION Yes.
13-01-2011