src/share/classes/java/lang/AutoCloseable.java

@@ -1,7 +1,7 @@
 /*
- * 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
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -31,11 +31,11 @@
  * @author Josh Bloch
  * @since 1.7
  */
 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.
      *
      * <p>Classes implementing this method are strongly encouraged to
      * be declared to throw more specific exceptions (or no exception

@@ -46,9 +46,13 @@
      * is <em>not</em> required to be idempotent.  In other words,
      * calling this {@code close} method more than once may have some
      * 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;
 }