com.sun.squawk.io.mailboxes
Class Channel

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

public final class Channel
extends Object

A Channel is a private bidirectional message passing mechanism, typically between Isolates. A Channel can send(com.sun.squawk.io.mailboxes.Envelope) or receive() envelopes, which can contain bytes arrays, bytes array input streams, or other objects.

Channels are created by lookup(java.lang.String), which creates a local channel instance, then looks for a registered ServerChannel by name and asks it to create a remote channel instance to handle communication with the new local channel. When a Channel is closed, the remote channel is also closed.

When an Isolate exits or is hibernated, all of it's channels are closed. An external isolate waiting in receive() will get an AddressClosedException. Similarly, any threads in the local isolate that are waiting in receive() will get an AddressClosedException. When an Isolate that was hibernated is unhibernated, any further calls to send() will throw AddressClosedException, and any calls to receive() will get an MailboxClosedException.

Code that uses inter-isolate communication and supports isolate hibernation must detect AddressClosedExceptions and MailboxClosedExceptions, and re-connect the channels to the appropriate isolates. Note that an isolate may be hibernated, migrated to another isolate, and then unhibernated on another device. The new device may have capabilities than the original device, which might mean that there is now appropriate ServerChannel to reconnect to. Or the new device may have different properties (such as radio addresses) that must be taken into account by higher-level libraries.

See Also:

ServerChannel, Isolate

Method Summary

void	close() Closes the Channel at both ends asynchronously.
boolean	isOpen() Return true if the channel is open, both from here to the remote channel, and from the remote channel back.
static Channel	lookup(String serverChannelName) Create a connection to a remote Channel using the name of registered ServerChannel.
Envelope	receive() Wait for an envelope sent to this channel.
void	send(Envelope env) Sends a message to the remote channel.

Methods inherited from class java.lang.Object

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

Method Detail

close

public void close()

Closes the Channel at both ends asynchronously.

isOpen

public boolean isOpen()

Return true if the channel is open, both from here to the remote channel, and from the remote channel back.

Returns:

true if open.

lookup

public static Channel lookup(String serverChannelName)
                      throws NoSuchMailboxException

Create a connection to a remote Channel using the name of registered ServerChannel. The act of creating the local channel causes the ServerChannel to create a corresponding remote Channel.

Parameters:

serverChannelName - the name of a registered ServerChannel

Returns:

a Channel to the new Channel created by the ServerChannel to accept the connection

Throws:

NoSuchMailboxException - if there is no ServerChannel registered with that name

receive

public Envelope receive()
                 throws AddressClosedException,
                        MailboxClosedException

Wait for an envelope sent to this channel. Blocks waiting for messages. If the channel was closed before this call, a MailboxClosedException will be thrown. If the channel was closed while waiting for an envelope, an AddressClosedException will be thrown. This can occur both if the local or remote isolate exits while a thread is waiting for an envelope.

Returns:

an Envelope containing the sent message.

Throws:

AddressClosedException - if the channel is closed while waiting

MailboxClosedException - if the channel closed when called

send

public void send(Envelope env)
          throws AddressClosedException

Sends a message to the remote channel. Does not wait for acknowledgment. The channel must not be closed or an AddressClosedException will be thrown.

Parameters:

env - the message to send

Throws:

AddressClosedException - if the channel is closed.