java.io

Class PipedInputStream

public class PipedInputStream extends InputStream

An input stream that reads its bytes from an output stream to which it is connected.

Data is read and written to an internal buffer. It is highly recommended that the PipedInputStream and connected PipedOutputStream be part of different threads. If they are not, the read and write operations could deadlock their thread.

UNKNOWN: The JDK implementation appears to have some undocumented functionality where it keeps track of what thread is writing to pipe and throws an IOException if that thread susequently dies. This behaviour seems dubious and unreliable - we don't implement it.

Field Summary
protected byte[]	buffer This is the internal circular buffer used for storing bytes written to the pipe and from which bytes are read by this stream
protected int	in The index into buffer where the next byte from the connected `PipedOutputStream` will be written.
protected int	out This index into the buffer where bytes will be read from.
protected static int	PIPE_SIZE The size of the internal buffer used for input/output.

Constructor Summary
	PipedInputStream() Creates a new `PipedInputStream` that is not connected to a `PipedOutputStream`.
	PipedInputStream(PipedOutputStream source) This constructor creates a new `PipedInputStream` and connects it to the passed in `PipedOutputStream`.

Method Summary
int	available() This method returns the number of bytes that can be read from this stream before blocking could occur.
void	close() This methods closes the stream so that no more data can be read from it.
void	connect(PipedOutputStream source) This method connects this stream to the passed in `PipedOutputStream`.
int	read() This method reads one byte from the stream.
int	read(byte[] buf, int offset, int len) This method reads bytes from the stream into a caller supplied buffer.
protected void	receive(int val) This method receives a byte of input from the source PipedOutputStream.

Field Detail

buffer

protected byte[] buffer

This is the internal circular buffer used for storing bytes written to the pipe and from which bytes are read by this stream

in

protected int in

The index into buffer where the next byte from the connected PipedOutputStream will be written. If this variable is equal to out, then the buffer is full. If set to < 0, the buffer is empty.

out

protected int out

This index into the buffer where bytes will be read from.

PIPE_SIZE

protected static final int PIPE_SIZE

The size of the internal buffer used for input/output.

Constructor Detail

PipedInputStream

public PipedInputStream()

Creates a new PipedInputStream that is not connected to a PipedOutputStream. It must be connected before bytes can be read from this stream.

PipedInputStream

public PipedInputStream(PipedOutputStream source)

This constructor creates a new PipedInputStream and connects it to the passed in PipedOutputStream. The stream is then ready for reading.

Parameters: source The PipedOutputStream to connect this stream to

Throws: IOException If source is already connected.

Method Detail

available

public int available()

This method returns the number of bytes that can be read from this stream before blocking could occur. This is the number of bytes that are currently unread in the internal circular buffer. Note that once this many additional bytes are read, the stream may block on a subsequent read, but it not guaranteed to block.

Returns: The number of bytes that can be read before blocking might occur

Throws: IOException If an error occurs

close

public void close()

This methods closes the stream so that no more data can be read from it.

Throws: IOException If an error occurs

connect

public void connect(PipedOutputStream source)

This method connects this stream to the passed in PipedOutputStream. This stream is then ready for reading. If this stream is already connected or has been previously closed, then an exception is thrown

Parameters: source The PipedOutputStream to connect this stream to

Throws: IOException If this PipedInputStream or source has been connected already.

read

public int read()

This method reads one byte from the stream. -1 is returned to indicated that no bytes can be read because the end of the stream was reached. If the stream is already closed, a -1 will again be returned to indicate the end of the stream.

This method will block if no byte is available to be read.

Returns: the value of the read byte value, or -1 of the end of the stream was reached

Throws: IOException if an error occured

read

public int read(byte[] buf, int offset, int len)

This method reads bytes from the stream into a caller supplied buffer. It starts storing bytes at position offset into the buffer and reads a maximum of len bytes. Note that this method can actually read fewer than len bytes. The actual number of bytes read is returned. A -1 is returned to indicated that no bytes can be read because the end of the stream was reached - ie close() was called on the connected PipedOutputStream.

This method will block if no bytes are available to be read.

Parameters: buf The buffer into which bytes will be stored offset The index into the buffer at which to start writing. len The maximum number of bytes to read.

Throws: IOException If close() was called on this Piped InputStream.

receive

protected void receive(int val)

This method receives a byte of input from the source PipedOutputStream. If the internal circular buffer is full, this method blocks.

Parameters: val The byte to write to this stream

Throws: IOException if error occurs

UNKNOWN: Weird. This method must be some sort of accident.