SunSPOT API V3.0


com.sun.squawk.io.mailboxes
Class Channel

java.lang.Object
  extended by 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.

SunSPOT API V3.0


Copyright © 2006, 2007 Sun Microsystems, Inc. All Rights Reserved.