Module org.refcodes.io

Package org.refcodes.io

Class AvailableInputStream

java.lang.Object

java.io.InputStream

org.refcodes.io.TimeoutInputStream

org.refcodes.io.AvailableInputStream

All Implemented Interfaces:

Closeable, AutoCloseable, org.refcodes.mixin.ReadTimeoutMillisAccessor

public class AvailableInputStream
extends TimeoutInputStream

The AvailableInputStream decorates an InputStream with time-out functionality using the InputStream.available() method. This decorator works only when the decorated InputStream returns realistic values when calling InputStream.available(). This is most probably the case e.g. for serial communication (TTY/COM) as those devices usually buffer for incoming bytes. If this cannot be guaranteed, please use the TimeoutInputStream! The benefit of the AvailableInputStream over the TimeoutInputStream is that the AvailableInputStream does not use any additional threads for asynchronous operation so it is a good fit for IoT devices!

Nested Class Summary

Nested classes/interfaces inherited from interface org.refcodes.mixin.ReadTimeoutMillisAccessor

org.refcodes.mixin.ReadTimeoutMillisAccessor.ReadTimeoutMillisBuilder<B extends org.refcodes.mixin.ReadTimeoutMillisAccessor.ReadTimeoutMillisBuilder<B>>, org.refcodes.mixin.ReadTimeoutMillisAccessor.ReadTimeoutMillisMutator, org.refcodes.mixin.ReadTimeoutMillisAccessor.ReadTimeoutMillisProperty

Field Summary

Fields inherited from class org.refcodes.io.TimeoutInputStream

_inputStream, _isClosed, _readTimeoutMillis

Constructor Summary

Constructors

Constructor	Description
AvailableInputStream(InputStream aInputStream)	Constructs a AvailableInputStream decorating an InputStream with additional timeout functionality.
AvailableInputStream(InputStream aInputStream, long aTimeoutMillis)	Constructs a AvailableInputStream decorating an InputStream with additional timeout functionality.
AvailableInputStream(InputStream aInputStream, long aTimeoutMillis, Object aMonitor)	Constructs a AvailableInputStream decorating an InputStream with additional timeout functionality.
AvailableInputStream(InputStream aInputStream, Long aTimeoutMillis)	Constructs a AvailableInputStream decorating an InputStream with additional timeout functionality.
AvailableInputStream(InputStream aInputStream, Object aMonitor)	Constructs a AvailableInputStream decorating an InputStream with additional timeout functionality.

Method Summary

Modifier and Type	Method	Description
int	read(byte[] b, int off, int len, long aTimeoutMillis)	Enriches the TimeoutInputStream.read(byte[], int, int) method with a timeout.
int	read(byte[] b, long aTimeoutMillis)	Enriches the TimeoutInputStream.read(byte[]) method with a timeout.
int	read(long aTimeoutMillis)	Enriches the TimeoutInputStream.read() method with a timeout.
int	readNBytes(byte[] b, int off, int len, long aTimeoutMillis)	Enriches the TimeoutInputStream.readNBytes(byte[], int, int) method with a timeout.
byte[]	readNBytes(int len, long aTimeoutMillis)	Enriches the TimeoutInputStream.readNBytes(int) method with a timeout.

Methods inherited from class org.refcodes.io.TimeoutInputStream

available, close, getReadTimeoutMillis, mark, markSupported, read, read, read, readAllBytes, readNBytes, readNBytes, reset, skip, skipNBytes, transferTo

Methods inherited from class java.io.InputStream

nullInputStream, readAllBytes, skip, skipNBytes, transferTo

Methods inherited from class java.lang.Object

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

Constructor Details

AvailableInputStream

public AvailableInputStream(InputStream aInputStream,
 long aTimeoutMillis)

Constructs a AvailableInputStream decorating an InputStream with additional timeout functionality.

Parameters:

aInputStream - The InputStream to be decorated.

aTimeoutMillis - The default timeout for read operations not explicitly called with a timeout argument. With a value of -1 timeout handling is disabled (blocking mode).

AvailableInputStream

public AvailableInputStream(InputStream aInputStream,
 Long aTimeoutMillis)

Constructs a AvailableInputStream decorating an InputStream with additional timeout functionality.

Parameters:

aInputStream - The InputStream to be decorated.

aTimeoutMillis - The default timeout for read operations not explicitly called with a timeout argument. With a value of -1 timeout handling is disabled (blocking mode).

