refcodes-io: Paving the road for complex and low level I/O across boundaries

README

“The REFCODES.ORG codes represent a group of artifacts consolidating parts of my work in the past years. Several topics are covered which I consider useful for you, programmers, developers and software engineers.”

What is this repository for?

This artifact defines basic types handling communication between processes (across system boundaries), to be harnessed by complex and low level I/O, such as InputStream decorators adding replay, filter, clipboard, compression, replace or timeout functionality as well as OutputStream decorators which add clipboard, line break or compression functionality.

How do I get set up?

To get up and running, include the following dependency (without the three dots “…”) in your pom.xml:

1
2
3
4
5
6
7
8
9
<dependencies>
	...
	<dependency>
		<artifactId>refcodes-io</artifactId>
		<groupId>org.refcodes</groupId>
		<version>3.3.5</version>
	</dependency>
	...
</dependencies>

The artifact is hosted directly at Maven Central. Jump straight to the source codes at Bitbucket. Read the artifact’s javadoc at javadoc.io.

Snippets of interest

Below find some code snippets which demonstrate the various aspects of using the refcodes-io artifact (and , if applicable, its offsprings). See also the example source codes of this artifact for further information on the usage of this artifact.

Replaying input streams

The ReplayInputStream decorates any InputStream with replay functionality for streams not supporting the mark and reset operations:

1
2
3
4
5
6
7
8
9
10
11
12
13
...
InputStream theInptuStream = ...;
byte[] theBytes = new byte[16];
byte[] theReset = new byte[16];
try (ReplayInputStream theReplayInputStream = new ReplayInputStream( theInptuStream )) {
	theReplayInputStream.mark( 128 );
	theReplayInputStream.read( theBytes );
	...
	theReplayInputStream.reset();
	theReplayInputStream.read( theReset );
	...
}
...

In the above example, the replay size is set to 128 bytes (line 6) and the number of bytes we want to read twice is set to 16 (lines 3 and 4). We read the first 16 bytes (line 7) before resetting the stream (line 9) and reading the same bytes from the same stream again (line 10).

Filtering input streams

The FilterInputStream decorates any InputStream with filter functionality for removing unwanted data from the original stream:

1
2
3
4
5
6
7
8
9
10
...
InputStream theInptuStream = ...;
try (FilterInputStream theFilterInputStream = new FilterInputStream( theInputStream, '\n', '\t', '\r', ' ' )) {
	int e;
	while ( (e = theFilterInputStream.read()) != -1 ) {
		...
	}
	...
}
...

In the above example, we decorate our InputStream with a filter removing the white spaces \n, \t, \r as well as the space character (line 3). The data read from the InputStream (line 5) does not contain these white spaces anymore so that the filtered data can be processed (line 6) as required.

Find and replace for input streams

The ReplaceInputStream is similar to the FilterInputStream in that it manipulates any InputStream though instead of filtering data from the original stream data from the original stream is substituted with the according replacements:

1
2
3
4
5
6
7
8
9
10
...
InputStream theInptuStream = ...;
try (ReplaceInputStream theReplaceInputStream = new ReplaceInputStream( theInptuStream, "world", "universe" )) {
	int e;
	while ( (e = theReplaceInputStream.read()) != -1 ) {
		...
	}
	...
}
...

In the above example, we decorate our InputStream to replace the word “world” with the word “universe” (line 3). The data read from the InputStream (line 5) does now contain the words “universe” where the original stream has delivered the words “world” so that the modified (“find & replace”) data can be processed (line 6) as required. Instead of providing the words “world” and “universe”, you can use raw byte arrays. To apply multiple find & replace operations, you may nest multiple ReplaceInputStream instances.

Timeouted input streams

The TimeoutInputStream adds timeout functionality to the read operations of the original InputStream. The usage is straight forward:

1
2
3
4
5
6
7
8
9
10
...
InputStream theInptuStream = ...;
try (TimeoutInputStream theTimeoutInputStream = new TimeoutInputStream( theInptuStream, 500 )) {
	int e;
	while ( (e = theTimeoutInputStream.read()) != -1 ) {
		...
	}
	...
}
...

In the above example, we decorate our InputStream with a timeout of 500 milliseconds (line 3). In case the read operation exceeds the 500 milliseconds (line 5), an IOException is thrown (actually the more specific TimeoutIOException is being thrown).

The TimeoutInputStream works despite the decorated InputStream returning realistic values when calling the available method. If it can be guaranteed that the available method of the original InputStream returns realistic values, then you may use the AvailableInputStream: The benefit of the AvailableInputStream over the TimeoutInputStream is that the AvailableInputStream does not(!) use any additional threads for under the hood asynchronous operation!

Copy & paste to and from the clipboard

Copy

The ClipboardOutputStream provides an OutputStream for directly writing to the system’s clipboard. Whenever data is written to an OutputStream, the data may also be copied into the system clipboard by using the ClipboardOutputStream:

1
2
3
4
5
...
try (OutputStream theClipboardOutputStream = new ClipboardOutputStream()) {
	theClipboardOutputStream.write( "Hello world!" );
}
...

In the above example, after preparing to write to the clipboard (line 2), we copy the text “Hello world!” into the system’s clipboard (line 3).

Paste

The ClipboardInputStream provides the system’s clipboard as InputStream. Whenever data is read from an InputStream, the data may also be pasted from the system’s clipboard when using the ClipboardInputStream:

1
2
3
4
5
6
7
8
...
try (InputStream theClipboardInputStream = new ClipboardInputStream()) {
	int e;
	while ( (e = theClipboardInputStream.read()) != -1 ) {
		...
	}
}
...

In the above example, after preparing to read from the system clipboard (line 2), we paste from the system’s clipboard (line 4) for further processing (line 5).

Examples

See the example source codes of this artifact for further information on the usage of this artifact.

Contribution guidelines

Report issues
Finding bugs
Helping fixing bugs
Making code and documentation better
Enhance the code

Who do I talk to?

Siegfried Steiner (steiner@refcodes.org)

Terms and conditions

The REFCODES.ORG group of artifacts is published under some open source licenses; covered by the refcodes-licensing (org.refcodes group) artifact - evident in each artifact in question as of the pom.xml dependency included in such artifact.

refcodes-io: Paving the road for complex and low level I/O across boundaries

Categories

Tags