Package io.cui.tools.io

Class IOStreams

  • public final class IOStreams
extends Object
    Provides a number of utilities in context InputStream and OutputStreams. The content is inspired / copied from org.apache.commons.io.IOUtils
    Author:
    Oliver Wolff

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int DEFAULT_BUFFER_SIZE
      The default buffer size (4096) to use in copy methods.
      static int EOF
      Represents the end-of-file (or stream).

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static boolean contentEquals​(InputStream input1, InputStream input2)
      Compares the contents of two Streams to determine if they are equal or not.
      static boolean contentEquals​(Reader input1, Reader input2)
      Compares the contents of two Readers to determine if they are equal or not.
      static int copy​(InputStream input, OutputStream output)
      Copies bytes from an InputStream to an OutputStream.
      static long copy​(InputStream input, OutputStream output, int bufferSize)
      Copies bytes from an InputStream to an OutputStream using an internal buffer of the given size.
      static void copy​(InputStream input, Writer output, String inputEncoding)
      Copies bytes from an InputStream to chars on a Writer using the specified character encoding.
      static void copy​(InputStream input, Writer output, Charset inputEncoding)
      Copies bytes from an InputStream to chars on a Writer using the specified character encoding.
      static void copy​(Reader input, OutputStream output, String outputEncoding)
      Copies chars from a Reader to bytes on an OutputStream using the specified character encoding, and calling flush.
      static void copy​(Reader input, OutputStream output, Charset outputEncoding)
      Copies chars from a Reader to bytes on an OutputStream using the specified character encoding, and calling flush.
      static int copy​(Reader input, Writer output)
      Copies chars from a Reader to a Writer.
      static long copyLarge​(InputStream input, OutputStream output)
      Copies bytes from a large (over 2GB) InputStream to an OutputStream.
      static long copyLarge​(InputStream input, OutputStream output, byte[] buffer)
      Copies bytes from a large (over 2GB) InputStream to an OutputStream.
      static long copyLarge​(InputStream input, OutputStream output, long inputOffset, long length)
      Copies some or all bytes from a large (over 2GB) InputStream to an OutputStream, optionally skipping input bytes.
      static long copyLarge​(InputStream input, OutputStream output, long inputOffset, long length, byte[] buffer)
      Copies some or all bytes from a large (over 2GB) InputStream to an OutputStream, optionally skipping input bytes.
      static long copyLarge​(Reader input, Writer output)
      Copies chars from a large (over 2GB) Reader to a Writer.
      static long copyLarge​(Reader input, Writer output, char[] buffer)
      Copies chars from a large (over 2GB) Reader to a Writer.
      static long copyLarge​(Reader input, Writer output, long inputOffset, long length)
      Copies some or all chars from a large (over 2GB) InputStream to an OutputStream, optionally skipping input chars.
      static long copyLarge​(Reader input, Writer output, long inputOffset, long length, char[] buffer)
      Copies some or all chars from a large (over 2GB) InputStream to an OutputStream, optionally skipping input chars.
      static long skip​(InputStream input, long toSkip)
      Skips bytes from an input byte stream.
      static long skip​(Reader input, long toSkip)
      Skips characters from an input character stream.
      static void skipFully​(InputStream input, long toSkip)
      Skips the requested number of bytes or fail if there are not enough left.
      static void skipFully​(Reader input, long toSkip)
      Skips the requested number of characters or fail if there are not enough left.
      static BufferedReader toBufferedReader​(Reader reader)
      Returns the given reader if it is a BufferedReader, otherwise creates a BufferedReader from the given reader.
      static byte[] toByteArray​(InputStream input)
      Gets the contents of an InputStream as a byte[].
      static Charset toCharset​(String charset)
      Returns a Charset for the named charset.
      static Charset toCharset​(Charset charset)
      Returns the given Charset or the default Charset if the given Charset is null.
      static InputStream toInputStream​(String input)
      Wraps an ByteArrayInputStream around a given String assuming StandardCharsets.UTF_8
      static String toString​(InputStream input)
      Gets the contents of an InputStream as a String using the specified character encoding.
      static String toString​(InputStream input, Charset encoding)
      Gets the contents of an InputStream as a String using the specified character encoding.

    • Method Detail

      • contentEquals

        public static boolean contentEquals​(InputStream input1,
                                    InputStream input2)
                             throws IOException
        Compares the contents of two Streams to determine if they are equal or not.

        This method buffers the input internally using BufferedInputStream if they are not already buffered.

        Parameters:
        input1 - the first stream
        input2 - the second stream
        Returns:
        true if the content of the streams are equal or they both don't exist, false otherwise
        Throws:
        NullPointerException - if either input is null
        IOException - if an I/O error occurs

      • contentEquals

        public static boolean contentEquals​(Reader input1,
                                    Reader input2)
                             throws IOException
        Compares the contents of two Readers to determine if they are equal or not.

        This method buffers the input internally using BufferedReader if they are not already buffered.

        Parameters:
        input1 - the first reader
        input2 - the second reader
        Returns:
        true if the content of the readers are equal or they both don't exist, false otherwise
        Throws:
        NullPointerException - if either input is null
        IOException - if an I/O error occurs

      • toString

        public static String toString​(InputStream input)
                       throws IOException
        Gets the contents of an InputStream as a String using the specified character encoding.

        This method buffers the input internally, so there is no need to use a BufferedInputStream.

        Parameters:
        input - the InputStream to read from, using UTF-8 encoding.
        Returns:
        the requested String
        Throws:
        NullPointerException - if the input is null
        IOException - if an I/O error occurs

      • toString

        public static String toString​(InputStream input,
                              Charset encoding)
                       throws IOException
        Gets the contents of an InputStream as a String using the specified character encoding.

        This method buffers the input internally, so there is no need to use a BufferedInputStream.

        Parameters:
        input - the InputStream to read from
        encoding - the encoding to use, null means platform default
        Returns:
        the requested String
        Throws:
        IllegalArgumentException - if the input is null
        IOException - if an I/O error occurs

      • copy

        public static int copy​(InputStream input,
                       OutputStream output)
                throws IOException
        Copies bytes from an InputStream to an OutputStream.

        This method buffers the input internally, so there is no need to use a BufferedInputStream.

        Large streams (over 2GB) will return a bytes copied value of -1 after the copy has completed since the correct number of bytes cannot be returned as an int. For large streams use the copyLarge(InputStream, OutputStream) method.

        Parameters:
        input - the InputStream to read from
        output - the OutputStream to write to
        Returns:
        the number of bytes copied, or -1 if > Integer.MAX_VALUE
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copy

        public static long copy​(InputStream input,
                        OutputStream output,
                        int bufferSize)
                 throws IOException
        Copies bytes from an InputStream to an OutputStream using an internal buffer of the given size.

        This method buffers the input internally, so there is no need to use a BufferedInputStream.

        Parameters:
        input - the InputStream to read from
        output - the OutputStream to write to
        bufferSize - the bufferSize used to copy from the input to the output
        Returns:
        the number of bytes copied
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copyLarge

        public static long copyLarge​(InputStream input,
                             OutputStream output)
                      throws IOException
        Copies bytes from a large (over 2GB) InputStream to an OutputStream.

        This method buffers the input internally, so there is no need to use a BufferedInputStream.

        The buffer size is given by DEFAULT_BUFFER_SIZE.

        Parameters:
        input - the InputStream to read from
        output - the OutputStream to write to
        Returns:
        the number of bytes copied
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copyLarge

        public static long copyLarge​(InputStream input,
                             OutputStream output,
                             byte[] buffer)
                      throws IOException
        Copies bytes from a large (over 2GB) InputStream to an OutputStream.

        This method uses the provided buffer, so there is no need to use a BufferedInputStream.

        Parameters:
        input - the InputStream to read from
        output - the OutputStream to write to
        buffer - the buffer to use for the copy
        Returns:
        the number of bytes copied
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copyLarge

        public static long copyLarge​(InputStream input,
                             OutputStream output,
                             long inputOffset,
                             long length)
                      throws IOException
        Copies some or all bytes from a large (over 2GB) InputStream to an OutputStream, optionally skipping input bytes.

        This method buffers the input internally, so there is no need to use a BufferedInputStream.

        Note that the implementation uses skip(InputStream, long). This means that the method may be considerably less efficient than using the actual skip implementation, this is done to guarantee that the correct number of characters are skipped.

        The buffer size is given by DEFAULT_BUFFER_SIZE.
        Parameters:
        input - the InputStream to read from
        output - the OutputStream to write to
        inputOffset - number of bytes to skip from input before copying -ve values are ignored
        length - number of bytes to copy. -ve means all
        Returns:
        the number of bytes copied
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copyLarge

        public static long copyLarge​(InputStream input,
                             OutputStream output,
                             long inputOffset,
                             long length,
                             byte[] buffer)
                      throws IOException
        Copies some or all bytes from a large (over 2GB) InputStream to an OutputStream, optionally skipping input bytes.

        This method uses the provided buffer, so there is no need to use a BufferedInputStream.

        Note that the implementation uses skip(InputStream, long). This means that the method may be considerably less efficient than using the actual skip implementation, this is done to guarantee that the correct number of characters are skipped.

        Parameters:
        input - the InputStream to read from
        output - the OutputStream to write to
        inputOffset - number of bytes to skip from input before copying -ve values are ignored
        length - number of bytes to copy. -ve means all
        buffer - the buffer to use for the copy
        Returns:
        the number of bytes copied
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copy

        public static void copy​(InputStream input,
                        Writer output,
                        Charset inputEncoding)
                 throws IOException
        Copies bytes from an InputStream to chars on a Writer using the specified character encoding.

        This method buffers the input internally, so there is no need to use a BufferedInputStream.

        This method uses InputStreamReader.

        Parameters:
        input - the InputStream to read from
        output - the Writer to write to
        inputEncoding - the encoding to use for the input stream, null means platform default
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • toCharset

        public static Charset toCharset​(Charset charset)
        Returns the given Charset or the default Charset if the given Charset is null.
        Parameters:
        charset - A charset or null.
        Returns:
        the given Charset or the default Charset if the given Charset is null

      • copy

        public static void copy​(InputStream input,
                        Writer output,
                        String inputEncoding)
                 throws IOException
        Copies bytes from an InputStream to chars on a Writer using the specified character encoding.

        This method buffers the input internally, so there is no need to use a BufferedInputStream.

        Character encoding names can be found at IANA.

        This method uses InputStreamReader.

        Parameters:
        input - the InputStream to read from
        output - the Writer to write to
        inputEncoding - the encoding to use for the InputStream, null means platform default
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs
        UnsupportedCharsetException - thrown instead of .UnsupportedEncodingException in version 2.2 if the encoding is not supported.

      • toCharset

        public static Charset toCharset​(String charset)
        Returns a Charset for the named charset. If the name is null, return the default Charset.
        Parameters:
        charset - The name of the requested charset, may be null.
        Returns:
        a Charset for the named charset
        Throws:
        UnsupportedCharsetException - If the named charset is unavailable

      • copy

        public static int copy​(Reader input,
                       Writer output)
                throws IOException
        Copies chars from a Reader to a Writer.

        This method buffers the input internally, so there is no need to use a BufferedReader.

        Large streams (over 2GB) will return a chars copied value of -1 after the copy has completed since the correct number of chars cannot be returned as an int. For large streams use the copyLarge(Reader, Writer) method.

        Parameters:
        input - the Reader to read from
        output - the Writer to write to
        Returns:
        the number of characters copied, or -1 if > Integer.MAX_VALUE
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copyLarge

        public static long copyLarge​(Reader input,
                             Writer output)
                      throws IOException
        Copies chars from a large (over 2GB) Reader to a Writer.

        This method buffers the input internally, so there is no need to use a BufferedReader.

        The buffer size is given by DEFAULT_BUFFER_SIZE.

        Parameters:
        input - the Reader to read from
        output - the Writer to write to
        Returns:
        the number of characters copied
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copyLarge

        public static long copyLarge​(Reader input,
                             Writer output,
                             char[] buffer)
                      throws IOException
        Copies chars from a large (over 2GB) Reader to a Writer.

        This method uses the provided buffer, so there is no need to use a BufferedReader.

        Parameters:
        input - the Reader to read from
        output - the Writer to write to
        buffer - the buffer to be used for the copy
        Returns:
        the number of characters copied
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copyLarge

        public static long copyLarge​(Reader input,
                             Writer output,
                             long inputOffset,
                             long length)
                      throws IOException
        Copies some or all chars from a large (over 2GB) InputStream to an OutputStream, optionally skipping input chars.

        This method buffers the input internally, so there is no need to use a BufferedReader.

        The buffer size is given by DEFAULT_BUFFER_SIZE.

        Parameters:
        input - the Reader to read from
        output - the Writer to write to
        inputOffset - number of chars to skip from input before copying -ve values are ignored
        length - number of chars to copy. -ve means all
        Returns:
        the number of chars copied
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copyLarge

        public static long copyLarge​(Reader input,
                             Writer output,
                             long inputOffset,
                             long length,
                             char[] buffer)
                      throws IOException
        Copies some or all chars from a large (over 2GB) InputStream to an OutputStream, optionally skipping input chars.

        This method uses the provided buffer, so there is no need to use a BufferedReader.

        Parameters:
        input - the Reader to read from
        output - the Writer to write to
        inputOffset - number of chars to skip from input before copying -ve values are ignored
        length - number of chars to copy. -ve means all
        buffer - the buffer to be used for the copy
        Returns:
        the number of chars copied
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copy

        public static void copy​(Reader input,
                        OutputStream output,
                        Charset outputEncoding)
                 throws IOException
        Copies chars from a Reader to bytes on an OutputStream using the specified character encoding, and calling flush.

        This method buffers the input internally, so there is no need to use a BufferedReader.

        Due to the implementation of OutputStreamWriter, this method performs a flush.

        This method uses OutputStreamWriter.

        Parameters:
        input - the Reader to read from
        output - the OutputStream to write to
        outputEncoding - the encoding to use for the OutputStream, null means platform default
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs

      • copy

        public static void copy​(Reader input,
                        OutputStream output,
                        String outputEncoding)
                 throws IOException
        Copies chars from a Reader to bytes on an OutputStream using the specified character encoding, and calling flush.

        This method buffers the input internally, so there is no need to use a BufferedReader.

        Character encoding names can be found at IANA.

        Due to the implementation of OutputStreamWriter, this method performs a flush.

        This method uses OutputStreamWriter.

        Parameters:
        input - the Reader to read from
        output - the OutputStream to write to
        outputEncoding - the encoding to use for the OutputStream, null means platform default
        Throws:
        NullPointerException - if the input or output is null
        IOException - if an I/O error occurs
        UnsupportedCharsetException - thrown instead of .UnsupportedEncodingException in version 2.2 if the encoding is not supported.

      • skip

        public static long skip​(Reader input,
                        long toSkip)
                 throws IOException
        Skips characters from an input character stream. This implementation guarantees that it will read as many characters as possible before giving up; this may not always be the case for skip() implementations in subclasses of Reader.

        Note that the implementation uses Reader.read(char[], int, int) rather than delegating to Reader.skip(long). This means that the method may be considerably less efficient than using the actual skip implementation, this is done to guarantee that the correct number of characters are skipped.

        Parameters:
        input - character stream to skip
        toSkip - number of characters to skip.
        Returns:
        number of characters actually skipped.
        Throws:
        IOException - if there is a problem reading the file
        IllegalArgumentException - if toSkip is negative
        See Also:
        Reader.skip(long), IO-203 - Add skipFully() method for InputStreams

      • skipFully

        public static void skipFully​(InputStream input,
                             long toSkip)
                      throws IOException
        Skips the requested number of bytes or fail if there are not enough left.

        This allows for the possibility that InputStream.skip(long) may not skip as many bytes as requested (most likely because of reaching EOF).

        Note that the implementation uses skip(InputStream, long). This means that the method may be considerably less efficient than using the actual skip implementation, this is done to guarantee that the correct number of characters are skipped.

        Parameters:
        input - stream to skip
        toSkip - the number of bytes to skip
        Throws:
        IOException - if there is a problem reading the file
        IllegalArgumentException - if toSkip is negative
        EOFException - if the number of bytes skipped was incorrect
        See Also:
        InputStream.skip(long)

      • skipFully

        public static void skipFully​(Reader input,
                             long toSkip)
                      throws IOException
        Skips the requested number of characters or fail if there are not enough left.

        This allows for the possibility that Reader.skip(long) may not skip as many characters as requested (most likely because of reaching EOF).

        Note that the implementation uses skip(Reader, long). This means that the method may be considerably less efficient than using the actual skip implementation, this is done to guarantee that the correct number of characters are skipped.

        Parameters:
        input - stream to skip
        toSkip - the number of characters to skip
        Throws:
        IOException - if there is a problem reading the file
        IllegalArgumentException - if toSkip is negative
        EOFException - if the number of characters skipped was incorrect
        See Also:
        Reader.skip(long)

      • toByteArray

        public static byte[] toByteArray​(InputStream input)
                          throws IOException
        Gets the contents of an InputStream as a byte[].

        This method buffers the input internally, so there is no need to use a BufferedInputStream.

        Parameters:
        input - the InputStream to read from
        Returns:
        the requested byte array
        Throws:
        NullPointerException - if the input is null
        IOException - if an I/O error occurs