All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.common.io.Closer Maven / Gradle / Ivy

Go to download

Guava is a suite of core and expanded libraries that include utility classes, google's collections, io classes, and much much more.

There is a newer version: 33.3.0-jre
Show newest version
/*
 * Copyright (C) 2012 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package com.google.common.io;

import static com.google.common.base.Preconditions.checkNotNull;

import com.google.common.annotations.GwtIncompatible;
import com.google.common.annotations.J2ktIncompatible;
import com.google.common.annotations.VisibleForTesting;
import com.google.common.base.Throwables;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import java.io.Closeable;
import java.io.IOException;
import java.lang.reflect.Method;
import java.util.ArrayDeque;
import java.util.Deque;
import java.util.logging.Level;
import javax.annotation.CheckForNull;
import org.checkerframework.checker.nullness.qual.Nullable;

/**
 * A {@link Closeable} that collects {@code Closeable} resources and closes them all when it is
 * {@linkplain #close 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: * *

{@code
 * 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 {@code * close()}). * *

This pattern ensures the following: * *

    *
  • Each {@code Closeable} resource that is successfully registered will be closed later. *
  • If a {@code 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 {@code Throwable.addSuppressed(Throwable)}. *
  • Java 6: Exceptions are suppressed by logging them instead. *
* * @author Colin Decker * @since 14.0 */ // Coffee's for {@link Closer closers} only. @J2ktIncompatible @GwtIncompatible @ElementTypesAreNonnullByDefault public final class Closer implements Closeable { /** The suppressor implementation to use for the current Java version. */ private static final Suppressor SUPPRESSOR; static { SuppressingSuppressor suppressingSuppressor = SuppressingSuppressor.tryCreate(); SUPPRESSOR = suppressingSuppressor == null ? LoggingSuppressor.INSTANCE : suppressingSuppressor; } /** Creates a new {@link Closer}. */ public static Closer create() { return new Closer(SUPPRESSOR); } @VisibleForTesting final Suppressor suppressor; // only need space for 2 elements in most cases, so try to use the smallest array possible private final Deque stack = new ArrayDeque<>(4); @CheckForNull private Throwable thrown; @VisibleForTesting Closer(Suppressor suppressor) { this.suppressor = checkNotNull(suppressor); // checkNotNull to satisfy null tests } /** * Registers the given {@code closeable} to be closed when this {@code Closer} is {@linkplain * #close closed}. * * @return the given {@code closeable} */ // close. this word no longer has any meaning to me. @CanIgnoreReturnValue @ParametricNullness public C register(@ParametricNullness C closeable) { if (closeable != null) { stack.addFirst(closeable); } return closeable; } /** * Stores the given throwable and rethrows it. It will be rethrown as is if it is an {@code * IOException}, {@code RuntimeException} or {@code Error}. Otherwise, it will be rethrown wrapped * in a {@code 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 {@code throw closer.rethrow(e);} * to ensure the compiler knows that it will throw. * * @return this method does not return; it always throws * @throws IOException when the given throwable is an IOException */ public RuntimeException rethrow(Throwable e) throws IOException { checkNotNull(e); thrown = e; Throwables.propagateIfPossible(e, IOException.class); throw new RuntimeException(e); } /** * Stores the given throwable and rethrows it. It will be rethrown as is if it is an {@code * IOException}, {@code RuntimeException}, {@code Error} or a checked exception of the given type. * Otherwise, it will be rethrown wrapped in a {@code 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 {@code throw closer.rethrow(e, * ...);} to ensure the compiler knows that it will throw. * * @return this method does not return; it always throws * @throws IOException when the given throwable is an IOException * @throws X when the given throwable is of the declared type X */ public RuntimeException rethrow(Throwable e, Class declaredType) throws IOException, X { checkNotNull(e); thrown = e; Throwables.propagateIfPossible(e, IOException.class); Throwables.propagateIfPossible(e, declaredType); throw new RuntimeException(e); } /** * Stores the given throwable and rethrows it. It will be rethrown as is if it is an {@code * IOException}, {@code RuntimeException}, {@code Error} or a checked exception of either of the * given types. Otherwise, it will be rethrown wrapped in a {@code 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 {@code throw closer.rethrow(e, * ...);} to ensure the compiler knows that it will throw. * * @return this method does not return; it always throws * @throws IOException when the given throwable is an IOException * @throws X1 when the given throwable is of the declared type X1 * @throws X2 when the given throwable is of the declared type X2 */ public RuntimeException rethrow( Throwable e, Class declaredType1, Class declaredType2) throws IOException, X1, X2 { checkNotNull(e); thrown = e; Throwables.propagateIfPossible(e, IOException.class); Throwables.propagateIfPossible(e, declaredType1, declaredType2); throw new RuntimeException(e); } /** * Closes all {@code Closeable} instances that have been added to this {@code Closer}. If an * exception was thrown in the try block and passed to one of the {@code 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. */ @Override public void close() throws IOException { Throwable throwable = thrown; // close closeables in LIFO order while (!stack.isEmpty()) { Closeable closeable = stack.removeFirst(); try { closeable.close(); } catch (Throwable e) { if (throwable == null) { throwable = e; } else { suppressor.suppress(closeable, throwable, e); } } } if (thrown == null && throwable != null) { Throwables.propagateIfPossible(throwable, IOException.class); throw new AssertionError(throwable); // not possible } } /** Suppression strategy interface. */ @VisibleForTesting interface Suppressor { /** * Suppresses the given exception ({@code suppressed}) which was thrown when attempting to close * the given closeable. {@code thrown} is the exception that is actually being thrown from the * method. Implementations of this method should not throw under any circumstances. */ void suppress(Closeable closeable, Throwable thrown, Throwable suppressed); } /** Suppresses exceptions by logging them. */ @VisibleForTesting static final class LoggingSuppressor implements Suppressor { static final LoggingSuppressor INSTANCE = new LoggingSuppressor(); @Override public void suppress(Closeable closeable, Throwable thrown, Throwable suppressed) { // log to the same place as Closeables Closeables.logger.log( Level.WARNING, "Suppressing exception thrown when closing " + closeable, suppressed); } } /** * Suppresses exceptions by adding them to the exception that will be thrown using JDK7's * addSuppressed(Throwable) mechanism. */ @VisibleForTesting static final class SuppressingSuppressor implements Suppressor { @CheckForNull static SuppressingSuppressor tryCreate() { Method addSuppressed; try { addSuppressed = Throwable.class.getMethod("addSuppressed", Throwable.class); } catch (Throwable e) { return null; } return new SuppressingSuppressor(addSuppressed); } private final Method addSuppressed; private SuppressingSuppressor(Method addSuppressed) { this.addSuppressed = addSuppressed; } @Override public void suppress(Closeable closeable, Throwable thrown, Throwable suppressed) { // ensure no exceptions from addSuppressed if (thrown == suppressed) { return; } try { addSuppressed.invoke(thrown, suppressed); } catch (Throwable e) { // if, somehow, IllegalAccessException or another exception is thrown, fall back to logging LoggingSuppressor.INSTANCE.suppress(closeable, thrown, suppressed); } } } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy