A base class that must be implemented by all classes wishing to provide a class that reads in a stream of bytes. More...

#include <src/main/decaf/io/InputStream.h>

Inheritance diagram for decaf::io::InputStream:

[legend]

Public Member Functions
	InputStream ()
virtual	~InputStream ()
virtual void	close ()
	Closes the InputStream freeing any resources that might have been acquired during the lifetime of this stream.
virtual void	mark (int readLimit)
	Marks the current position in the stream A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes.
virtual void	reset ()
	Repositions this stream to the position at the time the mark method was last called on this input stream.
virtual bool	markSupported () const
	Determines if this input stream supports the mark and reset methods.
virtual int	available () const
	Indicates the number of bytes available.
virtual int	read ()
	Reads a single byte from the buffer.
virtual int	read (unsigned char *buffer, int size)
	Reads up to size bytes of data from the input stream into an array of bytes.
virtual int	read (unsigned char *buffer, int size, int offset, int length)
	Reads up to length bytes of data from the input stream into an array of bytes.
virtual long long	skip (long long num)
	Skips over and discards n bytes of data from this input stream.
virtual std::string	toString () const
	Output a String representation of this object.
virtual void	lock ()
	Locks the object.
virtual bool	tryLock ()
	Attempts to Lock the object, if the lock is already held by another thread than this method returns false.
virtual void	unlock ()
	Unlocks the object.
virtual void	wait ()
	Waits on a signal from this object, which is generated by a call to Notify.
virtual void	wait (long long millisecs)
	Waits on a signal from this object, which is generated by a call to Notify.
virtual void	wait (long long millisecs, int nanos)
	Waits on a signal from this object, which is generated by a call to Notify.
virtual void	notify ()
	Signals a waiter on this object that it can now wake up and continue.
virtual void	notifyAll ()
	Signals the waiters on this object that it can now wake up and continue.
Public Member Functions inherited from decaf::io::Closeable
virtual	~Closeable ()
Public Member Functions inherited from decaf::util::concurrent::Synchronizable
virtual	~Synchronizable ()

Protected Member Functions
virtual int	doReadByte ()=0
virtual int	doReadArray (unsigned char *buffer, int size)
virtual int	doReadArrayBounded (unsigned char *buffer, int size, int offset, int length)

Detailed Description

A base class that must be implemented by all classes wishing to provide a class that reads in a stream of bytes.

Since: 1.0

Constructor & Destructor Documentation

decaf::io::InputStream::InputStream ( )

virtual decaf::io::InputStream::~InputStream ( )

virtual

Member Function Documentation

virtual int decaf::io::InputStream::available ( ) const

inlinevirtual

Indicates the number of bytes available.

The default implementation of this methods returns 0. Classes that override this method may return the total number of bytes that are currently available for reading and others may simply return a value of one indicating that there is some data avaiable. The caller should view the result of this method as an absolute.

The default implementation of this method returns zero.

Returns: the number of bytes available on this input stream.

Exceptions

IOException if an I/O error occurs.

Reimplemented in decaf::io::ByteArrayInputStream, decaf::io::PushbackInputStream, decaf::util::zip::InflaterInputStream, decaf::io::BufferedInputStream, decaf::io::BlockingByteArrayInputStream, decaf::io::FilterInputStream, decaf::internal::net::tcp::TcpSocketInputStream, decaf::internal::net::ssl::openssl::OpenSSLSocketInputStream, and decaf::internal::io::StandardInputStream.

virtual void decaf::io::InputStream::close ( )

virtual

Closes the InputStream freeing any resources that might have been acquired during the lifetime of this stream.

The default implementation of this method does nothing.

Exceptions

IOException if an I/O error occurs while closing the InputStream.

Implements decaf::io::Closeable.

Reimplemented in decaf::util::zip::InflaterInputStream, decaf::io::BufferedInputStream, decaf::io::BlockingByteArrayInputStream, decaf::io::FilterInputStream, decaf::internal::net::tcp::TcpSocketInputStream, and decaf::internal::net::ssl::openssl::OpenSSLSocketInputStream.

virtual int decaf::io::InputStream::doReadArray	(	unsigned char *	buffer,
		int	size
	)

protectedvirtual

Reimplemented in decaf::io::FilterInputStream.

virtual int decaf::io::InputStream::doReadArrayBounded	(	unsigned char *	buffer,
		int	size,
		int	offset,
		int	length
	)

protectedvirtual

Reimplemented in decaf::io::ByteArrayInputStream, decaf::util::zip::InflaterInputStream, decaf::io::PushbackInputStream, decaf::io::BufferedInputStream, decaf::io::FilterInputStream, decaf::io::BlockingByteArrayInputStream, decaf::internal::net::tcp::TcpSocketInputStream, decaf::util::zip::CheckedInputStream, decaf::internal::net::ssl::openssl::OpenSSLSocketInputStream, and activemq::io::LoggingInputStream.

virtual int decaf::io::InputStream::doReadByte ( )

protectedpure virtual

Implemented in decaf::io::ByteArrayInputStream, decaf::util::zip::InflaterInputStream, decaf::io::PushbackInputStream, decaf::io::BufferedInputStream, decaf::io::FilterInputStream, decaf::io::BlockingByteArrayInputStream, decaf::internal::net::tcp::TcpSocketInputStream, decaf::util::zip::CheckedInputStream, decaf::internal::net::ssl::openssl::OpenSSLSocketInputStream, activemq::io::LoggingInputStream, and decaf::internal::io::StandardInputStream.

virtual void decaf::io::InputStream::lock ( )

inlinevirtual

Locks the object.

Exceptions

RuntimeException if an error occurs while locking the object.

Implements decaf::util::concurrent::Synchronizable.

virtual void decaf::io::InputStream::mark ( int readLimit )

virtual

Marks the current position in the stream A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes.

If a stream instance reports that marks are supported then the stream will ensure that the same bytes can be read again after the reset method is called so long the readLimit is not reached.

Calling mark on a closed stream instance should have no effect.

The default implementation of this method does nothing.

Parameters

readLimit The max bytes read before marked position is invalid.

Reimplemented in decaf::io::ByteArrayInputStream, decaf::io::PushbackInputStream, decaf::util::zip::InflaterInputStream, decaf::io::BufferedInputStream, and decaf::io::FilterInputStream.

virtual bool decaf::io::InputStream::markSupported ( ) const

inlinevirtual

Determines if this input stream supports the mark and reset methods.

Whether or not mark and reset are supported is an invariant property of a particular input stream instance.

The default implementation of this method returns false.

Returns: true if this stream instance supports marks

Reimplemented in decaf::io::ByteArrayInputStream, decaf::io::PushbackInputStream, decaf::util::zip::InflaterInputStream, decaf::io::BufferedInputStream, and decaf::io::FilterInputStream.

virtual void decaf::io::InputStream::notify ( )

inlinevirtual

Signals a waiter on this object that it can now wake up and continue.

Must have this object locked before calling.

Exceptions

IllegalMonitorStateException	- if the current thread is not the owner of the the Synchronizable Object.
RuntimeException	if an error occurs while notifying one of the waiting threads.

Implements decaf::util::concurrent::Synchronizable.

virtual void decaf::io::InputStream::notifyAll ( )

inlinevirtual

Signals the waiters on this object that it can now wake up and continue.

Must have this object locked before calling.

Exceptions

IllegalMonitorStateException	- if the current thread is not the owner of the the Synchronizable Object.
RuntimeException	if an error occurs while notifying the waiting threads.

Implements decaf::util::concurrent::Synchronizable.

virtual int decaf::io::InputStream::read ( )

virtual

Reads a single byte from the buffer.

The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

