A Closeable that collects Closeable resources and closes them all when it is closed. This is intended to approximately emulate the behavior of Java 7's try-with-resources statement in JDK6-compatible code. Running on Java 7, code using this should be approximately equivalent in behavior to the same code written with try-with-resources. Running on Java 6, exceptions that cannot be thrown must be logged rather than being added to the thrown exception as a suppressed exception.

This class is intended to be used in the following pattern:

Closer closer = Closer.create();
try {
  InputStream in = closer.register(openInputStream());
  OutputStream out = closer.register(openOutputStream());
  // do stuff
} catch (Throwable e) {
  // ensure that any checked exception types other than IOException that could be thrown are
  // provided here, e.g. throw closer.rethrow(e, CheckedException.class);
  throw closer.rethrow(e);
} finally {
  closer.close();
}

Note that this try-catch-finally block is not equivalent to a try-catch-finally block using try-with-resources. To get the equivalent of that, you must wrap the above code in another try block in order to catch any exception that may be thrown (including from the call to close()).

This pattern ensures the following:

Each Closeable resource that is successfully registered will be closed later.
If a Throwable is thrown in the try block, no exceptions that occur when attempting to close resources will be thrown from the finally block. The throwable from the try block will be thrown.
If no exceptions or errors were thrown in the try block, the first exception thrown by an attempt to close a resource will be thrown.
Any exception caught when attempting to close a resource that is not thrown (because another exception is already being thrown) is suppressed.

An exception that is suppressed is not thrown. The method of suppression used depends on the version of Java the code is running on:

Java 7+: Exceptions are suppressed by adding them to the exception that will be thrown using Throwable.addSuppressed(Throwable).
Java 6: Exceptions are suppressed by logging them instead.

Modifier and Type	Class and Description
pack-priv static class	Closer.LoggingSuppressor Suppresses exceptions by logging them.
pack-priv static class	Closer.SuppressingSuppressor Suppresses exceptions by adding them to the exception that will be thrown using JDK7's addSuppressed(Throwable) mechanism.
pack-priv static interface	Closer.Suppressor Suppression strategy interface.

Modifier and Type	Field and Description
private final Deque<Closeable>	stack
private static final Closer.Suppressor	SUPPRESSOR The suppressor implementation to use for the current Java version.
pack-priv final Closer.Suppressor	suppressor
private Throwable	thrown

Access	Constructor and Description
pack-priv	Closer(Closer.Suppressor suppressor)

Method Summary

Modifier and Type	Method and Description
public void	close() Implements java.io.Closeable.close. Closes all `Closeable` instances that have been added to this `Closer`.
public static Closer	create() Creates a new `Closer`.
public <C extends @Nullable Closeable> C	Returns: the given `closeable` register(C closeable) Registers the given `closeable` to be closed when this `Closer` is closed.
public RuntimeException	Returns: this method does not return; it always throws rethrow(Throwable e) Stores the given throwable and rethrows it.
public <X extends Exception> RuntimeException	Returns: this method does not return; it always throws rethrow(Throwable e, Class<X> declaredType) Stores the given throwable and rethrows it.
public <X1 extends Exception, X2 extends Exception> RuntimeException	Returns: this method does not return; it always throws rethrow(Throwable e, Class<X1> declaredType1, Class<X2> declaredType2) Stores the given throwable and rethrows it.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

stack	back to summary
private final Deque<Closeable> stack

SUPPRESSOR	back to summary
private static final Closer.Suppressor SUPPRESSOR The suppressor implementation to use for the current Java version.

suppressor	back to summary
pack-priv final Closer.Suppressor suppressor Annotations @VisibleForTesting

thrown	back to summary
private Throwable thrown Annotations @CheckForNull

Constructor Detail

Closer	back to summary
pack-priv Closer(Closer.Suppressor suppressor) Annotations @VisibleForTesting

Method Detail

close back to summary

close	back to summary
public void close() throws IOException Implements java.io.Closeable.close. Closes all `Closeable` instances that have been added to this `Closer`. If an exception was thrown in the try block and passed to one of the `exceptionThrown` methods, any exceptions thrown when attempting to close a closeable will be suppressed. Otherwise, the first exception to be thrown from an attempt to close a closeable will be thrown and any additional exceptions that are thrown after that will be suppressed. Annotations @Override Exceptions IOException: Doc from java.io.Closeable.close. if an I/O error occurs

public void close() throws IOException

Implements java.io.Closeable.close.

Closes all Closeable instances that have been added to this Closer. If an exception was thrown in the try block and passed to one of the exceptionThrown methods, any exceptions thrown when attempting to close a closeable will be suppressed. Otherwise, the first exception to be thrown from an attempt to close a closeable will be thrown and any additional exceptions that are thrown after that will be suppressed.

