Package org.apache.commons.io.input

Class BOMInputStream

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    public class BOMInputStream
extends ProxyInputStream
    This class is used to wrap a stream that includes an encoded ByteOrderMark as its first bytes.

    This class detects these bytes and, if required, can automatically skip them and return the subsequent byte as the first byte in the stream.

    The ByteOrderMark implementation has the following predefined BOMs:

    To build an instance, use BOMInputStream.Builder.

    Example 1 - Detecting and excluding a UTF-8 BOM

     BOMInputStream bomIn = BOMInputStream.builder().setInputStream(in).get();
 if (bomIn.hasBOM()) {
     // has a UTF-8 BOM
 }

    Example 2 - Detecting a UTF-8 BOM without excluding it

     boolean include = true;
 BOMInputStream bomIn = BOMInputStream.builder().setInputStream(in).setInclude(include).get();
 if (bomIn.hasBOM()) {
     // has a UTF-8 BOM
 }

    Example 3 - Detecting Multiple BOMs

     BOMInputStream bomIn = BOMInputStream.builder().setInputStream(in)
         .setByteOrderMarks(ByteOrderMark.UTF_16LE, ByteOrderMark.UTF_16BE, ByteOrderMark.UTF_32LE, ByteOrderMark.UTF_32BE).get();
 if (bomIn.hasBOM() == false) {
     // No BOM found
 } else if (bomIn.hasBOM(ByteOrderMark.UTF_16LE)) {
     // has a UTF-16LE BOM
 } else if (bomIn.hasBOM(ByteOrderMark.UTF_16BE)) {
     // has a UTF-16BE BOM
 } else if (bomIn.hasBOM(ByteOrderMark.UTF_32LE)) {
     // has a UTF-32LE BOM
 } else if (bomIn.hasBOM(ByteOrderMark.UTF_32BE)) {
     // has a UTF-32BE BOM
 }

    To build an instance, use BOMInputStream.Builder.

    This class is not thread-safe.

    Since:
    2.0
    See Also:
    BOMInputStream.Builder, ByteOrderMark, Wikipedia - Byte Order Mark

    • Constructor Detail

      • BOMInputStream

        @Deprecated
public BOMInputStream​(java.io.InputStream delegate,
                      boolean include)
               throws java.io.IOException
        Deprecated.
        Use builder(), BOMInputStream.Builder, and BOMInputStream.Builder.get().
        Constructs a new BOM InputStream that detects a ByteOrderMark.UTF_8 and optionally includes it.
        Parameters:
        delegate - the InputStream to delegate to.
        include - true to include the UTF-8 BOM or false to exclude it.
        Throws:
        java.io.IOException - if an error reading the first bytes of the stream occurs.

      • BOMInputStream

        @Deprecated
public BOMInputStream​(java.io.InputStream delegate,
                      boolean include,
                      ByteOrderMark... boms)
               throws java.io.IOException
        Deprecated.
        Use builder(), BOMInputStream.Builder, and BOMInputStream.Builder.get().
        Constructs a new BOM InputStream that detects the specified BOMs and optionally includes them.
        Parameters:
        delegate - the InputStream to delegate to.
        include - true to include the specified BOMs or false to exclude them.
        boms - The BOMs to detect and optionally exclude.
        Throws:
        java.io.IOException - if an error reading the first bytes of the stream occurs.

      • BOMInputStream

        @Deprecated
public BOMInputStream​(java.io.InputStream delegate,
                      ByteOrderMark... boms)
               throws java.io.IOException
        Deprecated.
        Use builder(), BOMInputStream.Builder, and BOMInputStream.Builder.get()
        Constructs a new BOM InputStream that excludes the specified BOMs.
        Parameters:
        delegate - the InputStream to delegate to.
        boms - The BOMs to detect and exclude.
        Throws:
        java.io.IOException - if an error reading the first bytes of the stream occurs.

    • Method Detail

      • getBOM

        public ByteOrderMark getBOM()
        Gets the ByteOrderMark (Byte Order Mark).
        Returns:
        The BOM or null if none matched.

      • getBOMCharsetName

        public java.lang.String getBOMCharsetName()
                                   throws java.io.IOException
        Gets the BOM charset Name - ByteOrderMark.getCharsetName().
        Returns:
        The BOM charset Name or null if no BOM found.
        Throws:
        java.io.IOException - if an error reading the first bytes of the stream occurs.

      • hasBOM

        public boolean hasBOM()
               throws java.io.IOException
        Tests whether the stream contains one of the specified BOMs.
        Returns:
        true if the stream has one of the specified BOMs, otherwise false if it does not.
        Throws:
        java.io.IOException - if an error reading the first bytes of the stream occurs.

      • hasBOM

        public boolean hasBOM​(ByteOrderMark bom)
               throws java.io.IOException
        Tests whether the stream contains the specified BOM.
        Parameters:
        bom - The BOM to check for.
        Returns:
        true if the stream has the specified BOM, otherwise false if it does not.
        Throws:
        java.lang.IllegalArgumentException - if the BOM is not one the stream is configured to detect.
        java.io.IOException - if an error reading the first bytes of the stream occurs.

      • mark

        public void mark​(int readLimit)
        Invokes the delegate's InputStream.mark(int) method.
        Overrides:
        mark in class ProxyInputStream
        Parameters:
        readLimit - read ahead limit.

      • read

        public int read()
         throws java.io.IOException
        Invokes the delegate's read() method, detecting and optionally skipping BOM.
        Overrides:
        read in class ProxyInputStream
        Returns:
        the byte read (excluding BOM) or -1 if the end of stream.
        Throws:
        java.io.IOException - if an I/O error occurs.

      • read

        public int read​(byte[] buf)
         throws java.io.IOException
        Invokes the delegate's InputStream.read(byte[]) method, detecting and optionally skipping BOM.
        Overrides:
        read in class ProxyInputStream
        Parameters:
        buf - the buffer to read the bytes into, never null
        Returns:
        the number of bytes read (excluding BOM) or -1 if the end of stream.
        Throws:
        java.lang.NullPointerException - if the buffer is null
        java.io.IOException - if an I/O error occurs.

      • read

        public int read​(byte[] buf,
                int off,
                int len)
         throws java.io.IOException
        Invokes the delegate's InputStream.read(byte[], int, int) method, detecting and optionally skipping BOM.
        Overrides:
        read in class ProxyInputStream
        Parameters:
        buf - the buffer to read the bytes into.
        off - The start offset.
        len - The number of bytes to read (excluding BOM).
        Returns:
        the number of bytes read or -1 if the end of stream.
        Throws:
        java.lang.NullPointerException - if the buffer is null.
        java.lang.IndexOutOfBoundsException - if off or len are negative, or if off + len is greater than buf.length.
        java.io.IOException - if an I/O error occurs.

      • reset

        public void reset()
           throws java.io.IOException
        Invokes the delegate's InputStream.reset() method.
        Overrides:
        reset in class ProxyInputStream
        Throws:
        java.io.IOException - if an I/O error occurs.

      • skip

        public long skip​(long n)
          throws java.io.IOException
        Invokes the delegate's InputStream.skip(long) method, detecting and optionally skipping BOM.
        Overrides:
        skip in class ProxyInputStream
        Parameters:
        n - the number of bytes to skip.
        Returns:
        the number of bytes to skipped or -1 if the end of stream.
        Throws:
        java.io.IOException - if an I/O error occurs.