ARM API Support

[Joe Darcy]

Greetings

The initial API changes to support the Project Coin feature automatic 
resource management (ARM) blocks have been pushed into JDK 7 [1] and 
will appear in subsequent builds. The corresponding compiler changes to 
support the actual language feature remain in progress.

The initial API work to support ARM was divided into two pieces, 
essential API support and retrofitting platform classes. The essential 
support includes:

* A new interface java.lang.AutoCloseable which defines a single method
  void close() throws Exception

* A new enum constant in the language model:
  javax.lang.model.element.ElementKind.RESOURCE_VARIABLE

* Methods on java.lang.Throwable to add and retrieve information about 
suppressed exceptions, including printing out suppressed exceptions in 
stack traces.

The retrofitting includes:

* Having java.io.Closeable extend java.lang.AutoCloseable. (From a 
typing perspective, a subtype of AutoCloseable can be declared to throw 
fewer exceptions than the supertype. Therefore is is fine for the close 
method in AutoCloseable to throw Exception and the close method in 
Closeable to throw the more specific IOException. It would even be fine 
for the close method in a subtype of AutoCloseable to be declared to 
throw no exceptions at all.)

* Adding a close method to java.nio.channels.FileLock and having 
FileLock implement AutoCloseable.

* Adding Closeable as an interface implemented by 
javax.imageio.stream.ImageInputStream.

Other platform classes may be retrofitted to implement AutoCloseable or 
Closable in future builds.

Compared to the API support in earlier versions of the ARM proposal, the 
top-level interface to mark participation in ARM is in package java.lang 
rather than its own package and, after consultation with the JDBC and 
graphics teams, neither java.sql.* nor java.awt.Graphics were 
retrofitted for ARM.

-Joe

[1] http://hg.openjdk.java.net/jdk7/tl/jdk/rev/c4d60bcce958
    http://hg.openjdk.java.net/jdk7/tl/langtools/rev/be5cafeb318d