net.sf.zig_project.gpl.common.io
Class TelescopicInputStream

java.lang.Object
  java.io.InputStream
      java.io.FilterInputStream
          net.sf.zig_project.gpl.common.io.TelescopicInputStream

public class TelescopicInputStream

extends FilterInputStream

An InputStream that not only encapsulates another InputStream, but is encapsulated by an InputStream. When such a stream encounters a subsection that requires an additional filter, it can be inserted as an "expansion" into the correct location within the stream. Likewise, when a filter has completed operation, the stream can "collapse" removing the pass through filtration.

For example consider a hypothetical network stream.

Socket input stream -> decompresser -> application input

During a bulk read, an encryption enable feature is discovered. First, the remainder the bulk read is put back into the input stream, as

Socket input stream -> decompresser -> byte[] reservoir -> application input

then the stream is expanded with a decipher stream

Socket input stream -> decompresser -> byte[] reservoir -> decipher -> application input

as input is read from the stream, eventually the reservoir is depleted, and the memory can be reclaimed.

Socket input stream -> decompresser -> byte[] reservoir -> decipher -> application input

Leaving the present stream as:

Socket input stream -> decompresser -> decipher -> application input

The default implementation of this class will automatically collapse. Subclasses are encouraged to override the read(byte[], int, int) and read() methods, calling their super counterparts to indicate that filtration has completed and the filter may be safely collapsed.

Version:

November 27, 2004

Author:

Frank Ziglar

Field Summary

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

TelescopicInputStream(InputStream is)
Creates a new TelescopicInputStream using is as the underlayer.

Method Summary

protected void	complete() Called when the current filter has completed all possible filtration.
int	read() Reads one byte from the input.
int	read(byte[] buf, int off, int len) Bulk read from input.

Methods inherited from class java.io.FilterInputStream

available, close, mark, markSupported, read, reset, skip

Methods inherited from class java.lang.Object

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

Constructor Detail

TelescopicInputStream

public TelescopicInputStream(InputStream is)

Creates a new TelescopicInputStream using is as the underlayer.

Method Detail

complete

protected void complete()

Called when the current filter has completed all possible filtration. This method will attempt to collapse the current filter, joining the overlayer directly to the underlayer. However, if a join can not be completed, this method does nothing.

read

public int read()
         throws IOException

Reads one byte from the input. The default will attempt to collapse the current stream after returning

Returns:

a value < 0 if the input can not complete (such as an end of stream). Otherwise, returns an unsigned byte from the input.

Throws:

IOException

read

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

Bulk read from input. The default will attempt to collapse the current stream after returning directly from the underlayer.

Returns:

a value < 0 if the input can not complete (such as an end of stream). Otherwise, returns the number of bytes read into the buffer.

Throws:

IOException