The default implementation of this method calls the internal virtual method doReadByte which is a pure virtual method and must be overridden by all subclasses.

Returns: The next byte or -1 if the end of stream is reached.

Exceptions

IOException if an I/O error occurs.

virtual int decaf::io::InputStream::read	(	unsigned char *	buffer,
		int	size
	)

virtual

Reads up to size bytes of data from the input stream into an array of bytes.

An attempt is made to read as many as size bytes, but a smaller number may be read. The number of bytes actually read is returned as an integer.

This method blocks until input data is available, end of file is detected, or an exception is thrown.

If size is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b.

This method called the protected virtual method doReadArray which by default is the same as calling read( buffer, size, 0, size ). Subclasses can customize the behavior of this method by overriding the doReadArray method to provide a better performing read operation.

Parameters

buffer	The target buffer to write the read in data to.
size	The size in bytes of the target buffer.

Returns: The number of bytes read or -1 if EOF is detected

Exceptions

IOException	if an I/O error occurs.
NullPointerException	if buffer passed is NULL.

virtual int decaf::io::InputStream::read	(	unsigned char *	buffer,
		int	size,
		int	offset,
		int	length
	)

virtual

Reads up to length bytes of data from the input stream into an array of bytes.

An attempt is made to read as many as length bytes, but a smaller number may be read. The number of bytes actually read is returned as an integer.

This method blocks until input data is available, end of file is detected, or an exception is thrown.

If length is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b.

The first byte read is stored into element b[off], the next one into b[off+1], and so on. The number of bytes read is, at most, equal to length. Let k be the number of bytes actually read; these bytes will be stored in elements b[off] through b[off+k-1], leaving elements b[offset+k] through b[offset+length-1] unaffected.

In every case, elements b[0] through b[offset] and elements b[offset+length] through b[b.length-1] are unaffected.

This method called the protected virtual method doReadArrayBounded which simply calls the method doReadByte() repeatedly. If the first such call results in an IOException, that exception is returned. If any subsequent call to doReadByte() results in a IOException, the exception is caught and treated as if it were end of file; the bytes read up to that point are stored into the buffer and the number of bytes read before the exception occurred is returned. The default implementation of this method blocks until the requested amount of input data has been read, end of file is detected, or an exception is thrown. Subclasses are encouraged to provide a more efficient implementation of this method.

Parameters

buffer	The target buffer to write the read in data to.
size	The size in bytes of the target buffer.
offset	The position in the buffer to start inserting the read in data.
length	The maximum number of bytes that should be read into buffer.

Returns: The number of bytes read or -1 if EOF is detected

Exceptions

IOException	if an I/O error occurs.
NullPointerException	if buffer passed is NULL.
IndexOutOfBoundsException	if length > size - offset.

virtual void decaf::io::InputStream::reset ( )

virtual

Repositions this stream to the position at the time the mark method was last called on this input stream.

If the method markSupported returns true, then:

If the method mark has not been called since the stream was created, or the number of bytes read from the stream since mark was last called is larger than the argument to mark at that last call, then an IOException might be thrown.
If such an IOException is not thrown, then the stream is reset to a state such that all the bytes read since the most recent call to mark (or since the start of the file, if mark has not been called) will be resupplied to subsequent callers of the read method, followed by any bytes that otherwise would have been the next input data as of the time of the call to reset.

If the method markSupported returns false, then:

The call to reset may throw an IOException.
If an IOException is not thrown, then the stream is reset to a fixed state that depends on the particular type of the input stream and how it was created. The bytes that will be supplied to subsequent callers of the read method depend on the particular type of the input stream.

The default implementation of this method throws an IOException.

Exceptions

IOException if an I/O error occurs.

Reimplemented in decaf::io::ByteArrayInputStream, decaf::io::PushbackInputStream, decaf::util::zip::InflaterInputStream, decaf::io::BufferedInputStream, and decaf::io::FilterInputStream.

