EaglerForge/sources/main/java/com/google/common/io/Closer.java

/*
 * 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 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.Nullable;

import com.google.common.annotations.Beta;
import com.google.common.annotations.VisibleForTesting;
import com.google.common.base.Throwables;

/**
 * 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 <a href=
 * "http://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html">
 * try-with-resources</a> 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.
 *
 * <p>
 * This class is intended to be used in the following pattern:
 *
 * <pre>
 * {
 * 	&#64;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();
 * 	}
 * }
 * </pre>
 *
 * <p>
 * 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 <i>another</i> try block in order to
 * catch any exception that may be thrown (including from the call to
 * {@code close()}).
 *
 * <p>
 * This pattern ensures the following:
 *
 * <ul>
 * <li>Each {@code Closeable} resource that is successfully registered will be
 * closed later.</li>
 * <li>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.</li>
 * <li>If no exceptions or errors were thrown in the try block, the <i>first</i>
 * exception thrown by an attempt to close a resource will be thrown.</li>
 * <li>Any exception caught when attempting to close a resource that is
 * <i>not</i> thrown (because another exception is already being thrown) is
 * <i>suppressed</i>.</li>
 * </ul>
 *
 * <p>
 * An exception that is suppressed is not thrown. The method of suppression used
 * depends on the version of Java the code is running on:
 *
 * <ul>
 * <li><b>Java 7+:</b> Exceptions are suppressed by adding them to the exception
 * that <i>will</i> be thrown using
 * {@code Throwable.addSuppressed(Throwable)}.</li>
 * <li><b>Java 6:</b> Exceptions are suppressed by logging them instead.</li>
 * </ul>
 *
 * @author Colin Decker
 * @since 14.0
 */
// Coffee's for {@link Closer closers} only.
@Beta
public final class Closer implements Closeable {

	/**
	 * The suppressor implementation to use for the current Java version.
	 */
	private static final Suppressor SUPPRESSOR = SuppressingSuppressor.isAvailable() ? SuppressingSuppressor.INSTANCE
			: LoggingSuppressor.INSTANCE;

	/**
	 * 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<Closeable> stack = new ArrayDeque<Closeable>(4);
	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.
	public <C extends Closeable> C register(@Nullable 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}.
	 * <b>Note:</b> 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.
	 *
	 * <p>
	 * 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}. <b>Note:</b> 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.
	 *
	 * <p>
	 * 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 <X extends Exception> RuntimeException rethrow(Throwable e, Class<X> 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}. <b>Note:</b> 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.
	 *
	 * <p>
	 * 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 <X1 extends Exception, X2 extends Exception> RuntimeException rethrow(Throwable e, Class<X1> declaredType1,
			Class<X2> 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 <i>first</i>
	 * 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 {

		static final SuppressingSuppressor INSTANCE = new SuppressingSuppressor();

		static boolean isAvailable() {
			return addSuppressed != null;
		}

		static final Method addSuppressed = getAddSuppressed();

		private static Method getAddSuppressed() {
			try {
				return Throwable.class.getMethod("addSuppressed", Throwable.class);
			} catch (Throwable e) {
				return null;
			}
		}

		@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);
			}
		}
	}
}