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:

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.

Since:

2.0

See Also:

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

Class BOMInputStream

Example 1 - Detecting and excluding a UTF-8 BOM

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

Example 3 - Detecting Multiple BOMs

Nested Class Summary

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

Field Summary

Fields inherited from class java.io.FilterInputStream

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Constructor Details

BOMInputStream

BOMInputStream

BOMInputStream

BOMInputStream

Method Details

builder

getBOM

getBOMCharsetName

hasBOM

hasBOM

mark

read

read

read

reset

skip