virtual long long decaf::io::InputStream::skip ( long long num )

virtual

Skips over and discards n bytes of data from this input stream.

The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. The actual number of bytes skipped is returned.

The skip method of InputStream creates a byte array and then repeatedly reads into it until num bytes have been read or the end of the stream has been reached. Subclasses are encouraged to provide a more efficient implementation of this method.

Parameters

num	The number of bytes to skip.

Returns: total bytes skipped

Exceptions

IOException	if an I/O error occurs.
UnsupportedOperationException	if the concrete stream class does not support skipping bytes.

Reimplemented in decaf::io::ByteArrayInputStream, decaf::io::PushbackInputStream, decaf::util::zip::InflaterInputStream, decaf::io::BufferedInputStream, decaf::io::BlockingByteArrayInputStream, decaf::internal::net::tcp::TcpSocketInputStream, decaf::io::FilterInputStream, decaf::util::zip::CheckedInputStream, and decaf::internal::net::ssl::openssl::OpenSSLSocketInputStream.

virtual std::string decaf::io::InputStream::toString ( ) const

virtual

Output a String representation of this object.

The default version of this method just prints the Class Name.

Returns: a string representation of the object.

virtual bool decaf::io::InputStream::tryLock ( )

inlinevirtual

Attempts to Lock the object, if the lock is already held by another thread than this method returns false.

Returns: true if the lock was acquired, false if it is already held by another thread.

Exceptions

RuntimeException if an error occurs while locking the object.

Implements decaf::util::concurrent::Synchronizable.

virtual void decaf::io::InputStream::unlock ( )

inlinevirtual

Unlocks the object.

Exceptions

RuntimeException if an error occurs while unlocking the object.

Implements decaf::util::concurrent::Synchronizable.

virtual void decaf::io::InputStream::wait ( )

inlinevirtual

Waits on a signal from this object, which is generated by a call to Notify.

Must have this object locked before calling.

Exceptions

RuntimeException	if an error occurs while waiting on the object.
InterruptedException	if the wait is interrupted before it completes.
IllegalMonitorStateException	- if the current thread is not the owner of the the Synchronizable Object.

Implements decaf::util::concurrent::Synchronizable.

virtual void decaf::io::InputStream::wait ( long long millisecs )

inlinevirtual

Waits on a signal from this object, which is generated by a call to Notify.

Must have this object locked before calling. This wait will timeout after the specified time interval.

Parameters

millisecs the time in milliseconds to wait, or WAIT_INIFINITE

Exceptions

RuntimeException	if an error occurs while waiting on the object.
InterruptedException	if the wait is interrupted before it completes.
IllegalMonitorStateException	- if the current thread is not the owner of the the Synchronizable Object.

Implements decaf::util::concurrent::Synchronizable.

virtual void decaf::io::InputStream::wait	(	long long	millisecs,
		int	nanos
	)

inlinevirtual

Waits on a signal from this object, which is generated by a call to Notify.

Must have this object locked before calling. This wait will timeout after the specified time interval. This method is similar to the one argument wait function except that it add a finer grained control over the amount of time that it waits by adding in the additional nanosecond argument.

NOTE: The ability to wait accurately at a nanosecond scale depends on the platform and OS that the Decaf API is running on, some systems do not provide an accurate enough clock to provide this level of granularity.

Parameters

millisecs	the time in milliseconds to wait, or WAIT_INIFINITE
nanos	additional time in nanoseconds with a range of 0-999999

Exceptions

IllegalArgumentException	if an error occurs or the nanos argument is not in the range of [0-999999]
RuntimeException	if an error occurs while waiting on the object.
InterruptedException	if the wait is interrupted before it completes.
IllegalMonitorStateException	- if the current thread is not the owner of the the Synchronizable Object.

Implements decaf::util::concurrent::Synchronizable.

The documentation for this class was generated from the following file:

src/main/decaf/io/InputStream.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation