Package one.world.rep

This package implements remote event passing (REP).

See:
Description

Class Summary

AnnounceEvent	Implementation of an announce event.
BenchmarkREP	This class performs remote event passing benchmarks.
BenchmarkREPEcho	Implements the echo server required for a latency benchmark for remote event passing.
BenchmarkREPLatency	Performs the latency benchmark for remote event passing.
BenchmarkREPReceiver	Performs the receiver side of a throughput benchmark for remote event passing.
BenchmarkREPSender	Performs the sender side of a throughput benchmark for the REP component.
DiscoveredResource	Implementation of a discovered resource.
DiscoveryClient	A client for service discovery.
DiscoveryServer	A service discovery server.
ElectionEvent	An event to perform
ElectionManager	A component to perform discovery server elections.
LocalizedResource	A localized resource is a resource that is associated with a particular host and port number.
NamedResource	Implementation of a name for a remote event handler.
RemoteDescriptor	Implementation of a remote export descriptor.
RemoteEvent	Implements a remote event, an event which is to be delivered to a remote host.
RemoteManager	A manager for remote event passing.
RemoteReference	Implementation of a reference to a remote event handler.
ResolutionRequest	A request to resolve a SymbolicHandler.
ResolutionResponse	Implements the result of a resolution.
TestREP	Regression tests for RemoteManager.

Exception Summary

AlreadyBoundException	Implementation of a already bound exception.
ConnectionFailedException	Implementation of a connection failed exception.

Package one.world.rep Description

This package implements remote event passing (REP). REP allows events to be sent to event handlers on remote hosts. To become remotely accessible, an event handler must handle remote events and remotely export itself via a binding request. Event handlers must also be exported if they wish to send remote events and receive responses.

Two kinds of remote resources are used to refer to event handlers on remote hosts: DiscoveredResource and LocalizedResource. Both descend from SymbolicHandler and do not directly handle events. Discovered resources are named by some query describing the desired attributes of the resource, and are located by the discovery service if one is available. Localized resources are located with a RemoteManager running on a particular machine and a particular port. LocalizedResource is an abstract class with two subclasses: NamedResource and RemoteReference. The actual event handler which is bound to a named resource may change over time, but remote references always refer uniquely to a single event handler.

The following three event types are handled by the request handler of an Environment or RemoteManager.

1. BindingRequests are used to export event handlers. The descriptor for the binding request should be an RemoteDescriptor. If the operation is successful, the resulting BindingResponse will contain a RemoteReference that refers uniquely to the newly exported event handler. The operation may fail with a AlreadyBoundException.

2. RemoteEvents are used to send events to a remote event handler. A failure may be indicated with an UnknownResourceException or a ConnectionFailedException.

3. ResolutionRequests are used to resolve remote resources to specific remote references. If resolution is successful, the response will be a ResolutionResponse. Otherwise, the result will be an UnknownResourceException or a ConnectionFailedException.

   Because resolution may require communication with a remote host, the source of a ResolutionRequest must be a RemoteReference in order to receive a result. An InvalidTupleException will be returned if this is not the case.

AbstractHandler and IOUtilities provide several utility methods that are useful in exporting event handlers and sending remote events.

Examples

In these examples, handler is an EventHandler and requestHandler is the Environment's request handler.

Exporting an event handler:

// Construct an export descriptor with a name as the 
// event handler descriptor.
RemoteDescriptor descriptor = new RemoteDescriptor(handler, "name");

// Construct the binding request.
Event request =
    new BindingRequest(null, null, descriptor, 60*1000);

// Use synchronous invokation to send the request.
Event response = Synchronous.invoke(requestHandler, request);

if (response instanceof BindingResponse) {
  // The event handler was successfully exported.  
  // Extract the lease and the remote reference.
  BindingResponse br = (BindingResponse)response;
  EventHandler lease = br.lease;
  RemoteReference handlerReference = (RemoteReference)br.resource;

} else if (response instanceof ExceptionalEvent) {
  if (((ExceptionalEvent)response).x instanceof AlreadyBoundException) {
    // The desired name is already in use by someone else.
  } 

} else {
  // The event handler was not successfully exported.
}

After exporting the event handler, it can be refered to with the descriptor NamedDescriptor("hostname", Constants.REP_PORT, "name") as well as with the RemoteReference returned in the binding response.

Sending a remote event:

// A remote reference to the sending event handler should be stored here
// after exporting the event handler.
RemoteReference myReference = ...;

// Construct a remote resource for the destination.
NamedResource destination = 
    new NamedResource("hostname", Constants.REP_PORT, "name");

// Construct the event we wish to send.  The source of the event (and all
// other event handlers in the event) must be remote resources.
Event nestedEvent = 
    new DynamicTuple(myReference, "Hello world!");

// Construct the remote event.
RemoteEvent remoteEvent =
    new RemoteEvent(this, null, destination, nestedEvent);

// Invoke the environment's request handler on the event.
requestHandler.handle(remoteEvent);

Handling a remote event:

class MyHandler extends AbstractHandler {
  
  /** 
   * A remote reference to this event handler, obtained by exporting it.
   */
  RemoteReference myReference;

  ...
  

  protected boolean handle1(Event e) {
    if (e instanceof RemoteEvent) {

      // Extract the nested event.
      Event nestedEvent = ((RemoteEvent)e).event;

      // Extract the nested event source.
      SymbolicHandler source = (SymbolicHandler)nestedEvent.source;
      
      // Generate a response to the nested event.
      Event response = ...;

      // Send the response to the nested event, via the environment's
      // request handler.
      requestHandler.handle(
          new RemoteEvent(this, null, source, response)):

      return true;
    }
    return false;
  }
}

See RemoteReceiver and RemoteSender for a simple example application.

Constants

• Constants.REP_PORT specifies the TCP port on which the global remote manager will listen.
• Connections to remote hosts are cached, so that the same connection may be reused if several events are sent to the remote host. Constants.REP_CACHE_TIMEOUT gives the frequency with which to check if a connection is still active.
• If an attempt to send an event to a remote host fails with a ConnectionFailedException, the send may be retried up to Constants.REP_MAX_RETRIES times before giving up and reporting the exception to the remote host.
• Events are queued while a connection to a remote host is being established. Constants.REP_QUEUE_CAPACITY is the queue capacity, after which the response to all events for that connection is a NoBufferSpaceException.