Tomcat 10.1.19 · org.apache.tomcat.util.http.fileupload.IOUtils

General IO stream manipulation utilities.

This class provides static utility methods for input/output operations.

closeQuietly - these methods close a stream ignoring nulls and exceptions
toXxx/read - these methods read data from a stream
write - these methods write data to a stream
copy - these methods copy all the data from one stream to another
contentEquals - these methods compare the content of two streams

The byte-to-char methods and char-to-byte methods involve a conversion step. Two methods are provided in each case, one that uses the platform default encoding and the other which allows you to specify an encoding. You are encouraged to always specify an encoding because relying on the platform default can lead to unexpected results, for example when moving from development to production.

All the methods in this class that read a stream are buffered internally. This means that there is no cause to use a BufferedInputStream or BufferedReader. The default buffer size of 4K has been shown to be efficient in tests.

Wherever possible, the methods in this class do not flush or close the stream. This is to avoid making non-portable assumptions about the streams' origin and further use. Thus the caller is still responsible for closing streams after use.

Origin of code: Excalibur.

Field Summary

Modifier and Type	Field and Description
private static final int	DEFAULT_BUFFER_SIZE The default buffer size (4096) to use for `copyLarge(InputStream, OutputStream)`.
public static final int	EOF Represents the end-of-file (or stream).

Constructor Summary

Access	Constructor and Description
public	IOUtils()

Method Summary

Modifier and Type	Method and Description
public static void	closeQuietly(final Closeable the objects to close, may be null or already closed closeable) Closes a `Closeable` unconditionally.
public static int	Returns: the number of bytes copied, or -1 if > Integer.MAX_VALUE copy(final InputStream the `InputStream` to read from input, final OutputStream the `OutputStream` to write to output) Copies bytes from an `InputStream` to an `OutputStream`.
public static long	Returns: the number of bytes copied copyLarge(final InputStream the `InputStream` to read from input, final OutputStream the `OutputStream` to write to output) Copies bytes from a large (over 2GB) `InputStream` to an `OutputStream`.
public static int	Returns: actual length read; may be less than requested if EOF was reached read(final InputStream where to read input from input, final byte[] destination buffer, final int initial offset into buffer offset, final int length to read, must be >= 0 length) Reads bytes from an input stream.
public static void	readFully(final InputStream where to read input from input, final byte[] destination buffer, final int initial offset into buffer offset, final int length to read, must be >= 0 length) Reads the requested number of bytes or fail if there are not enough left.
public static void	readFully(final InputStream where to read input from input, final byte[] destination buffer) Reads the requested number of bytes or fail if there are not enough left.

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

Field Detail

DEFAULT_BUFFER_SIZE	back to summary
private static final int DEFAULT_BUFFER_SIZE The default buffer size (4096) to use for `copyLarge(InputStream, OutputStream)`.

EOF	back to summary
public static final int EOF Represents the end-of-file (or stream). Since 2.5 (made public)

EOF

back to summary

public static final int EOF

Represents the end-of-file (or stream).

Since: 2.5 (made public)

Constructor Detail

IOUtils	back to summary
public IOUtils()

Method Detail

closeQuietly back to summary

