Package org.apache.lucene.util

Class IOUtils

java.lang.Object

org.apache.lucene.util.IOUtils

public final class IOUtils
extends Object

Utilities for dealing with Closeables.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	IOUtils.IOConsumer<T>	Deprecated, for removal: This API element is subject to removal in a future version. was replaced by IOConsumer.
static interface	IOUtils.IOFunction<T,R>	Deprecated, for removal: This API element is subject to removal in a future version. was replaced by IOFunction.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	UTF_8	UTF-8 charset string.

Method Summary

Modifier and Type	Method	Description
static <T> void	applyToAll(Collection<T> collection, IOUtils.IOConsumer<T> consumer)	Applies the consumer to all non-null elements in the collection even if an exception is thrown.
static void	close(Closeable... objects)	Closes all given Closeables.
static void	close(Iterable<? extends Closeable> objects)	Closes all given Closeables.
static void	closeWhileHandlingException(Closeable... objects)	Closes all given Closeables, suppressing all thrown exceptions.
static void	closeWhileHandlingException(Iterable<? extends Closeable> objects)	Closes all given Closeables, suppressing all thrown non VirtualMachineError exceptions.
static void	deleteFiles(Directory dir, Collection<String> names)	Deletes all given file names.
static void	deleteFilesIfExist(Path... files)	Deletes all given Paths, if they exist.
static void	deleteFilesIfExist(Collection<? extends Path> files)	Deletes all given Paths, if they exist.
static void	deleteFilesIgnoringExceptions(Path... files)	Deletes all given files, suppressing all thrown IOExceptions.
static void	deleteFilesIgnoringExceptions(Collection<? extends Path> files)	Deletes all given files, suppressing all thrown IOExceptions.
static void	deleteFilesIgnoringExceptions(Directory dir, String... files)
static void	deleteFilesIgnoringExceptions(Directory dir, Collection<String> files)	Deletes all given files, suppressing all thrown IOExceptions.
static void	fsync(Path fileToSync, boolean isDir)	Ensure that any writes to the given file is written to the storage device that contains it.
static Reader	getDecodingReader(InputStream stream, Charset charSet)	Wrapping the given InputStream in a reader using a CharsetDecoder.
static Reader	getDecodingReader(Class<?> clazz, String resource, Charset charSet)	Deprecated, for removal: This API element is subject to removal in a future version. Class.getResourceAsStream(String) is caller sensitive and cannot load resources across Java Modules.
static <T> T	requireResourceNonNull(T resource, String name)	Wrap all calls to Class.getResource(String) or Class.getResourceAsStream(String) using this method to enforce existence of the resource.
static Error	rethrowAlways(Throwable th)	This utility method takes a previously caught (non-null) Throwable and rethrows either the original argument if it was a subclass of the IOException or an RuntimeException with the cause set to the argument.
static void	rm(Path... locations)	Deletes one or more files or directories (and everything underneath it).
static <T extends Throwable> T	useOrSuppress(T first, T second)	Returns the second throwable if the first is null otherwise adds the second as suppressed to the first and returns it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

UTF_8

public static final String UTF_8

UTF-8 charset string.

Where possible, use StandardCharsets.UTF_8 instead, as using the String constant may slow things down.

See Also:

• StandardCharsets.UTF_8

Method Details

close

public static void close(Closeable... objects)
                  throws IOException

Closes all given Closeables. Some of the Closeables may be null; they are ignored. After everything is closed, the method either throws the first exception it hit while closing, or completes normally if there were no exceptions.

Parameters:

objects - objects to call close() on

Throws:

IOException

close

public static void close(Iterable<? extends Closeable> objects)
                  throws IOException

Closes all given Closeables.

Throws:

IOException

See Also:

• close(Closeable...)

closeWhileHandlingException

public static void closeWhileHandlingException(Closeable... objects)

Closes all given Closeables, suppressing all thrown exceptions. Some of the Closeables may be null, they are ignored.

Parameters:

objects - objects to call close() on

closeWhileHandlingException

public static void closeWhileHandlingException(Iterable<? extends Closeable> objects)

Closes all given Closeables, suppressing all thrown non VirtualMachineError exceptions. Even if a VirtualMachineError is thrown all given closeable are closed.

See Also:

• closeWhileHandlingException(Closeable...)

getDecodingReader

public static Reader getDecodingReader(InputStream stream,
 Charset charSet)

Wrapping the given InputStream in a reader using a CharsetDecoder. Unlike Java's defaults this reader will throw an exception if your it detects the read charset doesn't match the expected Charset.

Decoding readers are useful to load configuration files, stopword lists or synonym files to detect character set problems. However, it's not recommended to use as a common purpose reader.

Parameters:

stream - the stream to wrap in a reader

charSet - the expected charset

Returns:

a wrapping reader

requireResourceNonNull

public static <T> T requireResourceNonNull(T resource,
 String name)
                                    throws IOException

