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, see `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
       }

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

- - ### Nested Class Summary

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

  - ### Field Summary

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

      `in`

  - ### Constructor Summary

    Constructors
    Constructor and 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

    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 BOM (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`

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

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

- - ### Constructor Detail

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

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

      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

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