1/*
2 * Copyright (C) 2012 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.google.common.io;
18
19import static com.google.common.base.Preconditions.checkNotNull;
20
21import com.google.common.annotations.Beta;
22import com.google.common.annotations.VisibleForTesting;
23import com.google.common.base.Throwables;
24
25import java.io.Closeable;
26import java.io.IOException;
27import java.lang.reflect.Method;
28import java.util.ArrayDeque;
29import java.util.Deque;
30import java.util.logging.Level;
31
32import javax.annotation.Nullable;
33
34/**
35 * A {@link Closeable} that collects {@code Closeable} resources and closes them all when it is
36 * {@linkplain #close closed}. This is intended to approximately emulate the behavior of Java 7's
37 * <a href="http://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html">
38 * try-with-resources</a> statement in JDK6-compatible code. Running on Java 7, code using this
39 * should be approximately equivalent in behavior to the same code written with try-with-resources.
40 * Running on Java 6, exceptions that cannot be thrown must be logged rather than being added to the
41 * thrown exception as a suppressed exception.
42 *
43 * <p>This class is intended to be used in the following pattern:
44 *
45 * <pre>   {@code
46 *   Closer closer = Closer.create();
47 *   try {
48 *     InputStream in = closer.register(openInputStream());
49 *     OutputStream out = closer.register(openOutputStream());
50 *     // do stuff
51 *   } catch (Throwable e) {
52 *     // ensure that any checked exception types other than IOException that could be thrown are
53 *     // provided here, e.g. throw closer.rethrow(e, CheckedException.class);
54 *     throw closer.rethrow(e);
55 *   } finally {
56 *     closer.close();
57 *   }}</pre>
58 *
59 * <p>Note that this try-catch-finally block is not equivalent to a try-catch-finally block using
60 * try-with-resources. To get the equivalent of that, you must wrap the above code in <i>another</i>
61 * try block in order to catch any exception that may be thrown (including from the call to
62 * {@code close()}).
63 *
64 * <p>This pattern ensures the following:
65 *
66 * <ul>
67 *   <li>Each {@code Closeable} resource that is successfully registered will be closed later.</li>
68 *   <li>If a {@code Throwable} is thrown in the try block, no exceptions that occur when attempting
69 *   to close resources will be thrown from the finally block. The throwable from the try block will
70 *   be thrown.</li>
71 *   <li>If no exceptions or errors were thrown in the try block, the <i>first</i> exception thrown
72 *   by an attempt to close a resource will be thrown.</li>
73 *   <li>Any exception caught when attempting to close a resource that is <i>not</i> thrown
74 *   (because another exception is already being thrown) is <i>suppressed</i>.</li>
75 * </ul>
76 *
77 * <p>An exception that is suppressed is not thrown. The method of suppression used depends on the
78 * version of Java the code is running on:
79 *
80 * <ul>
81 *   <li><b>Java 7+:</b> Exceptions are suppressed by adding them to the exception that <i>will</i>
82 *   be thrown using {@code Throwable.addSuppressed(Throwable)}.</li>
83 *   <li><b>Java 6:</b> Exceptions are suppressed by logging them instead.</li>
84 * </ul>
85 *
86 * @author Colin Decker
87 * @since 14.0
88 */
89// Coffee's for {@link Closer closers} only.
90@Beta
91public final class Closer implements Closeable {
92
93  /**
94   * The suppressor implementation to use for the current Java version.
95   */
96  private static final Suppressor SUPPRESSOR = SuppressingSuppressor.isAvailable()
97      ? SuppressingSuppressor.INSTANCE
98      : LoggingSuppressor.INSTANCE;
99
100  /**
101   * Creates a new {@link Closer}.
102   */
103  public static Closer create() {
104    return new Closer(SUPPRESSOR);
105  }
106
107  @VisibleForTesting final Suppressor suppressor;
108
109  // only need space for 2 elements in most cases, so try to use the smallest array possible
110  private final Deque<Closeable> stack = new ArrayDeque<Closeable>(4);
111  private Throwable thrown;
112
113  @VisibleForTesting Closer(Suppressor suppressor) {
114    this.suppressor = checkNotNull(suppressor); // checkNotNull to satisfy null tests
115  }
116
117  /**
118   * Registers the given {@code closeable} to be closed when this {@code Closer} is
119   * {@linkplain #close closed}.
120   *
121   * @return the given {@code closeable}
122   */
123  // close. this word no longer has any meaning to me.
124  public <C extends Closeable> C register(@Nullable C closeable) {
125    if (closeable != null) {
126      stack.addFirst(closeable);
127    }
128
129    return closeable;
130  }
131
132  /**
133   * Stores the given throwable and rethrows it. It will be rethrown as is if it is an
134   * {@code IOException}, {@code RuntimeException} or {@code Error}. Otherwise, it will be rethrown
135   * wrapped in a {@code RuntimeException}. <b>Note:</b> Be sure to declare all of the checked
136   * exception types your try block can throw when calling an overload of this method so as to avoid
137   * losing the original exception type.
138   *
139   * <p>This method always throws, and as such should be called as
140   * {@code throw closer.rethrow(e);} to ensure the compiler knows that it will throw.
141   *
142   * @return this method does not return; it always throws
143   * @throws IOException when the given throwable is an IOException
144   */
145  public RuntimeException rethrow(Throwable e) throws IOException {
146    checkNotNull(e);
147    thrown = e;
148    Throwables.propagateIfPossible(e, IOException.class);
149    throw new RuntimeException(e);
150  }
151
152  /**
153   * Stores the given throwable and rethrows it. It will be rethrown as is if it is an
154   * {@code IOException}, {@code RuntimeException}, {@code Error} or a checked exception of the
155   * given type. Otherwise, it will be rethrown wrapped in a {@code RuntimeException}. <b>Note:</b>
156   * Be sure to declare all of the checked exception types your try block can throw when calling an
157   * overload of this method so as to avoid losing the original exception type.
158   *
159   * <p>This method always throws, and as such should be called as
160   * {@code throw closer.rethrow(e, ...);} to ensure the compiler knows that it will throw.
161   *
162   * @return this method does not return; it always throws
163   * @throws IOException when the given throwable is an IOException
164   * @throws X when the given throwable is of the declared type X
165   */
166  public <X extends Exception> RuntimeException rethrow(Throwable e,
167      Class<X> declaredType) throws IOException, X {
168    checkNotNull(e);
169    thrown = e;
170    Throwables.propagateIfPossible(e, IOException.class);
171    Throwables.propagateIfPossible(e, declaredType);
172    throw new RuntimeException(e);
173  }
174
175  /**
176   * Stores the given throwable and rethrows it. It will be rethrown as is if it is an
177   * {@code IOException}, {@code RuntimeException}, {@code Error} or a checked exception of either
178   * of the given types. Otherwise, it will be rethrown wrapped in a {@code RuntimeException}.
179   * <b>Note:</b> Be sure to declare all of the checked exception types your try block can throw
180   * when calling an overload of this method so as to avoid losing the original exception type.
181   *
182   * <p>This method always throws, and as such should be called as
183   * {@code throw closer.rethrow(e, ...);} to ensure the compiler knows that it will throw.
184   *
185   * @return this method does not return; it always throws
186   * @throws IOException when the given throwable is an IOException
187   * @throws X1 when the given throwable is of the declared type X1
188   * @throws X2 when the given throwable is of the declared type X2
189   */
190  public <X1 extends Exception, X2 extends Exception> RuntimeException rethrow(
191      Throwable e, Class<X1> declaredType1, Class<X2> declaredType2) throws IOException, X1, X2 {
192    checkNotNull(e);
193    thrown = e;
194    Throwables.propagateIfPossible(e, IOException.class);
195    Throwables.propagateIfPossible(e, declaredType1, declaredType2);
196    throw new RuntimeException(e);
197  }
198
199  /**
200   * Closes all {@code Closeable} instances that have been added to this {@code Closer}. If an
201   * exception was thrown in the try block and passed to one of the {@code exceptionThrown} methods,
202   * any exceptions thrown when attempting to close a closeable will be suppressed. Otherwise, the
203   * <i>first</i> exception to be thrown from an attempt to close a closeable will be thrown and any
204   * additional exceptions that are thrown after that will be suppressed.
205   */
206  @Override
207  public void close() throws IOException {
208    Throwable throwable = thrown;
209
210    // close closeables in LIFO order
211    while (!stack.isEmpty()) {
212      Closeable closeable = stack.removeFirst();
213      try {
214        closeable.close();
215      } catch (Throwable e) {
216        if (throwable == null) {
217          throwable = e;
218        } else {
219          suppressor.suppress(closeable, throwable, e);
220        }
221      }
222    }
223
224    if (thrown == null && throwable != null) {
225      Throwables.propagateIfPossible(throwable, IOException.class);
226      throw new AssertionError(throwable); // not possible
227    }
228  }
229
230  /**
231   * Suppression strategy interface.
232   */
233  @VisibleForTesting interface Suppressor {
234    /**
235     * Suppresses the given exception ({@code suppressed}) which was thrown when attempting to close
236     * the given closeable. {@code thrown} is the exception that is actually being thrown from the
237     * method. Implementations of this method should not throw under any circumstances.
238     */
239    void suppress(Closeable closeable, Throwable thrown, Throwable suppressed);
240  }
241
242  /**
243   * Suppresses exceptions by logging them.
244   */
245  @VisibleForTesting static final class LoggingSuppressor implements Suppressor {
246
247    static final LoggingSuppressor INSTANCE = new LoggingSuppressor();
248
249    @Override
250    public void suppress(Closeable closeable, Throwable thrown, Throwable suppressed) {
251      // log to the same place as Closeables
252      Closeables.logger.log(Level.WARNING,
253          "Suppressing exception thrown when closing " + closeable, suppressed);
254    }
255  }
256
257  /**
258   * Suppresses exceptions by adding them to the exception that will be thrown using JDK7's
259   * addSuppressed(Throwable) mechanism.
260   */
261  @VisibleForTesting static final class SuppressingSuppressor implements Suppressor {
262
263    static final SuppressingSuppressor INSTANCE = new SuppressingSuppressor();
264
265    static boolean isAvailable() {
266      return addSuppressed != null;
267    }
268
269    static final Method addSuppressed = getAddSuppressed();
270
271    private static Method getAddSuppressed() {
272      try {
273        return Throwable.class.getMethod("addSuppressed", Throwable.class);
274      } catch (Throwable e) {
275        return null;
276      }
277    }
278
279    @Override
280    public void suppress(Closeable closeable, Throwable thrown, Throwable suppressed) {
281      // ensure no exceptions from addSuppressed
282      if (thrown == suppressed) {
283        return;
284      }
285      try {
286        addSuppressed.invoke(thrown, suppressed);
287      } catch (Throwable e) {
288        // if, somehow, IllegalAccessException or another exception is thrown, fall back to logging
289        LoggingSuppressor.INSTANCE.suppress(closeable, thrown, suppressed);
290      }
291    }
292  }
293}
294