original

The try-with-resources Statement

try-with-resources 声明

The try-with-resources statement is a try statement that declares one or more resources. A resource is an object that must be closed after the program is finished with it. The try-with-resources statement ensures that each resource is closed at the end of the statement. Any object that implements java.lang.AutoCloseable, which includes all objects which implement java.io.Closeable, can be used as a resource.
try-with-resources声明是一个try声明中定义了一个或多个资源。资源是指程序结束使用它后必须被关闭的实体。try-with-resources声明可以确保每一个资源都会在声明结束部分被关闭。任何实现了java.lang.AutoCloseable，包括所有实现了java.io.Closeable可以被当做资源使用。

The following example reads the first line from a file. It uses an instance of BufferedReader to read data from the file. BufferedReader is a resource that must be closed after the program is finished with it:
下面的例子读取了文件的第一行。它使用了一个BufferedReader实例来读取文件中的数据。BufferedReader是一个程序结束后必须被关闭的资源。

static String readFirstLineFromFile(String path) throws IOException {
    **try (BufferedReader br =
                   new BufferedReader(new FileReader(path)))** {
        return br.readLine();
    }
}

In this example, the resource declared in the try-with-resources statement is a BufferedReader. The declaration statement appears within parentheses immediately after the try keyword. The class BufferedReader, in Java SE 7 and later, implements the interface java.lang.AutoCloseable. Because the BufferedReader instance is declared in a try-with-resource statement, it will be closed regardless of whether the try statement completes normally or abruptly (as a result of the method BufferedReader.readLine throwing an IOException).
在这个例子中，一个BufferedReader作为资源声明在了try-with-resources结构中。声明的动作出现在try关键字之后的圆括号内。在JavaSE7以及之后版本，BufferedReader类实现了接口java.lang.AutoCloseable，因为BufferedReader实例声明在了try-with-resources结构中，它一定会被关闭，不论try结构的代码完整执行还是产生异常(BufferedReader.readLine方法的结果是可能抛出IO异常的)。

Prior to Java SE 7, you can use a finally block to ensure that a resource is closed regardless of whether the try statement completes normally or abruptly. The following example uses a finally block instead of a try-with-resources statement:
JavaSE7之前的版本，您可以使用finally代码块来确保资源可以被关闭，不论try代码块是否报异常。下面的例子使用了finally代码块代替try-with-resources结构。

static String readFirstLineFromFileWithFinallyBlock(String path)
                                                     throws IOException {
    BufferedReader br = new BufferedReader(new FileReader(path));
    try {
        return br.readLine();
    } finally {
        if (br != null) br.close();
    }
}

However, in this example, if the methods readLine and close both throw exceptions, then the method readFirstLineFromFileWithFinallyBlock throws the exception thrown from the finally block; the exception thrown from the try block is suppressed. In contrast, in the example readFirstLineFromFile, if exceptions are thrown from both the try block and the try-with-resources statement, then the method readFirstLineFromFile throws the exception thrown from the try block; the exception thrown from the try-with-resources block is suppressed. In Java SE 7 and later, you can retrieve suppressed exceptions; see the section Suppressed Exceptions for more information.

但是，在这例子中，如果readLine和close两个方法都抛出异常，那么方法readFirstLineFromFileWithFinallyBlock就会抛出异常，这个异常由finally代码块中抛出；try代码块中的抛出的异常被抑制了。相反地，在例子readFirstLineFromFile中，如果异常try代码块以及try-with-resources结构中都抛出异常，那么readFirstLineFromFile方法抛出的异常会由try代码块抛出；由try-with-resources结构中抛出的异常会被抑制。在JavaSE7以及之后版本中，你可以恢复被抑制的异常，更多信息请查看文档Suppressed Exceptions

You may declare one or more resources in a try-with-resources statement. The following example retrieves the names of the files packaged in the zip file zipFileName and creates a text file that contains the names of these files:

在try-with-resources结构中，你可能会声明一个或多个资源。下面的例子检索了打包在zip压缩文件zipFileName中的文件的名称，并且创建了一个文本文件来保存这些文件名。

public static void writeToFileZipFileContents(String zipFileName,
                                           String outputFileName)
                                           throws java.io.IOException {

    java.nio.charset.Charset charset =
         java.nio.charset.StandardCharsets.US_ASCII;
    java.nio.file.Path outputFilePath =
         java.nio.file.Paths.get(outputFileName);

    // Open zip file and create output file with 
    // try-with-resources statement

    try (
        java.util.zip.ZipFile zf =
             new java.util.zip.ZipFile(zipFileName);
        java.io.BufferedWriter writer = 
            java.nio.file.Files.newBufferedWriter(outputFilePath, charset)
    ) {
        // Enumerate each entry
        for (java.util.Enumeration entries =
                                zf.entries(); entries.hasMoreElements();) {
            // Get the entry name and write it to the output file
            String newLine = System.getProperty("line.separator");
            String zipEntryName =
                 ((java.util.zip.ZipEntry)entries.nextElement()).getName() +
                 newLine;
            writer.write(zipEntryName, 0, zipEntryName.length());
        }
    }
}

