net.sf.kdgcommons.io

Class CombiningInputStream

java.lang.Object

java.io.InputStream

net.sf.kdgcommons.io.CombiningInputStream

All Implemented Interfaces:

Closeable, AutoCloseable

public class CombiningInputStream
extends InputStream

This class combines multiple source streams into a single stream. This can be used for purposes ranging from combining files that were previously split, to inserting a standard prologue before a stream.

The behavior of several of the standard InputStream methods changes; see available() and mark(int) for details. Also, note that this class will not close its consituent streams unless you call close().

This class is not thread-safe.

Constructor Summary

Constructors

Constructor and Description
CombiningInputStream(InputStream... constituents) Combines one or more constituent streams.

Method Summary

Modifier and Type	Method and Description
int	available() Returns the number of bytes available without blocking, from the current stream.
void	close() Attempts to close all constituent streams.
void	mark(int readlimit) Sets a mark on the current stream.
boolean	markSupported() Determines whether a mark can be placed at this point in the stream.
int	read() Reads a single byte of data, transparently switching between input streams as necessary.
int	read(byte[] b)
int	read(byte[] b, int off, int len) Reads up to len bytes, transparently swtching between input streams as necessary.
void	reset()
long	skip(long n) Attempts to skip up to N bytes, transparently switching streams as needed.

Methods inherited from class java.lang.Object

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

Constructor Detail

CombiningInputStream

public CombiningInputStream(InputStream... constituents)

Combines one or more constituent streams.

Note that we directly use the passed array. If you want to play games with changing its elements after constructing the stream, you're on your own.

Method Detail

available

public int available()
              throws IOException

Returns the number of bytes available without blocking, from the current stream. Will not look at subsequent streams, because the current stream may have unreported data and would block when trying to read that data.

Overrides:

available in class InputStream

Throws:

IOException

close

public void close()
           throws IOException

Attempts to close all constituent streams. If any consituent stream throws an exception, will preserve that exception and continue to close other streams. If multiple streams throw, only the last will be preserved.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class InputStream

Throws:

IOException

read

public int read()
         throws IOException

Reads a single byte of data, transparently switching between input streams as necessary. Will block until either data is available, EOF is reached on the last stream, or an exception is thrown.

Specified by:

read in class InputStream

Returns:

The byte read, or -1 when EOF is reached on the last stream.

Throws:

IOException

read

public int read(byte[] b,
                int off,
                int len)
         throws IOException

Reads up to len bytes, transparently swtching between input streams as necessary. Will block when reading from the current stream, but does not block when switching streams; if no data is available from the new stream, will not attempt to read it.

Overrides:

read in class InputStream

Returns:

The number of bytes read from all streams, -1 if at EOF on the last stream.

Throws:

IOException

read

public int read(byte[] b)
         throws IOException

Overrides:

read in class InputStream

Throws:

IOException

markSupported

public boolean markSupported()

Determines whether a mark can be placed at this point in the stream. Examines the current and all subsequent streams, and returns true if all support marking. This means that you can set a mark if one of the constituent streams does not support marking, but you have already exhausted it.

Note that this will return false if you have exhausted a stream that does not support marking, but have not yet performed a read that switches streams. This method will not block.

Overrides:

markSupported in class InputStream

mark

public void mark(int readlimit)

Sets a mark on the current stream. The current stream and all subsequent streams must support marking; if not, the failure will occur during reset().

Overrides:

mark in class InputStream

reset

public void reset()
           throws IOException

Overrides:

reset in class InputStream

Throws:

IOException

skip

public long skip(long n)
          throws IOException

Attempts to skip up to N bytes, transparently switching streams as needed. Will return -1 if already at EOF, otherwise returns the number of bytes actually skipped.

This method is implemented by repeatedly calling skip() on the constituent streams. If any such call returns 0, we try to read from the stream to verify EOF. This can lead to an inefficient loop, in which skip() constantly indicates zero bytes, but we're able to read from the file. Shouldn't happen in practice.

Overrides:

skip in class InputStream

Throws:

IOException