com.cafesoft.core.message
Class MessageInputStream

java.lang.Object
  |
  +--java.io.InputStream
        |
        +--com.cafesoft.core.message.MessageInputStream

public class MessageInputStream

extends InputStream

The MessageInputStream stream object extends the abstract InputStream. In essence, this class is responsible for reading data from the InputStream transport.

More specifically it is responsible for reading data from data envelopes the Messaging Framework calls Packets. The InputStream reads data from the packets and understands various data limits imposed as well as error conditions that could occur while reading from a packet. The InputStream gets the packets from the specified PacketProducer. Once a packet has been digested it is discarded.

Since:

2/21/02

Constructor Summary

MessageInputStream(PacketProducer packetProducer, PacketObjectPool objectPool)
Create a new MessageInputStream

Method Summary

int	available() Returns the number of bytes that can be read (or skipped over) from this input stream without blocking by the next caller of a method for this input stream.
void	close() Closes this input stream and releases any system resources associated with the stream.
void	finish() Finish input on the InputStream.
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.
int	read() Reads the next byte of data from the input stream.
int	read(byte[] b) Reads some number of bytes from the input stream and stores them into the buffer array b.
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	readInteger(Value value) Reads an int from the input stream.
int	readString(Value value) Reads a String from the input stream.
int	readUnsignedShort(Value value) Reads an unsigned short from the input stream.
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.

Methods inherited from class java.lang.Object

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

Constructor Detail

MessageInputStream

public MessageInputStream(PacketProducer packetProducer,
                          PacketObjectPool objectPool)

Create a new MessageInputStream

Parameters:

packetProducer - The PacketProducer to obtain packets from

Method Detail

readString

public int readString(Value value)
               throws IOException

Reads a String from the input stream.

Parameters:

value - the value object to populate with the read String

Returns:

returns the number of bytes read of the String

Throws:

IOException - thrown if I/O Error occurs. In particularly, thrown if the InputStream is closed, or if the Value object passed in is null, or the entire String cannot be read from the InputStream, or if the size of the String cannot be determined or finally if the encoding used to read the String from the stream is not supported.

readInteger

public int readInteger(Value value)
                throws IOException

Reads an int from the input stream.

Parameters:

value - the Value object to write the read integer value to

Returns:

returns the number of bytes read from the InputStream, -1 if the end of the InputStream is reached.

Throws:

IOException - thrown if I/O Error occurs. In particular, if the InputStream is closed, or the Value object is null, or if the packet to read from is empty, or there are not enough bytes remaining on the InputStream to obtain an integer value.

readUnsignedShort

public int readUnsignedShort(Value value)
                      throws IOException

Reads an unsigned short from the input stream.

Parameters:

value - the Value object to write the read short value to

Returns:

returns the number of bytes read from the InputStream, -1 if the end of the InputStream is reached.

Throws:

IOException - thrown if I/O Error occurs. In particular, if the InputStream is closed, or the Value object is null, or if the packet to read from is empty, or there are not enough bytes remaining on the InputStream to obtain an short value

finish

public void finish()

Finish input on the InputStream.

This method essentially tells the InputStream that a message has been received. Therefore reset all message markers and throw away the current packet.

read

public int read()
         throws IOException

Reads the next byte of data from the input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

Implementation Details:
This method will attempt to read a byte of data from the current packet.

If the packet still has data to be read the byte is obtained from the packets buffer and returned.

If the packet does not have enough data to be read the stream determines if the packet is the last packet of the message. If the packet is the last packet of a message then -1 is returned.

If the packet is not the last in a message, the input stream will block and try to obtain a new packet from its corresponding PacketQueue. Once the packet is received the data is retreived and returned.

If the PacketQueue throws a PacketTimeoutException that exception is transformed into a IOException and is thrown.

Specified by:

read in class InputStream

Returns:

the next byte of data, or -1 if the end of the stream is reached.

Throws:

IOException - if an I/O error occurs. In particular, if the stream is closed, or if the packet the InputStream is reading from is empty and is not marked as the end of a message

read