In this example, the try-with-resources statement contains two declarations that are separated by a semicolon: ZipFile and BufferedWriter. When the block of code that directly follows it terminates, either normally or because of an exception, the close methods of the BufferedWriter and ZipFile objects are automatically called in this order. Note that the close methods of resources are called in the opposite order of their creation.

在这个例子中，try-with-resources结构包含了ZipFile 和 BufferedWriter两个资源的声明，它们由分号隔开。无论是否产生异常，当代码块执行完毕时，BufferedWriter 和 ZipFile的close方法都会被自定地执行。请注意，是先执行BufferedWriter的close，后执行ZipFile的close，这个顺序与他们的创建顺序是相反的。

The following example uses a try-with-resources statement to automatically close a java.sql.Statement object:
下面的例子使用了try-with-resources声明自动关闭了java.sql.Statement对象。

public static void viewTable(Connection con) throws SQLException {

    String query = "select COF_NAME, SUP_ID, PRICE, SALES, TOTAL from COFFEES";

    try (Statement stmt = con.createStatement())** {
        ResultSet rs = stmt.executeQuery(query);

        while (rs.next()) {
            String coffeeName = rs.getString("COF_NAME");
            int supplierID = rs.getInt("SUP_ID");
            float price = rs.getFloat("PRICE");
            int sales = rs.getInt("SALES");
            int total = rs.getInt("TOTAL");

            System.out.println(coffeeName + ", " + supplierID + ", " + 
                               price + ", " + sales + ", " + total);
        }
    } catch (SQLException e) {
        JDBCTutorialUtilities.printSQLException(e);
    }
}

The resource java.sql.Statement used in this example is part of the JDBC 4.1 and later API.
例子中的java.sql.Statement作为资源是JDBC4.1以及之后版本的一部分。

Note: A try-with-resources statement can have catch and finally blocks just like an ordinary try statement. In a try-with-resources statement, any catch or finally block is run after the resources declared have been closed.
请注意：try-with-resources声明也可以像平常的try结构一样使用catch和finally代码块。在try-with-resources结构中，所有的catch或finally代码块会在资源被关闭后执行。

Suppressed Exceptions

被抑制的异常

An exception can be thrown from the block of code associated with the try-with-resources statement. In the example writeToFileZipFileContents, an exception can be thrown from the try block, and up to two exceptions can be thrown from the try-with-resources statement when it tries to close the ZipFile and BufferedWriter objects. If an exception is thrown from the try block and one or more exceptions are thrown from the try-with-resources statement, then those exceptions thrown from the try-with-resources statement are suppressed, and the exception thrown by the block is the one that is thrown by the writeToFileZipFileContents method. You can retrieve these suppressed exceptions by calling the Throwable.getSuppressed method from the exception thrown by the try block.
在try-with-resources声明中，代码块中可以抛出异常。在writeToFileZipFileContents的例子中，try代码块可以爆出一个异常，尝试关闭两个资源时，try-with-resources声明中最多可以抛出两个异常。如果try代码块抛出一个异常，try-with-resources声明中抛出一个或两个异常，那么try-with-resources声明中抛出的异常会被抑制，try代码块中的异常会被方法writeToFileZipFileContents抛出。你可以通过调用try代码块中抛出的异常对象的Throwable.getSuppressed方法来恢复那些被抑制的异常。

Classes That Implement the AutoCloseable or Closeable Interface

那些实现了AutoCloseable或Closeable接口的类

See the Javadoc of the AutoCloseable and Closeable interfaces for a list of classes that implement either of these interfaces. The Closeable interface extends the AutoCloseable interface. The close method of the Closeable interface throws exceptions of type IOException while the close method of the AutoCloseable interface throws exceptions of type Exception. Consequently, subclasses of the AutoCloseable interface can override this behavior of the close method to throw specialized exceptions, such as IOException, or no exception at all.

查看java文档AutoCloseable 和 Closeable获取一个列表，这个列表中的类实现了这两个接口中的其中一个。Closeable接口继承了AutoCloseable接口。Closeable接口中的close方法抛出了IOException的异常，然而AutoCloseable接口中的close方法抛出了Exception类型的异常。因此，实现了AutoCloseable接口的子类可以重写这个close方法来覆盖这个行为，可以改成抛出指定异常，例如IOException，或者根本不抛出异常。