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:
java.io.Closeable
,java.lang.AutoCloseable
public class BOMInputStream extends ProxyInputStream
This class is used to wrap a stream that includes an encodedByteOrderMark
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 Description static class
BOMInputStream.Builder
Builds a newBOMInputStream
instance.
-
Field Summary
Fields Modifier and Type Field Description private java.util.List<ByteOrderMark>
boms
BOMs are sorted from longest to shortest.private ByteOrderMark
byteOrderMark
private static java.util.Comparator<ByteOrderMark>
ByteOrderMarkLengthComparator
Compares ByteOrderMark objects in descending length order.private int
fbIndex
private int
fbLength
private int[]
firstBytes
private boolean
include
private boolean
markedAtStart
private int
markFbIndex
-
Constructor Summary
Constructors Constructor Description BOMInputStream(java.io.InputStream delegate)
Deprecated.BOMInputStream(java.io.InputStream delegate, boolean include)
Deprecated.BOMInputStream(java.io.InputStream delegate, boolean include, ByteOrderMark... boms)
Deprecated.BOMInputStream(java.io.InputStream delegate, ByteOrderMark... boms)
Deprecated.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static BOMInputStream.Builder
builder()
Constructs a newBOMInputStream.Builder
.private ByteOrderMark
find()
Find a BOM with the specified bytes.ByteOrderMark
getBOM()
Gets the BOM (Byte Order Mark).java.lang.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'smark(int)
method.private boolean
matches(ByteOrderMark bom)
Checks if the bytes match a BOM.int
read()
Invokes the delegate'sread()
method, detecting and optionally skipping BOM.int
read(byte[] buf)
Invokes the delegate'sread(byte[])
method, detecting and optionally skipping BOM.int
read(byte[] buf, int off, int len)
Invokes the delegate'sread(byte[], int, int)
method, detecting and optionally skipping BOM.private int
readFirstBytes()
This method reads and either preserves or skips the first bytes in the stream.void
reset()
Invokes the delegate'sreset()
method.long
skip(long n)
Invokes the delegate'sskip(long)
method, detecting and optionally skipping BOM.-
Methods inherited from class org.apache.commons.io.input.ProxyInputStream
afterRead, available, beforeRead, close, handleIOException, markSupported
-
-
-
-
Field Detail
-
ByteOrderMarkLengthComparator
private static final java.util.Comparator<ByteOrderMark> ByteOrderMarkLengthComparator
Compares ByteOrderMark objects in descending length order.
-
boms
private final java.util.List<ByteOrderMark> boms
BOMs are sorted from longest to shortest.
-
byteOrderMark
private ByteOrderMark byteOrderMark
-
fbIndex
private int fbIndex
-
fbLength
private int fbLength
-
firstBytes
private int[] firstBytes
-
include
private final boolean include
-
markedAtStart
private boolean markedAtStart
-
markFbIndex
private int markFbIndex
-
-
Constructor Detail
-
BOMInputStream
@Deprecated public BOMInputStream(java.io.InputStream delegate)
Deprecated.Constructs a new BOM InputStream that excludes aByteOrderMark.UTF_8
BOM.- Parameters:
delegate
- the InputStream to delegate to
-
BOMInputStream
@Deprecated public BOMInputStream(java.io.InputStream delegate, boolean include)
Deprecated.Constructs a new BOM InputStream that detects aByteOrderMark.UTF_8
and optionally includes it.- Parameters:
delegate
- the InputStream to delegate toinclude
- true to include the UTF-8 BOM or false to exclude it
-
BOMInputStream
@Deprecated public BOMInputStream(java.io.InputStream delegate, boolean include, ByteOrderMark... boms)
Deprecated.Constructs a new BOM InputStream that detects the specified BOMs and optionally includes them.- Parameters:
delegate
- the InputStream to delegate toinclude
- true to include the specified BOMs or false to exclude themboms
- The BOMs to detect and optionally exclude
-
BOMInputStream
@Deprecated public BOMInputStream(java.io.InputStream delegate, ByteOrderMark... boms)
Deprecated.Constructs a new BOM InputStream that excludes the specified BOMs.- Parameters:
delegate
- the InputStream to delegate toboms
- The BOMs to detect and exclude
-
-
Method Detail
-
builder
public static BOMInputStream.Builder builder()
Constructs a newBOMInputStream.Builder
.- Returns:
- a new
BOMInputStream.Builder
. - Since:
- 2.12.0
-
find
private ByteOrderMark find()
Find a BOM with the specified bytes.- Returns:
- The matched BOM or null if none matched
-
getBOM
public ByteOrderMark getBOM() throws java.io.IOException
Gets the BOM (Byte Order Mark).- Returns:
- The BOM or null if none
- Throws:
java.io.IOException
- if an error reading the first bytes of the stream occurs
-
getBOMCharsetName
public java.lang.String getBOMCharsetName() throws java.io.IOException
Gets the BOM charset Name -ByteOrderMark.getCharsetName()
.- Returns:
- The BOM charset Name or null if no BOM found
- Throws:
java.io.IOException
- if an error reading the first bytes of the stream occurs
-
hasBOM
public boolean hasBOM() throws java.io.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:
java.io.IOException
- if an error reading the first bytes of the stream occurs
-
hasBOM
public boolean hasBOM(ByteOrderMark bom) throws java.io.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:
java.lang.IllegalArgumentException
- if the BOM is not one the stream is configured to detectjava.io.IOException
- if an error reading the first bytes of the stream occurs
-
mark
public void mark(int readlimit)
Invokes the delegate'smark(int)
method.- Overrides:
mark
in classProxyInputStream
- Parameters:
readlimit
- read ahead limit
-
matches
private boolean matches(ByteOrderMark bom)
Checks if the bytes match a BOM.- Parameters:
bom
- The BOM- Returns:
- true if the bytes match the bom, otherwise false
-
read
public int read() throws java.io.IOException
Invokes the delegate'sread()
method, detecting and optionally skipping BOM.- Overrides:
read
in classProxyInputStream
- Returns:
- the byte read (excluding BOM) or -1 if the end of stream
- Throws:
java.io.IOException
- if an I/O error occurs
-
read
public int read(byte[] buf) throws java.io.IOException
Invokes the delegate'sread(byte[])
method, detecting and optionally skipping BOM.- Overrides:
read
in classProxyInputStream
- 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:
java.io.IOException
- if an I/O error occurs
-
read
public int read(byte[] buf, int off, int len) throws java.io.IOException
Invokes the delegate'sread(byte[], int, int)
method, detecting and optionally skipping BOM.- Overrides:
read
in classProxyInputStream
- Parameters:
buf
- the buffer to read the bytes intooff
- The start offsetlen
- The number of bytes to read (excluding BOM)- Returns:
- the number of bytes read or -1 if the end of stream
- Throws:
java.io.IOException
- if an I/O error occurs
-
readFirstBytes
private int readFirstBytes() throws java.io.IOException
This method reads and either preserves or skips the first bytes in the stream. It behaves like the single-byteread()
method, either returning a valid byte or -1 to indicate that the initial bytes have been processed already.- Returns:
- the byte read (excluding BOM) or -1 if the end of stream
- Throws:
java.io.IOException
- if an I/O error occurs
-
reset
public void reset() throws java.io.IOException
Invokes the delegate'sreset()
method.- Overrides:
reset
in classProxyInputStream
- Throws:
java.io.IOException
- if an I/O error occurs
-
skip
public long skip(long n) throws java.io.IOException
Invokes the delegate'sskip(long)
method, detecting and optionally skipping BOM.- Overrides:
skip
in classProxyInputStream
- Parameters:
n
- the number of bytes to skip- Returns:
- the number of bytes to skipped or -1 if the end of stream
- Throws:
java.io.IOException
- if an I/O error occurs
-
-