Cross-Platform C++

ot::io
class BufferedInputStream

#include "ot/io/BufferedInputStream.h"

ot::io::InputStream ot::ManagedObject A BufferedInputStream wraps another InputStream object and provides buffering as well as support for the mark() and reset() methods. When the BufferedInputStream is constructed, an internal buffer is created. The size of the internal buffer can be specified by using the overloaded constructor.

As bytes from the stream are read, the internal buffer is refilled as necessary from the contained input stream. In this way i/o efficiency can be improved by translating multiple small read operations into one large one.

To improve efficiency and avoid the needless copying of data, if the application performs a read request that is larger than the internal buffer, the internal buffer is empty and there is not a mark() operation outstanding, the internal buffer is bypassed and bytes are read directly into the application's buffer.

mark() and reset() are supported by buffering all data after a mark() operation until the readLimit has been exceeded. If mark() is called with a readLimit that is larger than the internal buffer, the buffer is re-allocated to the size requested.




Constructor/Destructor Summary
BufferedInputStream(InputStream* pInputStream)
         Constructs a BufferedInputStream with a default buffer size and pInputStream as the contained InputStream.
BufferedInputStream(InputStream* pInputStream, size_t bufSize)
         Constructs a BufferedInputStream using pInputStream as the contained input stream and a buffer size of bufSize.
~BufferedInputStream()
         Destroys the internal buffer.

Method Summary
 virtual size_t available()
         Returns the number of bytes that can be read without blocking.
 virtual void close()
         Closes the contained input stream and releases any system resources associated with it.
 virtual void mark(size_t readLimit)
         Marks the current position in the byte stream.
 virtual bool markSupported() const
         Tests whether the BufferedInputStream supports the mark() operation, which it does.
 virtual long read(Byte* pBuffer, size_t bufLen)
         Reads up to bufLen bytes into the supplied buffer.
 virtual void reset()
         Resets the position in the byte stream to a previously marked position.

Methods inherited from class ot::io::InputStream
read, skip

Methods inherited from class ot::ManagedObject
addRef, getRefCount, onFinalRelease, operator=, release

Constructor/Destructor Detail

BufferedInputStream

 BufferedInputStream(InputStream* pInputStream)
Constructs a BufferedInputStream with a default buffer size and pInputStream as the contained InputStream.

Exceptions:
NullPointerException - if pInputStream is null.

BufferedInputStream

 BufferedInputStream(InputStream* pInputStream,
                     size_t bufSize)
Constructs a BufferedInputStream using pInputStream as the contained input stream and a buffer size of bufSize. if bufSize is zero, the default buffer size is used.

Exceptions:
NullPointerException - if pInputStream is null.

~BufferedInputStream

virtual ~BufferedInputStream()
Destroys the internal buffer. Any buffered data that has not been read is lost. The contained InputStream is not closed by this operation.


Method Detail

available

virtual size_t available()
Returns the number of bytes that can be read without blocking. Some data sources (notably network socket and pipe streams) may make bytes available at a rate that is slower than the application can read them. In this case calls to read() may block until at least one byte becomes available. This method may be used to avoid making blocking calls.

Note, however, that the utility of this function is severely limited. Some sub-classes (e.g. FileInputStream) always return zero from available() and zero is also returned when the stream is at the end. For these reasons, it is rarely appropriate for an application to loop waiting for a positive return value from available().

Returns:
the number of bytes that can be read without blocking
Exceptions:
IOException - if an I/O error occurs

close

virtual void close()
Closes the contained input stream and releases any system resources associated with it.


mark

virtual void mark(size_t readLimit)
Marks the current position in the byte stream. Subsequent reset() operations will attempt to re-establish the stream's position to the marked position. This is guaranteed to succeed so long as the application does not read more than readLimit bytes.

When the readLimit is exceeded, the marked position is automatically invalidated, with the result that subsequent reset() operations will fail with an IOException.

Only one mark position is maintained by the InputStream. Further calls to mark() will establish a new mark position; reset() can only reset the position to the most recently established mark position.

If the current buffer has less than readLimit bytes available then the buffer is re-organized or reallocated so that is can hold at least readLimit bytes forward from the current position.

Parameters:
readLimit - specifies the minimum number of bytes that the BufferedInputStream must return before making the marked position invalid.
Exceptions:
IOException - if the input stream is closed
See also:
markSupported() , reset()

markSupported

virtual bool markSupported() const
Tests whether the BufferedInputStream supports the mark() operation, which it does.

Returns:
true.
See also:
mark() , reset()

read

virtual long read(Byte* pBuffer,
                  size_t bufLen)
Reads up to bufLen bytes into the supplied buffer.

Parameters:
pBuffer - A pointer to the buffer into which the bytes will be copied. This must be capable of holding at least bufLen bytes.
bufLen - The maximum number of bytes to read into the passed buffer. If this exceeds the maximum value that can be represented by a long integer, it is reduced to a value that can be so represented.
Returns:
The number of bytes read or InputStream::EndOfFile if the end of the stream has been reached.
Exceptions:
IllegalArgumentException - if bufLen is zero
NullPointerException - if pBuffer is null
IOException - if an error occurs while reading from the byte stream

reset

virtual void reset()
Resets the position in the byte stream to a previously marked position. It is permitted to call reset() multiple times. Each time it is called, the position will be reset to the position established by the most recent mark() operation.

Exceptions:
IOException - if mark() was not successfully called or the internal buffer has been exhausted (i.e. the readLimit specified in the mark() call has been exceeded)
IOException - if the InputStream is closed
See also:
mark()


Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements