001/*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.io;
016
017import com.google.common.annotations.Beta;
018import com.google.common.annotations.GwtIncompatible;
019import com.google.common.annotations.VisibleForTesting;
020import java.io.Closeable;
021import java.io.IOException;
022import java.io.InputStream;
023import java.io.Reader;
024import java.util.logging.Level;
025import java.util.logging.Logger;
026import javax.annotation.CheckForNull;
027
028/**
029 * Utility methods for working with {@link Closeable} objects.
030 *
031 * @author Michael Lancaster
032 * @since 1.0
033 */
034@Beta
035@GwtIncompatible
036@ElementTypesAreNonnullByDefault
037public final class Closeables {
038  @VisibleForTesting static final Logger logger = Logger.getLogger(Closeables.class.getName());
039
040  private Closeables() {}
041
042  /**
043   * Closes a {@link Closeable}, with control over whether an {@code IOException} may be thrown.
044   * This is primarily useful in a finally block, where a thrown exception needs to be logged but
045   * not propagated (otherwise the original exception will be lost).
046   *
047   * <p>If {@code swallowIOException} is true then we never throw {@code IOException} but merely log
048   * it.
049   *
050   * <p>Example:
051   *
052   * <pre>{@code
053   * public void useStreamNicely() throws IOException {
054   *   SomeStream stream = new SomeStream("foo");
055   *   boolean threw = true;
056   *   try {
057   *     // ... code which does something with the stream ...
058   *     threw = false;
059   *   } finally {
060   *     // If an exception occurs, rethrow it only if threw==false:
061   *     Closeables.close(stream, threw);
062   *   }
063   * }
064   * }</pre>
065   *
066   * @param closeable the {@code Closeable} object to be closed, or null, in which case this method
067   *     does nothing
068   * @param swallowIOException if true, don't propagate IO exceptions thrown by the {@code close}
069   *     methods
070   * @throws IOException if {@code swallowIOException} is false and {@code close} throws an {@code
071   *     IOException}.
072   */
073  public static void close(@CheckForNull Closeable closeable, boolean swallowIOException)
074      throws IOException {
075    if (closeable == null) {
076      return;
077    }
078    try {
079      closeable.close();
080    } catch (IOException e) {
081      if (swallowIOException) {
082        logger.log(Level.WARNING, "IOException thrown while closing Closeable.", e);
083      } else {
084        throw e;
085      }
086    }
087  }
088
089  /**
090   * Closes the given {@link InputStream}, logging any {@code IOException} that's thrown rather than
091   * propagating it.
092   *
093   * <p>While it's not safe in the general case to ignore exceptions that are thrown when closing an
094   * I/O resource, it should generally be safe in the case of a resource that's being used only for
095   * reading, such as an {@code InputStream}. Unlike with writable resources, there's no chance that
096   * a failure that occurs when closing the stream indicates a meaningful problem such as a failure
097   * to flush all bytes to the underlying resource.
098   *
099   * @param inputStream the input stream to be closed, or {@code null} in which case this method
100   *     does nothing
101   * @since 17.0
102   */
103  public static void closeQuietly(@CheckForNull InputStream inputStream) {
104    try {
105      close(inputStream, true);
106    } catch (IOException impossible) {
107      throw new AssertionError(impossible);
108    }
109  }
110
111  /**
112   * Closes the given {@link Reader}, logging any {@code IOException} that's thrown rather than
113   * propagating it.
114   *
115   * <p>While it's not safe in the general case to ignore exceptions that are thrown when closing an
116   * I/O resource, it should generally be safe in the case of a resource that's being used only for
117   * reading, such as a {@code Reader}. Unlike with writable resources, there's no chance that a
118   * failure that occurs when closing the reader indicates a meaningful problem such as a failure to
119   * flush all bytes to the underlying resource.
120   *
121   * @param reader the reader to be closed, or {@code null} in which case this method does nothing
122   * @since 17.0
123   */
124  public static void closeQuietly(@CheckForNull Reader reader) {
125    try {
126      close(reader, true);
127    } catch (IOException impossible) {
128      throw new AssertionError(impossible);
129    }
130  }
131}