Package ucb.util.mailbox

Interface Mailbox<Msg extends java.io.Serializable>

All Superinterfaces:

java.rmi.Remote

All Known Implementing Classes:

QueuedMailbox, Rendezvous, SinkBox

public interface Mailbox<Msg extends java.io.Serializable>
extends java.rmi.Remote

A repository for messages, suitable for remote use. Has facilities for forwarding copies of messages to other mailboxes. Messages are received and forwarded in the order deposited. A mailbox has a "capacity", which is the maximum allowed excess of completed deposits over completely processed messages. A message is "completely" processed when it has been received (if retains() is true) and has been forwarded to all requesters. A capacity of Integer.MAX_VALUE indicates that there is no set limit. When a Mailbox has a capacity of 0, it synchronizes senders and receivers: a deposit does not complete until its message is picked up by receive (and forwarded, if called for).

Method Summary

Modifier and Type	Method	Description
int	capacity()	The capacity (see interface comment above) of THIS.
<T extends java.io.Serializable> Mailbox<T>	checkType(java.lang.Class<T> msgClass)	Returns THIS, assuming that THIS conveys messages of class MSGCLASS.
void	close()	Short for close (0).
void	close(long millis)	Performs a flush(MILLIS) and then invalidates THIS for all future use, deleting all remaining messages.
void	deposit(Msg msg)	Deposit MSG in this Mailbox.
boolean	deposit(Msg msg, long millis)	Deposit MSG in this Mailbox, if this can be done within approximately MILLIS milliseconds.
boolean	flush(long millis)	Wait for all queued messages to be received, or MILLIS milliseconds, whichever comes first.
void	forwardTo(java.util.List<Mailbox<Msg>> boxes)	Forward copies of all messages (including any already present) to BOXES in the order received.
void	forwardTo(Mailbox<Msg> box)	Forward copies of all messages (including any already present) to BOX in the order received.
boolean	isClosed()	True iff THIS is closed.
boolean	isForwarding()	True iff THIS is currently forwarding messages as a result of forwardTo.
java.lang.Class<Msg>	messageType()	The (runtime) type of message sent through this box.
Msg	receive()	Receive the next queued message in this Mailbox.
Msg	receive(long millis)	Receive the next queued message in this Mailbox, if one is available within MILLIS milliseconds.
void	stopForwarding()	Stop forwarding copies of messages.

Method Detail

deposit

void deposit(Msg msg)
      throws java.rmi.RemoteException,
             java.lang.InterruptedException

Deposit MSG in this Mailbox. If the Mailbox is full, wait if necessary for space to be available. MSG must be non-null. Throws Interrupted exception and does nothing if current thread is interrupted. Throws an IllegalStateException (or RemoteException) if THIS is closed. Throws IllegalArgumentException if MSG is null.

Throws:

java.rmi.RemoteException

java.lang.InterruptedException

deposit

boolean deposit(Msg msg,
                long millis)
         throws java.rmi.RemoteException,
                java.lang.InterruptedException

Deposit MSG in this Mailbox, if this can be done within approximately MILLIS milliseconds. Returns true iff the message was deposited. Does not block if MILLIS is 0. MSG must be non-null. Throws Interrupted exception and does nothing if current thread is interrupted. Throws IllegalStateException (or RemoteException) if THIS is closed. Throws IllegalArgumentException if MSG is null.

Throws:

java.rmi.RemoteException

java.lang.InterruptedException

receive

Msg receive()
     throws java.rmi.RemoteException,
            java.lang.InterruptedException

Receive the next queued message in this Mailbox. Returns null if THIS is closed. Throws Interrupted exception and does nothing if the current thread is interrupted.

Throws:

java.rmi.RemoteException

java.lang.InterruptedException

receive

Msg receive(long millis)
     throws java.rmi.RemoteException,
            java.lang.InterruptedException

Receive the next queued message in this Mailbox, if one is available within MILLIS milliseconds. Returns null otherwise, including if THIS is closed. Does not block if MILLIS is 0. Throws Interrupted exception and does nothing if current thread is interrupted.

Throws:

java.rmi.RemoteException

java.lang.InterruptedException

forwardTo

void forwardTo(Mailbox<Msg> box)
        throws java.rmi.RemoteException,
               java.lang.InterruptedException

Forward copies of all messages (including any already present) to BOX in the order received. Once forwarded, messages are otherwise treated as usual. Deposit blocks until all forwarding is complete.

Throws:

java.rmi.RemoteException

java.lang.InterruptedException

forwardTo

void forwardTo(java.util.List<Mailbox<Msg>> boxes)
        throws java.rmi.RemoteException,
               java.lang.InterruptedException

Forward copies of all messages (including any already present) to BOXES in the order received. Once forwarded to all destinations, messages are otherwise treated as usual. Deposit blocks until all forwarding is complete.

Throws:

java.rmi.RemoteException

java.lang.InterruptedException

stopForwarding

void stopForwarding()
             throws java.rmi.RemoteException

Stop forwarding copies of messages.

Throws:

java.rmi.RemoteException

flush

boolean flush(long millis)
       throws java.rmi.RemoteException,
              java.lang.InterruptedException

Wait for all queued messages to be received, or MILLIS milliseconds, whichever comes first. During this wait, the Mailbox acts as if full from the point of view of all threads attempting to deposit. Returns true if all messages were flushed within the time limit.

Throws:

java.rmi.RemoteException

java.lang.InterruptedException

close

void close(long millis)
    throws java.rmi.RemoteException,
           java.lang.InterruptedException

Performs a flush(MILLIS) and then invalidates THIS for all future use, deleting all remaining messages. Any waiting threads or subsequent calls receive an immediate RemoteException indicating an invalid state. In general, the thread that uses a Mailbox to send messages is the one that closes it.

Throws:

java.rmi.RemoteException

java.lang.InterruptedException

close

void close()
    throws java.rmi.RemoteException,
           java.lang.InterruptedException

Short for close (0).

Throws:

java.rmi.RemoteException

java.lang.InterruptedException

isForwarding

boolean isForwarding()
              throws java.rmi.RemoteException

True iff THIS is currently forwarding messages as a result of forwardTo.

Throws:

java.rmi.RemoteException

isClosed

boolean isClosed()
          throws java.rmi.RemoteException

True iff THIS is closed.

Throws:

java.rmi.RemoteException

capacity

int capacity()
      throws java.rmi.RemoteException

The capacity (see interface comment above) of THIS.

Throws:

java.rmi.RemoteException

messageType

java.lang.Class<Msg> messageType()
                          throws java.rmi.RemoteException

The (runtime) type of message sent through this box.

Throws:

java.rmi.RemoteException

checkType

<T extends java.io.Serializable> Mailbox<T> checkType(java.lang.Class<T> msgClass)
                                               throws java.rmi.RemoteException

Returns THIS, assuming that THIS conveys messages of class MSGCLASS.

Throws:

java.rmi.RemoteException