org.elkoserver.foundation.net
Class ChunkyByteArrayInputStream

java.lang.Object
  java.io.InputStream
      org.elkoserver.foundation.net.ChunkyByteArrayInputStream

All Implemented Interfaces:

Closeable

public class ChunkyByteArrayInputStream
extends InputStream

Input stream similar to ByteArrayInputStream but backed by an ongoing series of byte arrays that can be added to during the stream object's lifetime.

Constructor Summary

ChunkyByteArrayInputStream()
Constructor.

Method Summary

void	addBuffer(byte[] buf, int length) Be given a buffer full of input bytes.
int	available() Get the number of bytes that can be read from this input stream without blocking.
void	preserveBuffers() Copy any unread portions of the client buffer passed to addBuffer(byte[], int).
int	read() Read the next byte of data from the input stream.
String	readASCIILine() Read the next line of raw ASCII characters from the input stream.
int	readByte() Read the next raw byte of data from the input stream.
byte[]	readBytes(int count) Read a fixed number of bytes from the input stream.
int	readUTF8Char() Read the next UTF-8 encoded character from the input stream.
String	readUTF8Line() Read the next line of UTF-8 encoded characters from the input stream.
String	readUTF8String(int byteCount) Read a string of UTF-8 encoded characters from the input stream.

Methods inherited from class java.io.InputStream

close, mark, markSupported, read, read, reset, skip

Methods inherited from class java.lang.Object

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

Constructor Detail

ChunkyByteArrayInputStream

public ChunkyByteArrayInputStream()

Constructor. Initially, no input has been provided.

Method Detail

addBuffer

public void addBuffer(byte[] buf,
                      int length)

Be given a buffer full of input bytes.

Note: this class assumes that it may continue to freely make direct use of the contents of the byte buffer that is given to this method (i.e., without copying it to internal storage) until preserveBuffers() is called; after that, the buffer contents may be modifed externally. This is somewhat delicate, but eliminates a vast amount of unnecessary byte array allocation and copying.

Parameters:

buf - The bytes themselves.

length - Number of bytes in 'buf' to read (<= buf.length).

available

public int available()
              throws IOException

Get the number of bytes that can be read from this input stream without blocking. Since this class never actually blocks, this is just the number of bytes available at the moment.

Overrides:

available in class InputStream

Returns:

the number of bytes that can be read from this input stream.

Throws:

IOException

preserveBuffers

public void preserveBuffers()

Copy any unread portions of the client buffer passed to addBuffer(byte[], int). This has the side effect of passing responsibility for the client buffer back to the client. This indirection minimizes unnecessary byte array allocation and copying.

read

public int read()
         throws IOException

Read the next byte of data from the input stream. The byte value is returned as an int in the range 0 to 255. If no byte is available, the value -1 is returned.

Specified by:

read in class InputStream

Returns:

the next byte of data, or -1 if the end of the currently available input is reached.

Throws:

IOException - if an incomplete line is in the buffers upon the true end of input.

EOFException - if the true end of input is reached normally

readByte

public int readByte()
             throws IOException

Read the next raw byte of data from the input stream. The byte value is returned as an int in the range 0 to 255. If no byte is available, the value -1 is returned. This method assumes that the byte is intended to be used as a raw value, not as part of a potentially multi-byte character.

Returns:

the next byte of data, or -1 if the end of the currently available input is reached.

Throws:

IOException - if the true end of input is reached normally

readBytes

public byte[] readBytes(int count)
                 throws IOException

Read a fixed number of bytes from the input stream. The result is returned as a byte array of the requested length. If insufficient data is available, null is returned.

Parameters:

count - The number of bytes desired

Returns:

an array of 'count' bytes, or null if that many bytes are not currently available.

Throws:

IOException - if the true end of input is reached normally

readUTF8Char

public int readUTF8Char()
                 throws IOException

Read the next UTF-8 encoded character from the input stream. If another full character is not available, -1 is returned, even if there are still bytes remaining in the input stream.

Returns:

the next character in the input, or -1 if the end of the currently available input is reached.

Throws:

IOException - if an incomplete line is in the buffers upon encountering the true end of input.

readASCIILine

public String readASCIILine()
                     throws IOException

Read the next line of raw ASCII characters from the input stream. However, if a complete line is not available in the buffers, null is returned.

Takes ASCII characters from the buffers until a newline (optionally preceded by a carriage return) is read, at which point the line is returned as a String, not including the line terminator character(s).

Returns:

the next line of ASCII characters in the input, or null if another complete line is not currently available.

Throws:

EOFException - if the true end of input is reached.

IOException

readUTF8Line

public String readUTF8Line()
                    throws IOException

Read the next line of UTF-8 encoded characters from the input stream. Howerver, If a complete line is not available in the buffers, null is returned.

Takes UTF-8 characters from the buffers until a newline (optionally preceded by a carriage return) is read, at which point the line is returned as a String, not including the line terminator character(s).

Returns:

the next line of UTF-8 characters in the input, or null if another complete line is not currently available.

Throws:

EOFException - if the true end of input is reached.

IOException

readUTF8String

public String readUTF8String(int byteCount)
                      throws IOException

Read a string of UTF-8 encoded characters from the input stream. Will read until all currently available characters or 'byteCount' bytes are consumed, whichever happens first.

Parameters:

byteCount - Number of bytes of "good" UTF-8 data known to be available for reading.

Throws:

IOException