PipedInputStream

public class PipedInputStream extends InputStream

Receives information from a communications pipe. When two threads want to pass data back and forth, one creates a piped output stream and the other one creates a piped input stream.

See Also

• PipedOutputStream

Constant Summary

int

PIPE_SIZE

The size of the default pipe in bytes.

Field Summary

protected byte[]	buffer	The circular buffer through which data is passed.
protected int	in	The index in buffer where the next byte will be written.
protected int	out	The index in buffer where the next byte will be read.

Public Constructor Summary

	PipedInputStream() Constructs a new unconnected PipedInputStream.
	PipedInputStream(PipedOutputStream out) Constructs a new PipedInputStream connected to the PipedOutputStream out.
	PipedInputStream(int pipeSize) Constructs a new unconnected PipedInputStream with the given buffer size.
	PipedInputStream(PipedOutputStream out, int pipeSize) Constructs a new PipedInputStream connected to the given PipedOutputStream, with the given buffer size.

Public Method Summary

synchronized int	available() Returns an estimate of the number of bytes that can be read (or skipped over) from this input stream without blocking by the next invocation of a method for this input stream. Unlike most streams, PipedInputStream returns 0 rather than throwing IOException if the stream has been closed.
synchronized void	close() Closes this stream.
void	connect(PipedOutputStream src) Connects this PipedInputStream to a PipedOutputStream.
synchronized int	read() Reads a single byte from this stream and returns it as an integer in the range from 0 to 255.
synchronized int	read(byte[] bytes, int offset, int byteCount) Reads at most byteCount bytes from this stream and stores them in the byte array bytes starting at offset.

Protected Method Summary

synchronized void

receive(int oneByte) Receives a byte and stores it in this stream's buffer.

Inherited Method Summary

From class java.io.InputStream

int	available() Returns an estimate of the number of bytes that can be read (or skipped over) from this input stream without blocking by the next invocation of a method for this input stream.
void	close() Closes this input stream and releases any system resources associated with the stream.
synchronized void	mark(int readlimit) Marks the current position in this input stream.
boolean	markSupported() Tests if this input stream supports the mark and reset methods.
abstract int	read() Reads the next byte of data from the input stream.
int	read(byte[] b, int off, int len) Reads up to len bytes of data from the input stream into an array of bytes.
int	read(byte[] b) Reads some number of bytes from the input stream and stores them into the buffer array b.
synchronized void	reset() Repositions this stream to the position at the time the mark method was last called on this input stream.
long	skip(long n) Skips over and discards n bytes of data from this input stream.

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

From interface java.io.Closeable

abstract void

close() Closes this stream and releases any system resources associated with it.

From interface java.lang.AutoCloseable

abstract void

close() Closes this resource, relinquishing any underlying resources.

Constants

protected static final int PIPE_SIZE

The size of the default pipe in bytes.

Constant Value: 1024

Fields

protected byte[] buffer

The circular buffer through which data is passed. Data is read from the range [out, in) and written to the range [in, out). Data in the buffer is either sequential:

     { - - - X X X X X X X - - - - - }
             ^             ^
             |             |
            out           in

...or wrapped around the buffer's end:

     { X X X X - - - - - - - - X X X }
               ^               ^
               |               |
              in              out

When the buffer is empty, in == -1. Reading when the buffer is empty will block until data is available. When the buffer is full, in == out. Writing when the buffer is full will block until free space is available.

protected int in

The index in buffer where the next byte will be written.

protected int out

The index in buffer where the next byte will be read.

Public Constructors

public PipedInputStream ()

Constructs a new unconnected PipedInputStream. The resulting stream must be connected to a PipedOutputStream before data may be read from it.

public PipedInputStream (PipedOutputStream out)

Constructs a new PipedInputStream connected to the PipedOutputStream out. Any data written to the output stream can be read from the this input stream.

Parameters

out	the piped output stream to connect to.

Throws

IOException	if this stream or out are already connected.

public PipedInputStream (int pipeSize)

