Package com.norconex.commons.lang.io

# Class IoUtil

java.lang.Object
com.norconex.commons.lang.io.IoUtil

public final class IoUtil extends Object
I/O related utility methods.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static byte[]`
  `borrowBytes(@NonNull InputStream is, int qty)`
  Gets and resets the specified number of bytes from the input stream.
  `static char[]`
  `borrowCharacters(@NonNull Reader reader, int qty)`
  Gets and resets the specified number of characters from the reader.
  `static void`
  `closeQuietly(Closeable... closeable)`
  Given Apache has deprecated its `IOUtils#closeQuietly(java.io.Closeable)` method, this one offers an alternative.
  `static int`
  `consume(InputStream is)`
  Fully consumes an input stream.
  `static int`
  `consume(Reader reader)`
  Fully consumes an input stream.
  `static int`
  `consumeUntil(Reader reader, String str, Appendable appendable)`
  Consumes reader characters until after encountering the supplied string (the matching string is also consumed) or the end of stream is reached.
  `static int`
  `consumeUntil(Reader reader, IntPredicate predicate)`
  Consumes markable reader characters until the predicate returns `true` for a character or the end of stream is reached.
  `static int`
  `consumeUntil(Reader reader, IntPredicate predicate, Appendable appendable)`
  Consumes markable reader characters until the predicate returns `true` for a character or the end of stream is reached.
  `static int`
  `consumeWhile(Reader reader, IntPredicate predicate)`
  Consumes markable reader characters while the predicate returns `true` for a character or the end of stream is reached.
  `static int`
  `consumeWhile(Reader reader, IntPredicate predicate, Appendable appendable)`
  Consumes markable reader characters while the predicate returns `true` for a character or the end of stream is reached.
  `static String[]`
  `head(InputStream is, int lineQty)`
  Gets the first lines from an input stream, using UTF-8.
  `static String[]`
  `head(InputStream is, String encoding, int lineQty)`
  Gets the first lines from an input stream, using the specified encoding.
  `static String[]`
  `head(InputStream is, Charset encoding, int lineQty)`
  Gets the first lines from an input stream, using the specified encoding.
  `static boolean`
  `isEmpty(InputStream is)`
  Gets whether the given input stream is `null` or empty.
  `static boolean`
  `isEmpty(Reader reader)`
  Gets whether the given Reader is `null` or empty.
  `static boolean`
  `startsWith(InputStream is, byte[] bytes)`
  Whether the given input stream starts the specified bytes array or not.
  `static String[]`
  `tail(InputStream is, int lineQty)`
  Gets the last lines from an input stream, using UTF-8.
  `static String[]`
  `tail(InputStream is, String encoding, int lineQty)`
  Gets the last lines from an input stream, using the specified encoding.
  `static String[]`
  `tail(InputStream is, Charset encoding, int lineQty)`
  Gets the last lines from an input stream, using the specified encoding.
  `static BufferedInputStream`
  `toBufferedInputStream(@NonNull InputStream in)`
  Wraps the input stream in a `BufferedInputStream` if not a subclass already.
  `static BufferedReader`
  `toBufferedReader(@NonNull Reader reader)`
  Wraps the reader in a `BufferedReader` if not a subclass already.
  `static InputStream`
  `toNonNullInputStream(InputStream is)`
  Gets an "empty" input stream (zero size) when the supplied input stream is `null`.
  `static OutputStream`
  `toNonNullOutputStream(OutputStream os)`
  Gets a non-effective output stream when the supplied output stream is `null` (writing to it has no effect).
  `static Reader`
  `toNonNullReader(Reader reader)`
  Gets an "empty" reader (zero size) when the supplied reader is `null`.
  `static Writer`
  `toNonNullWriter(Writer writer)`
  Gets a non-effective writer when the supplied writer is `null` (writing to it has no effect).

  ### Methods inherited from class java.lang.Object

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

