nu.dll.io
Class SpyInputStream

java.lang.Object
  |
  +--java.io.InputStream
        |
        +--java.io.FilterInputStream
              |
              +--nu.dll.io.SpyInputStream

public class SpyInputStream

extends java.io.FilterInputStream

The SpyInputStream and SpyOutputStream classes are Input- and OutputStream filters that enabled "spying" on input and output streams by attaching OutputStream objects as "spies", to which, whenever data is written to or read from the underlying stream, exactly the same data is written to all currently attached spy output streams.

The eavesdroppers can be attached and removed through the addSpy() and removeSpy() methods, or by the two-args constructor which takes an output stream to dump the data to as the second argument. An arbitrary number of spy streams can be attached, but it inevitably affects the performance, since read() and write() methods blocks until all data has been written to all eavesdropping output streams.

The data is written to the attached eavesdroppers using the same methods by which the SpyStream object is called, or, in the case of SpyInputStream, each read() call triggers it's eavesdropper's corresponding write() call.

This class also contains the functionality to print out debug information every n bytes, where n is set by the setStatusLimit(int) method (defaults to 100 bytes). It also keeps track of the total number of bytes passed through the underlying stream. This is useful to debug the efficiency of bulk write() calls, for example.

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

SpyInputStream(java.io.InputStream in)
Constructs a SpyInputStream with no eavesdropping output stream.

SpyInputStream(java.io.InputStream in, java.io.OutputStream out)
Constructs a SpyInputStream with one eavesdropping output stream.

Method Summary

void	addSpy(java.io.OutputStream spy) Adds an OutputStream as an eavesdropper to this stream.
void	close() Closes the underlying input stream, but not any eavesdropping output streams.
void	finalize() If autoStatus, write the byte count upon object finalization.
long	getCount() Returns the total number of bytes passed through the underlying OutputStream.
long	getCountOff() Returns the number of bytes read since the last call to this method.
int	read() Reads one byte from the underlying input stream, incrementing the byte count by one if successful, and writes the byte to all eavesdropping output stream.
int	read(byte[] b, int off, int len) Reads len bytes from the underlying input stream, placing them into the supplied byte array b at the supplied offset off, according the general contract of java.io.InputStream.read(byte[], int, int).
void	removeSpy(java.io.OutputStream spy) Removes the supplied OutputStream from the list of eavesdroppers.
void	setAutoStatus(boolean B) Tells this SpyInputStream to automatically print status messages about the total number of bytes written, to stdout, every n bytes passed through the underlying input stream.
void	setStatusLimit(long I) Sets the treshold of the number of bytes to pass before automatically writing debug info to stdout.
protected static void	trace(java.lang.String s)
void	writeStatusMaybe() If the number of bytes read since the last call to this method exceeds the value of statusLimit (set by setStatusLimit()), debug data containing the number of bytes totally read and and since last call is written to System.out.

Methods inherited from class java.io.FilterInputStream

available, mark, markSupported, read, reset, skip

Methods inherited from class java.lang.Object

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

Constructor Detail

SpyInputStream

public SpyInputStream(java.io.InputStream in)

Constructs a SpyInputStream with no eavesdropping output stream.

Parameters:

in - the underlying InputStream from which to read data from

SpyInputStream

public SpyInputStream(java.io.InputStream in,
                      java.io.OutputStream out)

Constructs a SpyInputStream with one eavesdropping output stream.

Parameters:

in - the underlying InputStream from which to read data from

out - an OutputStream to write all read data to

Method Detail

addSpy

public void addSpy(java.io.OutputStream spy)

Adds an OutputStream as an eavesdropper to this stream.

Parameters:

spy - an OutputStream to write all read data to

removeSpy

public void removeSpy(java.io.OutputStream spy)

Removes the supplied OutputStream from the list of eavesdroppers.

Parameters:

spy - the OutputStream to be removed

setAutoStatus

public void setAutoStatus(boolean B)

Tells this SpyInputStream to automatically print status messages about the total number of bytes written, to stdout, every n bytes passed through the underlying input stream.

Parameters:

B - if true, debug data will be written

See Also:

setStatusLimit(long)

setStatusLimit

public void setStatusLimit(long I)

Sets the treshold of the number of bytes to pass before automatically writing debug info to stdout.

Parameters:

I - the number of bytes

See Also:

setAutoStatus(boolean)

read

public int read()
         throws java.io.IOException

Reads one byte from the underlying input stream, incrementing the byte count by one if successful, and writes the byte to all eavesdropping output stream. Perhaps writes debug info to stdout if autoStatus is true

Overrides:

read in class java.io.FilterInputStream

See Also:

setAutoStatus(boolean), setStatusLimit(long), InputStream.read()

read

public int read(byte[] b,
                int off,
                int len)
         throws java.io.IOException

Reads len bytes from the underlying input stream, placing them into the supplied byte array b at the supplied offset off, according the general contract of java.io.InputStream.read(byte[], int, int). Additionally, increments the byte count by the number of bytes actually read, and writes the bytes to all eavesdropping output stream. Perhaps writes debug info to stdout if autoStatus is true

Overrides:

read in class java.io.FilterInputStream

See Also:

setAutoStatus(boolean), setStatusLimit(long), InputStream.read(byte[], int, int)

writeStatusMaybe

public void writeStatusMaybe()

If the number of bytes read since the last call to this method exceeds the value of statusLimit (set by setStatusLimit()), debug data containing the number of bytes totally read and and since last call is written to System.out.

See Also:

setStatusLimit(long), setAutoStatus(boolean)

getCount

public long getCount()

Returns the total number of bytes passed through the underlying OutputStream.

getCountOff

public long getCountOff()

Returns the number of bytes read since the last call to this method.

close

public void close()
           throws java.io.IOException

Closes the underlying input stream, but not any eavesdropping output streams.

Overrides:

close in class java.io.FilterInputStream

finalize

public void finalize()

If autoStatus, write the byte count upon object finalization.

Overrides:

finalize in class java.lang.Object

trace

protected static void trace(java.lang.String s)