org.apache.lucene.util

## Class IOUtils

- java.lang.Object
- - org.apache.lucene.util.IOUtils

-     public final class IOUtils
      extends Object

  This class emulates the new Java 7 "Try-With-Resources" statement. Remove once Lucene is on Java 7.
  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 and Description
    --- | ---
    `static interface` | `IOUtils.IOConsumer<T>` An IO operation with a single input.
    `static interface` | `IOUtils.IOFunction<T,R>` A Function that may throw an IOException

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `UTF_8` UTF-8 charset string.

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and 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 `Closeable`s.
    `static void` | `close(Iterable<? extends Closeable> objects)` Closes all given `Closeable`s.
    `static void` | `closeWhileHandlingException(Closeable... objects)` Closes all given `Closeable`s, suppressing all thrown exceptions.
    `static void` | `closeWhileHandlingException(Iterable<? extends Closeable> objects)` Closes all given `Closeable`s, suppressing all thrown non `VirtualMachineError` exceptions.
    `static void` | `deleteFiles(Directory dir, Collection<String> names)` Deletes all given file names.
    `static void` | `deleteFilesIfExist(Collection<? extends Path> files)` Deletes all given `Path`s, if they exist.
    `static void` | `deleteFilesIfExist(Path... files)` Deletes all given `Path`s, if they exist.
    `static void` | `deleteFilesIgnoringExceptions(Collection<? extends Path> files)` Deletes all given files, suppressing all thrown IOExceptions.
    `static void` | `deleteFilesIgnoringExceptions(Directory dir, Collection<String> files)` Deletes all given files, suppressing all thrown IOExceptions.
    `static void` | `deleteFilesIgnoringExceptions(Directory dir, String... files)`
    `static void` | `deleteFilesIgnoringExceptions(Path... 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(Class<?> clazz, String resource, Charset charSet)` Opens a Reader for the given resource using a `CharsetDecoder`.
    `static Reader` | `getDecodingReader(InputStream stream, Charset charSet)` Wrapping the given `InputStream` in a reader using a `CharsetDecoder`.
    `static void` | `reThrow(Throwable th)` Deprecated. This method is deprecated in favor of `rethrowAlways(java.lang.Throwable)`. Code should be updated to `rethrowAlways(java.lang.Throwable)` and guarded with an additional null-argument check (because `rethrowAlways(java.lang.Throwable)` is not accepting null arguments).
    `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` | `reThrowUnchecked(Throwable th)` Deprecated. This method is deprecated in favor of `rethrowAlways(java.lang.Throwable)`. Code should be updated to `rethrowAlways(java.lang.Throwable)` and guarded with an additional null-argument check (because `rethrowAlways(java.lang.Throwable)` is not accepting null arguments).
    `static void` | `rm(Path... locations)` Deletes one or more files or directories (and everything underneath it).
    `static boolean` | `spins(Directory dir)` If the dir is an `FSDirectory` or wraps one via possibly nested `FilterDirectory` or `FileSwitchDirectory`, this returns `spins(Path)` for the wrapped directory, else, true.
    `static boolean` | `spins(Path path)` Rough Linux-only heuristics to determine whether the provided `Path` is backed by spinning storage.
    `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 Detail

    - #### 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 Detail

    - #### close

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

      Closes all given `Closeable`s. Some of the `Closeable`s 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 `Closeable`s.
      Throws:
        `IOException`
      See Also:
        `close(Closeable...)`

    - #### closeWhileHandlingException

          public static void closeWhileHandlingException(Closeable... objects)

      Closes all given `Closeable`s, suppressing all thrown exceptions. Some of the `Closeable`s 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 `Closeable`s, 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

    - #### getDecodingReader

          public static Reader getDecodingReader(Class<?> clazz,
                                                 String resource,
                                                 Charset charSet)
                                          throws IOException

      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 `Path`s, if they exist. Some of the `File`s 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 `Path`s, if they exist. Some of the `File`s 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 detailsa 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.

    - #### reThrow

          @Deprecated
          public static void reThrow(Throwable th)
                                          throws IOException

      Deprecated. This method is deprecated in favor of `rethrowAlways(java.lang.Throwable)`. Code should be updated to `rethrowAlways(java.lang.Throwable)` and guarded with an additional null-argument check (because `rethrowAlways(java.lang.Throwable)` is not accepting null arguments).
      Rethrows the argument as `IOException` or `RuntimeException` if it's not null.
      Throws:
        `IOException`

    - #### reThrowUnchecked

          @Deprecated
          public static void reThrowUnchecked(Throwable th)

      Deprecated. This method is deprecated in favor of `rethrowAlways(java.lang.Throwable)`. Code should be updated to `rethrowAlways(java.lang.Throwable)` and guarded with an additional null-argument check (because `rethrowAlways(java.lang.Throwable)` is not accepting null arguments).

    - #### 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`

    - #### spins

          public static boolean spins(Directory dir)
                               throws IOException

      If the dir is an `FSDirectory` or wraps one via possibly nested `FilterDirectory` or `FileSwitchDirectory`, this returns `spins(Path)` for the wrapped directory, else, true.
      Throws:
        `IOException` - if `path` does not exist.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    - #### spins

          public static boolean spins(Path path)
                               throws IOException

      Rough Linux-only heuristics to determine whether the provided `Path` is backed by spinning storage. For example, this returns false if the disk is a solid-state disk.
      Parameters:
        `path` - a location to check which must exist. the mount point will be determined from this location.
      Returns:
        false if the storage is non-rotational (e.g. an SSD), or true if it is spinning or could not be determined
      Throws:
        `IOException` - if `path` does not exist.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    - #### 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`

Copyright © 2000-2024 Apache Software Foundation. All Rights Reserved.