org.apache.commons.io.input

## Class BOMInputStream

- java.lang.Object
- - java.io.InputStream
  - - java.io.FilterInputStream
    - - org.apache.commons.io.input.ProxyInputStream
      - - org.apache.commons.io.input.BOMInputStream

- All Implemented Interfaces:
    Closeable, 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:

  - UTF-8 - `ByteOrderMark.UTF_8`
  - UTF-16BE - `ByteOrderMark.UTF_16LE`
  - UTF-16LE - `ByteOrderMark.UTF_16BE`
  - UTF-32BE - `ByteOrderMark.UTF_32LE`
  - UTF-32LE - `ByteOrderMark.UTF_32BE`

  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.

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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `BOMInputStream.Builder` Builds a new `BOMInputStream`.

    - ### Nested classes/interfaces inherited from class org.apache.commons.io.input.ProxyInputStream

      `ProxyInputStream.AbstractBuilder<T,B extends AbstractStreamBuilder<T,B>>`

  - ### Field Summary

    - ### Fields inherited from class java.io.FilterInputStream

      `in`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static BOMInputStream.Builder` | `builder()` Constructs a new `BOMInputStream.Builder`.
    `ByteOrderMark` | `getBOM()` Gets the ByteOrderMark (Byte Order Mark).
    `String` | `getBOMCharsetName()` Gets the BOM charset Name - `ByteOrderMark.getCharsetName()`.
    `boolean` | `hasBOM()` Tests whether the stream contains one of the specified BOMs.
    `boolean` | `hasBOM(ByteOrderMark bom)` Tests whether the stream contains the specified BOM.
    `void` | `mark(int readLimit)` Invokes the delegate's `mark(int)` method.
    `int` | `read()` Invokes the delegate's `read()` method, detecting and optionally skipping BOM.
    `int` | `read(byte[] buf)` Invokes the delegate's `read(byte[])` method, detecting and optionally skipping BOM.
    `int` | `read(byte[] buf, int off, int len)` Invokes the delegate's `read(byte[], int, int)` method, detecting and optionally skipping BOM.
    `void` | `reset()` Invokes the delegate's `reset()` method.
    `long` | `skip(long n)` Invokes the delegate's `skip(long)` method, detecting and optionally skipping BOM.

    - ### Methods inherited from class org.apache.commons.io.input.ProxyInputStream

      `afterRead, available, beforeRead, checkOpen, close, handleIOException, isClosed, markSupported, setReference, unwrap`

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### builder

          public static BOMInputStream.Builder builder()

      Constructs a new `BOMInputStream.Builder`.
      Returns:
        a new `BOMInputStream.Builder`.

    - #### getBOM

          public ByteOrderMark getBOM()
                               throws IOException

      Gets the ByteOrderMark (Byte Order Mark).
      Returns:
        The BOM or null if none matched.
      Throws:
        `IOException` - if an error reading the first bytes of the stream occurs.

    - #### getBOMCharsetName

          public String getBOMCharsetName()
                                   throws IOException

      Gets the BOM charset Name - `ByteOrderMark.getCharsetName()`.
      Returns:
        The BOM charset Name or null if no BOM found
      Throws:
        `IOException` - if an error reading the first bytes of the stream occurs

    - #### hasBOM

          public boolean hasBOM()
                         throws 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:
        `IOException` - if an error reading the first bytes of the stream occurs

    - #### hasBOM

          public boolean hasBOM(ByteOrderMark bom)
                         throws 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:
        `IllegalArgumentException` - if the BOM is not one the stream is configured to detect
        `IOException` - if an error reading the first bytes of the stream occurs

    - #### mark

          public void mark(int readLimit)

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

    - #### read

          public int read()
                   throws 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:
        `IOException` - if an I/O error occurs

    - #### read

          public int read(byte[] buf)
                   throws IOException

      Invokes the delegate's `read(byte[])` method, detecting and optionally skipping BOM.
      Overrides:
        `read` in class `ProxyInputStream`
      Parameters:
        `buf` - the buffer to read the bytes into
      Returns:
        the number of bytes read (excluding BOM) or -1 if the end of stream
      Throws:
        `IOException` - if an I/O error occurs

    - #### read

          public int read(byte[] buf,
                          int off,
                          int len)
                   throws IOException

      Invokes the delegate's `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:
        `IOException` - if an I/O error occurs

    - #### reset

          public void reset()
                     throws IOException

      Invokes the delegate's `reset()` method.
      Overrides:
        `reset` in class `ProxyInputStream`
      Throws:
        `IOException` - if an I/O error occurs

    - #### skip

          public long skip(long n)
                    throws IOException

      Invokes the delegate's `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:
        `IOException` - if an I/O error occurs