closeQuietly	back to summary
public static void closeQuietly(final Closeable closeable) Closes a `Closeable` unconditionally. Equivalent to `Closeable#close()`, except any exceptions will be ignored. This is typically used in finally blocks. Example code: Closeable closeable = null; try { closeable = new FileReader("foo.txt"); // process closeable closeable.close(); } catch (Exception e) { // error handling } finally { IOUtils.closeQuietly(closeable); } Closing all streams: try { return IOUtils.copy(inputStream, outputStream); } finally { IOUtils.closeQuietly(inputStream); IOUtils.closeQuietly(outputStream); } Parameters closeable:Closeable the objects to close, may be null or already closed Since 2.0

public static void closeQuietly(final Closeable closeable)

Closes a Closeable unconditionally.

Equivalent to Closeable#close(), except any exceptions will be ignored. This is typically used in finally blocks.

Example code:

Closeable closeable = null;
try {
    closeable = new FileReader("foo.txt");
    // process closeable
    closeable.close();
} catch (Exception e) {
    // error handling
} finally {
    IOUtils.closeQuietly(closeable);
}

Closing all streams:

try {
    return IOUtils.copy(inputStream, outputStream);
} finally {
    IOUtils.closeQuietly(inputStream);
    IOUtils.closeQuietly(outputStream);
}

Parameters

closeable:Closeable: the objects to close, may be null or already closed

Since

2.0

copy back to summary

copy	back to summary
public static int copy(final InputStream input, final OutputStream output) throws IOException Copies bytes from an `InputStream` to an `OutputStream`. This method buffers the input internally, so there is no need to use a `BufferedInputStream`. Large streams (over 2GB) will return a bytes copied value of `-1` after the copy has completed since the correct number of bytes cannot be returned as an int. For large streams use the `copyLarge(InputStream, OutputStream)` method. Parameters input:InputStream the `InputStream` to read from output:OutputStream the `OutputStream` to write to Returns:int the number of bytes copied, or -1 if > Integer.MAX_VALUE Exceptions IOException: if an I/O error occurs NullPointerException: if the input or output is null Since 1.1

public static int copy(final InputStream input, final OutputStream output) throws IOException

Copies bytes from an InputStream to an OutputStream.

This method buffers the input internally, so there is no need to use a BufferedInputStream.

Large streams (over 2GB) will return a bytes copied value of -1 after the copy has completed since the correct number of bytes cannot be returned as an int. For large streams use the copyLarge(InputStream, OutputStream) method.

Parameters

input:InputStream: the InputStream to read from
output:OutputStream: the OutputStream to write to

Returns:int

the number of bytes copied, or -1 if > Integer.MAX_VALUE

Exceptions

IOException:: if an I/O error occurs
NullPointerException:: if the input or output is null

Since

1.1

copyLarge back to summary

copyLarge	back to summary
public static long copyLarge(final InputStream input, final OutputStream output) throws IOException Copies bytes from a large (over 2GB) `InputStream` to an `OutputStream`. This method buffers the input internally, so there is no need to use a `BufferedInputStream`. The buffer size is given by `DEFAULT_BUFFER_SIZE`. Parameters input:InputStream the `InputStream` to read from output:OutputStream the `OutputStream` to write to Returns:long the number of bytes copied Exceptions IOException: if an I/O error occurs NullPointerException: if the input or output is null Since 1.3

public static long copyLarge(final InputStream input, final OutputStream output) throws IOException

Copies bytes from a large (over 2GB) InputStream to an OutputStream.

This method buffers the input internally, so there is no need to use a BufferedInputStream.

The buffer size is given by DEFAULT_BUFFER_SIZE.

Parameters

input:InputStream: the InputStream to read from
output:OutputStream: the OutputStream to write to

Returns:long

the number of bytes copied

Exceptions

IOException:: if an I/O error occurs
NullPointerException:: if the input or output is null

Since

1.3

read back to summary

read	back to summary
public static int read(final InputStream input, final byte[] buffer, final int offset, final int length) throws IOException Reads bytes from an input stream. This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case for subclasses of `InputStream`. Parameters input:InputStream where to read input from buffer:byte[] destination offset:int initial offset into buffer length:int length to read, must be >= 0 Returns:int actual length read; may be less than requested if EOF was reached Exceptions IOException: if a read error occurs Since 2.2

public static int read(final InputStream input, final byte[] buffer, final int offset, final int length) throws IOException

Reads bytes from an input stream. This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case for subclasses of InputStream.

Parameters

input:InputStream: where to read input from
buffer:byte[]: destination
offset:int: initial offset into buffer
length:int: length to read, must be >= 0

Returns:int

actual length read; may be less than requested if EOF was reached

Exceptions

IOException:: if a read error occurs

Since

2.2

readFully back to summary

readFully	back to summary
public static void readFully(final InputStream input, final byte[] buffer, final int offset, final int length) throws IOException Reads the requested number of bytes or fail if there are not enough left. This allows for the possibility that `InputStream#read(byte[], int, int)` may not read as many bytes as requested (most likely because of reaching EOF). Parameters input:InputStream where to read input from buffer:byte[] destination offset:int initial offset into buffer length:int length to read, must be >= 0 Exceptions IOException: if there is a problem reading the file IllegalArgumentException: if length is negative EOFException: if the number of bytes read was incorrect Since 2.2

public static void readFully(final InputStream input, final byte[] buffer, final int offset, final int length) throws IOException

Reads the requested number of bytes or fail if there are not enough left.

This allows for the possibility that InputStream#read(byte[], int, int) may not read as many bytes as requested (most likely because of reaching EOF).

Parameters

input:InputStream: where to read input from
buffer:byte[]: destination
offset:int: initial offset into buffer
length:int: length to read, must be >= 0

Exceptions

IOException:: if there is a problem reading the file
IllegalArgumentException:: if length is negative
EOFException:: if the number of bytes read was incorrect

Since

2.2

readFully back to summary

readFully	back to summary
public static void readFully(final InputStream input, final byte[] buffer) throws IOException Reads the requested number of bytes or fail if there are not enough left. This allows for the possibility that `InputStream#read(byte[], int, int)` may not read as many bytes as requested (most likely because of reaching EOF). Parameters input:InputStream where to read input from buffer:byte[] destination Exceptions IOException: if there is a problem reading the file IllegalArgumentException: if length is negative EOFException: if the number of bytes read was incorrect Since 2.2

public static void readFully(final InputStream input, final byte[] buffer) throws IOException

Reads the requested number of bytes or fail if there are not enough left.

This allows for the possibility that InputStream#read(byte[], int, int) may not read as many bytes as requested (most likely because of reaching EOF).

Parameters

input:InputStream: where to read input from
buffer:byte[]: destination

Exceptions

IOException:: if there is a problem reading the file
IllegalArgumentException:: if length is negative
EOFException:: if the number of bytes read was incorrect

Since

2.2

public Class IOUtils

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail