Package com.globalmentor.io

Class InputStreams

  • public class InputStreams
extends java.lang.Object
    Class to manipulate input streams.
    Author:
    Garret Wilson

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.io.InputStream EMPTY_INPUT_STREAM
      The shared instance of an input stream with no content.

    • Constructor Summary

      Constructors 
      Constructor Description
      InputStreams()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.io.InputStream checkMarkSupported​(java.io.InputStream inputStream)
      Checks whether the given input stream supports mark/reset and throws an exception if not.
      static java.nio.charset.Charset detectCharset​(java.io.InputStream inputStream)
      Attempts to automatically detect the charset of a particular input stream based upon its byte order marker (BOM).
      static java.nio.charset.Charset detectCharset​(java.io.InputStream inputStream, java.nio.charset.Charset defaultCharset)
      Attempts to automatically detect the charset from the byte order mark (BOM) of a particular input stream.
      static byte[] getBytes​(java.io.InputStream inputStream)
      Loads the contents of an input stream into an array of bytes.
      static byte[] getBytes​(java.io.InputStream inputStream, int length)
      Reads a specified number of bytes from the stream and returns them in a byte array.
      static byte[] getBytes​(java.io.InputStream inputStream, long offset, int length)
      Reads a specified number of bytes from the stream and returns them in a byte array, starting at a given offset.
      static boolean isEmpty​(java.io.InputStream inputStream)
      Checks whether the given input stream is empty (at its end).
      static int read​(java.io.InputStream inputStream, byte[] buffer)
      Fills a buffer with bytes from an input stream, blocking until the buffer is full or the end of the stream is reached.
      static java.io.InputStream toMarkSupportedInputStream​(java.io.InputStream inputStream)
      Retrieves an input stream that support mark/reset.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • EMPTY_INPUT_STREAM

        public static final java.io.InputStream EMPTY_INPUT_STREAM
        The shared instance of an input stream with no content.

    • Constructor Detail

      • InputStreams

        public InputStreams()

    • Method Detail

      • getBytes

        public static byte[] getBytes​(java.io.InputStream inputStream)
                       throws java.io.IOException
        Loads the contents of an input stream into an array of bytes. This is accomplished by creating a series of smaller buffers and, once the end of the stream has been reached, creating a new buffer and copying the contents of each buffer into the new buffer. This is assumed to be faster than using ByteArrayOutputStream because that class copies all bytes that have been read each time the buffer needs to be expanded. The input stream will be left open after this operation.
        Parameters:
        inputStream - The input stream from which to read.
        Returns:
        An array of bytes from the input stream.
        Throws:
        java.io.IOException - Thrown if there is an error loading the bytes.

      • getBytes

        public static byte[] getBytes​(java.io.InputStream inputStream,
                              int length)
                       throws java.io.IOException
        Reads a specified number of bytes from the stream and returns them in a byte array.
        Parameters:
        inputStream - The input stream from which to read.
        length - The number of bytes to read
        Returns:
        An array of bytes containing the read characters, which may be shorter than the length specified if the number of bytes actually available were less than requested.
        Throws:
        java.lang.IllegalArgumentException - if the offset or the length is negative.
        java.io.IOException - if there is an error reading from the input stream.

      • getBytes

        public static byte[] getBytes​(java.io.InputStream inputStream,
                              long offset,
                              int length)
                       throws java.io.IOException
        Reads a specified number of bytes from the stream and returns them in a byte array, starting at a given offset.
        Parameters:
        inputStream - The input stream from which to read.
        offset - The number of bytes to skip at the beginning of the input stream.
        length - The number of bytes to read
        Returns:
        An array of bytes containing the read characters, which may be shorter than the length specified if the number of bytes actually available were less than requested.
        Throws:
        java.lang.IllegalArgumentException - if the offset or the length is negative.
        java.io.IOException - if there is an error reading from the input stream.

      • isEmpty

        public static boolean isEmpty​(java.io.InputStream inputStream)
                       throws java.io.IOException
        Checks whether the given input stream is empty (at its end). The input stream must support mark/reset.
        Parameters:
        inputStream - The input stream to check.
        Returns:
        true if reading from the given input stream would return -1.
        Throws:
        java.lang.NullPointerException - if the given input stream is null.
        java.lang.IllegalArgumentException - if the given input stream does not support mark/reset.
        java.io.IOException - if there was an error accessing the input stream.
        See Also:
        InputStream.markSupported()

      • checkMarkSupported

        public static java.io.InputStream checkMarkSupported​(java.io.InputStream inputStream)
        Checks whether the given input stream supports mark/reset and throws an exception if not.
        Parameters:
        inputStream - The input stream to check.
        Returns:
        The given input stream.
        Throws:
        java.lang.NullPointerException - if the given input stream is null.
        java.lang.IllegalArgumentException - if the given input stream does not support mark/reset.
        See Also:
        InputStream.markSupported()

      • toMarkSupportedInputStream

        public static java.io.InputStream toMarkSupportedInputStream​(java.io.InputStream inputStream)
        Retrieves an input stream that support mark/reset. If the given input stream supports mark/reset, it is returned; otherwise, a buffered input stream is constructed around the input stream and returned.
        Parameters:
        inputStream - The input stream ultimately supplying the information.
        Returns:
        An input stream that supports mark/reset, but that will return the same data as the given input stream.
        Throws:
        java.lang.NullPointerException - if the given input stream is null.
        See Also:
        InputStream.markSupported()

      • read

        public static int read​(java.io.InputStream inputStream,
                       byte[] buffer)
                throws java.io.IOException
        Fills a buffer with bytes from an input stream, blocking until the buffer is full or the end of the stream is reached.
        Parameters:
        inputStream - The input stream from which to read.
        buffer - The buffer to fill.
        Returns:
        The number of bytes actually read; if less than the size of the buffer, the end of the stream has been reached.
        Throws:
        java.io.IOException - if there is an error reading from the input stream.

      • detectCharset

        public static java.nio.charset.Charset detectCharset​(java.io.InputStream inputStream)
                                              throws java.io.IOException
        Attempts to automatically detect the charset of a particular input stream based upon its byte order marker (BOM).

        The input stream must be at its beginning and must support marking and resetting.

        Parameters:
        inputStream - The stream the charset of which will be detected.
        Returns:
        The charset detected, or null if no byte order mark could be detected.
        Throws:
        java.io.IOException - if a mixed byte order mark is encountered.
        java.io.IOException - if an I/O error occurred.
        See Also:
        ByteOrderMark, ByteOrderMark.isMixed()

      • detectCharset

        public static java.nio.charset.Charset detectCharset​(java.io.InputStream inputStream,
                                                     java.nio.charset.Charset defaultCharset)
                                              throws java.io.IOException
        Attempts to automatically detect the charset from the byte order mark (BOM) of a particular input stream.

        The input stream must be at its beginning and must support marking and resetting.

        Parameters:
        inputStream - The stream the charset of which will be detected.
        defaultCharset - The charset to return if the encoding can't be determined by the byte order mark.
        Returns:
        The charset detected, or the given default charset if no byte order mark could be detected.
        Throws:
        java.io.IOException - if a mixed byte order mark is encountered.
        java.io.IOException - if an I/O error occurred.
        See Also:
        ByteOrderMark, ByteOrderMark.isMixed()