Annotations

@Override

Exceptions

IOException:

Doc from java.io.Closeable.close.

if an I/O error occurs

create	back to summary
public static Closer create() Creates a new `Closer`.

register	back to summary
public <C extends @Nullable Closeable> C register(C closeable) Registers the given `closeable` to be closed when this `Closer` is closed. Returns:C the given `closeable` Annotations @CanIgnoreReturnValue @ParametricNullness

public <C extends @Nullable Closeable> C register(C closeable)

Registers the given closeable to be closed when this Closer is closed.

Returns:C

the given closeable

Annotations

@CanIgnoreReturnValue
@ParametricNullness

rethrow back to summary

rethrow	back to summary
public RuntimeException rethrow(Throwable e) throws IOException Stores the given throwable and rethrows it. It will be rethrown as is if it is an `IOException`, `RuntimeException` or `Error`. Otherwise, it will be rethrown wrapped in a `RuntimeException` Note Be sure to declare all of the checked exception types your try block can throw when calling an overload of this method so as to avoid losing the original exception type. This method always throws, and as such should be called as `throw closer.rethrow(e);` to ensure the compiler knows that it will throw. Returns:RuntimeException this method does not return; it always throws Exceptions IOException: when the given throwable is an IOException

public RuntimeException rethrow(Throwable e) throws IOException

Stores the given throwable and rethrows it. It will be rethrown as is if it is an IOException, RuntimeException or Error. Otherwise, it will be rethrown wrapped in a RuntimeException

Note

Be sure to declare all of the checked exception types your try block can throw when calling an overload of this method so as to avoid losing the original exception type.

This method always throws, and as such should be called as throw closer.rethrow(e); to ensure the compiler knows that it will throw.

Returns:RuntimeException

this method does not return; it always throws

Exceptions

IOException:: when the given throwable is an IOException

rethrow back to summary

rethrow	back to summary
public <X extends Exception> RuntimeException rethrow(Throwable e, Class<X> declaredType) throws IOException, Class-:X Stores the given throwable and rethrows it. It will be rethrown as is if it is an `IOException`, `RuntimeException`, `Error` or a checked exception of the given type. Otherwise, it will be rethrown wrapped in a `RuntimeException` Note Be sure to declare all of the checked exception types your try block can throw when calling an overload of this method so as to avoid losing the original exception type. This method always throws, and as such should be called as `throw closer.rethrow(e, ...);` to ensure the compiler knows that it will throw. Returns:RuntimeException this method does not return; it always throws Exceptions IOException: when the given throwable is an IOException Class-:X: when the given throwable is of the declared type X

public <X extends Exception> RuntimeException rethrow(Throwable e, Class<X> declaredType) throws IOException, Class-:X

Stores the given throwable and rethrows it. It will be rethrown as is if it is an IOException, RuntimeException, Error or a checked exception of the given type. Otherwise, it will be rethrown wrapped in a RuntimeException

Note

Be sure to declare all of the checked exception types your try block can throw when calling an overload of this method so as to avoid losing the original exception type.

This method always throws, and as such should be called as throw closer.rethrow(e, ...); to ensure the compiler knows that it will throw.

Returns:RuntimeException

this method does not return; it always throws

Exceptions

IOException:: when the given throwable is an IOException
Class-:X:: when the given throwable is of the declared type X

rethrow back to summary

rethrow	back to summary
public <X1 extends Exception, X2 extends Exception> RuntimeException rethrow(Throwable e, Class<X1> declaredType1, Class<X2> declaredType2) throws IOException, Class-:X1, Class-:X2 Stores the given throwable and rethrows it. It will be rethrown as is if it is an `IOException`, `RuntimeException`, `Error` or a checked exception of either of the given types. Otherwise, it will be rethrown wrapped in a `RuntimeException` Note Be sure to declare all of the checked exception types your try block can throw when calling an overload of this method so as to avoid losing the original exception type. This method always throws, and as such should be called as `throw closer.rethrow(e, ...);` to ensure the compiler knows that it will throw. Returns:RuntimeException this method does not return; it always throws Exceptions IOException: when the given throwable is an IOException Class-:X1: when the given throwable is of the declared type X1 Class-:X2: when the given throwable is of the declared type X2

public <X1 extends Exception, X2 extends Exception> RuntimeException rethrow(Throwable e, Class<X1> declaredType1, Class<X2> declaredType2) throws IOException, Class-:X1, Class-:X2

Stores the given throwable and rethrows it. It will be rethrown as is if it is an IOException, RuntimeException, Error or a checked exception of either of the given types. Otherwise, it will be rethrown wrapped in a RuntimeException

