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.

Because resolution may require communication with a remote host,
the source of a ResolutionRequestmust 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.

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

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.