jsimple.io

Class InputStream

java.lang.Object

jsimple.lang.AutoCloseable

jsimple.io.InputStream

All Implemented Interfaces:

java.lang.AutoCloseable

Direct Known Subclasses:

ByteArrayInputStream, JavaHttpResponse.EmptyInputStream, JSimpleInputStreamOnJavaStream, SequenceInputStream, SubstreamInputStream

public abstract class InputStream
extends AutoCloseable

This class was based on, and modified from, the Apache Harmony java.io.InputStream class. Unlike the Java InputStream class, this doesn't support mark, reset, or skip, doesn't throw any checked exceptions, and none of the methods are synchronized.

The base class for all input streams. An input stream is a means of reading data from a source in a byte-wise manner.

Some input streams also support marking a position in the input stream and returning to this position later. This abstract class does not provide a fully working implementation, so it needs to be subclassed, and at least the read() method needs to be overridden. Overriding some of the non-abstract methods is also often advised, since it might result in higher efficiency.

Since:

10/7/12 12:31 AM

See Also:

OutputStream

Constructor Summary

Constructors

Constructor and Description
InputStream()

Method Summary

Modifier and Type	Method and Description
abstract void	close() Closes this stream.
void	copyTo(OutputStream outputStream) Write the remaining contents of this stream to the specified output stream, closing this input stream when done.
ByteArrayRange	copyToByteArray() Write the remaining contents of this stream to a byte array, closing this input stream when done.
protected void	finalize()
abstract int	read() Reads a single byte from this stream and returns it as an integer in the range from 0 to 255.
int	read(byte[] buffer) Reads bytes from this stream and stores them in the byte array b.
abstract int	read(byte[] buffer, int offset, int length) Reads at most length bytes from this stream and stores them in the byte array b starting at offset.
int	readFully(byte[] buffer) This method is the same as read except that it's guaranteed to read as much as possible, blocking until it's read length bytes or the end of stream is reached.
int	readFully(byte[] buffer, int offset, int length) This method is the same as read except that it's guaranteed to read as much as possible, blocking until it's read length bytes or the end of stream is reached.

Methods inherited from class java.lang.Object

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

Constructor Detail

InputStream

public InputStream()

Method Detail

close

public abstract void close()

Closes this stream. If the stream is already closed, then this method should do nothing. Concrete implementations of this class should free any resources during close.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in class AutoCloseable

Throws:

IOException - if an error occurs while closing this stream

finalize

protected void finalize()

Overrides:

finalize in class java.lang.Object

read

public abstract 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 the stream has been reached. Blocks until one byte has been read, the end of the source stream is detected or an exception is thrown.

Returns:

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

Throws:

IOException - if an error occurs while reading

read

public int read(byte[] buffer)

Reads bytes from this stream and stores them in the byte array b.

Parameters:

buffer - the byte array in which to store the bytes read

Returns:

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

Throws:

IOException - if an error occurs while reading

readFully

public int readFully(byte[] buffer)

This method is the same as read except that it's guaranteed to read as much as possible, blocking until it's read length bytes or the end of stream is reached. That is, if it returns < length bytes read, then it's guaranteed that that's all the data left in the stream and the next call to read will return -1. Subclasses are free to override this method and implement it directly if they already read as much as possible anyway, and thus can implement it a little more efficiently just doing whatever read does.

Parameters:

buffer - the byte array in which to store the bytes read

Returns:

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

Throws:

IOException - if an error occurs while reading

read

public abstract int read(byte[] buffer,
                         int offset,
                         int length)

Reads at most length bytes from this stream and stores them in the byte array b starting at offset.

Parameters:

buffer - the byte array in which to store the bytes read

offset - the initial position in buffer to store the bytes read from this stream

length - the maximum number of bytes to store in b

Returns:

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

Throws:

IOException - if an error occurs while reading

readFully

public int readFully(byte[] buffer,
                     int offset,
                     int length)

This method is the same as read except that it's guaranteed to read as much as possible, blocking until it's read length bytes or the end of stream is reached. That is, if it returns < length bytes read, then it's guaranteed that that's all the data left in the stream and the next call to read will return -1. Subclasses are free to override this method and implement it directly if they already read as much as possible anyway, and thus can implement it a little more efficiently just doing whatever read does.

Parameters:

buffer - the byte array in which to store the bytes read

offset - the initial position in buffer to store the bytes read from this stream

length - the maximum number of bytes to store in b

Returns:

the number of bytes actually read (which is guaranteed to be as much as possible) or -1 if the end of the stream has been reached

copyTo

public void copyTo(OutputStream outputStream)

Write the remaining contents of this stream to the specified output stream, closing this input stream when done. The inputStream is closed after it's completely read, though it won't be closed if an exception occurs in the middle of reading from it.

Parameters:

outputStream - output stream to copy to

copyToByteArray

public ByteArrayRange copyToByteArray()

Write the remaining contents of this stream to a byte array, closing this input stream when done. The inputStream is closed after it's completely read, though it won't be closed if an exception occurs in the middle of reading from it.

Returns:

ByteArrayRange containing the stream contents