A text stream fetching helper for Java

Overview

This is a simple helper to fetch the complete content of an readable.

Consult the documentation and the usage description for further information:

• Fetching text streams
• Automatic closing of supplied streams
• Listen to fetch progress
• Handling of null arguments
• 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-text-fetcher</artifactId>
	<version>1.0.2</version>
</dependency>

Motivation

Copying the complete content of an Readable into a char[], String or into an Appendable 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. A 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 text streams

This library provides the TextFetcher which features three main functionalities to handle char streams:

// create a simple TextFetcher
TextFetcher fetcher = new BufferedTextFetcher();

// copy the content of an Readable into a byte[]
char[] characters = fetcher.fetch(readable);

// copy the content of an Readable into a String
String string = fetcher.read(readable);

// copy the content of an Readable into an Appendable
fetcher.copy(readable, appendable);

Automatic closing of supplied streams

All methods have optional boolean parameters, that can be used to instruct the TextFetcher to close the supplied streams. Doing so allows to write compact code like:

foo.setContent(new BufferedTextFetcher().fetch(new FileReader(file), true));

Otherwise, it would be necessary to write unnecessarily verbose code like:

Reader in = new FileReader(file);
foo.setContent(new BuffereddataFetcher().fetch(in));
in.close();

Listen to fetch progress

All methods optionally take a TextFetchProgressListener that gets notified on various points in the lifecycle (started, progressed, succeeded or failed, finished) of a fetch operation. The IdleTextFetchProgressListener is a convenient base implementation with empty methods.

new BufferedTextFetcher().fetch(
	new FileReader(inFile),
	new FileWriter(outFile),
	new IdleTextFetchProgressListener() {
		public void onProgress(long charactersFetched) {
			System.out.println(charactersFetched + " characters copied so far.");
		}
	},
	true,
	true
);

Handling of null arguments

Missing or invalid arguments are handled gracefully with the following behaviour:

• If null is given as the Readable, it is simply ignored and handled as if there was nothing to read. That means, nothing is written to the Appendable and, if requested, the Appendable will be closed.
• If null is given as the Appendable, it is simply ignored, but the content of the given Readable is fetched anyway. If requested, the Readable be closed.

Customizability

This library provides BufferedTextFetcher as the simplest possible implementations of TextFetcher. It eagerly allocates a char[] during construction and uses it as a buffer to perform fetch operations by sequentially reading from the Readable into the buffer and then writing from the buffer to the Appendable. 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 AbstractTextFetcher or AbstractBufferedTextFetcher respectively.

AbstractTextFetcher reduces all methods from the TextFetcher interface to the single method doCopy(Reader, Writer, TextFetchProgressListener) where every parameter is guaranteed to be not null, and therefore greatly simplifies the implementation of new fetch strategies. AbstractBufferedTextFetcher is such an implementation of the aforementioned buffering fetch strategy that handles the sequentially write-read cycles and notifies the TextFetchProgressListener accordingly, but leaves the buffer allocation strategy to be specified.