Project Coin: ARM API

The initial API changes to support the Project Coin feature automatic resource management (ARM) blocks have been pushed into JDK 7 (langtools, jdk) 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:

  • 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 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

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.


For those of us not following Project Coin, can you elaborate on why JDBC and graphics aren't retrofitting AutoClosable? I'm curious.

Posted by Kevin on June 23, 2010 at 02:29 PM PDT #


The JDBC group has discussed how auto-closing would interact with transactions and they don't want to update the types in question at this time, although they may decide to do so in the future.

For the graphics class in question, there were compatibility concerns around adding a close method to those classes and from an implementation perspective the existing "dispose" method has not been needed to be called to free resources since 1.2.

Posted by Joe Darcy on June 23, 2010 at 05:08 PM PDT #

mmm, project coin is increasingly looking like the sweet spot of jdk7.
thumbs up!

Posted by guest on June 23, 2010 at 08:26 PM PDT #

It would be very disappointing for JDBC not to support the feature. After all, JDBC is one of the MAIN places where this is useful!

Posted by am on June 25, 2010 at 04:03 AM PDT #

Yes, closing ResultSet-s and PreparedStatements are the single most important places, where most of the developers would be using this feature. Except probably with Input and OutputStreams.

Posted by Zsombor on June 26, 2010 at 12:13 AM PDT #

Yes, JDBC indeed is the most useful place for this feature. It is really a pity that it would no be introduced there. As for the interaction with transactions - it is not a big issue IMHO, as only auto-closing of result sets and statements likely will not influence transactional behavior at all and for connections the policy shall be quite straightforward - any changes that are not committed to the
moment of the closing of the connection must be rolled back.

Posted by al0 on June 29, 2010 at 08:24 PM PDT #

@am, @Zsombor, and @al0,

We've consulted with Lance Andersen and the JDBC expert group. It is that group's call on if and when the JDBC interfaces are retrofitted to work with ARM. Just because JDBC has not beem updated for ARM now now does not imply they won't be updated at some time point in the future.

Posted by Joe Darcy on July 03, 2010 at 02:46 AM PDT #

We only can hope that that point is not in the year 3001.

Posted by al0 on July 03, 2010 at 02:53 AM PDT #

Joe, thanks to you and everyone else for the effort with Project Coin, it is much appreciated.

I'm a little disappointed that JDBC hasn't been updated to use AutoCloseable as this is one of the areas I've seen where resources aren't always released appropriately. I've taken a shot at creating a small library to adapt the JDBC classes to AutoCloseable and I'd love any feedback:

Here's an example usage:

import static;
// "arm" the datasource to get an AutoCloseable instance
try ( AutoCloseConnection c = arm(dataSource).getConnection();
AutoClosePreparedStatement stmt = c.prepareStatement("select 1 from dual");
AutoCloseResultSet rs = stmt.executeQuery() ) {

while ( {
// do something with the result set
// the result set, prepared statement, and connection are all automatically closed

Posted by David Schlosnagle on July 24, 2010 at 07:12 AM PDT #

The changes to add support for ARM would be part of JDBC 4.1 which we hope to include in Java SE 7. If JDBC 4.1 makes it into Java SE 7 we should be able to include this feature. We have been discussing this in the JDBC EG and at this time we do not see any potential gotchas for the interfaces which support a close() method.

Posted by Lance Andersen on July 28, 2010 at 01:56 AM PDT #

Lance, great news. I'd love for ARM support to be included in the JDBC spec and Java SE 7. There is one JDBC specific interaction with AutoCloseable that developers would need to be cautious of -- the java.sql.Connection needs to be committed or rolled back prior to the invocation of close() (whether explicit or implicit via the ARM construct) [1]. This isn't really any different than if someone was already explicitly closing the Connection, but I could see some cases where developers naively assume that using the ARM construct with a Connection would automatically handle this for them, and unfortunately this could be considered a violation of the "do no harm" principle.

It is strongly recommended that an application explicitly commits or rolls
back an active transaction prior to calling the close method. If the close
method is called and there is an active transaction, the results are

Posted by David Schlosnagle on July 28, 2010 at 02:18 AM PDT #

A happy update on on JDBC and try-with-resources, JDBC 4.1 in JDK 7 has been retrofitted to implement AutoCloseable:

Posted by Joe Darcy on September 14, 2010 at 06:45 PM PDT #

Post a Comment:
Comments are closed for this entry.



« July 2016

No bookmarks in folder