IOUtils

package saker.build.thirdparty.saker.util.io

public class IOUtils

saker.build.thirdparty.saker.util.io.IOUtils

java.lang.Object

Utility class containing functions for dealing with I/O related functionality.

The class defines a set of exceptions that are considered to be safe to be caught, which means that the operation will not abort if an exception of the following types are caught:

StackOverflowError: The execution should be able to recover from this.
OutOfMemoryError: The execution should be able to recover from this.
LinkageError: Happens when classes are no longer compatible with each other. This usually means that the runtime classpath is different from the compile classpath. This is usually non recoverable, or hard to do, but is safe to catch, as this doesn't hinder the further operations on different objects.
ServiceConfigurationError: When some service configuration is invalid. This can be caught, as this is a recoverable error that is more like a RuntimeException.
AssertionError: In case some assertion failed. An error of this kind is recoverable, as this doesn't signal a VM error, but only some runtime validation failed in some implementation.
Exception: Generic exception, can be caught.

An exception that is an instance of the above types are considered to be safe, and is referred to such in the documentation of utility functions. As a general rule of thumb, if an operation (e.g. closing) is to be performed on multiple objects, and a safe exception is caught, the operation will continue to execute the action on the remaining elements, and throw the exception after the action was performed on all of the objects.

The term safe errors contain only the Error types from the safe exceptions.

Many of the methods in this class work with AutoCloseable instances, but declare only IOException as its thrown exception types. When an AutoCloseable throws an Exception declared by its AutoCloseable.close() method, it will be wrapped into an IOException, and rethrown as that. As in most cases users work with Closeable types, which throw IOException, this is an acceptable compromise to support AutoCloseable types as well, but have them work like Closeables.

If the above happens for multiple AutoCloseables, only the first caught exception will be wrapped into an IOException, the laters will be added as suppressed exceptions to the first caught exception.

Methods that start with close will call AutoCloseable.close() on the argument object(s). The closing will occur for all argument objects, and any exception caught will be handled according to each method documentation. Using this methods can be useful when multiple closeables need to be closed without having a nested try-finally block in the caller method.

Example:
Instead of closing multiple closeables like this:

 try {
 	closeable1.close();
 } finally {
 	try {
 		closeable2.close();
 	} finally {
 		try {
 			closeable3.close();
 		} finally {
 			closeable4.close();
 		}
 	}
 }

Use:

 IOUtils.close(closeable1, closeable2, closeable3, closeable4);

The latter approach also have the advantage that all the exceptions will be reported as suppressed, or cause exceptions, instead of just the last in the first approach.

The closing methods in this class will silently ignore if the argument collection is null, or any of the closeable object is null.

Methods

public static IOException	addExc(IOException prev, Throwable next) Aggregates two exceptions with an IOException base.
public static <E extends Throwable> E	addExc(E prev, E next) Aggregates two exceptions of the same type.
public static <E extends Throwable, T extends Throwable> E	addExc(E prev, T next, Function<? super T, ? extends E> creator) Aggregates two exceptions of the different type using the specified creator function.
public static void	close(Iterable<? extends AutoCloseable> closeables) Calls AutoCloseable.close() for every object in the argument iterable, and throws any exceptions at the end.
public static void	close(Iterator<? extends AutoCloseable> closeables) Calls AutoCloseable.close() for every object in the argument iterable, and throws any exceptions at the end.
public static void	close(AutoCloseable... closeables) Calls AutoCloseable.close() for every object in the argument iterable, and throws any exceptions at the end.
public static IOException	closeExc(IOException prevexc, Iterable<? extends AutoCloseable> closeables) Calls AutoCloseable.close() for every object in the argument iterable, and aggregates any thrown exception with the previous argument.
public static IOException	closeExc(IOException prevexc, Iterator<? extends AutoCloseable> closeables) Calls AutoCloseable.close() for every object in the argument iterable, and aggregates any thrown exception with the previous argument.
public static IOException	closeExc(IOException prevexc, AutoCloseable... closeables) Calls AutoCloseable.close() for every object in the argument iterable, and aggregates any thrown exception with the previous argument.
public static IOException	closeExc(Iterable<? extends AutoCloseable> closeables) Calls AutoCloseable.close() for every object in the argument iterable, and returns the thrown exception if any.
public static IOException	closeExc(Iterator<? extends AutoCloseable> closeables) Calls AutoCloseable.close() for every object in the argument iterable, and returns the thrown exception if any.
public static IOException	closeExc(AutoCloseable... closeables) Calls AutoCloseable.close() for every object in the argument iterable, and returns the thrown exception if any.
public static void	closeIgnore(Iterable<? extends AutoCloseable> closeables) Calls AutoCloseable.close() for every object in the argument iterable, and ignores the possibly thrown exceptions.
public static void	closeIgnore(Iterator<? extends AutoCloseable> closeables) Calls AutoCloseable.close() for every object in the argument iterable, and ignores the possibly thrown exceptions.
public static void	closeIgnore(AutoCloseable... closeables) Calls AutoCloseable.close() for every object in the argument iterable, and ignores the possibly thrown exceptions.
public static void	closePrint(Iterable<? extends AutoCloseable> closeables) Calls AutoCloseable.close() for every object in the argument iterable, and prints the stack trace of the possibly thrown exceptions.
public static void	closePrint(Iterator<? extends AutoCloseable> closeables) Calls AutoCloseable.close() for every object in the argument iterable, and prints the stack trace of the possibly thrown exceptions.
public static void	closePrint(AutoCloseable... closeables) Calls AutoCloseable.close() for every object in the argument iterable, and prints the stack trace of the possibly thrown exceptions.
public static <T extends Throwable> List<T>	collectExc(List<T> collector, T exc) Collects the argument exception into a list.
public static <T> void	foreach(Iterable<? extends T> objects, IOConsumer<? super T> action) Executes the given I/O action for every object in the argument iterable.
public static void	lockIO(Lock lock) Acquires the lock in interruptable mode, and throws InterruptedIOException if the current thread is interrupted.
public static void	lockIO(Lock lock, String message) Acquires the lock in interruptable mode, and throws InterruptedIOException if the current thread is interrupted.
public static void	printExc(Throwable t) Prints the stacktrace of the argument exception if it is non-`null`.
public static <T extends Throwable> void	throwExc(T throwable) Throws the argument exception if it is non-`null`.
public static boolean	tryLockIO(Lock lock, long time, TimeUnit unit) Attempts to acquire the lock in interruptable mode, and throws InterruptedIOException if the current thread is interrupted.
public static boolean	tryLockIO(Lock lock, long time, TimeUnit unit, String message) Attempts to acquire the lock in interruptable mode, and throws InterruptedIOException if the current thread is interrupted.

Inherited methods
From: Object clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

public static IOException addExc(IOException prev, Throwable next)

Aggregates two exceptions with an IOException base.

This method takes two exception arguments (only one of them can be non-null), and returns an aggregated exception based on them

If the next exception is null, the argument prev is returned.

If the prev argument is null, the next will be returned, possibly wrapping it in an IOException. If the next is already an instance if IOException, it will be plainly returned.

If both are non-null, then the next will be added to prev as suppressed exception, and prev is returned.

prevThe previous exception or null if there was none.

nextThe next exception or null if there was none.

The aggregated exception.

public static <E extends Throwable> E addExc(E prev, E next)

Aggregates two exceptions of the same type.

This method works the same ways as addExc(IOException, Throwable), but doesn't wrap the next exception into an IOException.

EThe exception type.

prevThe previous exception or null if there was none.

nextThe next exception or null if there was none.

The aggregated exception.

public static <E extends Throwable, T extends Throwable> E addExc(E prev, T next, Function<? super T, ? extends E> creator) throws NullPointerException

Aggregates two exceptions of the different type using the specified creator function.

This method works the same ways as addExc(IOException, Throwable), but uses the specified creator function to wrap the next exception into the type of the previous exception.

EThe previous exception type.

TThe next exception type.

prevThe previous exception or null if there was none.

nextThe next exception or null if there was none.

creatorThe creator function that is used when the next exception needs to be converted to the previous exception type.

The aggregated exception.

NullPointerExceptionIf the creator function is null.

public static void close(Iterable<? extends AutoCloseable> closeables) throws IOException

Calls AutoCloseable.close() for every object in the argument iterable, and throws any exceptions at the end.

Any thrown safe errors defined by this class do not abort the operation, but they are rethrown at the end.

closeablesThe closeables.

IOExceptionIf any exception is caught during the closing of the objects.

public static void close(Iterator<? extends AutoCloseable> closeables) throws IOException

Calls AutoCloseable.close() for every object in the argument iterable, and throws any exceptions at the end.

Any thrown safe errors defined by this class do not abort the operation, but they are rethrown at the end.

closeablesThe closeables.

IOExceptionIf any exception is caught during the closing of the objects.

public static void close(AutoCloseable... closeables) throws IOException

Calls AutoCloseable.close() for every object in the argument iterable, and throws any exceptions at the end.

Any thrown safe errors defined by this class do not abort the operation, but they are rethrown at the end.

closeablesThe closeables.

