Apache POI - Common 5.3.0 · org.apache.poi.util.IOUtils

Modifier and Type	Field and Description
private static int	BYTE_ARRAY_MAX_OVERRIDE The current set global allocation limit override, -1 means limits are applied per record type.
private static final int	DEFAULT_BUFFER_SIZE The default size of the bytearray used while reading input streams.
private static final Logger	LOG
private static int	MAX_BYTE_ARRAY_INIT_SIZE The max init size of ByteArrayOutputStream.
private static final int	SKIP_BUFFER_SIZE The default buffer size to use for the skip() methods.

Access	Constructor and Description
private	IOUtils()

Method Summary

Modifier and Type	Method and Description
pack-priv static int	calculateByteArrayInitLength(final boolean isLengthKnown, final int length, final int maxLength)
public static long	calculateChecksum(byte[] data) Calculate checksum on input data
public static long	calculateChecksum(InputStream stream) Calculate checksum on all the data read from input stream.
private static void	checkByteSizeLimit(int length)
private static void	checkByteSizeLimit(long length)
private static void	checkLength(long length, int maxLength)
public static void	closeQuietly(final Closeable resource to close closeable) Quietly (no exceptions) close Closable resource.
public static long	Returns: the amount of bytes copied copy(InputStream The `InputStream` which provides the data inp, OutputStream The `OutputStream` to write the data to out) Copies all the data from the given InputStream to the OutputStream.
public static long	Returns: the amount of bytes copied copy(InputStream The `InputStream` which provides the data inp, OutputStream The `OutputStream` to write the data to out, long limit the copied bytes - use `-1` for no limit limit) Copies all the data from the given InputStream to the OutputStream.
public static long	Returns: the amount of bytes copied copy(InputStream The `InputStream` which provides the data srcStream, File The file where the data should be stored destFile) Copy the contents of the stream to a new file.
public static int	Returns: the max init size of ByteArrayOutputStream. -1 (the default) means init size of ByteArrayOutputStream could be up to `Integer#MAX_VALUE` getMaxByteArrayInitSize()
public static byte[]	peekFirst8Bytes(InputStream stream) Peeks at the first 8 bytes of the stream.
public static byte[]	peekFirstNBytes(InputStream stream, int limit) Peeks at the first N bytes of the stream.
public static int	Returns: byte read, unless readByte(InputStream input stream to read is) Simple utility function to check that you haven't hit EOF when reading a byte.
public static int	Returns: the number of bytes read or -1 if no bytes were read readFully(InputStream the stream from which the data is read. in, byte[] the buffer into which the data is read. b) Helper method, just calls `readFully(in, b, 0, b.length)`
public static int	Returns: the number of bytes read or -1 if no bytes were read readFully(InputStream the stream from which the data is read. in, byte[] the buffer into which the data is read. b, int the start offset in array `b` at which the data is written. off, int the maximum number of bytes to read. len) Same as the normal `InputStream#read(byte[], int, int)`, but tries to ensure that the entire len number of bytes is read.
public static int	Returns: the number of bytes read or -1 if no bytes were read readFully(ReadableByteChannel The byte-channel to read data from channel, ByteBuffer the buffer into which the data is read. b) Same as the normal `channel.read(b)`, but tries to ensure that the buffer is filled completely if possible, i.e. b.remaining() returns 0.
public static byte[]	safelyAllocate(long length, int maxLength)
public static void	safelyAllocateCheck(long length, int maxLength)
public static byte[]	safelyClone(byte[] src, int offset, int length, int maxLength)
public static void	setByteArrayMaxOverride(int The maximum number of bytes that should be possible to be allocated in one step. maxOverride) If this value is set to > 0, `safelyAllocate(long, int)` will ignore the maximum record length parameter.
public static void	setMaxByteArrayInitSize(final int the max init size of ByteArrayOutputStream. -1 (the default) means init size of ByteArrayOutputStream could be up to `Integer#MAX_VALUE` maxOverride)
public static long	Returns: number of bytes actually skipped. skipFully(final InputStream byte stream to skip input, final long number of bytes to skip. toSkip) Skips bytes from an input byte stream.
private static void	throwRecordTruncationException(final int maxLength)
private static void	throwRFE(long length, int maxLength)
public static byte[]	Returns: A byte array with the read bytes. toByteArray(InputStream The byte stream of data to read. stream) Reads all the data from the input stream, and returns the bytes read.
public static byte[]	Returns: A byte array with the read bytes. toByteArray(InputStream The byte stream of data to read. stream, final int The maximum length to read, use `Integer#MAX_VALUE` to read the stream until EOF. length) Reads up to `length` bytes from the input stream, and returns the bytes read.
public static byte[]	Returns: A byte array with the read bytes. toByteArray(InputStream The byte stream of data to read. stream, final int The maximum length to read, use `Integer#MAX_VALUE` to read the stream until EOF length, final int if the input is equal to/longer than `maxLength` bytes, then throw an `IOException` complaining about the length. use `Integer#MAX_VALUE` to disable the check - if `setByteArrayMaxOverride(int)` is set then that max of that value and this maxLength is used maxLength) Reads up to `length` bytes from the input stream, and returns the bytes read.
private static byte[]	toByteArray(InputStream stream, final int length, final int maxLength, final boolean checkEOFException, final boolean isLengthKnown)
public static byte[]	toByteArray(ByteBuffer buffer, int length) Returns an array (that shouldn't be written to!) of the ByteBuffer.
public static byte[]	Returns: A byte array with the read bytes. toByteArrayWithMaxLength(InputStream The byte stream of data to read. stream, final int if the input is equal to/longer than `maxLength` bytes, then throw an `IOException` complaining about the length. use `Integer#MAX_VALUE` to disable the check - if `setByteArrayMaxOverride(int)` is set then that max of that value and this maxLength is used maxLength) Reads the input stream, and returns the bytes read.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

BYTE_ARRAY_MAX_OVERRIDE	back to summary
private static int BYTE_ARRAY_MAX_OVERRIDE The current set global allocation limit override, -1 means limits are applied per record type.

DEFAULT_BUFFER_SIZE	back to summary
private static final int DEFAULT_BUFFER_SIZE The default size of the bytearray used while reading input streams. This is meant to be pretty small.

LOG	back to summary
private static final Logger LOG

MAX_BYTE_ARRAY_INIT_SIZE	back to summary
private static int MAX_BYTE_ARRAY_INIT_SIZE The max init size of ByteArrayOutputStream. -1 means init size of ByteArrayOutputStream could be up to Integer.MAX_VALUE

SKIP_BUFFER_SIZE	back to summary
private static final int SKIP_BUFFER_SIZE The default buffer size to use for the skip() methods.

IOUtils	back to summary
private IOUtils()

Method Detail

calculateByteArrayInitLength	back to summary
pack-priv static int calculateByteArrayInitLength(final boolean isLengthKnown, final int length, final int maxLength)

calculateChecksum	back to summary
public static long calculateChecksum(byte[] data) Calculate checksum on input data

calculateChecksum	back to summary
public static long calculateChecksum(InputStream stream) throws IOException Calculate checksum on all the data read from input stream. This should be more efficient than the equivalent code `IOUtils.calculateChecksum(IOUtils.toByteArray(stream))`

checkByteSizeLimit	back to summary
private static void checkByteSizeLimit(int length)

checkByteSizeLimit	back to summary
private static void checkByteSizeLimit(long length)

checkLength	back to summary
private static void checkLength(long length, int maxLength)

closeQuietly	back to summary
public static void closeQuietly(final Closeable closeable) Quietly (no exceptions) close Closable resource. In case of error it will be printed to IOUtils class logger. Parameters closeable:Closeable resource to close

closeQuietly

back to summary

public static void closeQuietly(final Closeable closeable)

Quietly (no exceptions) close Closable resource. In case of error it will be printed to IOUtils class logger.

Parameters

closeable:Closeable: resource to close

copy back to summary

copy	back to summary
public static long copy(InputStream inp, OutputStream out) throws IOException Copies all the data from the given InputStream to the OutputStream. It leaves both streams open, so you will still need to close them once done. Parameters inp:InputStream The `InputStream` which provides the data out:OutputStream The `OutputStream` to write the data to Returns:long the amount of bytes copied Exceptions IOException: If copying the data fails.

public static long copy(InputStream inp, OutputStream out) throws IOException

Copies all the data from the given InputStream to the OutputStream. It leaves both streams open, so you will still need to close them once done.

Parameters

inp:InputStream: The InputStream which provides the data
out:OutputStream: The OutputStream to write the data to

Returns:long

the amount of bytes copied

Exceptions

IOException:: If copying the data fails.

copy back to summary

copy	back to summary
public static long copy(InputStream inp, OutputStream out, long limit) throws IOException Copies all the data from the given InputStream to the OutputStream. It leaves both streams open, so you will still need to close them once done. Parameters inp:InputStream The `InputStream` which provides the data out:OutputStream The `OutputStream` to write the data to limit:long limit the copied bytes - use `-1` for no limit Returns:long the amount of bytes copied Exceptions IOException: If copying the data fails.

public static long copy(InputStream inp, OutputStream out, long limit) throws IOException

Copies all the data from the given InputStream to the OutputStream. It leaves both streams open, so you will still need to close them once done.

Parameters

inp:InputStream: The InputStream which provides the data
out:OutputStream: The OutputStream to write the data to
limit:long: limit the copied bytes - use -1 for no limit

Returns:long

the amount of bytes copied

Exceptions

IOException:: If copying the data fails.

copy back to summary

copy	back to summary
public static long copy(InputStream srcStream, File destFile) throws IOException Copy the contents of the stream to a new file. Parameters srcStream:InputStream The `InputStream` which provides the data destFile:File The file where the data should be stored Returns:long the amount of bytes copied Exceptions IOException: If the target directory does not exist and cannot be created or if copying the data fails.

public static long copy(InputStream srcStream, File destFile) throws IOException

Copy the contents of the stream to a new file.

Parameters

srcStream:InputStream: The InputStream which provides the data
destFile:File: The file where the data should be stored

Returns:long

the amount of bytes copied

Exceptions

IOException:: If the target directory does not exist and cannot be created or if copying the data fails.

getMaxByteArrayInitSize	back to summary
public static int getMaxByteArrayInitSize() Returns:int the max init size of ByteArrayOutputStream. -1 (the default) means init size of ByteArrayOutputStream could be up to `Integer#MAX_VALUE` Since POI 5.2.2

peekFirst8Bytes	back to summary
public static byte[] peekFirst8Bytes(InputStream stream) throws IOException, EmptyFileException Peeks at the first 8 bytes of the stream. Returns those bytes, but with the stream unaffected. Requires a stream that supports mark/reset, or a PushbackInputStream. If the stream has >0 but <8 bytes, remaining bytes will be zero. Exceptions EmptyFileException: if the stream is empty

peekFirst8Bytes

back to summary

public static byte[] peekFirst8Bytes(InputStream stream) throws IOException, EmptyFileException

Peeks at the first 8 bytes of the stream. Returns those bytes, but with the stream unaffected. Requires a stream that supports mark/reset, or a PushbackInputStream. If the stream has >0 but <8 bytes, remaining bytes will be zero.

Exceptions

EmptyFileException:: if the stream is empty

peekFirstNBytes	back to summary
public static byte[] peekFirstNBytes(InputStream stream, int limit) throws IOException, EmptyFileException Peeks at the first N bytes of the stream. Returns those bytes, but with the stream unaffected. Requires a stream that supports mark/reset, or a PushbackInputStream. If the stream has >0 but <N bytes, remaining bytes will be zero. Exceptions EmptyFileException: if the stream is empty

peekFirstNBytes

back to summary

public static byte[] peekFirstNBytes(InputStream stream, int limit) throws IOException, EmptyFileException

Peeks at the first N bytes of the stream. Returns those bytes, but with the stream unaffected. Requires a stream that supports mark/reset, or a PushbackInputStream. If the stream has >0 but <N bytes, remaining bytes will be zero.

Exceptions

EmptyFileException:: if the stream is empty

readByte	back to summary
public static int readByte(InputStream is) throws IOException Simple utility function to check that you haven't hit EOF when reading a byte. Parameters is:InputStream input stream to read Returns:int byte read, unless Exceptions IOException: on IOException or EOF if -1 is read

readByte

back to summary

public static int readByte(InputStream is) throws IOException

Simple utility function to check that you haven't hit EOF when reading a byte.

Parameters

is:InputStream: input stream to read

Returns:int

byte read, unless

Exceptions

IOException:: on IOException or EOF if -1 is read

readFully back to summary

readFully	back to summary
public static int readFully(InputStream in, byte[] b) throws IOException Helper method, just calls `readFully(in, b, 0, b.length)` Parameters in:InputStream the stream from which the data is read. b:byte[] the buffer into which the data is read. Returns:int the number of bytes read or -1 if no bytes were read Exceptions IOException: if reading from the stream fails

public static int readFully(InputStream in, byte[] b) throws IOException

Helper method, just calls readFully(in, b, 0, b.length)

Parameters

in:InputStream: the stream from which the data is read.
b:byte[]: the buffer into which the data is read.

Returns:int

the number of bytes read or -1 if no bytes were read

Exceptions

IOException:: if reading from the stream fails

readFully back to summary

readFully	back to summary
public static int readFully(InputStream in, byte[] b, int off, int len) throws IOException Same as the normal `InputStream#read(byte[], int, int)`, but tries to ensure that the entire len number of bytes is read. If the end of file is reached before any bytes are read, returns `-1`. If the end of the file is reached after some bytes are read, returns the number of bytes read. If the end of the file isn't reached before `len` bytes have been read, will return `len` bytes. Parameters in:InputStream the stream from which the data is read. b:byte[] the buffer into which the data is read. off:int the start offset in array `b` at which the data is written. len:int the maximum number of bytes to read. Returns:int the number of bytes read or -1 if no bytes were read Exceptions IOException: if reading from the stream fails

public static int readFully(InputStream in, byte[] b, int off, int len) throws IOException

Same as the normal InputStream#read(byte[], int, int), but tries to ensure that the entire len number of bytes is read.

If the end of file is reached before any bytes are read, returns -1. If the end of the file is reached after some bytes are read, returns the number of bytes read. If the end of the file isn't reached before len bytes have been read, will return len bytes.

Parameters

in:InputStream: the stream from which the data is read.
b:byte[]: the buffer into which the data is read.
off:int: the start offset in array b at which the data is written.
len:int: the maximum number of bytes to read.

Returns:int

the number of bytes read or -1 if no bytes were read

Exceptions

IOException:: if reading from the stream fails

readFully back to summary

readFully	back to summary
public static int readFully(ReadableByteChannel channel, ByteBuffer b) throws IOException Same as the normal `channel.read(b)`, but tries to ensure that the buffer is filled completely if possible, i.e. b.remaining() returns 0. If the end of file is reached before any bytes are read, returns -1. If the end of the file is reached after some bytes are read, returns the number of bytes read. If the end of the file isn't reached before the buffer has no more remaining capacity, will return the number of bytes that were read. Parameters channel:ReadableByteChannel The byte-channel to read data from b:ByteBuffer the buffer into which the data is read. Returns:int the number of bytes read or -1 if no bytes were read Exceptions IOException: if reading from the stream fails

public static int readFully(ReadableByteChannel channel, ByteBuffer b) throws IOException

Same as the normal channel.read(b), but tries to ensure that the buffer is filled completely if possible, i.e. b.remaining() returns 0.

If the end of file is reached before any bytes are read, returns -1. If the end of the file is reached after some bytes are read, returns the number of bytes read. If the end of the file isn't reached before the buffer has no more remaining capacity, will return the number of bytes that were read.

Parameters

channel:ReadableByteChannel: The byte-channel to read data from
b:ByteBuffer: the buffer into which the data is read.

Returns:int

the number of bytes read or -1 if no bytes were read

Exceptions

IOException:: if reading from the stream fails

safelyAllocate	back to summary
public static byte[] safelyAllocate(long length, int maxLength)

safelyAllocateCheck	back to summary
public static void safelyAllocateCheck(long length, int maxLength)

safelyClone	back to summary
public static byte[] safelyClone(byte[] src, int offset, int length, int maxLength)

setByteArrayMaxOverride back to summary

setByteArrayMaxOverride	back to summary
public static void setByteArrayMaxOverride(int maxOverride) If this value is set to > 0, `safelyAllocate(long, int)` will ignore the maximum record length parameter. This is designed to allow users to bypass the hard-coded maximum record lengths if they are willing to accept the risk of allocating memory up to the size specified. It also allows to impose a lower limit than used for very memory constrained systems. Note This is a per-allocation limit and does not allow you to limit the overall sum of allocations! Use -1 for using the limits specified per record-type. Parameters maxOverride:int The maximum number of bytes that should be possible to be allocated in one step. Annotations @SuppressWarnings:unused Since 4.0.0

public static void setByteArrayMaxOverride(int maxOverride)

If this value is set to > 0, safelyAllocate(long, int) will ignore the maximum record length parameter. This is designed to allow users to bypass the hard-coded maximum record lengths if they are willing to accept the risk of allocating memory up to the size specified. It also allows to impose a lower limit than used for very memory constrained systems.

Note

This is a per-allocation limit and does not allow you to limit the overall sum of allocations! Use -1 for using the limits specified per record-type.

Parameters

maxOverride:int: The maximum number of bytes that should be possible to be allocated in one step.

Annotations

@SuppressWarnings:unused

Since

4.0.0

setMaxByteArrayInitSize	back to summary
public static void setMaxByteArrayInitSize(final int maxOverride) Parameters maxOverride:int the max init size of ByteArrayOutputStream. -1 (the default) means init size of ByteArrayOutputStream could be up to `Integer#MAX_VALUE` Since POI 5.2.2

skipFully back to summary

skipFully	back to summary
public static long skipFully(final InputStream input, final long toSkip) throws IOException Skips bytes from an input byte stream. This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case for skip() implementations in subclasses of `InputStream`. Note that the implementation uses `InputStream#read(byte[], int, int)` rather than delegating to `InputStream#skip(long)`. This means that the method may be considerably less efficient than using the actual skip implementation, this is done to guarantee that the correct number of bytes are skipped. This mimics POI's `readFully(InputStream, byte[])`. If the end of file is reached before any bytes are read, returns `-1`. If the end of the file is reached after some bytes are read, returns the number of bytes read. If the end of the file isn't reached before `len` bytes have been read, will return `len` bytes. Copied nearly verbatim from commons-io 41a3e9c Parameters input:InputStream byte stream to skip toSkip:long number of bytes to skip. Returns:long number of bytes actually skipped. Exceptions IOException: if there is a problem reading the file IllegalArgumentException: if toSkip is negative See Also `InputStream#skip(long)`

public static long skipFully(final InputStream input, final long toSkip) throws IOException

Skips bytes from an input byte stream. This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case for skip() implementations in subclasses of InputStream.

Note that the implementation uses InputStream#read(byte[], int, int) rather than delegating to InputStream#skip(long). This means that the method may be considerably less efficient than using the actual skip implementation, this is done to guarantee that the correct number of bytes are skipped.

This mimics POI's readFully(InputStream, byte[]). If the end of file is reached before any bytes are read, returns -1. If the end of the file is reached after some bytes are read, returns the number of bytes read. If the end of the file isn't reached before len bytes have been read, will return len bytes.

Copied nearly verbatim from commons-io 41a3e9c

Parameters

input:InputStream: byte stream to skip
toSkip:long: number of bytes to skip.

Returns:long

number of bytes actually skipped.

Exceptions

IOException:: if there is a problem reading the file
IllegalArgumentException:: if toSkip is negative

See Also

InputStream#skip(long)

throwRecordTruncationException	back to summary
private static void throwRecordTruncationException(final int maxLength)

throwRFE	back to summary
private static void throwRFE(long length, int maxLength)

toByteArray	back to summary
public static byte[] toByteArray(InputStream stream) throws IOException Reads all the data from the input stream, and returns the bytes read. Parameters stream:InputStream The byte stream of data to read. Returns:byte[] A byte array with the read bytes. Exceptions IOException: If reading data fails or EOF is encountered too early for the given length. RecordFormatException: If the requested length is invalid.

toByteArray

back to summary

public static byte[] toByteArray(InputStream stream) throws IOException

Reads all the data from the input stream, and returns the bytes read.

Parameters

stream:InputStream: The byte stream of data to read.

Returns:byte[]

A byte array with the read bytes.

Exceptions

IOException:: If reading data fails or EOF is encountered too early for the given length.
RecordFormatException:: If the requested length is invalid.

toByteArray back to summary

toByteArray	back to summary
public static byte[] toByteArray(InputStream stream, final int length) throws IOException Reads up to `length` bytes from the input stream, and returns the bytes read. Parameters stream:InputStream The byte stream of data to read. length:int The maximum length to read, use `Integer#MAX_VALUE` to read the stream until EOF. Returns:byte[] A byte array with the read bytes. Exceptions IOException: If reading data fails or EOF is encountered too early for the given length. RecordFormatException: If the requested length is invalid.

public static byte[] toByteArray(InputStream stream, final int length) throws IOException

Reads up to length bytes from the input stream, and returns the bytes read.

Parameters

stream:InputStream: The byte stream of data to read.
length:int: The maximum length to read, use Integer#MAX_VALUE to read the stream until EOF.

Returns:byte[]

A byte array with the read bytes.

Exceptions

IOException:: If reading data fails or EOF is encountered too early for the given length.
RecordFormatException:: If the requested length is invalid.

toByteArray back to summary

toByteArray	back to summary
public static byte[] toByteArray(InputStream stream, final int length, final int maxLength) throws IOException Reads up to `length` bytes from the input stream, and returns the bytes read. Parameters stream:InputStream The byte stream of data to read. length:int The maximum length to read, use `Integer#MAX_VALUE` to read the stream until EOF maxLength:int if the input is equal to/longer than `maxLength` bytes, then throw an `IOException` complaining about the length. use `Integer#MAX_VALUE` to disable the check - if `setByteArrayMaxOverride(int)` is set then that max of that value and this maxLength is used Returns:byte[] A byte array with the read bytes. Exceptions IOException: If reading data fails or EOF is encountered too early for the given length. RecordFormatException: If the requested length is invalid.

public static byte[] toByteArray(InputStream stream, final int length, final int maxLength) throws IOException

Reads up to length bytes from the input stream, and returns the bytes read.

Parameters

stream:InputStream: The byte stream of data to read.
length:int: The maximum length to read, use Integer#MAX_VALUE to read the stream until EOF
maxLength:int: if the input is equal to/longer than maxLength bytes, then throw an IOException complaining about the length. use Integer#MAX_VALUE to disable the check - if setByteArrayMaxOverride(int) is set then that max of that value and this maxLength is used

Returns:byte[]

A byte array with the read bytes.

Exceptions

IOException:: If reading data fails or EOF is encountered too early for the given length.
RecordFormatException:: If the requested length is invalid.

toByteArray	back to summary
private static byte[] toByteArray(InputStream stream, final int length, final int maxLength, final boolean checkEOFException, final boolean isLengthKnown) throws IOException

toByteArray	back to summary
public static byte[] toByteArray(ByteBuffer buffer, int length) Returns an array (that shouldn't be written to!) of the ByteBuffer. Will be of the requested length, or possibly longer if that's easier.

toByteArrayWithMaxLength back to summary

toByteArrayWithMaxLength	back to summary
public static byte[] toByteArrayWithMaxLength(InputStream stream, final int maxLength) throws IOException Reads the input stream, and returns the bytes read. Parameters stream:InputStream The byte stream of data to read. maxLength:int if the input is equal to/longer than `maxLength` bytes, then throw an `IOException` complaining about the length. use `Integer#MAX_VALUE` to disable the check - if `setByteArrayMaxOverride(int)` is set then that max of that value and this maxLength is used Returns:byte[] A byte array with the read bytes. Exceptions IOException: If reading data fails or EOF is encountered too early for the given length. RecordFormatException: If the requested length is invalid. Since POI 5.2.1

public static byte[] toByteArrayWithMaxLength(InputStream stream, final int maxLength) throws IOException

Reads the input stream, and returns the bytes read.

Parameters

stream:InputStream: The byte stream of data to read.
maxLength:int: if the input is equal to/longer than maxLength bytes, then throw an IOException complaining about the length. use Integer#MAX_VALUE to disable the check - if setByteArrayMaxOverride(int) is set then that max of that value and this maxLength is used

Returns:byte[]

A byte array with the read bytes.

Exceptions

IOException:: If reading data fails or EOF is encountered too early for the given length.
RecordFormatException:: If the requested length is invalid.

Since

POI 5.2.1

public final Class IOUtils

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail