ucb.util.mailbox
Interface Mailbox

All Superinterfaces:

java.rmi.Remote

All Known Implementing Classes:

QueuedMailbox, SimpleMailbox, SyncMailbox

public interface Mailbox

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. Thus, 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

int	capacity() The capacity (see interface comment above) of THIS.
void	close() Delete any pending messages and then invalidate this Mailbox, so that further use causes an exception.
int	concurrency() The level of concurrency for forwarding: 0 means mail is forwarded before deposit finishes; n>0 mean that n separate daemon threads deliver forwarded mail.
void	deposit(java.io.Serializable msg) Deposit MSG in this Mailbox.
boolean	depositIfPossible(java.io.Serializable msg) Deposit MSG in this Mailbox, if it is not full.
void	flush() Wait until all pending messages have been received.
void	forwardTo(Mailbox box, boolean forwardCurrent) Begin forwarding copies of all messages to BOX in the order received.
java.io.Serializable	receive() Receive the next queued message in this Mailbox.
java.io.Serializable	receiveIfPossible() Receive the next queued message in this Mailbox, if one is immediately available.
boolean	retains() True iff this Mailbox retains messages sent to it for later receipt.
void	stopForwardingTo(Mailbox box) Stop forwarding copies of messages to BOX.

Method Detail

deposit

public void deposit(java.io.Serializable 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.

depositIfPossible

public boolean depositIfPossible(java.io.Serializable msg)
                          throws java.rmi.RemoteException,
                                 java.lang.InterruptedException

Deposit MSG in this Mailbox, if it is not full. Returns true iff the message was deposited.

receive

public java.io.Serializable receive()
                             throws java.rmi.RemoteException,
                                    java.lang.InterruptedException

Receive the next queued message in this Mailbox.

receiveIfPossible

public java.io.Serializable receiveIfPossible()
                                       throws java.rmi.RemoteException,
                                              java.lang.InterruptedException

Receive the next queued message in this Mailbox, if one is immediately available. Returns null otherwise.

forwardTo

public void forwardTo(Mailbox box,
                      boolean forwardCurrent)
               throws java.rmi.RemoteException,
                      java.lang.InterruptedException

Begin forwarding copies of all messages to BOX in the order received. If FORWARDCURRENT, first forwards all messages currently contained in BOX and as yet unreceived.

stopForwardingTo

public void stopForwardingTo(Mailbox box)
                      throws java.rmi.RemoteException

Stop forwarding copies of messages to BOX.

flush

public void flush()
           throws java.rmi.RemoteException,
                  java.lang.InterruptedException

Wait until all pending messages have been received.

close

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

Delete any pending messages and then invalidate this Mailbox, so that further use causes an exception.

retains

public boolean retains()
                throws java.rmi.RemoteException

True iff this Mailbox retains messages sent to it for later receipt. A mailbox that neither retains nor forwards acts as a bit bucket.

concurrency

public int concurrency()
                throws java.rmi.RemoteException

The level of concurrency for forwarding: 0 means mail is forwarded before deposit finishes; n>0 mean that n separate daemon threads deliver forwarded mail.

capacity

public int capacity()
             throws java.rmi.RemoteException

The capacity (see interface comment above) of THIS.