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

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

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

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

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

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
"