public int read(byte[] b,
                int off,
                int len)
         throws IOException

Reads up to len bytes of data from the input stream into an array of bytes. An attempt is made to read as many as len bytes, but a smaller number may be read, possibly zero. The number of bytes actually read is returned as an integer.

This method blocks until input data is available, end of file is detected, or an exception is thrown.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

If len is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b.

The first byte read is stored into element b[off], the next one into b[off+1], and so on. The number of bytes read is, at most, equal to len. Let k be the number of bytes actually read; these bytes will be stored in elements b[off] through b[off+k-1], leaving elements b[off+k] through b[off+len-1] unaffected.

In every case, elements b[0] through b[off] and elements b[off+len] through b[b.length-1] are unaffected.

If the first byte cannot be read for any reason other than end of file, then an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed.

Overrides:

read in class InputStream

Parameters:

b - the buffer into which the data is read.

off - the start offset in array b at which the data is written.

len - the maximum number of bytes to read.

Returns:

the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.

Throws:

IOException - if an I/O error occurs. In particular, if the InputStream is closed, or if the packet the InputStream is reading from is empty and is not marked as an end of message packet

See Also:

InputStream.read()

read

public int read(byte[] b)
         throws IOException

Reads some number of bytes from the input stream and stores them into the buffer array b. The number of bytes actually read is returned as an integer. This method blocks until input data is available, end of file is detected, or an exception is thrown.

If b is null, a NullPointerException is thrown. If the length of b is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b.

The first byte read is stored into element b[0], the next one into b[1], and so on. The number of bytes read is, at most, equal to the length of b. Let k be the number of bytes actually read; these bytes will be stored in elements b[0] through b[k-1], leaving elements b[k] through b[b.length-1] unaffected.

If the first byte cannot be read for any reason other than end of file, then an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed.

Overrides:

read in class InputStream

Parameters:

b - the buffer into which the data is read.

Returns:

the total number of bytes read into the buffer, or -1 is there is no more data because the end of the stream has been reached.

Throws:

IOException - if an I/O error occurs. In particular, if the InputStream is closed, or if the packet the InputStream is reading from is empty and is not marked as an end of message packet.

See Also:

InputStream.read(byte[], int, int)

skip

public long skip(long n)
          throws IOException

Skips over and discards n bytes of data from this input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. The actual number of bytes skipped is returned. If n is negative, no bytes are skipped.

Overrides:

skip in class InputStream

Parameters:

n - the number of bytes to be skipped.

Returns:

the actual number of bytes skipped.

Throws:

IOException - if an I/O error occurs. In particular if the stream is closed

close

public void close()
           throws IOException

Closes this input stream and releases any system resources associated with the stream.

Overrides:

close in class InputStream

Throws:

IOException - if an I/O error occurs. Thrown if stream is already closed

available

public int available()
              throws IOException

Returns the number of bytes that can be read (or skipped over) from this input stream without blocking by the next caller of a method for this input stream. The next caller might be the same thread or or another thread.

Overrides:

available in class InputStream

Returns:

0 the functionality described above is not supported.

Throws:

IOException - if an I/O error occurs.

mark

public void mark(int readlimit)

Marks the current position in this input stream. A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes.

Implementation Details:
This method does nothing the functionality is not supported.

Overrides:

mark in class InputStream

Parameters:

readlimit - the maximum limit of bytes that can be read before the mark position becomes invalid.

See Also:

InputStream.reset()

reset

public void reset()
           throws IOException

Repositions this stream to the position at the time the mark method was last called on this input stream.

Implementation Details:
This method does nothing the functionality is not supported.

Overrides:

reset in class InputStream

Throws:

IOException - if this stream has not been marked or if the mark has been invalidated.

See Also:

InputStream.mark(int), IOException

markSupported

public boolean markSupported()

Tests if this input stream supports the mark and reset methods. The markSupported method of InputStream returns false.

Implementation Details:
This method always returns false

Overrides:

markSupported in class InputStream

Returns:

false this functionality is not supported

See Also:

InputStream.mark(int), InputStream.reset()