JarCastingA data stream fetching helper for Java
Overview
This is a simple helper to fetch the complete content of an input stream. It is, among other things, intended as an alternative to using IOUtils#readFully for this everyday task.
Consult the documentation and the usage description for further information:
- Fetching data streams
- Automatic closing of supplied streams
- Listen to fetch progress
- Handling of
nullarguments - Customizability
Maven
This library is hosted in the Maven Central Repository. You can use it with the following coordinates:
<dependency>
<groupId>net.markenwerk</groupId>
<artifactId>utils-data-fetcher</artifactId>
<version>4.0.2</version>
</dependency>
Motivation
Copying the complete content of an InputStream into a byte[] or into an OutputStream is a menial task, that has to be dealt with very commonly. While this is certainly not a difficult challenge for any programmer, it is still boring and annoying to do it over and over again, and – as pretty much everything – prone to be erroneously, if done in a hurry.
There are common solutions, beside coding it over and over again. The Oracle JRE provides the class IOUtils for this simple task. But this class is not a part of the official Java specifications, which means that using it yields a compiler warning like
The type 'IOUtils' is not API.
and may break at runtime; i.e. if a runtime environment other than the Oracle JRE is used. Another solution to accomplishing this simple task, could be to bundle a major library like Commons IO. But doing so may appear like overkill, especially if no other functionality of the library is likely to be used.
This library provides a simple and lightweight alternative.
Usage
Fetching data streams
This library provides the DataFetcher which features two main functionalities to handle byte streams:
// create a simple DataFetcher
DataFetcher fetcher = new BufferedDataFetcher();
// copy the content of an InputStream into a byte[]
byte[] bytes = fetcher.fetch(inputStream);
// copy the content of an InputStream into an OutputStream
fetcher.copy(inputStream, outputStream);
Automatic closing of supplied streams
All methods have optional boolean parameters, that can be used to instruct the DataFetcher to close the supplied streams. Doing so allows to write compact code like:
foo.setContent(new BufferedDataFetcher().fetch(new FileInputStream(file), true));
Otherwise, it would be necessary to write unnecessarily verbose code like:
InputStream in = new FileInputStream(file);
foo.setContent(new BuffereddataFetcher().fetch(in));
in.close();
Listen to fetch progress
All methods optionally take a DataFetchProgressListener that gets notified on various points in the lifecycle (started, progressed, succeeded or failed, finished) of a fetch operation. The IdleDataFetchProgressListener is a convenient base implementation with empty methods.
new BufferedDataFetcher().copy(
new FileInputStream(inFile),
new FileOutputStream(outFile),
new IdleDataFetchProgressListener() {
public void onProgress(long bytesFetched) {
System.out.println(bytesFetched + " bytes copied so far.");
}
},
true,
true
);
Handling of null arguments
Missing or invalid arguments are handled gracefully with the following behaviour:
- If
nullis given as theInputStream, it is simply ignored and handled as if there was nothing to read. That means, nothing is written to theOutputStreamand, if requested, theOutputStreamwill be closed. - If
nullis given as theOutputStream, it is simply ignored, but the content of the givenInputStreamis fetched anyway. If requested, theInputStreambe closed.
Customizability
This library provides BufferedDataFetcher as the simplest possible implementations of DataFetcher. It eagerly allocates a byte[] during construction and uses it as a buffer to perform fetch operations by sequentially reading from the InputStream into the buffer and then writing from the buffer to the OutputStream. It is not threadsafe.
Variations of the buffered copying strategy (e.g. lazy buffer creation, threadsafeness) or completely other copying strategies can easily be implemented by extending AbstractDataFetcher or AbstractBufferedDataFetcher respectively.
AbstractDataFetcher reduces all methods from the DataFetcher interface to the single method doCopy(InputStream, OutputStream, DataFetchProgressListener) where every parameter is guaranteed to be not null, and therefore greatly simplifies the implementation of new fetch strategies. AbstractBufferedDataFetcher is such an implementation of the aforementioned buffering fetch strategy that handles the sequentially write-read cycles and notifies the DataFetchProgressListener accordingly, but leaves the buffer allocation strategy to be specified.
