com.bluecatcode.common.io.Closeables Maven / Gradle / Ivy

package com.bluecatcode.common.io;

import javax.annotation.Nullable;
import javax.annotation.WillClose;
import javax.annotation.WillNotClose;
import java.io.Closeable;
import java.io.IOException;
import java.sql.Blob;
import java.sql.Clob;
import java.sql.Connection;
import java.sql.Statement;

import static com.bluecatcode.common.contract.Impossibles.impossible;
import static com.google.common.io.Closeables.close;

/**
 * Provides {@link Closeable} and {@link AutoCloseable} interfaces for incompatible resources
 * 
 * Enables usage of resources incompatible with Closable interface in contexts
 * where they are required, e.g. Java 7 try-with-resources.
 * 
 * Methods are wrapped with decorators and parameters can safely be null.
 * All decorators have non-throwing null-checks, null values are silently ignored.
 * All checked exceptions are translated to IOException and rethrown.
 */
public class Closeables {

    private Closeables() {
        throw new UnsupportedOperationException("Private constructor");
    }

    /**
     * Provides {@link Closeable} interface for {@link Connection}
     *
     * @param connection the connection to decorate
     * @return a closeable decorated connection
     */
    public static Closeable closeableFrom(@WillNotClose @Nullable final Connection connection) {
        return closeableFrom(connection, Connection::close);
    }

    /**
     * Provides {@link Closeable} interface for {@link Statement}
     *
     * @param statement the statement to decorate
     * @return a closeable decorated statement
     */
    public static Closeable closeableFrom(@WillNotClose @Nullable final Statement statement) {
        return closeableFrom(statement, Statement::close);
    }

    /**
     * Provides {@link Closeable} interface for {@link Clob}
     *
     * @param clob the clob to decorate
     * @return a closeable decorated clob
     */
    public static Closeable closeableFrom(@WillNotClose @Nullable final Clob clob) {
        return closeableFrom(clob, Clob::free);
    }

    /**
     * Provides {@link Closeable} interface for {@link Blob}
     *
     * @param blob the blob to decorate
     * @return a closeable decorated clob
     */
    public static Closeable closeableFrom(@WillNotClose @Nullable final Blob blob) {
        return closeableFrom(blob, Blob::free);
    }

    /**
     * Provides {@link Closeable} interface for {@link T}
     *
     * @param reference the object reference to decorate
     * @param closer    the closer function
     * @param        the closeable reference type
     * @return a closeable decorated clob
     */
    public static  CloseableReference closeableFrom(@WillNotClose @Nullable final T reference, Closer closer) {
        return new CloseableReference<>(reference, closer);
    }

    /**
     * Closes the given {@link Closeable}, logging any {@code IOException} that's thrown rather than
     * propagating it.
     *
     * While it's not safe in the general case to ignore exceptions that are thrown when closing
     * an I/O resource, it should generally be safe in the case of a resource that's being used only
     * for reading, such as a {@code Reader}. Unlike with writable resources, there's no chance that
     * a failure that occurs when closing the reader indicates a meaningful problem such as a failure
     * to flush all bytes to the underlying resource.
     *
     * @param closeable the reader to be closed, or {@code null} in which case this method does nothing
     */
    public static void closeQuietly(@WillClose @Nullable Closeable closeable) {
        try {
            close(closeable, true);
        } catch (IOException impossible) {
            impossible(impossible);
        }
    }
}