Module de.cuioss.java.tools
Package de.cuioss.tools.io

Class IOStreams

java.lang.Object
de.cuioss.tools.io.IOStreams
public 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 final int
    DEFAULT_BUFFER_SIZE
    The default buffer size (4096) to use in copy methods.
    static final int
    EOF
    Represents the end-of-file (or stream).

  • Constructor Summary

    Constructors
    Constructor
    Description
    IOStreams()
     

  • Method Summary

    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.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

  • Method Details

    • 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

    • toInputStream

      public static InputStream toInputStream(String input)
      Wraps an ByteArrayInputStream around a given String assuming StandardCharsets.UTF_8
      Parameters:
      input - to be wrapped, may be null or empty
      Returns:
      the created InputStream

    • 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

    • toBufferedReader

      public static BufferedReader toBufferedReader(Reader reader)
      Returns the given reader if it is a BufferedReader, otherwise creates a BufferedReader from the given reader.
      Parameters:
      reader - the reader to wrap or return (not null)
      Returns:
      the given reader or a new BufferedReader for the given reader
      Throws:
      NullPointerException - if the input parameter is null

    • 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(InputStream input, long toSkip) throws IOException
      Skips bytes from an input byte stream. This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case for skip() implementations in subclasses of InputStream.

      Note that the implementation uses InputStream.read(byte[], int, int) rather than delegating to InputStream.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 bytes are skipped.

      Parameters:
      input - byte stream to skip
      toSkip - number of bytes to skip.
      Returns:
      number of bytes actually skipped.
      Throws:
      IOException - if there is a problem reading the file
      IllegalArgumentException - if toSkip is negative
      See Also:

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

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

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

    • 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