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 pre-defined 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`

  ## Example 1 - Detect and exclude a UTF-8 BOM

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

  ## Example 2 - Detect a UTF-8 BOM (but don't exclude it)

       boolean include = true;
       BOMInputStream bomIn = new BOMInputStream(in, include);
       if (bomIn.hasBOM()) {
           // has a UTF-8 BOM
       }

  ## Example 3 - Detect Multiple BOMs

       BOMInputStream bomIn = new BOMInputStream(in,
         ByteOrderMark.UTF_16LE, ByteOrderMark.UTF_16BE,
         ByteOrderMark.UTF_32LE, ByteOrderMark.UTF_32BE
         );
       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
       }

  Since:
    2.0
  See Also:
    `ByteOrderMark`, Wikipedia - Byte Order Mark

- - ### Field Summary

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

      `in`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BOMInputStream(InputStream delegate)` Constructs a new BOM InputStream that excludes a `ByteOrderMark.UTF_8` BOM.
    `BOMInputStream(InputStream delegate, boolean include)` Constructs a new BOM InputStream that detects a a `ByteOrderMark.UTF_8` and optionally includes it.
    `BOMInputStream(InputStream delegate, boolean include, ByteOrderMark... boms)` Constructs a new BOM InputStream that detects the specified BOMs and optionally includes them.
    `BOMInputStream(InputStream delegate, ByteOrderMark... boms)` Constructs a new BOM InputStream that excludes the specified BOMs.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `ByteOrderMark` | `getBOM()` Return the BOM (Byte Order Mark).
    `String` | `getBOMCharsetName()` Return the BOM charset Name - `ByteOrderMark.getCharsetName()`.
    `boolean` | `hasBOM()` Indicates whether the stream contains one of the specified BOMs.
    `boolean` | `hasBOM(ByteOrderMark bom)` Indicates 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, close, handleIOException, markSupported`

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

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

- - ### Constructor Detail

    - #### BOMInputStream

          public BOMInputStream(InputStream delegate)

      Constructs a new BOM InputStream that excludes a `ByteOrderMark.UTF_8` BOM.
      Parameters:
        `delegate` - the InputStream to delegate to

    - #### BOMInputStream

          public BOMInputStream(InputStream delegate,
                                boolean include)

      Constructs a new BOM InputStream that detects a 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

    - #### BOMInputStream

          public BOMInputStream(InputStream delegate,
                                ByteOrderMark... boms)

      Constructs a new BOM InputStream that excludes the specified BOMs.
      Parameters:
        `delegate` - the InputStream to delegate to
        `boms` - The BOMs to detect and exclude

    - #### BOMInputStream

          public BOMInputStream(InputStream delegate,
                                boolean include,
                                ByteOrderMark... boms)

      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

  - ### Method Detail

    - #### hasBOM

          public boolean hasBOM()
                         throws IOException

      Indicates 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

      Indicates 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

    - #### getBOM

          public ByteOrderMark getBOM()
                               throws IOException

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

    - #### getBOMCharsetName

          public String getBOMCharsetName()
                                   throws IOException

      Return 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

    - #### 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,
                          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

    - #### 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

    - #### mark

          public void mark(int readlimit)

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

    - #### 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

Copyright © 2002–2020 The Apache Software Foundation. All rights reserved.