Package 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.

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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  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`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BOMInputStream(InputStream delegate)`
  Deprecated.
  Use `builder()`, `BOMInputStream.Builder`, and `BOMInputStream.Builder.get()`
  `BOMInputStream(InputStream delegate, boolean include)`
  Deprecated.
  Use `builder()`, `BOMInputStream.Builder`, and `BOMInputStream.Builder.get()`
  `BOMInputStream(InputStream delegate, boolean include, ByteOrderMark... boms)`
  Deprecated.
  Use `builder()`, `BOMInputStream.Builder`, and `BOMInputStream.Builder.get()`
  `BOMInputStream(InputStream delegate, ByteOrderMark... boms)`
  Deprecated.
  Use `builder()`, `BOMInputStream.Builder`, and `BOMInputStream.Builder.get()`

- ## Method Summary

  Modifier and Type
  Method
  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, close, handleIOException, markSupported, setReference, unwrap`

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

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

- ## Constructor Details

  - ### BOMInputStream

    @Deprecated public BOMInputStream(InputStream delegate)
    Deprecated.
    Use `builder()`, `BOMInputStream.Builder`, and `BOMInputStream.Builder.get()`
    Constructs a new BOM InputStream that excludes a `ByteOrderMark.UTF_8` BOM.
    Parameters:
      `delegate` - the InputStream to delegate to

  - ### BOMInputStream

    @Deprecated public BOMInputStream(InputStream delegate, boolean include)
    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

  - ### BOMInputStream

    @Deprecated public BOMInputStream(InputStream delegate, boolean include, ByteOrderMark... boms)
    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

  - ### BOMInputStream

    @Deprecated public BOMInputStream(InputStream delegate, ByteOrderMark... boms)
    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

- ## Method Details

  - ### builder

    public static BOMInputStream.Builder builder()
    Constructs a new `BOMInputStream.Builder`.
    Returns:
      a new `BOMInputStream.Builder`.
    Since:
      2.12.0

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