java.nio.channels
Class LinkChannel

java.lang.Object
  |
  +--java.nio.channels.spi.AbstractInterruptibleChannel
        |
        +--java.nio.channels.SelectableChannel
              |
              +--java.nio.channels.spi.AbstractSelectableChannel
                    |
                    +--java.nio.channels.LinkChannel

All Implemented Interfaces:

Channel, InterruptibleChannel

public abstract class LinkChannel

extends AbstractSelectableChannel

A selectable channel for a Link.

A LinkChannel is only obtained through a Link.getChannel() call and is uniquely associated with that Link. Invocations of send and receive on the Link and its associated LinkChannel are indistinguishable.

Because send and receive methods on a Link require a strict rendezvous between sender and receiver, only one side (sender or receiver) of a Link should be put in non-blocking mode; otherwise, neither side will block, and rendezvous will never happen. Additionally, once a LinkChannel instance is configured for non-blocking transfers, the associated Link should not be used for transfers as its send and receive methods will throw IllegalBlockingModeException.

The LinkChannel is most useful for applications that manage a large number of links in a scalable fashion. For example, the following example assumes that links are established to isolates to report their "status" (i.e., for each job completed, a report is sent). The run() method will execute as long as the Selector is open, waiting for available reports and processing them as necessary.

 public class ReportAggregator {
    private Selector reporters = new Selector.open();
 
    private static class Status { ... };

    public void registerLink(Isolate i, Link l) {
       assert l.isRecevier(Isolate.currentIsolate());
       assert l.isSender(i);
       SelectionKey sk;
       sk = l.getChannel().register(reporters, Selector.OP_READ);
       sk.attach(new Status(i));
    }

    private void handleReadyReporters() throws IOException {
       Iterator i = reporter.selectedKeys().iterator();
       while (i.hasNext()) {
          SelectionKey key = (SelectionKey)(i.next());
          Status status = (Status)(key.attachment());
          LinkMessage lm = ((LinkChannel)(key.channel())).receive();
          if (lm != null)
             status.addReport(lm);
          i.remove();
       }
    }

    public void run() throws IOException {
       while (reporters.isOpen()) {
          try {
             reporters.select();
             handleReadyReporters();
          } 
          catch (ClosedSelectorException cse) { ; }
       }
    }
 }
 

Since:

1.5

See Also:

Link

Method Summary

java.lang.isolate.Link	link() Returns the unique Link associated with this LinkChannel.
abstract java.lang.isolate.LinkMessage	receive() Receive a copy of a message on this Link.
abstract boolean	send(java.lang.isolate.LinkMessage lm) Send the given message on this Link.
int	validOps() Returns valid Channel-related ops for this LinkChannel.

Methods inherited from class java.nio.channels.spi.AbstractSelectableChannel

blockingLock, configureBlocking, isBlocking, isRegistered, keyFor, provider, register

Methods inherited from class java.nio.channels.SelectableChannel

register

Methods inherited from class java.nio.channels.spi.AbstractInterruptibleChannel

close, isOpen

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Method Detail

validOps

public int validOps()

Returns valid Channel-related ops for this LinkChannel.

Returns (SelectionKey.OP_READ | SelectionKey.OP_WRITE).

Returns:

valid Channel-related ops for this LinkChannel.

link

public java.lang.isolate.Link link()

Returns the unique Link associated with this LinkChannel.

send

public abstract boolean send(java.lang.isolate.LinkMessage lm)
                      throws ClosedLinkException,
                             LinkSerializationException

Send the given message on this Link.

Like Link.send except this this method returns a boolean which indicates if the send succeeded (true) or if there was no waiting receiver thread (false). False can only be returned if this LinkChannel has been configured for non-blocking and there is no receiver available; otherwise, the invoking thread should block until a receiver is available.

Parameters:

lm - the @{link LinkMessage message} to send

Returns:

true if the send succeeded, false if there was no waiting receiver.

Throws:

ClosedLinkException - See Link.send(java.lang.isolate.LinkMessage)

ResourceException - See Link.send(java.lang.isolate.LinkMessage)

LinkSerializationException - See Link.send(java.lang.isolate.LinkMessage)

UnsupportedOperationException - See Link.send(java.lang.isolate.LinkMessage)

receive

public abstract java.lang.isolate.LinkMessage receive()
                                               throws ClosedLinkException

Receive a copy of a message on this Link.

Like Link.recieve except this method returns null if there was no waiting sender. null can only be returned if this LinkChannel has been configured for non-blocking, and there is no sender available; otherwise, the invoking thread should block until a sender is available.

Returns:

A LinkMessage containing the message from the sender or null if there was no waiting sender to rendezvous with

Throws:

ClosedLinkException - See Link.send(java.lang.isolate.LinkMessage)

ResourceException - See Link.send(java.lang.isolate.LinkMessage)

LinkSerializationException - See Link.send(java.lang.isolate.LinkMessage)

UnsupportedOperationException - See Link.send(java.lang.isolate.LinkMessage)