Package com.globalmentor.io

Class IOStreams

java.lang.Object

com.globalmentor.io.IOStreams

public class IOStreams
extends Object

Utilities for working with streams generally.

Author:

Garret Wilson

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT_BUFFER_SIZE	The recommended default size of I/O buffers.

Constructor Summary

Constructors

Constructor	Description
IOStreams()

Method Summary

Modifier and Type	Method	Description
static long	copy(InputStream inputStream, OutputStream outputStream)	Copies all information from an input stream to an output stream.
static long	copy(InputStream inputStream, OutputStream outputStream, long expectedContentLength)	Copies all information from an input stream to an output stream.
static long	copy(InputStream inputStream, OutputStream outputStream, long expectedContentLength, ProgressListener progressListener)	Copies all information from an input stream to an output stream.
static long	copy(InputStream inputStream, OutputStream outputStream, ProgressListener progressListener)	Copies all information from an input stream to an output stream.

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

The recommended default size of I/O buffers.

API Note:

The general consensus is that many I/O devices use block sizes of 4096 or 8192 so the buffer size is optimal at a multiple of this. But the value needs to be low enough to fit in the CPU cache. Many JDK buffers such as that in BufferedInputStream and the utilities in Files have been tuned to 8192.

Implementation Note:

This value may change in the future if warranted by new technology.

See Also:

• How do you determine the ideal buffer size when using FileInputStream?
• File I/O with streams - best memory buffer size
• Constant Field Values

Constructor Details

IOStreams

public IOStreams()

Method Details

copy

public static long copy(InputStream inputStream,
 OutputStream outputStream)
                 throws IOException

Copies all information from an input stream to an output stream. After copying is finished, both streams are left open.

API Note:

This method will likely eventually be deprecated in favor of Java 9+ InputStream.transferTo(OutputStream).

Implementation Specification:

This implementation delegates to copy(InputStream, OutputStream, ProgressListener).

Parameters:

inputStream - The source of the data.

outputStream - The destination of the data.

Returns:

The total number of bytes copied.

Throws:

IOException - Thrown if there is an error reading from or writing to a stream.

copy

public static long copy(InputStream inputStream,
 OutputStream outputStream,
 ProgressListener progressListener)
                 throws IOException

Copies all information from an input stream to an output stream. Both streams are used as-is. After copying is finished, both streams are left open.

Implementation Specification:

This implementation delegates to copy(InputStream, OutputStream, long, ProgressListener).

Parameters:

inputStream - The source of the data.

outputStream - The destination of the data.

progressListener - A listener to be notified of progress, or null if no progress notifications is requested.

Returns:

The total number of bytes copied.

Throws:

IOException - Thrown if there is an error reading from or writing to a stream.

IOException - if an expected content length was given and the number of bytes written to the output stream is not what was expected.

copy

public static long copy(InputStream inputStream,
 OutputStream outputStream,
 long expectedContentLength)
                 throws IOException

Copies all information from an input stream to an output stream. Both streams are used as-is. After copying is finished, both streams are left open.

Implementation Specification:

This implementation delegates to copy(InputStream, OutputStream, long, ProgressListener).

Parameters:

inputStream - The source of the data.

outputStream - The destination of the data.

expectedContentLength - The length of content expected, or -1 if the length is unknown.

Returns:

The total number of bytes copied.

Throws:

IOException - Thrown if there is an error reading from or writing to a stream.

IOException - if an expected content length was given and the number of bytes written to the output stream is not what was expected.

copy

public static long copy(InputStream inputStream,
 OutputStream outputStream,
 long expectedContentLength,
 ProgressListener progressListener)
                 throws IOException

Copies all information from an input stream to an output stream. Both streams are used as-is. After copying is finished, both streams are left open.

Implementation Specification:

This implementation uses a single buffer of size 8192.

Implementation Note:

An earlier implementation attempted to optimize by using larger buffers for input streams known to contain a lot of data. Until there is empirical or authoritative evidence of any benefit from larger buffer sizes, the current implementation simply uses uses the default buffer size 8192 or the known total number of bytes, whichever is smaller. This approach saves memory and the transfer is usually I/O bound, not CPU bound, anyway. Using a single, fixed-size buffer is also the approach of the Java 9+ InputStream.transferTo(OutputStream) method.

Parameters:

inputStream - The source of the data.

outputStream - The destination of the data.

expectedContentLength - The length of content expected, or -1 if the length is unknown.

progressListener - A listener to be notified of progress, or null if no progress notifications is requested.

Returns:

The total number of bytes copied.

Throws:

IOException - Thrown if there is an error reading from or writing to a stream.

IOException - if an expected content length was given and the number of bytes written to the output stream is not what was expected.

See Also:

• DEFAULT_BUFFER_SIZE