IOExceptionIf any exception is caught during the closing of the objects.

public static IOException closeExc(IOException prevexc, Iterable<? extends AutoCloseable> closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and aggregates any thrown exception with the previous argument.

Any thrown safe errors defined by this class do not abort the operation, but they are collected.

If the previous argument serves as a base when collecting thrown exceptions. If there is a previous exception, any thrown exception will be added as suppressed exception to it, and that will be returned. If there is no previous, the caught exceptions is returned.

It is strongly recommended that callers handle any returned exception somehow instead of ignoring it.

This method can be used in a chained way:

 IOException exc = null;
 exc = IOUtils.closeExc(exc, closeable1);
 exc = IOUtils.closeExc(exc, closeable2, closeable3);
 //handle the exception somehow
 IOUtils.throwExc(exc);

prevexcThe previous exception to aggregate any closing exception with or null if there was none.

closeablesThe closeables.

The previous exception if non-null, or the caught exception during closing, or null if there was none.

public static IOException closeExc(IOException prevexc, Iterator<? extends AutoCloseable> closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and aggregates any thrown exception with the previous argument.

Any thrown safe errors defined by this class do not abort the operation, but they are collected.

It is strongly recommended that callers handle any returned exception somehow instead of ignoring it.

This method can be used in a chained way:

 IOException exc = null;
 exc = IOUtils.closeExc(exc, closeable1);
 exc = IOUtils.closeExc(exc, closeable2, closeable3);
 //handle the exception somehow
 IOUtils.throwExc(exc);

prevexcThe previous exception to aggregate any closing exception with or null if there was none.

closeablesThe closeables.

The previous exception if non-null, or the caught exception during closing, or null if there was none.

public static IOException closeExc(IOException prevexc, AutoCloseable... closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and aggregates any thrown exception with the previous argument.

Any thrown safe errors defined by this class do not abort the operation, but they are collected.

It is strongly recommended that callers handle any returned exception somehow instead of ignoring it.

This method can be used in a chained way:

 IOException exc = null;
 exc = IOUtils.closeExc(exc, closeable1);
 exc = IOUtils.closeExc(exc, closeable2, closeable3);
 //handle the exception somehow
 IOUtils.throwExc(exc);

prevexcThe previous exception to aggregate any closing exception with or null if there was none.

closeablesThe closeables.

The previous exception if non-null, or the caught exception during closing, or null if there was none.

public static IOException closeExc(Iterable<? extends AutoCloseable> closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and returns the thrown exception if any.

Any thrown safe errors defined by this class do not abort the operation, but they are collected.

It is strongly recommended that callers handle any returned exception somehow instead of ignoring it.

closeablesThe closeables.

The caught exception during closing, or null if there was none.

public static IOException closeExc(Iterator<? extends AutoCloseable> closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and returns the thrown exception if any.

Any thrown safe errors defined by this class do not abort the operation, but they are collected.

It is strongly recommended that callers handle any returned exception somehow instead of ignoring it.

closeablesThe closeables.

The caught exception during closing, or null if there was none.

public static IOException closeExc(AutoCloseable... closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and returns the thrown exception if any.

Any thrown safe errors defined by this class do not abort the operation, but they are collected.

It is strongly recommended that callers handle any returned exception somehow instead of ignoring it.

closeablesThe closeables.

The caught exception during closing, or null if there was none.

public static void closeIgnore(Iterable<? extends AutoCloseable> closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and ignores the possibly thrown exceptions.

Any thrown safe errors defined by this class do not abort the operation, but they are rethrown at the end.

closeablesThe closeables.

public static void closeIgnore(Iterator<? extends AutoCloseable> closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and ignores the possibly thrown exceptions.

Any thrown safe errors defined by this class do not abort the operation, but they are rethrown at the end.

closeablesThe closeables.

public static void closeIgnore(AutoCloseable... closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and ignores the possibly thrown exceptions.

Any thrown safe errors defined by this class do not abort the operation, but they are rethrown at the end.

closeablesThe closeables.

public static void closePrint(Iterable<? extends AutoCloseable> closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and prints the stack trace of the possibly thrown exceptions.

Any thrown safe errors defined by this class do not abort the operation, but they are rethrown at the end.

Any Exceptions thrown from closing methods will be printed using Throwable.printStackTrace().

closeablesThe closeables.

public static void closePrint(Iterator<? extends AutoCloseable> closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and prints the stack trace of the possibly thrown exceptions.

Any thrown safe errors defined by this class do not abort the operation, but they are rethrown at the end.

Any Exceptions thrown from closing methods will be printed using Throwable.printStackTrace().

closeablesThe closeables.

public static void closePrint(AutoCloseable... closeables)

Calls AutoCloseable.close() for every object in the argument iterable, and prints the stack trace of the possibly thrown exceptions.

Any thrown safe errors defined by this class do not abort the operation, but they are rethrown at the end.

Any Exceptions thrown from closing methods will be printed using Throwable.printStackTrace().

closeablesThe closeables.

public static <T extends Throwable> List<T> collectExc(List<T> collector, T exc)

Collects the argument exception into a list.

This method will add the argument exception to the specified List instance. If the given list is null, a new one will be instantiated, and returned. If non-null, the exception is added to it, and the list itself is returned.

If the exception is null, the argument list is directly returned.

This method can be used in a chain to lazily instantiate an exception container when any exceptions is thrown. Example:

 List<Exception> excs = null;
 while (condition) {
 	try {
 		//some work
 	} catch (Exception e) {
 		excs = IOUtils.collectExc(excs, e);
 	}
 }
 //handle the collected exceptions if any.

TThe type of the exception.

collectorThe exception collector list or null, if none.

excThe exception to collect.

The list that aggregates the exceptions.

public static <T> void foreach(Iterable<? extends T> objects, IOConsumer<? super T> action) throws IOException, NullPointerException

Executes the given I/O action for every object in the argument iterable.

The action will called in order for every object in the iterable. If an action throws an exception, it will be rethrown from this method after the remaining actions for the objects are called. Any thrown safe exception defined by this class do not abort the operation.

TThe type of the objects.

objectsThe objects to call the action for.

actionThe action.

IOExceptionIf an action throws an exception. Non IOException exceptions will be wrapped into one.

NullPointerExceptionIf the action is null.

public static void lockIO(Lock lock) throws NullPointerException, InterruptedIOException

Acquires the lock in interruptable mode, and throws InterruptedIOException if the current thread is interrupted.

If the locking is interrupted, the current thread interrupt status will be set.

lockThe lock to acquire.

NullPointerExceptionIf the lock is null.

InterruptedIOExceptionIf the current thread is interrupted while acquiring the lock.

Lock.lockInterruptibly()

InterruptedIOException.InterruptedIOException()

saker.util 0.8.4

public static void lockIO(Lock lock, String message) throws NullPointerException, InterruptedIOException

Acquires the lock in interruptable mode, and throws InterruptedIOException if the current thread is interrupted.

If the locking is interrupted, the current thread interrupt status will be set.

lockThe lock to acquire.

messageThe message to instantiate the new InterruptedIOException with. (May be null)

NullPointerExceptionIf the lock is null.

InterruptedIOExceptionIf the current thread is interrupted while acquiring the lock.

Lock.lockInterruptibly()

InterruptedIOException.InterruptedIOException(String)

saker.util 0.8.4

public static void printExc(Throwable t)

Prints the stacktrace of the argument exception if it is non-null.

tThe exception.

public static <T extends Throwable> void throwExc(T throwable) throws T

Throws the argument exception if it is non-null.

throwableThe exception.

TThe argument if non-null.

public static boolean tryLockIO(Lock lock, long time, TimeUnit unit) throws NullPointerException, InterruptedIOException

Attempts to acquire the lock in interruptable mode, and throws InterruptedIOException if the current thread is interrupted.

If the locking is interrupted, the current thread interrupt status will be set.

lockThe lock to acquire.

timeThe maximum time to wait for the lock.

unitThe time unit of the time argument.

true if the lock was acquired and false if the waiting time elapsed before the lock was acquired.

NullPointerExceptionIf the lock is null.

InterruptedIOExceptionIf the current thread is interrupted while acquiring the lock.

Lock.tryLock(long, TimeUnit)

InterruptedIOException.InterruptedIOException()

saker.util 0.8.4

public static boolean tryLockIO(Lock lock, long time, TimeUnit unit, String message) throws NullPointerException, InterruptedIOException

Attempts to acquire the lock in interruptable mode, and throws InterruptedIOException if the current thread is interrupted.

If the locking is interrupted, the current thread interrupt status will be set.

lockThe lock to acquire.

timeThe maximum time to wait for the lock.

unitThe time unit of the time argument.

messageThe message to instantiate the new InterruptedIOException with. (May be null)

true if the lock was acquired and false if the waiting time elapsed before the lock was acquired.

NullPointerExceptionIf the lock is null.

InterruptedIOExceptionIf the current thread is interrupted while acquiring the lock.

Lock.tryLock(long, TimeUnit)

InterruptedIOException.InterruptedIOException(String)

saker.util 0.8.4