Wrap all calls to Class.getResource(String) or Class.getResourceAsStream(String) using this method to enforce existence of the resource. This code works around those methods returning null to signal non-existence.

Parameters:

resource - return value of above methods

name - of resource

Returns:

the resource passed in if existent

Throws:

FileNotFoundException - if resource was not found

IOException

getDecodingReader

@Deprecated(forRemoval=true,
            since="9.1")
public static Reader getDecodingReader(Class<?> clazz,
 String resource,
 Charset charSet)
                                throws IOException

Deprecated, for removal: This API element is subject to removal in a future version.

Class.getResourceAsStream(String) is caller sensitive and cannot load resources across Java Modules. Please call the getResourceAsStream() directly and use requireResourceNonNull(Object,String) to signal missing resources null

Opens a Reader for the given resource using a CharsetDecoder. Unlike Java's defaults this reader will throw an exception if your it detects the read charset doesn't match the expected Charset.

Decoding readers are useful to load configuration files, stopword lists or synonym files to detect character set problems. However, it's not recommended to use as a common purpose reader.

Parameters:

clazz - the class used to locate the resource

resource - the resource name to load

charSet - the expected charset

Returns:

a reader to read the given file

Throws:

IOException

deleteFilesIgnoringExceptions

public static void deleteFilesIgnoringExceptions(Directory dir,
 Collection<String> files)

Deletes all given files, suppressing all thrown IOExceptions.

Note that the files should not be null.

deleteFilesIgnoringExceptions

public static void deleteFilesIgnoringExceptions(Directory dir,
 String... files)

deleteFiles

public static void deleteFiles(Directory dir,
 Collection<String> names)
                        throws IOException

Deletes all given file names. Some of the file names may be null; they are ignored. After everything is deleted, the method either throws the first exception it hit while deleting, or completes normally if there were no exceptions.

Parameters:

dir - Directory to delete files from

names - file names to delete

Throws:

IOException

deleteFilesIgnoringExceptions

public static void deleteFilesIgnoringExceptions(Path... files)

Deletes all given files, suppressing all thrown IOExceptions.

Some of the files may be null, if so they are ignored.

deleteFilesIgnoringExceptions

public static void deleteFilesIgnoringExceptions(Collection<? extends Path> files)

Deletes all given files, suppressing all thrown IOExceptions.

Some of the files may be null, if so they are ignored.

deleteFilesIfExist

public static void deleteFilesIfExist(Path... files)
                               throws IOException

Deletes all given Paths, if they exist. Some of the Files may be null; they are ignored. After everything is deleted, the method either throws the first exception it hit while deleting, or completes normally if there were no exceptions.

Parameters:

files - files to delete

Throws:

IOException

deleteFilesIfExist

public static void deleteFilesIfExist(Collection<? extends Path> files)
                               throws IOException

Deletes all given Paths, if they exist. Some of the Files may be null; they are ignored. After everything is deleted, the method either throws the first exception it hit while deleting, or completes normally if there were no exceptions.

Parameters:

files - files to delete

Throws:

IOException

rm

public static void rm(Path... locations)
               throws IOException

Deletes one or more files or directories (and everything underneath it).

Throws:

IOException - if any of the given files (or their subhierarchy files in case of directories) cannot be removed.

rethrowAlways

public static Error rethrowAlways(Throwable th)
                           throws IOException,
RuntimeException

This utility method takes a previously caught (non-null) Throwable and rethrows either the original argument if it was a subclass of the IOException or an RuntimeException with the cause set to the argument.

This method never returns any value, even though it declares a return value of type Error. The return value declaration is very useful to let the compiler know that the code path following the invocation of this method is unreachable. So in most cases the invocation of this method will be guarded by an if and used together with a throw statement, as in:

 if (t != null) throw IOUtils.rethrowAlways(t)
 

Parameters:

th - The throwable to rethrow, must not be null.

Returns:

This method always results in an exception, it never returns any value. See method documentation for details and usage example.

Throws:

IOException - if the argument was an instance of IOException

RuntimeException - with the Throwable.getCause() set to the argument, if it was not an instance of IOException.

fsync

public static void fsync(Path fileToSync,
 boolean isDir)
                  throws IOException

Ensure that any writes to the given file is written to the storage device that contains it.

Parameters:

fileToSync - the file to fsync

isDir - if true, the given file is a directory (we open for read and ignore IOExceptions, because not all file systems and operating systems allow to fsync on a directory)

Throws:

IOException

useOrSuppress

public static <T extends Throwable> T useOrSuppress(T first,
 T second)

Returns the second throwable if the first is null otherwise adds the second as suppressed to the first and returns it.

applyToAll

public static <T> void applyToAll(Collection<T> collection,
 IOUtils.IOConsumer<T> consumer)
                           throws IOException

Applies the consumer to all non-null elements in the collection even if an exception is thrown. The first exception thrown by the consumer is re-thrown and subsequent exceptions are suppressed.

Throws:

IOException