AvailableInputStream

public AvailableInputStream(InputStream aInputStream,
 Object aMonitor)

Constructs a AvailableInputStream decorating an InputStream with additional timeout functionality.

Parameters:

aInputStream - The InputStream to be decorated.

aMonitor - The monitor to use when waiting the poll loop time. This is useful required available data can be read before the poll loop time expires. E.g. an underlying system might call Object.notifyAll() on the monitor as soon as it received new data.

AvailableInputStream

public AvailableInputStream(InputStream aInputStream)

Constructs a AvailableInputStream decorating an InputStream with additional timeout functionality.

Parameters:

aInputStream - The InputStream to be decorated.

AvailableInputStream

public AvailableInputStream(InputStream aInputStream,
 long aTimeoutMillis,
 Object aMonitor)

Constructs a AvailableInputStream decorating an InputStream with additional timeout functionality.

Parameters:

aInputStream - The InputStream to be decorated.

aTimeoutMillis - The default timeout for read operations not explicitly called with a timeout argument. With a value of -1 timeout handling is disabled (blocking mode).

aMonitor - The monitor to use when waiting the poll loop time. This is useful required available data can be read before the poll loop time expires. E.g. an underlying system might call Object.notifyAll() on the monitor as soon as it received new data.

Method Details

read

public int read(long aTimeoutMillis)
         throws IOException

Enriches the TimeoutInputStream.read() method with a timeout. This methods blocks till the result is available and can be returned or the timeout is reached. A timeout of -1 disables the timeout.

Overrides:

read in class TimeoutInputStream

Parameters:

aTimeoutMillis - The timeout in milliseconds to wait for the next byte available.With a value of -1 timeout handling is disabled (blocking mode).

Returns:

The next byte of data, or -1 if the end of the stream is reached.

Throws:

IOException - thrown in case of according I/O related problems or an expired timeout.

read

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

Enriches the TimeoutInputStream.read(byte[], int, int) method with a timeout. This methods blocks till the result is available and can be returned or the timeout is reached. A timeout of -1 disables the timeout.

Overrides:

read in class TimeoutInputStream

Parameters:

b - The byte array into which the data is read.

off - The start offset in b at which the data is written.

len - The maximum number of bytes to read.

aTimeoutMillis - The timeout in milliseconds to wait for the next byte available.With a value of -1 timeout handling is disabled (blocking mode).

Returns:

The total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.

Throws:

IOException - thrown in case of according I/O related problems or an expired timeout.

read

public int read(byte[] b,
 long aTimeoutMillis)
         throws IOException

Enriches the TimeoutInputStream.read(byte[]) method with a timeout. This methods blocks till the result is available and can be returned or the timeout is reached. A timeout of -1 disables the timeout. Calling this method has the same effect a read(b, 0, b.length), so we try to read as many bytes as the buffer's length is.

Overrides:

read in class TimeoutInputStream

Parameters:

b - The byte array into which the data is read.

aTimeoutMillis - The timeout in milliseconds to wait for the next byte available.With a value of -1 timeout handling is disabled (blocking mode).

Returns:

The total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.

Throws:

IOException - thrown in case of according I/O related problems or an expired timeout.

readNBytes

public int readNBytes(byte[] b,
 int off,
 int len,
 long aTimeoutMillis)
               throws IOException

Enriches the TimeoutInputStream.readNBytes(byte[], int, int) method with a timeout. This methods blocks till the result is available and can be returned or the timeout is reached. A timeout of -1 disables the timeout.

Overrides:

readNBytes in class TimeoutInputStream

Parameters:

b - the byte array into which the data is read

off - the start offset in b at which the data is written

len - the maximum number of bytes to read

aTimeoutMillis - The timeout in milliseconds.

Returns:

the actual number of bytes read into the buffer

Throws:

IOException - if an I/O error occurs

readNBytes

public byte[] readNBytes(int len,
 long aTimeoutMillis)
                  throws IOException

Enriches the TimeoutInputStream.readNBytes(int) method with a timeout. This methods blocks till the result is available and can be returned or the timeout is reached. A timeout of -1 disables the timeout.

Overrides:

readNBytes in class TimeoutInputStream

Parameters:

len - the maximum number of bytes to read

aTimeoutMillis - The timeout in milliseconds.

Returns:

The byte array containing the bytes read from this input stream

Throws:

IOException - Signals that an I/O exception has occurred.