com.sun.squawk.io.mailboxes
Class Mailbox

java.lang.Object
  com.sun.squawk.io.mailboxes.Mailbox

public final class Mailbox
extends Object

deprecated Use the higher-level Channel and ServerChannel classes instead.

The Mailbox class is likely to become a private imeplementation-only class.

A Mailbox is used to receive and read messages. Only the "owning" isolate has a reference to a Mailbox. A Mailbox may be registered with the system by name, allowing clients to get a MailboxAddress that refers to this Mailbox. A Mailbox can accept messages from any number of clients, and these messages are queued in the order received.

Messages from each client are tagged by the client's private MailboxAddress. A client may use multiple independent MailboxAddress to the same Mailbox. This allows multiple logical connections to be managed by the same message queue.

The logical connections are created by the system when the client does a MailboxAdress.lookup(). The connections are closed when the client closes the MailboxAddress, which causes a AddressClosedEnvelope message to be sent to the Mailbox, or when the Mailbox is closed, which invalidates the MailboxAddresses that refer to it.

A Mailbox has to acknowledge a new logical connection by providing the MailboxAdress that a client should use for future messages. A server must specify a MailboxHandler to handle opening new logical connections when it registers it's Mailbox by name. A MailboxHandler may create a new MailBox and new Mailbox address, in order to support private Mailboxes for different clients (see ServerChannel).

The MailboxHandler is also responisble for handling MailboxAddress closed events. It may track the event, and cleanup other state, or it may indicate that that an AddressClosedException should be thrown once all previous sent envelopes have been received.

See Also:

Channel, ServerChannel

getName

public String getName()

Returns the registered name of the mail box, if registered. Otherwise returns some other String (may or may not be unique).

Returns:

the name of this mailbox.

close

public void close()

Closes a Mailbox. If registered, unregisters the Mailbox. Any further attempts by clients to send messages to this Mailbox result in MailboxClosedException being thrown. If any threads are waiting to receive messages, they will be woken up and an exception will be thrown. Redundant closes on a Mailbox are ignored.

isOpen

public boolean isOpen()

Returns true if the mailbox is open.

create

public static Mailbox create(String name,
                             MailboxHandler handler)
                      throws MailboxInUseException

Creates a Mailbox with the given name and registers it with the system. create may immediately begin receiving messages. The handler will be used to initiate and close the logical connection to a client.

Parameters:

name - the name that this Mailbox can be looked up under.

handler - the class used to manage clients opening and closing new logical connections to the new Mailbox.

Returns:

the new Mailbox.

Throws:

MailboxInUseException - if there is already a mailbox registered under the name name.

create

public static Mailbox create()

This method creates a private, single-client, unregistered Mailbox. If the client closes its connection to this Mailbox, Mailbox.receive() will throw an AddressClosedException exception.

Returns:

the new Mailbox.

createSubMailbox

public Mailbox createSubMailbox()

This method creates a private, single-client, unregistered Mailbox, owned by the same Isolate as this isolate. If the client closes its connection to this Mailbox, Mailbox.receive() will throw an AddressClosedException exception.

Returns:

the new Mailbox.

receive

public Envelope receive()
                 throws AddressClosedException,
                        MailboxClosedException

Blocks waiting for messages. If a logical connection to this Mailbox is closed, the MailboxHandler's handleClose() method will be called. If that method returns an exception object, it will be thrown in due time by the receive() method. Otherwise receive() will NOT throw an exception if a client closes its connection to the Mailbox.

Returns:

an Envelope containing the sent message.

Throws:

AddressClosedException - if the MailboxHandler for this mailbox is setup to throw an exception when the client closes its connection to this mailbox (a DefaultClientHandler, for example).

MailboxClosedException - if the Mailbox itself is closed.

isRegistered

public boolean isRegistered()

Returns true if this Mailbox is registered by name with the system.

Returns:

true if registered

toString

public String toString()

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:

toString in class Object

Returns:

a string representation of the object.