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