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

*** 1,7 ****
  /*
!  * Copyright (c) 2009, 2010, 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
--- 1,7 ----
  /*
!  * 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,41 ****
   * @author Josh Bloch
   * @since 1.7
   */
  public interface AutoCloseable {
      /**
!      * Close 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
--- 31,41 ----
   * @author Josh Bloch
   * @since 1.7
   */
  public interface AutoCloseable {
      /**
!      * 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,54 ****
--- 46,58 ----
       * 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;
  }