Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| " 2013 FRC Java API "
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`

Method Summary
`void` | `close()` Closes a Mailbox.
`static Mailbox` | `create()` This method creates a private, single-client, unregistered Mailbox.
`static Mailbox` | `create(String name, MailboxHandler handler)` Creates a Mailbox with the given name and registers it with the system.
`Mailbox` | `createSubMailbox()` This method creates a private, single-client, unregistered Mailbox, owned by the same Isolate as this isolate.
`String` | `getName()` Returns the registered name of the mail box, if registered.
`boolean` | `isOpen()` Returns true if the mailbox is open.
`boolean` | `isRegistered()` Returns true if this Mailbox is registered by name with the system.
`Envelope` | `receive()` Blocks waiting for messages.
`String` | `toString()` Returns a string representation of the object.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Method Detail

### 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| " 2013 FRC Java API "
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

"
For updated information see the Java FRC site
"