edu.rice.cs.plt.io
Class DirectInputStream

java.lang.Object
  java.io.InputStream
      edu.rice.cs.plt.io.DirectInputStream

All Implemented Interfaces:

Closeable

Direct Known Subclasses:

WrappedDirectInputStream

public abstract class DirectInputStream
extends InputStream

An InputStream that supports reading directly into an OutputStream. This class provides default implementations defined in terms of InputStream and OutputStream methods. Subclasses can override (at least) readAll(OutputStream, byte[]) and read(OutputStream, int, byte[]) to provide better implementations (by, for example, not invoking InputStream.read(byte[])).

Also guarantees that, consistent with the Reader class, all read operations are by default defined in terms of the (declared abstract) read(byte[], int, int) method.

See Also:

DirectReader, DirectOutputStream, DirectWriter

Field Summary

protected static int

DEFAULT_BUFFER_SIZE

Constructor Summary

DirectInputStream()

Method Summary

int	read() Delegate to the more general read(byte[], int, int) method
int	read(byte[] bbuf) Delegate to the more general read(byte[], int, int) method
abstract int	read(byte[] bbuf, int offset, int bytes) Subclasses are, at a minimum, required to implement this method.
int	read(OutputStream out, int bytes) Read some number of bytes from this stream, sending them to the provided OutputStream.
int	read(OutputStream out, int bytes, byte[] buffer) Read some number of bytes from this stream, sending them to the provided OutputStream.
int	read(OutputStream out, int bytes, int bufferSize) Read some number of bytes from this stream, sending them to the provided OutputStream.
int	readAll(OutputStream out) Read the full contents of this stream, sending the bytes to the provided OutputStream.
int	readAll(OutputStream out, byte[] buffer) Read the full contents of this stream, sending the bytes to the provided OutputStream.
int	readAll(OutputStream out, int bufferSize) Read the full contents of this stream, sending the bytes to the provided OutputStream.

Methods inherited from class java.io.InputStream

available, close, mark, markSupported, reset, skip

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BUFFER_SIZE

protected static final int DEFAULT_BUFFER_SIZE

See Also:

Constant Field Values

Constructor Detail

DirectInputStream

public DirectInputStream()

Method Detail

read

public int read()
         throws IOException

Delegate to the more general read(byte[], int, int) method

Specified by:

read in class InputStream

Throws:

IOException

read

public int read(byte[] bbuf)
         throws IOException

Delegate to the more general read(byte[], int, int) method

Overrides:

read in class InputStream

Throws:

IOException

read

public abstract int read(byte[] bbuf,
                         int offset,
                         int bytes)
                  throws IOException

Subclasses are, at a minimum, required to implement this method.

Overrides:

read in class InputStream

Throws:

IOException

read

public int read(OutputStream out,
                int bytes)
         throws IOException

Read some number of bytes from this stream, sending them to the provided OutputStream. The default implementation invokes read(OutputStream, int, int) with the minimum of bytes and DEFAULT_BUFFER_SIZE. Subclasses that know the size of this stream's remaining contents, or that do not rely on a buffer in read(OutputStream, int, byte[]), should override this method.

Parameters:

out - A stream to be written to

bytes - The number of bytes to read

Returns:

-1 if this stream is at the end of file; otherwise, the number of bytes read

Throws:

IOException - If an error occurs during reading or writing

read

public int read(OutputStream out,
                int bytes,
                int bufferSize)
         throws IOException

Read some number of bytes from this stream, sending them to the provided OutputStream. The default implementation invokes read(OutputStream, int, byte[]) with a newly-allocated array of the given size. Subclasses that do not rely on a buffer in read(OutputStream, int, byte[]) should override this method.

Parameters:

out - A stream to be written to

bytes - The number of bytes to read

bufferSize - The size of buffer to use (if necessary). Smaller values may reduce the amount of memory required; larger values may increase performance of large streams

Returns:

-1 if this stream is at the end of file; otherwise, the number of bytes read

Throws:

IOException - If an error occurs during reading or writing

IllegalArgumentException - If bufferSize <= 0

read

public int read(OutputStream out,
                int bytes,
                byte[] buffer)
         throws IOException

Read some number of bytes from this stream, sending them to the provided OutputStream. The given buffer is useful in repeated read invocations to avoid unnecessary memory allocation. The default implementation repeatedly fills the given buffer via a InputStream.read(byte[], int, int) operation, then writes it via OutputStream.write(byte[], int, int). Subclasses that do not require an external buffer should override this method.

Parameters:

out - A stream to be written to

bytes - The number of bytes to read

buffer - A buffer used to copy bytes from this stream to the output stream. Note that this is only used to avoid unnecessary memory allocation. No assumptions are made about the buffer's contents (which may be overwritten), and no assumptions should be made about the contents of the buffer after the method invocation.

Returns:

-1 if this stream is at the end of file; otherwise, the number of bytes read

Throws:

IOException - If an error occurs during reading or writing

IllegalArgumentException - If buffer has size 0

readAll

public int readAll(OutputStream out)
            throws IOException

Read the full contents of this stream, sending the bytes to the provided OutputStream. The method will block until an end-of-file is reached. The default implementation invokes readAll(OutputStream, int) with DEFAULT_BUFFER_SIZE. Subclasses that know the size of this stream's remaining contents, or that do not rely on a buffer in readAll(OutputStream, byte[]), should override this method.

Parameters:

out - A stream to be written to

Returns:

-1 if this stream is at the end of file; otherwise, the number of bytes read (or, if the number is too large, Integer.MAX_VALUE)

Throws:

IOException - If an error occurs during reading or writing

readAll

public int readAll(OutputStream out,
                   int bufferSize)
            throws IOException

Read the full contents of this stream, sending the bytes to the provided OutputStream. The method will block until an end-of-file is reached. The default implementation invokes readAll(OutputStream, byte[]) with a newly-allocated array of the given size. Subclasses that do not rely on a buffer in readAll(OutputStream, byte[]) should override this method.

Parameters:

out - A stream to be written to

bufferSize - The size of buffer to use (if necessary). Smaller values may reduce the amount of memory required; larger values may increase performance of large streams

Returns:

-1 if this stream is at the end of file; otherwise, the number of bytes read (or, if the number is too large, Integer.MAX_VALUE)

Throws:

IOException - If an error occurs during reading or writing

IllegalArgumentException - If bufferSize <= 0

readAll

public int readAll(OutputStream out,
                   byte[] buffer)
            throws IOException

Read the full contents of this stream, sending the bytes to the provided OutputStream. The given buffer is useful in repeated readAll invocations to avoid unnecessary memory allocation. The method will block until an end-of-file is reached. The default implementation repeatedly fills the given buffer via a InputStream.read(byte[]) operation, then writes it via OutputStream.write(byte[]). Subclasses that do not require an external buffer should override this method.

Parameters:

out - A stream to be written to

buffer - A buffer used to copy bytes from this stream to the output stream. Note that this is only used to avoid unnecessary memory allocation. No assumptions are made about the buffer's contents (which may be overwritten), and no assumptions should be made about the contents of the buffer after the method invocation.

Returns:

-1 if this stream is at the end of file; otherwise, the number of bytes read (or, if the number is too large, Integer.MAX_VALUE)

Throws:

IOException - If an error occurs during reading or writing

IllegalArgumentException - If buffer has size 0