Constructs a new unconnected PipedInputStream with the given buffer size. The resulting stream must be connected to a PipedOutputStream before data may be read from it.

Parameters

pipeSize	the size of the buffer in bytes.

Throws

IllegalArgumentException	if pipeSize is less than or equal to zero.

public PipedInputStream (PipedOutputStream out, int pipeSize)

Constructs a new PipedInputStream connected to the given PipedOutputStream, with the given buffer size. Any data written to the output stream can be read from this input stream.

Parameters

out	the PipedOutputStream to connect to.
pipeSize	the size of the buffer in bytes.

Throws

IOException	if an I/O error occurs.
IllegalArgumentException	if pipeSize is less than or equal to zero.

Public Methods

public synchronized int available ()

Returns an estimate of the number of bytes that can be read (or skipped over) from this input stream without blocking by the next invocation of a method for this input stream. The next invocation might be the same thread or another thread. A single read or skip of this many bytes will not block, but may read or skip fewer bytes.

Note that while some implementations of InputStream will return the total number of bytes in the stream, many will not. It is never correct to use the return value of this method to allocate a buffer intended to hold all data in this stream.

A subclass' implementation of this method may choose to throw an IOException if this input stream has been closed by invoking the close() method.

The available method for class InputStream always returns 0.

This method should be overridden by subclasses.

Unlike most streams, PipedInputStream returns 0 rather than throwing IOException if the stream has been closed. Unconnected and broken pipes also return 0.

Returns

• an estimate of the number of bytes that can be read (or skipped over) from this input stream without blocking or 0 when it reaches the end of the input stream.

Throws

IOException	if an I/O error occurs

public synchronized void close ()

Closes this stream. This implementation releases the buffer used for the pipe and notifies all threads waiting to read or write.

Throws

IOException	if an error occurs while closing this stream.

public void connect (PipedOutputStream src)

Connects this PipedInputStream to a PipedOutputStream. Any data written to the output stream becomes readable in this input stream.

Parameters

src	the source output stream.

Throws

IOException	if either stream is already connected.

public synchronized int read ()

Reads a single byte from this stream and returns it as an integer in the range from 0 to 255. Returns -1 if the end of this stream has been reached. If there is no data in the pipe, this method blocks until data is available, the end of the stream is detected or an exception is thrown.

Separate threads should be used to read from a PipedInputStream and to write to the connected PipedOutputStream. If the same thread is used, a deadlock may occur.

Returns

• the byte read or -1 if the end of the source stream has been reached.

Throws

IOException	if this stream is closed or not connected to an output stream, or if the thread writing to the connected output stream is no longer alive.

public synchronized int read (byte[] bytes, int offset, int byteCount)

Reads at most byteCount bytes from this stream and stores them in the byte array bytes starting at offset. Blocks until at least one byte has been read, the end of the stream is detected or an exception is thrown.

Separate threads should be used to read from a PipedInputStream and to write to the connected PipedOutputStream. If the same thread is used, a deadlock may occur.

Parameters

bytes	the buffer into which the data is read.
offset	the start offset in array b at which the data is written.
byteCount	the maximum number of bytes to read.

Returns

• the number of bytes actually read or -1 if the end of the stream has been reached.

Throws

IndexOutOfBoundsException	if offset < 0 or byteCount < 0, or if offset + byteCount is greater than the size of bytes.
InterruptedIOException	if the thread reading from this stream is interrupted.
IOException	if this stream is closed or not connected to an output stream, or if the thread writing to the connected output stream is no longer alive.
NullPointerException	if bytes is null.

Protected Methods

protected synchronized void receive (int oneByte)

Receives a byte and stores it in this stream's buffer. This method is called by PipedOutputStream.write(int). The least significant byte of the integer oneByte is stored at index in in the buffer.

This method blocks as long as buffer is full.

Parameters

oneByte	the byte to store in this pipe.

Throws

InterruptedIOException	if the buffer is full and the thread that has called this method is interrupted.
IOException	if this stream is closed or the thread that has last read from this stream is no longer alive.