com.cometway.io
Class PushBackBufferedInputStream

java.lang.Object
  java.io.InputStream
      com.cometway.io.PushBackBufferedInputStream

All Implemented Interfaces:

java.io.Closeable, java.lang.Runnable

public class PushBackBufferedInputStream
extends java.io.InputStream
implements java.lang.Runnable

This extension of InputStream is meant to be a J2ME compatible version of the J2SE PushBackInputStream and BufferedInputStream. If you are running J2SE, you are better off using java.io.BufferedInputStream and java.io.PushBackInputStream since they work natively and this class does not.

This class requires a Thread to do that actual reading of the parent InputStream and buffer it accordingly. It will block if the buffer is full and wait for read() to be called to free up more buffer space. The number of times it will wait is determined by the attemptsBeforeFlushBuffer field, which is by default set to 1. The danger of waiting for read() to be called in order to free up buffer space is incoming data through the parent InputStream may be lost. If this class waits the proper number of times and the buffer is still full, 1/3 of the front of the buffer will be flushed (thus the data will be lost). Uses of this class must understand how the parent InputStream works and how data is to be read from this InputStream. If data is sent quickly to the parent InputStream but data read from this class is slow, a large buffer and many attemptsBeforeFlushBuffer may be required for things to run smoothly. If it is expected that the calling thread of read() of this InputStream occurs more frequently than data is written to the parent InputStream, a small buffer_size and few attemptsBeforeFlushBuffer will suffice. If large number of bytes is expected to be pushed back (unread()), a larger buffer_size may be required. The push back mechanism will flush whatever data is at the end of the buffer when data is pushed back. The maximum memory usage for buffer arithemetic, where N is the buffer size, will not exceed 3N and will always be at least (5/4)N. The closeOnEOF field tells this InputStream to stop reading from the parent if it has reached EOF. Otherwise the Thread will continue to block until PushBackBufferedInputStream.close() is called.

See Also:

BufferedInputStream, java.io.PushBackInputStream

Field Summary

int	attemptsBeforeFlushBuffer THis field tells the buffering mechanism how many times to wait for the buffer to be read from before it flushes the buffer
boolean	closeOnEOF This field tells the buffering mechanism to stop reading from the parent InputStream if an EOF is encountered
static int	DEFAULT_BUFFER_SIZE This is the default buffer size.

Constructor Summary

PushBackBufferedInputStream(java.io.InputStream input)
Construct a PushBackBufferedInputStream with default parameters and the given parent InputStream.

PushBackBufferedInputStream(java.io.InputStream input, int buffer_size, int readTimeOut)
Construct a PushBackBufferedInputStream with the given parent InputStream, with a buffer whose size will be buffer_size and with a read() timeout of readTimeOut.

Method Summary

int	available() This method returns the number of available bytes that can be read from the buffer.
void	close() This method stops the reading of the parent InputStream and causes the run() method to return.
static void	main(java.lang.String[] args)
void	mark(int i) This functionality is not supported.
boolean	markSupported() This method will always return true
int	read() Read a single byte from the local buffer.
int	read(byte[] readBuffer) Read an array of bytes from the buffer (note: the number of bytes read will never exceed the size of the buffer).
int	read(byte[] readBuffer, int start, int length) Read an array of bytes form the buffer with a starting position and length.
void	reset() THis funcitonality is not supported.
void	run() This method reads bytes from the parent InputStream and buffers it accordingly.
void	stop() This method will cause the run() method to return, thus freeing the thread that this instance of PushBackBufferedInputStream was using.
void	unread(byte[] b) Push an array of bytes back into the buffer.
void	unread(byte[] b, int start, int length) Push an array of bytes back into the buffer.
void	unread(int b) Push a byte back into the buffer.

Methods inherited from class java.io.InputStream

skip

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

This is the default buffer size. This size is used if the buffer size is not provided

See Also:

Constant Field Values

attemptsBeforeFlushBuffer

public int attemptsBeforeFlushBuffer

THis field tells the buffering mechanism how many times to wait for the buffer to be read from before it flushes the buffer

closeOnEOF

public boolean closeOnEOF

This field tells the buffering mechanism to stop reading from the parent InputStream if an EOF is encountered

Constructor Detail

PushBackBufferedInputStream

public PushBackBufferedInputStream(java.io.InputStream input,
                                   int buffer_size,
                                   int readTimeOut)

Construct a PushBackBufferedInputStream with the given parent InputStream, with a buffer whose size will be buffer_size and with a read() timeout of readTimeOut.

PushBackBufferedInputStream

public PushBackBufferedInputStream(java.io.InputStream input)

Construct a PushBackBufferedInputStream with default parameters and the given parent InputStream.

Method Detail

read

public int read()
         throws java.io.IOException,
                java.io.InterruptedIOException

Read a single byte from the local buffer.

Specified by:

read in class java.io.InputStream

Throws:

java.io.IOException

java.io.InterruptedIOException

read

public int read(byte[] readBuffer)
         throws java.io.IOException

Read an array of bytes from the buffer (note: the number of bytes read will never exceed the size of the buffer).

Overrides:

read in class java.io.InputStream

Returns:

the number of bytes that were read.

Throws:

java.io.IOException

read

public int read(byte[] readBuffer,
                int start,
                int length)
         throws java.io.IOException

Read an array of bytes form the buffer with a starting position and length. (note: the number of bytes read will never exceed the size of the buffer).

Overrides:

read in class java.io.InputStream

Returns:

the number of bytes that were read.

Throws:

java.io.IOException

unread

public void unread(int b)
            throws java.io.IOException

Push a byte back into the buffer. If the buffer is currently full, the last byte in the buffer is flushed.

Throws:

java.io.IOException

unread

public void unread(byte[] b)
            throws java.io.IOException

Push an array of bytes back into the buffer. The bytes at the end of the buffer will be flushed (if the length of the array is greater than the amount of space left in the buffer).

Throws:

java.io.IOException

unread

public void unread(byte[] b,
                   int start,
                   int length)
            throws java.io.IOException

Push an array of bytes back into the buffer. The bytes at the end of the buffer will be flushed (if the length of the array is greater than the amount of space left in the buffer).

Throws:

java.io.IOException

run

public void run()

This method reads bytes from the parent InputStream and buffers it accordingly. If the buffer is full, it will block until bytes are read from the buffer. If the buffer is STILL full, it will continue to block attemptsBeforeFlushBuffer times. After this, if the buffer is STILL full, 1/3 of the front of the buffer (the least recently read bytes) will be flushed and that data will be lost.

Specified by:

run in interface java.lang.Runnable

available

public int available()

This method returns the number of available bytes that can be read from the buffer.

Overrides:

available in class java.io.InputStream

close

public void close()
           throws java.io.IOException

This method stops the reading of the parent InputStream and causes the run() method to return. The parent InputStream will also be closed.

Specified by:

close in interface java.io.Closeable

Overrides:

close in class java.io.InputStream

Throws:

java.io.IOException

mark

public void mark(int i)

This functionality is not supported.

Overrides:

mark in class java.io.InputStream

reset

public void reset()

THis funcitonality is not supported.

Overrides:

reset in class java.io.InputStream

markSupported

public boolean markSupported()

This method will always return true

Overrides:

markSupported in class java.io.InputStream

stop

public void stop()

This method will cause the run() method to return, thus freeing the thread that this instance of PushBackBufferedInputStream was using. The parent InputStream will not be closed.

main

public static void main(java.lang.String[] args)