- ## Method Details

  - ### startsWith

    public static boolean startsWith(InputStream is, byte[] bytes) throws IOException
    Whether the given input stream starts the specified bytes array or not. The input stream must support marking. If the byte array or the input stream is null, then `false` is returned.
    Parameters:
      `is` - input stream
      `bytes` - byte array to compare
    Returns:
      `true` if input stream starts with byte array
    Throws:
      `IOException` - if `InputStream.markSupported()` returns false

  - ### borrowBytes

    public static byte[] borrowBytes(@NonNull @NonNull InputStream is, int qty) throws IOException
    Gets and resets the specified number of bytes from the input stream. Must support marks.
    Parameters:
      `is` - input stream
      `qty` - number of bytes to read
    Returns:
      byte array of length matching the quantity requested
    Throws:
      `IOException` - if `InputStream.markSupported()` returns false
    Since:
      2.0.0

  - ### borrowCharacters

    public static char[] borrowCharacters(@NonNull @NonNull Reader reader, int qty) throws IOException
    Gets and resets the specified number of characters from the reader. Must support marks.
    Parameters:
      `reader` - reader
      `qty` - number of characters to read
    Returns:
      char array of length matching the quantity requested
    Throws:
      `IOException` - if `Reader.markSupported()` returns false
    Since:
      2.0.0

  - ### isEmpty

    public static boolean isEmpty(InputStream is) throws IOException
    Gets whether the given input stream is `null` or empty. Must support marks.
    Parameters:
      `is` - input stream
    Returns:
      `true` if `null` or empty
    Throws:
      `IOException` - if `InputStream.markSupported()` returns false
    Since:
      2.0.0

  - ### isEmpty

    public static boolean isEmpty(Reader reader) throws IOException
    Gets whether the given Reader is `null` or empty. Must support marks.
    Parameters:
      `reader` - reader
    Returns:
      `true` if `null` or empty
    Throws:
      `IOException` - if `Reader.markSupported()` returns false
    Since:
      2.0.0

  - ### toBufferedReader

    public static BufferedReader toBufferedReader(@NonNull @NonNull Reader reader)
    Wraps the reader in a `BufferedReader` if not a subclass already.
    Parameters:
      `reader` - the reader to wrap if needed
    Returns:
      buffered reader
    Since:
      1.6.0

  - ### toBufferedInputStream

    public static BufferedInputStream toBufferedInputStream(@NonNull @NonNull InputStream in)
    Wraps the input stream in a `BufferedInputStream` if not a subclass already.
    Parameters:
      `in` - the input stream to wrap if needed
    Returns:
      buffered input stream
    Since:
      1.6.0

  - ### tail

    public static String[] tail(InputStream is, int lineQty) throws IOException
    Gets the last lines from an input stream, using UTF-8. This method is null-safe. If the input stream is null or empty, an empty string array will be returned.
    Use of this method can often be a bad idea (especially on large streams) since it needs to read the entire stream to return the last lines. If you are dealing with files, use `FileUtil.tail(java.io.File, int)` instead, which can read a file starting from the end.
    Parameters:
      `is` - input stream
      `lineQty` - maximum number of lines to return
    Returns:
      lines as a string array
    Throws:
      `IOException` - problem reading lines

  - ### tail

    public static String[] tail(InputStream is, String encoding, int lineQty) throws IOException
    Gets the last lines from an input stream, using the specified encoding. This method is null-safe. If the input stream is null or empty, an empty string array will be returned.
    Use of this method can often be a bad idea (especially on large streams) since it needs to read the entire stream to return the last lines. If you are dealing with files, use `FileUtil.tail(File, String, int)` instead, which can read a file starting from the end.
    Parameters:
      `is` - input stream
      `encoding` - character encoding
      `lineQty` - maximum number of lines to return
    Returns:
      lines as a string array
    Throws:
      `IOException` - problem reading lines
    Since:
      1.5.0

  - ### tail

    public static String[] tail(InputStream is, Charset encoding, int lineQty) throws IOException
    Gets the last lines from an input stream, using the specified encoding. This method is null-safe. If the input stream is null or empty, an empty string array will be returned.
    Use of this method can often be a bad idea (especially on large streams) since it needs to read the entire stream to return the last lines. If you are dealing with files, use `FileUtil.tail(File, String, int)` instead, which can read a file starting from the end.
    Parameters:
      `is` - input stream
      `encoding` - character encoding
      `lineQty` - maximum number of lines to return
    Returns:
      lines as a string array
    Throws:
      `IOException` - problem reading lines
    Since:
      1.14.0

  - ### head

    public static String[] head(InputStream is, int lineQty) throws IOException
    Gets the first lines from an input stream, using UTF-8. This method is null-safe. If the input stream is null or empty, an empty string array will be returned.
    Parameters:
      `is` - input stream
      `lineQty` - maximum number of lines to return
    Returns:
      lines as a string array
    Throws:
      `IOException` - problem reading lines

  - ### head

    public static String[] head(InputStream is, String encoding, int lineQty) throws IOException
    Gets the first lines from an input stream, using the specified encoding. This method is null-safe. If the input stream is null or empty, an empty string array will be returned.
    Parameters:
      `is` - input stream
      `encoding` - character encoding
      `lineQty` - maximum number of lines to return
    Returns:
      lines as a string array
    Throws:
      `IOException` - problem reading lines

  - ### head

    public static String[] head(InputStream is, Charset encoding, int lineQty) throws IOException
    Gets the first lines from an input stream, using the specified encoding. This method is null-safe. If the input stream is null or empty, an empty string array will be returned.
    Parameters:
      `is` - input stream
      `encoding` - character encoding
      `lineQty` - maximum number of lines to return
    Returns:
      lines as a string array
    Throws:
      `IOException` - problem reading lines
    Since:
      1.14.0

  - ### toNonNullReader

    public static Reader toNonNullReader(Reader reader)
    Gets an "empty" reader (zero size) when the supplied reader is `null`. Else, return the supplied reader.
    Parameters:
      `reader` - original reader
    Returns:
      the supplied reader, or an empty reader
    Since:
      2.0.0

  - ### toNonNullInputStream

    public static InputStream toNonNullInputStream(InputStream is)
    Gets an "empty" input stream (zero size) when the supplied input stream is `null`. Else, return the supplied input stream.
    Parameters:
      `is` - original input stream
    Returns:
      the supplied input stream, or an empty input stream
    Since:
      2.0.0

  - ### toNonNullWriter

    public static Writer toNonNullWriter(Writer writer)
    Gets a non-effective writer when the supplied writer is `null` (writing to it has no effect). Else, return the supplied writer.
    Parameters:
      `writer` - original writer
    Returns:
      the supplied writer, or an empty writer
    Since:
      3.0.0

  - ### toNonNullOutputStream

    public static OutputStream toNonNullOutputStream(OutputStream os)
    Gets a non-effective output stream when the supplied output stream is `null` (writing to it has no effect). Else, return the supplied output stream.
    Parameters:
      `os` - original output stream
    Returns:
      the supplied output stream, or an empty output stream
    Since:
      3.0.0

  - ### consume

    public static int consume(InputStream is) throws IOException
    Fully consumes an input stream.
    Parameters:
      `is` - input stream
    Returns:
      number of bytes consumed
    Throws:
      `IOException` - could not consume stream
    Since:
      2.0.0

  - ### consume

    public static int consume(Reader reader) throws IOException
    Fully consumes an input stream.
    Parameters:
      `reader` - reader
    Returns:
      number of characters consumed
    Throws:
      `IOException` - could not consume reader
    Since:
      2.0.0

  - ### consumeUntil

    public static int consumeUntil(Reader reader, IntPredicate predicate) throws IOException
    Consumes markable reader characters until the predicate returns `true` for a character or the end of stream is reached. The character ending the consumption is not consumed (i.e., the reader cursor is reset just before that character).
    Parameters:
      `reader` - the reader to consume
      `predicate` - the character evaluation condition
    Returns:
      number of characters consumed (0 if reader is `null`)
    Throws:
      `IOException` - could not consume stream
      `IllegalArgumentException` - if reader does not support mark
    Since:
      2.0.0

  - ### consumeUntil

    public static int consumeUntil(Reader reader, IntPredicate predicate, Appendable appendable) throws IOException
    Consumes markable reader characters until the predicate returns `true` for a character or the end of stream is reached. Optionally append the consumed characters to an `Appendable` (e.g. StringBuilder). The character ending the consumption is not consumed (i.e., the reader cursor is reset just before that character).
    Parameters:
      `reader` - the reader to consume
      `predicate` - the character evaluation condition
      `appendable` - optional, to append consumed characters
    Returns:
      number of characters consumed (0 if reader is `null`)
    Throws:
      `IOException` - could not consume stream
      `IllegalArgumentException` - if reader does not support mark
    Since:
      2.0.0

  - ### consumeUntil

    public static int consumeUntil(Reader reader, String str, Appendable appendable) throws IOException
    Consumes reader characters until after encountering the supplied string (the matching string is also consumed) or the end of stream is reached. Optionally append the consumed characters to an `Appendable` (e.g. StringBuilder). The matching string is also consumed.
    Parameters:
      `reader` - the reader to consume
      `str` - the string to match
      `appendable` - optional, to append consumed characters
    Returns:
      number of characters consumed (0 if reader is `null`)
    Throws:
      `IOException` - could not consume stream
    Since:
      2.0.0

  - ### consumeWhile

    public static int consumeWhile(Reader reader, IntPredicate predicate) throws IOException
    Consumes markable reader characters while the predicate returns `true` for a character or the end of stream is reached. The character ending the consumption is not consumed (i.e., the reader cursor is reset just before that character).
    Parameters:
      `reader` - the reader to consume
      `predicate` - the character evaluation condition
    Returns:
      number of characters consumed (0 if reader is `null`)
    Throws:
      `IOException` - could not consume stream
      `IllegalArgumentException` - if reader does not support mark
    Since:
      2.0.0

  - ### consumeWhile

    public static int consumeWhile(Reader reader, IntPredicate predicate, Appendable appendable) throws IOException
    Consumes markable reader characters while the predicate returns `true` for a character or the end of stream is reached. Optionally append the consumed characters to an `Appendable` (e.g. StringBuilder). The character ending the consumption is not consumed (i.e., the reader cursor is reset just before that character).
    Parameters:
      `reader` - the reader to consume
      `predicate` - the character evaluation condition
      `appendable` - optional, to append consumed characters
    Returns:
      number of characters consumed (0 if reader is `null`)
    Throws:
      `IOException` - could not consume stream
      `IllegalArgumentException` - if reader does not support mark
    Since:
      2.0.0

  - ### closeQuietly

    public static void closeQuietly(Closeable... closeable)
    Given Apache has deprecated its `IOUtils#closeQuietly(java.io.Closeable)` method, this one offers an alternative.
    Parameters:
      `closeable` - one or more input streams to close quietly
    Since:
      2.0.0