Sometime ago I started writing a JNI wrapper around libgit2.
I quickly gave up on it. I was not confident on my very little C knowledge nor my very little JNI knowledge. So instead I started writing a pure Java GIT (partial) implementation.
A main takeaway from my brief JNI experience was my newfound appreciation of:
- Java's error signaling via exceptions. Checked exceptions included (as opposed to return codes); and
- Java's exception handling and resource releasing via
try
andtry-with-resources
statements (as opposed to a combination ofif
andgoto
statements).
What problems did the try-with-resources
solve?
As mentioned we handle exceptional conditions in Java via the try
and the try-with-resources
Java statements. The former exists since the first release of the language. The latter was introduced in Java 7.
At time of writing Java 7 is almost 11 years old. So let's remember why the try-with-resources
statement was introduced.
I was not there with the language designers. Nor did I research the mailing lists. So this section is about my assumptions. I just want this to be clear.
Anyways, what problems did the try-with-resources
solve? Wasn't the plain try
statement enough?
Let's investigate.
Our running example
For our investigations we will use a class that simulates a resource that needs to be released after it has been used.
For all purposes, think of it being like a java.io.FileWriter
.
Here is the code:
public class Resource implements Closeable {
final String name;
Resource(String name) {
this.name = name;
print0("created");
}
public static Resource create(String name) throws IOException {
return new Resource(name);
}
@Override
public void close() throws IOException {
print0("closed");
}
public void write(String s) throws IOException {
print0(s);
}
final void print0(String string) {
System.out.println(name + ": " + string);
}
}
To use it you first need to create a new instance by invoking the static create
method. It requires a name. Think of it as a pathname.
The class can throw an IOException
on creation, just like new FileWriter
or Files.newBufferedWriter
would. Examples of reasons why this might happen:
- the specified pathname resolves to a directory. You can't write to a directory as if it were a regular file; or
- the specified pathname could be of a location for which you do not have write permission.
Once the resource object is created it prints created
to System.out
.
You can write to it by invoking the write
method. It does actual I/O as it prints to System.out
.
After you have done writing you must close the resource by invoking the close
method. It is specified by the java.io.Closeable
interface which Resource
implements. It prints closed
signaling that closing was successful.
Single resource
So let's use our class. We will use a single resource to print a string to the console.
First using a plain try
statement:
public class Try {
public static void main(String[] args) throws IOException {
var out = Resource.create("TRY");
try {
out.write("Try statement (iteration 1)");
} finally {
out.close();
}
}
}
I know, I am not actually doing any error handling here, but bear with me.
Executing this example results in the following output to the console:
TRY: created
TRY: Try statement (iteration 1)
TRY: closed
Now, the same example using the try-with-resources
statement:
public class TryWithResources {
public static void main(String[] args) throws IOException {
try (var out = Resource.create("TWR")) {
out.write("Try-with-resources statement (iteration 1)");
}
}
}
Prints:
TWR: created
TWR: Try-with-resources statement (iteration 1)
TWR: closed
The try-with-resources
is more concise, the closing happens automatically and the resource variable is scoped to the statement itself.
Still, one can say that, in this example, the try
statement looks manageable, does it not?
I tend to agree, but I do not think this example illustrates the main reason for using the try-with-resources
statement.
Two resources
I think most problems arise when using more than one resource. This can be a common use-case, for instance:
- transferring data from an
InputStream
to anOutputStream
; - same thing but using Java NIO channels; or
- using plain JDBC and dealing with connection, statement and result set.
So let's write a version using two resources:
public class Try {
// Please avoid code like this in production
public static void main(String[] args) throws IOException {
var a = Resource.create("A");
var b = Resource.create("B");
try {
a.write("Try statement (iteration 2)");
b.write("Try statement (iteration 2)");
} finally {
a.close();
b.close();
}
}
}
This example has a number of problems which we will discuss in this section. For now, let's run it as it is:
A: created
B: created
A: Try statement (iteration 2)
B: Try statement (iteration 2)
A: closed
B: closed
While using the try-with-resources
statement:
public class TryWithResources {
public static void main(String[] args) throws IOException {
try (var a = Resource.create("A"); var b = Resource.create("B")) {
a.write("Try-with-resources statement (iteration 2)");
b.write("Try-with-resources statement (iteration 2)");
}
}
}
Gives:
A: created
B: created
A: Try-with-resources statement (iteration 2)
B: Try-with-resources statement (iteration 2)
B: closed
A: closed
Apart from the closing happening in a different order (we will look into it later) both examples produce an equivalent output.
So now what?
Two resources: error on creation
Let's modify our Resource
class to simulate an error on creation. As mentioned earlier, thinking the class as a FileWriter
, this could be caused by specifying a location for which we do not have writing permission:
public static Resource throwOnCreate(String name) throws IOException {
throw new IOException("Failed to create: " + name);
}
And we use it with the plain try
statement:
public class Try {
// Please avoid code like this in production
public static void main(String[] args) throws IOException {
var a = Resource.create("A");
var b = Resource.throwOnCreate("B");
try {
a.write("Try statement (iteration 3)");
b.write("Try statement (iteration 3)");
} finally {
b.close();
a.close();
}
}
}
Notice we reversed the order of the close statements.
Once again, this example still contain warning signs (in particular in the finally
block) which will discuss as we go.
Running this example prints:
A: created
Exception in thread "main" java.io.IOException: Failed to create: B
at shared.Resource.throwOnCreate(Resource.java:29)
at iter3.Try.main(Try.java:14)
Resource A
was created but it was never closed.
On the other hand, the same example using the try-with-resources
statement:
public class TryWithResources {
public static void main(String[] args) throws IOException {
try (var a = Resource.create("A"); var b = Resource.throwOnCreate("B")) {
a.write("Try-with-resources statement (iteration 3)");
b.write("Try-with-resources statement (iteration 3)");
}
}
}
Prints:
A: created
A: closed
Exception in thread "main" java.io.IOException: Failed to create: B
at shared.Resource.throwOnCreate(Resource.java:29)
at iter3.TryWithResources.main(TryWithResources.java:13)
Resource A
was created and was properly closed.
Two resources: error on closing
Let's modify our Resource
class once again to simulate an error when executing the close
method.
This can happen when using a buffered writer. During the close operation, flushing the buffer to the filesystem will fail if the disk runs out of space.
So we create a subclass that throws in the close
method:
private static class ThrowOnClose extends Resource {
ThrowOnClose(String name) {
super(name);
}
@Override
public void close() throws IOException {
print0("close() called");
throw new IOException("Failed to close: " + name);
}
}
And our create
method for this class is named throwOnClose
:
public static Resource throwOnClose(String name) throws IOException {
return new ThrowOnClose(name);
}
Let's use it in the plain try
case. We will have the B
resource to throw on the close operation:
public class Try {
// Please avoid code like this in production
public static void main(String[] args) throws IOException {
var a = Resource.create("A");
var b = Resource.throwOnClose("B");
try {
a.write("Try statement (iteration 4)");
b.write("Try statement (iteration 4)");
} finally {
b.close();
a.close();
}
}
}
Running this example results in:
A: created
B: created
A: Try statement (iteration 4)
B: Try statement (iteration 4)
B: close() called
Exception in thread "main" java.io.IOException: Failed to close: B
at shared.Resource$ThrowOnClose.close(Resource.java:54)
at iter4.Try.main(Try.java:20)
And the resource A
was not closed.
Let's write the same example using the try-with-resources
statement:
public class TryWithResources {
public static void main(String[] args) throws IOException {
try (var a = Resource.create("A"); var b = Resource.throwOnClose("B")) {
a.write("Try-with-resources statement (iteration 4)");
b.write("Try-with-resources statement (iteration 4)");
}
}
}
Which gives:
A: created
B: created
A: Try-with-resources statement (iteration 4)
B: Try-with-resources statement (iteration 4)
B: close() called
A: closed
Exception in thread "main" java.io.IOException: Failed to close: B
at shared.Resource$ThrowOnClose.close(Resource.java:54)
at iter4.TryWithResources.main(TryWithResources.java:16)
Resource A
was properly closed.
Two resources: exception during the try
block
We mentioned earlier that, so far, we were not actually doing any error handling. In other words, we were not declaring the catch
part of our statement.
Granted, in our example, I am not sure we can do much. Except maybe:
- give a proper message to the user (as opposed to a stack trace); and
- stop the execution normally (as opposed to abruptly by an uncaught exception).
The try
example was refactored to:
public class Try {
// Please avoid code like this in production
public static void main(String[] args) throws IOException {
Resource a = null;
Resource b = null;
try {
a = Resource.create("A");
a.throwOnWrite("Try statement (iteration 5)");
b = Resource.create("B");
b.write("Try statement (iteration 5)");
} catch (IOException e) {
System.err.println("The program failed: " + e.getMessage());
return; // explicitly stop execution
} finally {
b.close();
a.close();
}
System.out.println("More instructions...");
}
}
Notice that, on the A
resource, we invoked a throwOnWrite
method.
It is a method to simulate an IOException
during a write
operation:
public void throwOnWrite(String s) throws IOException {
throw new IOException("Failed to write: " + name);
}
Running the example:
A: created
The program failed: Failed to write: A
Exception in thread "main" java.lang.NullPointerException: Cannot invoke "shared.Resource.close()" because "b" is null
at iter5.Try.main(Try.java:27)
The A
resource does not get closed. To make matters worse, the program additionally exits abruptly with an uncaught exception: a NullPointerException
occurred when trying to close the B
resource.
The reason it happens is that the B
resource is never created as the A
resource throws before B
can be created. And we deliberately did not include a null-check before closing the resource.
Let's write the same example using the try-with-resources
statement:
public class TryWithResources {
public static void main(String[] args) throws IOException {
try (var a = Resource.create("A"); var b = Resource.create("B")) {
a.throwOnWrite("Try-with-resources statement (iteration 5)");
b.write("Try-with-resources statement (iteration 5)");
} catch (IOException e) {
System.err.println("The program failed: " + e.getMessage());
return; // explicitly stop execution
}
System.out.println("More instructions...");
}
}
Results:
A: created
B: created
B: closed
A: closed
The program failed: Failed to write: A
Both resources are properly closed and the program exits normally.
I am sure that, if we kept looking, we would find more issues. But this should do it for now.
Let's now see what's in a try-with-resources
statement.
What's in a try-with-resources
statement?
So what is in a try-with-resources
statement? Meaning can we rewrite it using the plain try
statement?
The answer is yes. In fact that is what the Java compiler does. Others have written about it, so I will not here. For example:
- Heinz Kabutz writes about it here
- there is also this StackOverflow answer
Here I will do something slightly different. Before we go into it, let's first look what the specification says.
Java Language Specification (JLS) 18
At time of writing, Java 18 is the current release of the language. The try-with-resources
statement is in section 14.20.3 of the Java language specification. In the first paragraph we read (emphasis mine):
A try-with-resources statement is parameterized with variables (known as resources) that are initialized before execution of the try block and closed automatically, in the reverse order from which they were initialized
So this explains why we had to reverse the order of the close operations in the previous section.
In section 14.20.3.1 we find the specification of the code the compiler must emit:
{
final {VariableModifierNoFinal} R Identifier = Expression;
Throwable #primaryExc = null;
try ResourceSpecification_tail
Block
catch (Throwable #t) {
#primaryExc = #t;
throw #t;
} finally {
if (Identifier != null) {
if (#primaryExc != null) {
try {
Identifier.close();
} catch (Throwable #suppressedExc) {
#primaryExc.addSuppressed(#suppressedExc);
}
} else {
Identifier.close();
}
}
}
}
The specification is recursive on ResourceSpecification_tail
when more than one resource is declared. In other words, when two resources are declared, there will be a second try
nested in this try
. When three resources are declared, there will be a third try
nested in the second one. And so on.
We are not trying to write a Java compiler. We just want to understand what happens when a try-with-resources
statement is executed.
So, can we write a version of this code in such ways that:
- produces the same effect, that is, "does the same job"; and
- is more readable by a Java developer (as opposed to being readable by a JVM)?
Let's give it a try.
A closing utility
A good initial refactoring candidate is the code in the finally
block. This block:
- closes the resource in a
null
safe way; and - handles the exception that can be thrown during the
close
operation.
Let's extract it to a utility class and rewrite slightly:
public final class Close {
public static Throwable ifPossible(Throwable t, AutoCloseable c) {
var res = t;
if (c != null) {
try {
c.close();
} catch (Throwable e) {
if (res == null) {
res = e;
} else {
res.addSuppressed(e);
}
}
}
return res;
}
}
First there is a null
check on the AutoCloseable
instance. It is there so the NullPointerException
we faced in the "Two resources: exception during the try
block" example does not happen.
Next the resource is closed in a try-catch
statement. The try-catch
is necessary as the close()
operation might throw:
- the
Exception
it declares itthrows
; - a
RuntimeException
. For example, aNullPointerException
from a programming error; - an
Error
. For example, aStackOverflowError
from a programming error.
We saw what happens if we don't catch this throwable in the "Two resources: error on closing" example.
In the catch
block we check if there was a previous exception. This would typically be the exception caught in the main try
block. In our examples this would be the one thrown while trying to write to the resource.
Now, if there were such exception it would be a distinct exception than the one thrown during a close operation. By this I mean that, even though in this particular case they might have some relation (both were thrown by the same instance), they do not share a cause effect. In other words, one should not be declared as the cause of the other.
On the other hand, it would be unwise to simply ignore one exception or the other.
Suppressed exception
So that the closing exception is not ignored, Java 7 introduced the concept of suppressed exceptions.
The exception thrown during the close operation is added as a suppressed exception of the previous exception if the latter exists.
If there was no previous exception then the exception thrown during the close operation is simply returned by our utility and it becomes our primary exception.
Rewriting our two resources try
examples
Let's use our new utility class by rewriting the two resources examples.
A happy path examples becomes:
public class Try {
public static void main(String[] args) {
Throwable rethrow = null;
Resource a = null;
Resource b = null;
try {
a = Resource.create("A");
b = Resource.create("B");
a.write("Try statement (iteration 6)");
b.write("Try statement (iteration 6)");
} catch (Throwable e) {
rethrow = e;
} finally {
rethrow = Close.ifPossible(rethrow, b);
rethrow = Close.ifPossible(rethrow, a);
}
if (rethrow != null) {
System.err.println("The program failed: " + rethrow.getMessage());
return; // explicitly stop execution
}
System.out.println("More instructions...");
}
}
The general recipe is:
- begin with a
null
throwable local variable namedrethrow
- declare all your resources initialized will
null
- at the start of the
try
block, create all your resources - do your work
- declare a single catch-all
catch
block - simply assign the caught throwable to the
rethrow
variable - in the
finally
block, using our utility and in the reverse order of the resource creation close all of the resources - if any error occurred, either in the
try
block or in thefinally
block, therethrow
variable will berethrow != null
. Handle the error appropriately - if no errors occurred, continue the execution
Running this program results in:
A: created
B: created
A: Try statement (iteration 6)
B: Try statement (iteration 6)
B: closed
A: closed
More instructions...
Which is equivalent to the output of the following try-with-resources
version:
public class TryWithResources {
public static void main(String[] args) {
try (var a = Resource.create("A"); var b = Resource.create("B")) {
a.write("Try-with-resources statement (iteration 6)");
b.write("Try-with-resources statement (iteration 6)");
} catch (Throwable e) {
System.err.println("The program failed: " + e.getMessage());
return; // explicitly stop execution
}
System.out.println("More instructions...");
}
}
Both versions are equivalent in the sense that both "do the same job". They are not "bytecode equivalent" however.
The try-with-resources
version:
- is more concise;
- the closing happens automatically; and
- the resource variable is scoped to the statement itself.
Additionally, the plain try
statement version is error-prone:
- a good indicator is the fact that the recipe we wrote has nine steps in it.
The remaining examples can be found in the GitHub repo.
Restricting the catch-all to catch IOException
only
Did you notice that, in the previous try-with-resources
example, we used a catch-all catch
clause?
Meaning that we declared it to catch Throwable
and not IOException
which is the only checked exception declared to be thrown in the statement:
- by the
create
operation; - by the
write
operation; and - by the
close
operation.
If using an IDE it would most likely suggest for the clause to catch an IOException
only and not a Throwable
:
} catch (IOException e) {
System.err.println("The program failed: " + e.getMessage());
return; // explicitly stop execution
}
To make our try
example equivalent our single if
statement after the try
statement would have to be rewritten to:
if (rethrow instanceof RuntimeException re) {
throw re;
}
if (rethrow instanceof Error err) {
throw err;
}
if (rethrow instanceof IOException ioe) {
System.err.println("The program failed: " + ioe.getMessage());
return; // explicitly stop execution
}
Meaning that:
If either a RuntimeException
or an Error
is thrown in either the try
block or during the closing of the resources then the program ends abruptly by an uncaught exception.
If an IOException
is thrown in either the try
block or during the closing of the resources then the program ends normally with the message "The program failed: {exception message}" printed to System.err
.
Suppressed exception example
As a final example, let's see the suppressed exceptions in action:
public class TrySuppressed {
public static void main(String[] args) throws IOException {
Throwable rethrow = null;
Resource a = null;
Resource b = null;
try {
a = Resource.create("A");
b = Resource.throwOnClose("B");
a.throwOnWrite("Try statement (suppressed in action)");
b.write("Try statement (suppressed in action)");
} catch (Throwable e) {
rethrow = e;
} finally {
rethrow = Close.ifPossible(rethrow, b);
rethrow = Close.ifPossible(rethrow, a);
}
if (rethrow != null) {
System.err.println("The program failed: " + rethrow.getMessage());
for (Throwable s : rethrow.getSuppressed()) {
System.err.println("\tsuppressed: " + s.getMessage());
}
return; // explicitly stop execution
}
System.out.println("More instructions...");
}
}
Resource B
is created such as it throws on closing. Resource A
throws during writing.
Running this example gives:
A: created
B: created
B: close() called
A: closed
The program failed: Failed to write: A
suppressed: Failed to close: B
The close
operation was invoked in both resources.
And the close exception thrown by B
was added as a suppressed exception to the exception thrown by A
.
AutoCloseable
Before we go I would like to write a few words on the AutoCloseable
type.
As you can see in its Javadocs
it was introduced in Java 7.
It marks types that are allowed to be used as resources in try-with-resources
statements. It is defined in the try-with-resources
section of the Java language specification:
The type of a local variable declared in a resource specification, or the type of an existing variable referred to in a resource specification, must be a subtype of AutoCloseable, or a compile-time error occurs.
Before its introduction there was no standard interface to indicate that a type had a method that had to be invoked in order for resources to be released. Yes, there was the Closeable
interface introduced in Java 5.
By the way, Closeable
was retrofitted to extend AutoCloseable
.
But not all "things that can be closed" implemented it. For instance:
-
java.util.zip.ZipFile. It had a
close()
method throwingIOException
in Java 6. But it did not implementCloseable
. Compare the javadocs: Java 6 vs. Java 7 -
java.sql.Connection, java.sql.Statement and java.sql.ResultSet. All had a
close()
method throwingSQLException
in Java 6. But they did not implement a common interface. In Java 7 they all implementedAutoCloseable
. Compare the javadocs for theStatement
interface: Java 6 vs. Java 7
Conclusion
In this blog post we took a in-depth look in the try-with-resources
Java statement.
We saw problems that can arise from the plain try
statement when dealing with resources that must be closed programmatically. With this we wanted to understand what issues the try-with-resources
was meant to address.
We then presented its formal definition in the Java language specification. We tried to understand it by rewriting it using the plain try
statement and a small closing utility. In the process we saw two API changes introduced in Java 7 to support it:
- suppressed exceptions
- the
AutoCloseable
interface
Finally we saw some examples of JDK classes that were modified so they could be used with the try-with-resources
statement.
The full source code of the examples listed in this post can be found in this GitHub repository.
Top comments (2)
Good article.
Could be great to mention that, it's possible to declare a
try-with-res
variable asnull
, and it's exception-free whentry(){}
is finished(no null pointer exception on callingclose()
later).Same good to mention,
try-with-res
declarations are kind offinal
, so they won't be assigned inside the block later. Example:Another fact is an
AutoCloseable
declaration could point out to an existing object, rather anew
one. Like followingAnd an important note is about, JVM doesn't keep track of
AutoCloseable.close()
calls, so if anAutoCloseable
object is referenced more than once in one(or many. either nested, or standalone)try(){}
blocks, theclose()
func will be called multiple times(as many as referenced). So this is User's duty to take care of object state.Example:
Thanks! I am glad you liked the article.
I didn't know about the
null
resource. Thanks, TIL.It makes sense it doesn't throw a NPE. In the "Java Language Specification (JLS) 18" section of the article, there's a null-check inside the
finally
block of the specification.You're right, any declared resource variable in the statement is implicitly
final
. I did not think of mentioning it and, I agree, it would have been nice if I did.Regarding JEP 213, which allows pointing to a new object (effectively final), I learned about it only after I wrote the original article! JEP 213 was introduced in Java 9. In fact, you can write your example simply as: