Package org.kiwiproject.io

Class KiwiIO

java.lang.Object
org.kiwiproject.io.KiwiIO
public final class KiwiIO extends Object
Static I/O utilities.

The closeQuietly methods that accept Closeable were copied directly from Apache Commons I/O and the deprecation warnings and annotations removed. While they should not be used often, sometimes they might come in handy, so we want to keep them around for posterity. Slight style modifications were made (e.g. replace obj != null checks with nonNull(obj, etc.) as well as adding logging. Did not bother copying all the closeQuietly methods that took a specific class such as Reader, Writer, Socket, etc. They all implement Closeable and were probably only there because those specific classes pre-dated Java 5 when Closeable was added to the JDK, and we assume early (pre-Java 5) versions of IOUtils provided them.

  • Method Details

    • closeQuietly

      public static void closeQuietly(Closeable closeable)
      Closes a Closeable unconditionally.

      Equivalent to Closeable.close(), except any exceptions will be ignored. This is typically used in finally blocks.

      Example code: 

       Closeable closeable = null;
 try {
     closeable = new FileReader("foo.txt");
     // process closeable
     closeable.close();
 } catch (Exception e) {
     // error handling
 } finally {
     IOUtils.closeQuietly(closeable);
 }

      Closing all streams: 

       try {
     return IOUtils.copy(inputStream, outputStream);
 } finally {
     IOUtils.closeQuietly(inputStream);
     IOUtils.closeQuietly(outputStream);
 }
      Parameters:
      closeable - the object to close, may be null or already closed
      See Also:
      Implementation Note:
      Copied from Apache Commons I/O's IOUtils once it became deprecated with the message "Please use the try-with-resources statement or handle suppressed exceptions manually."

    • closeQuietly

      public static void closeQuietly(Closeable... closeables)
      Closes a Closeable unconditionally.

      Equivalent to Closeable.close(), except any exceptions will be ignored.

      This is typically used in finally blocks to ensure that the closeable is closed even if an Exception was thrown before the normal close statement was reached.
      It should not be used to replace the close statement(s) which should be present for the non-exceptional case.
      It is only intended to simplify tidying up where normal processing has already failed and reporting close failure as well is not necessary or useful.

      Example code: 

       Closeable closeable = null;
 try {
     closeable = new FileReader("foo.txt");
     // processing using the closeable; may throw an Exception
     closeable.close(); // Normal close - exceptions not ignored
 } catch (Exception e) {
     // error handling
 } finally {
     IOUtils.closeQuietly(closeable); // In case normal close was skipped due to Exception
 }

      Closing all streams: 

       try {
     return IOUtils.copy(inputStream, outputStream);
 } finally {
     IOUtils.closeQuietly(inputStream, outputStream);
 }
      Parameters:
      closeables - the objects to close, may be null or already closed
      See Also:
      Implementation Note:
      Copied from Apache Commons I/O's IOUtils once it became deprecated with the message "Please use the try-with-resources statement or handle suppressed exceptions manually."

    • closeQuietly

      public static void closeQuietly(XMLStreamReader xmlStreamReader)
      Closes an XMLStreamReader unconditionally.

      Since XMLStreamReader does not implement Closeable, you cannot use a try-with-resources.

      Parameters:
      xmlStreamReader - the XMLStreamReader to close
      See Also:

    • closeQuietly

      public static void closeQuietly(XMLStreamWriter xmlStreamWriter)
      Closes an XMLStreamWriter unconditionally.

      Since XMLStreamWriter does not implement Closeable, you cannot use a try-with-resources.

      Parameters:
      xmlStreamWriter - the XMLStreamWriter to close
      See Also:

    • defaultCloseMethodNames

      public static List<String> defaultCloseMethodNames()
      Return the default method names used when closing objects using any of the methods to close generic Object.

      These method names are tried in order when attempting to close an Object when no explicit close method name is provided.

      The default names are

      Returns:
      the default close method names

    • closeObjectQuietly

      public static void closeObjectQuietly(Object object)
      Closes an object unconditionally. This method ignores null objects and exceptions.

      The object may be a KiwiIO.CloseableResource.

      Uses the default close method names.

      Parameters:
      object - the object to close, may be null or already closed
      See Also:

    • closeObjectQuietly

      public static void closeObjectQuietly(String closeMethodName, Object object)
      Closes an object unconditionally. This method ignores null objects and exceptions.

      The object may not be a KiwiIO.CloseableResource, since it could contain a different close method name.

      Parameters:
      closeMethodName - the name of the close method
      object - the object to close, may be null or already closed
      Throws:
      IllegalArgumentException - if closeMethodName is blank or object is a CloseableResource

    • closeObjectsQuietly

      public static void closeObjectsQuietly(Object... objects)
      Closes one or more objects unconditionally. This method ignores null objects and exceptions.

      The objects may contain KiwiIO.CloseableResource and/or other closeable objects.

      Uses the default close method names.

      Parameters:
      objects - the objects to close, may be null or already closed
      See Also:

    • closeObjectsQuietly

      public static void closeObjectsQuietly(String closeMethodName, Object... objects)
      Closes one or more objects unconditionally. This method ignores null objects and exceptions.

      The objects should not contain any KiwiIO.CloseableResource instances. The reason is that those could specify a different close method name.

      Parameters:
      closeMethodName - the name of the close method
      objects - the objects to close, may be null or already closed
      Throws:
      IllegalArgumentException - of objects contains any CloseableResource instances

    • closeResourceQuietly

      public static void closeResourceQuietly(KiwiIO.CloseableResource closeableResource)
      Closes a resource unconditionally. This method ignores null objects and exceptions.

      The object inside the resource may be null or already closed. The resource must contain at least one close method name.

      Parameters:
      closeableResource - the resource to close, must not be null
      Throws:
      IllegalArgumentException - if the closeableResource is null or has no close method names

    • newByteArrayInputStreamOfLines

      public static ByteArrayInputStream newByteArrayInputStreamOfLines(String... lines)
      Return a newly constructed ByteArrayInputStream containing the given lines separated by the System.lineSeparator() and using UTF-8 as the Charset when converting the joined lines to bytes.
      Parameters:
      lines - the lines to convert
      Returns:
      a ByteArrayInputStream containing the given lines, encoded using UTF-8

    • newByteArrayInputStream

      public static ByteArrayInputStream newByteArrayInputStream(String value)
      Creates a new ByteArrayInputStream containing the bytes of the given string using the UTF-8 character set.

      Note: The UTF-8 character set is widely used and supports a vast range of characters, making it suitable for most applications. However, if the string was encoded using a different character set, use the other version of this method that accepts a Charset to specify the character set that was used to encode the string.

      Parameters:
      value - the string from which to create the ByteArrayInputStream
      Returns:
      a new ByteArrayInputStream initialized with bytes from the provided string
      Throws:
      IllegalArgumentException - if the input string is null

    • newByteArrayInputStream

      public static ByteArrayInputStream newByteArrayInputStream(String value, Charset charset)
      Creates a new ByteArrayInputStream containing the bytes of the given string using the specified character set.
      Parameters:
      value - the string from which to create the ByteArrayInputStream
      charset - the character set used to encode the string as bytes
      Returns:
      a new ByteArrayInputStream initialized with bytes from the provided string
      Throws:
      IllegalArgumentException - if the input string or charset is null

    • emptyByteArrayInputStream

      public static ByteArrayInputStream emptyByteArrayInputStream()
      Return a newly constructed, empty ByteArrayInputStream.
      Returns:
      new ByteArrayInputStream

    • readLinesFromErrorStreamOf

      public static List<String> readLinesFromErrorStreamOf(Process process)
      Return a List of Strings from the error stream of the given Process using UTF-8 for the String encoding.
      Parameters:
      process - the process
      Returns:
      the list of UTF-8 encoded strings from the process' error stream

    • readLinesFromErrorStreamOf

      public static List<String> readLinesFromErrorStreamOf(Process process, Charset charset)
      Return a List of Strings from the error stream of the given Process using the specified Charset for the String encoding.
      Parameters:
      process - the process
      charset - the charset
      Returns:
      the list of UTF-8 encoded strings from the process' error stream

    • readLinesFromInputStreamOf

      public static List<String> readLinesFromInputStreamOf(Process process)
      Return a List of Strings from the input stream of the given Process using UTF-8 for the String encoding.
      Parameters:
      process - the process
      Returns:
      the list of UTF-8 encoded strings from the process' input stream

    • readLinesFromInputStreamOf

      public static List<String> readLinesFromInputStreamOf(Process process, Charset charset)
      Return a List of Strings from the input stream of the given Process using the specified Charset for the String encoding.
      Parameters:
      process - the process
      charset - the charset
      Returns:
      the list of UTF-8 encoded strings from the process' input stream

    • readLinesFrom

      public static List<String> readLinesFrom(InputStream stream, Charset charset)
      Return a List of Strings from the input stream using the specified Charset for the String encoding.
      Parameters:
      stream - the stream
      charset - the charset
      Returns:
      a list of strings from the input stream, encoded using the specified charset

    • streamLinesFromErrorStreamOf

      public static Stream<String> streamLinesFromErrorStreamOf(Process process)
      Return a Stream of Strings from the error stream of the given Process using UTF-8 for the String encoding.
      Parameters:
      process - the process
      Returns:
      the stream of UTF-8 encoded strings from the process' error stream

    • streamLinesFromErrorStreamOf

      public static Stream<String> streamLinesFromErrorStreamOf(Process process, Charset charset)
      Return a Stream of Strings from the error stream of the given Process using the specified Charset for the String encoding.
      Parameters:
      process - the process
      charset - the charset
      Returns:
      the stream of strings from the process' error stream, encoded using the specified charset

    • streamLinesFromInputStreamOf

      public static Stream<String> streamLinesFromInputStreamOf(Process process)
      Return a Stream of Strings from the input stream of the given Process using UTF-8 for the String encoding.
      Parameters:
      process - the process
      Returns:
      the stream of UTF-8 encoded strings from the process' input stream

    • streamLinesFromInputStreamOf

      public static Stream<String> streamLinesFromInputStreamOf(Process process, Charset charset)
      Return a Stream of Strings from the input stream of the given Process using the specified Charset for the String encoding.
      Parameters:
      process - the process
      charset - the charset
      Returns:
      the stream of strings from the process' input stream, encoded using the specified charset

    • streamLinesFrom

      public static Stream<String> streamLinesFrom(InputStream stream, Charset charset)
      Return a Stream of Strings from the given InputStream using the specified Charset for the String encoding.
      Parameters:
      stream - the stream
      charset - the charset
      Returns:
      the stream of strings from the input stream, encoded using the specified charset

    • readInputStreamOf

      public static String readInputStreamOf(Process process)
      Read the input stream of the give Process as a String using UTF-8 as the String encoding.

      Note that process output may contain one or more lines, which will therefore include line termination characters within or at the end of the returned string.

      Parameters:
      process - the process
      Returns:
      the process' input stream as a UTF-8 encoded string
      See Also:

    • readInputStreamOf

      public static String readInputStreamOf(Process process, Charset charset)
      Read the input stream of the give Process as a String using the specified Charset for the string encoding.

      Note that process output may contain one or more lines, which will therefore include line termination characters within or at the end of the returned string.

      Parameters:
      process - the process
      charset - the charset
      Returns:
      the process' input stream as a string, encoded using the specified charset
      See Also:

    • readErrorStreamOf

      public static String readErrorStreamOf(Process process)
      Read the error stream of the give Process as a String using UTF-8 as the string encoding.

      Note that process output may contain one or more lines, which will therefore include line termination characters within or at the end of the returned string.

      Parameters:
      process - the process
      Returns:
      the process' error stream as a UTF-8 encoded string
      See Also:

    • readErrorStreamOf

      public static String readErrorStreamOf(Process process, Charset charset)
      Read the error stream of the give Process as a String using the specified Charset for the string encoding.

      Note that process output may contain one or more lines, which will therefore include line termination characters within or at the end of the returned string.

      Parameters:
      process - the process
      charset - the charset
      Returns:
      the process' error stream as a string, encoded using the specified charset
      See Also:

    • readInputStreamAsString

      public static String readInputStreamAsString(InputStream inputStream)
      Convert the given InputStream to a UTF-8 encoded String.
      Parameters:
      inputStream - the input stream
      Returns:
      the input stream as a UTF-8 encoded string

    • readInputStreamAsString

      public static String readInputStreamAsString(InputStream inputStream, Charset charset)
      Convert the given InputStream to a String using the given Charset for the string encoding.
      Parameters:
      inputStream - the input stream
      charset - the charset
      Returns:
      the input stream as a string, encoded using the specified charset