Note

Be sure to declare all of the checked exception types your try block can throw when calling an overload of this method so as to avoid losing the original exception type.

This method always throws, and as such should be called as throw closer.rethrow(e, ...); to ensure the compiler knows that it will throw.

Returns:RuntimeException

this method does not return; it always throws

Exceptions

IOException:: when the given throwable is an IOException
Class-:X1:: when the given throwable is of the declared type X1
Class-:X2:: when the given throwable is of the declared type X2

com.google.common.io back to summary

pack-priv final Class Closer.LoggingSuppressor

Class Inheritance

extends Object
implements Suppressor

java.lang.Object
com.google.common.io.Closer.LoggingSuppressor

All Implemented Interfaces

com.google.common.io.Closer.Suppressor

Annotations

@VisibleForTesting

Suppresses exceptions by logging them.

Field Summary

Modifier and Type	Field and Description
pack-priv static final Closer.LoggingSuppressor	INSTANCE

Constructor Summary

Access	Constructor and Description
pack-priv	LoggingSuppressor()

Method Summary

Modifier and Type	Method and Description
public void	suppress(Closeable closeable, Throwable thrown, Throwable suppressed) Implements com.google.common.io.Closer.Suppressor.suppress. Suppresses the given exception (`suppressed`) which was thrown when attempting to close the given closeable.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

INSTANCE	back to summary
pack-priv static final Closer.LoggingSuppressor INSTANCE

Constructor Detail

LoggingSuppressor	back to summary
pack-priv LoggingSuppressor()

Method Detail

suppress back to summary

suppress	back to summary
public void suppress(Closeable closeable, Throwable thrown, Throwable suppressed) Implements com.google.common.io.Closer.Suppressor.suppress. Doc from com.google.common.io.Closer.Suppressor.suppress. Suppresses the given exception (`suppressed`) which was thrown when attempting to close the given closeable. `thrown` is the exception that is actually being thrown from the method. Implementations of this method should not throw under any circumstances. Annotations @Override

public void suppress(Closeable closeable, Throwable thrown, Throwable suppressed)

Implements com.google.common.io.Closer.Suppressor.suppress.

Doc from com.google.common.io.Closer.Suppressor.suppress.

Suppresses the given exception (suppressed) which was thrown when attempting to close the given closeable. thrown is the exception that is actually being thrown from the method. Implementations of this method should not throw under any circumstances.

Annotations

@Override

com.google.common.io back to summary

pack-priv final Class Closer.SuppressingSuppressor

Class Inheritance

extends Object
implements Suppressor

java.lang.Object
com.google.common.io.Closer.SuppressingSuppressor

All Implemented Interfaces

com.google.common.io.Closer.Suppressor

Annotations

@VisibleForTesting

Suppresses exceptions by adding them to the exception that will be thrown using JDK7's addSuppressed(Throwable) mechanism.

Field Summary

Modifier and Type	Field and Description
private final Method	addSuppressed

Constructor Summary

Access	Constructor and Description
private	SuppressingSuppressor(Method addSuppressed)

Method Summary

Modifier and Type	Method and Description
public void	suppress(Closeable closeable, Throwable thrown, Throwable suppressed) Implements com.google.common.io.Closer.Suppressor.suppress. Suppresses the given exception (`suppressed`) which was thrown when attempting to close the given closeable.
pack-priv static Closer.SuppressingSuppressor	tryCreate()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

addSuppressed	back to summary
private final Method addSuppressed

Constructor Detail

SuppressingSuppressor	back to summary
private SuppressingSuppressor(Method addSuppressed)

Method Detail

suppress back to summary

suppress	back to summary
public void suppress(Closeable closeable, Throwable thrown, Throwable suppressed) Implements com.google.common.io.Closer.Suppressor.suppress. Doc from com.google.common.io.Closer.Suppressor.suppress. Suppresses the given exception (`suppressed`) which was thrown when attempting to close the given closeable. `thrown` is the exception that is actually being thrown from the method. Implementations of this method should not throw under any circumstances. Annotations @Override

public void suppress(Closeable closeable, Throwable thrown, Throwable suppressed)

Implements com.google.common.io.Closer.Suppressor.suppress.

Doc from com.google.common.io.Closer.Suppressor.suppress.

Annotations

@Override

tryCreate	back to summary
pack-priv static Closer.SuppressingSuppressor tryCreate() Annotations @CheckForNull

public final Class Closer

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv final Class Closer.LoggingSuppressor

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv final Class Closer.SuppressingSuppressor

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv Interface Closer.Suppressor

Method Summary

Method Detail