com.ridgesoft.io
Class Mailbox

java.lang.Object
  com.ridgesoft.io.Mailbox

public class Mailbox
extends Object

This class implements a reliable means for passing messages over an unrelaible serial data stream, such as a serial port. The protocol supports messages as short arrays of binary data. It does not restrict the data which messages may contain, although the messages must be shorter than the specified receive length. The protocol ensures the messages are delivered to the receiver in the order they are transmitted. The protocol also implements flow control, ensuring the transmitter cannot send messages faster than the output stream can deliver them and the receiver can process them.

The protocol is symmetric, allowing both ends of the stream to use this class to pass data.

Constructor Summary

Mailbox(InputStream inputStream, OutputStream outputStream, int maximumReceiveLength, int basePriority)
Constructs a Mailbox object.

Method Summary

void	close() Close the mailbox.
byte[]	getMessage() Gets the next message sent by the peer.
byte[]	getMessage(int maximumWaitTime) Gets the next message sent by the peer.
int	getReceiveErrors() Gets the count of recieve message errors.
int	getRetransmitCount() Gets the count of retransmissions.
void	open() Open the mailbox, waiting as long as necessary to connect with the peer at the other end of the streams.
void	open(int timeout) Open the mailbox, waiting no longer than the timeout value to connect with the peer at the other end of the streams.
void	postMessage(byte[] message) Posts a message to be delivered to the peer.
void	postMessage(byte[] message, int maximumWaitTime) Posts a message to be delivered to the peer.
void	setRetransmitTime(int rxTime) Sets the amount of time to wait before retransmitting an unacknowledged message.
void	setRxSleepTime(int rxSleepTime) Sets the time the receiver thread sleeps between polls of the input stream when there is no data.

Methods inherited from class java.lang.Object

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

Constructor Detail

Mailbox

public Mailbox(InputStream inputStream,
               OutputStream outputStream,
               int maximumReceiveLength,
               int basePriority)

Constructs a Mailbox object.

Parameters:

inputStream - an InputStream object

outputStream - an OutputStream object

maximumReceiveLength - a value as large or larger than the maximum length of any receive message. Larger messages will be discarded.

basePriority - the base priority for the mailbox's threads. The mailbox will create threads which run at this priority and the next higher priority when it is openned.

Method Detail

close

public void close()

Close the mailbox.

getMessage

public byte[] getMessage()
                  throws IOException

Gets the next message sent by the peer. If no message is available, this method will block until a message arrives.

Returns:

a byte array containing the next message sent by the peer

Throws:

IOException

getMessage

public byte[] getMessage(int maximumWaitTime)
                  throws IOException

Gets the next message sent by the peer. If no message is available, this method will block until a message arrives or the maximum wait time has been exceeded.

Parameters:

maximumWaitTime - the maximum time in milliseconds to wait for a message

Returns:

a byte array containing the next message sent by the peer

Throws:

IOException

getReceiveErrors

public int getReceiveErrors()

Gets the count of recieve message errors.

Returns:

receive error count

getRetransmitCount

public int getRetransmitCount()

Gets the count of retransmissions.

Returns:

count of retransmits

open

public void open()
          throws IOException

Open the mailbox, waiting as long as necessary to connect with the peer at the other end of the streams.

Throws:

IOException

open

public void open(int timeout)
          throws IOException

Open the mailbox, waiting no longer than the timeout value to connect with the peer at the other end of the streams.

Parameters:

timeout - timeout in milliseconds

Throws:

IOException

postMessage

public void postMessage(byte[] message)
                 throws IOException

Posts a message to be delivered to the peer. This method does not wait for the peer to acknowledge receipt of the message. This method will block if the transmit queue is full, which prevents the peer's receiver from being overrun. This method does not timeout when it blocks.

Parameters:

message - a byte array containing the message to send

Throws:

IOException

postMessage

public void postMessage(byte[] message,
                        int maximumWaitTime)
                 throws IOException

Posts a message to be delivered to the peer. This method does not wait for the peer to acknowledge receipt of the message. This method will block if the transmit queue is full, which prevents the peer's receiver from being overrun. This method has a timeout to control how long it will wait when blcoked.

Parameters:

message - a byte array containing the message to send

maximumWaitTime - the maximum time in milliseconds to wait. The value 0 indicates do not timeout.

Throws:

IOException

setRetransmitTime

public void setRetransmitTime(int rxTime)

Sets the amount of time to wait before retransmitting an unacknowledged message.

Parameters:

rxTime - retransmit timeout in milliseconds. The default is 1000 milliseconds.

setRxSleepTime

public void setRxSleepTime(int rxSleepTime)

Sets the time the receiver thread sleeps between polls of the input stream when there is no data. This time must be small enough that the input stream's buffer does not get overrun.

Parameters:

rxSleepTime - time in milliseconds to wait between receive polls. The default is 4 milliseconds.