rice.pastry.commonapi
Class PastryEndpoint

java.lang.Object
  rice.pastry.client.PastryAppl
      rice.pastry.commonapi.PastryEndpoint

All Implemented Interfaces:

Endpoint, MessageReceiver

public class PastryEndpoint

extends PastryAppl

implements Endpoint

This class serves as gluecode, which allows applications written for the common API to work with pastry.

Field Summary

protected Application	application
protected Credentials	credentials

Fields inherited from class rice.pastry.client.PastryAppl

address, instance, thePastryNode

Constructor Summary

PastryEndpoint(PastryNode pn, Application application, java.lang.String instance)
Constructor.

Method Summary

boolean	enrouteMessage(Message msg, Id key, NodeId nextHop, SendOptions opt)
Credentials	getCredentials() Returns the credentials of this application.
Id	getId() Returns this node's id, which is its identifier in the namespace.
NodeHandle	getLocalNodeHandle() Returns a handle to the local node below this endpoint.
void	leafSetChange(NodeHandle nh, boolean wasAdded) Called by pastry when the leaf set changes.
NodeHandleSet	localLookup(Id key, int num, boolean safe) This method produces a list of nodes that can be used as next hops on a route towards key, such that the resulting route satisfies the overlay protocol's bounds on the number of hops taken.
void	messageForAppl(Message msg) Called by pastry when a message arrives for this application.
NodeHandleSet	neighborSet(int num) This method produces an unordered list of nodehandles that are neighbors of the local node in the ID space.
IdRange	range(NodeHandle n, int r, Id key) This method provides information about ranges of keys for which the node n is currently a r-root.
IdRange	range(NodeHandle n, int r, Id key, boolean cumulative) This method provides information about ranges of keys for which the node n is currently a r-root.
void	receiveMessage(Message msg) Called by pastry to deliver a message to this client.
NodeHandleSet	replicaSet(Id key, int max_rank) This method returns an ordered set of nodehandles on which replicas of the object with key can be stored.
void	route(Id key, Message msg, NodeHandle hint) This operation forwards a message towards the root of key.
java.util.TimerTask	scheduleMessage(Message message, long delay) Schedules a message to be delivered to this application after the provided number of milliseconds.
java.util.TimerTask	scheduleMessage(Message message, long delay, long period) Schedules a message to be delivered to this application every period number of milliseconds, after delay number of miliseconds have passed.

Methods inherited from class rice.pastry.client.PastryAppl

enrouteMessage, getAddress, getLeafSet, getNodeHandle, getNodeId, getRoutingTable, isClosest, notifyReady, registerReceiver, routeMsg, routeMsgDirect, routeSetChange, sendMessage

Methods inherited from class java.lang.Object

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

Field Detail

credentials

protected Credentials credentials

application

protected Application application

Constructor Detail

PastryEndpoint

public PastryEndpoint(PastryNode pn,
                      Application application,
                      java.lang.String instance)

Constructor.

Parameters:

pn - the pastry node that the application attaches to.

Method Detail

getId

public Id getId()

Returns this node's id, which is its identifier in the namespace.

Specified by:

getId in interface Endpoint

Returns:

The local node's id

route

public void route(Id key,
                  Message msg,
                  NodeHandle hint)

This operation forwards a message towards the root of key. The optional hint argument specifies a node that should be used as a first hop in routing the message. A good hint, e.g. one that refers to the key's current root, can result in the message being delivered in one hop; a bad hint adds at most one extra hop to the route. Either K or hint may be NULL, but not both. The operation provides a best-effort service: the message may be lost, duplicated, corrupted, or delayed indefinitely.

Specified by:

route in interface Endpoint

Parameters:

key - the key

msg - the message to deliver.

hint - the hint

scheduleMessage

public java.util.TimerTask scheduleMessage(Message message,
                                           long delay)

Schedules a message to be delivered to this application after the provided number of milliseconds.

Specified by:

scheduleMessage in interface Endpoint

Parameters:

message - The message to be delivered

delay - The number of milliseconds to wait before delivering the message

scheduleMessage

public java.util.TimerTask scheduleMessage(Message message,
                                           long delay,
                                           long period)

Schedules a message to be delivered to this application every period number of milliseconds, after delay number of miliseconds have passed.

Specified by:

scheduleMessage in interface Endpoint

Parameters:

message - The message to be delivered

delay - The number of milliseconds to wait before delivering the fist message

localLookup

public NodeHandleSet localLookup(Id key,
                                 int num,
                                 boolean safe)

This method produces a list of nodes that can be used as next hops on a route towards key, such that the resulting route satisfies the overlay protocol's bounds on the number of hops taken. If safe is true, the expected fraction of faulty nodes in the list is guaranteed to be no higher than the fraction of faulty nodes in the overlay; if false, the set may be chosen to optimize performance at the expense of a potentially higher fraction of faulty nodes. This option allows applications to implement routing in overlays with byzantine node failures. Implementations that assume fail-stop behavior may ignore the safe argument. The fraction of faulty nodes in the returned list may be higher if the safe parameter is not true because, for instance, malicious nodes have caused the local node to build a routing table that is biased towards malicious nodes~\cite{Castro02osdi}.

Specified by:

localLookup in interface Endpoint

Parameters:

key - the message's key

num - the maximal number of next hops nodes requested

safe -

Returns:

the nodehandle set

neighborSet

public NodeHandleSet neighborSet(int num)

This method produces an unordered list of nodehandles that are neighbors of the local node in the ID space. Up to num node handles are returned.

Specified by:

neighborSet in interface Endpoint

Parameters:

num - the maximal number of nodehandles requested

Returns:

the nodehandle set

replicaSet

public NodeHandleSet replicaSet(Id key,
                                int max_rank)

This method returns an ordered set of nodehandles on which replicas of the object with key can be stored. The call returns nodes with a rank up to and including max_rank. If max_rank exceeds the implementation's maximum replica set size, then its maximum replica set is returned. The returned nodes may be used for replicating data since they are precisely the nodes which become roots for the key when the local node fails.

Specified by:

replicaSet in interface Endpoint

Parameters:

key - the key

max_rank - the maximal number of nodehandles returned

Returns:

the replica set

range

public IdRange range(NodeHandle n,
                     int r,
                     Id key,
                     boolean cumulative)

This method provides information about ranges of keys for which the node n is currently a r-root. The operations returns null if the range could not be determined. It is an error to query the range of a node not present in the neighbor set as returned by the update upcall or the neighborSet call. Some implementations may have multiple, disjoint ranges of keys for which a given node is responsible (Pastry has two). The parameter key allows the caller to specify which range should be returned. If the node referenced by n is the r-root for key, then the resulting range includes key. Otherwise, the result is the nearest range clockwise from key for which n is responsible.

Specified by:

range in interface Endpoint

Parameters:

n - nodeHandle of the node whose range is being queried

r - the rank

key - the key

cumulative - if true, returns ranges for which n is an i-root for 0Returns:

the range of keys, or null if range could not be determined for the given node and rank

range

public IdRange range(NodeHandle n,
                     int r,
                     Id key)

This method provides information about ranges of keys for which the node n is currently a r-root. The operations returns null if the range could not be determined. It is an error to query the range of a node not present in the neighbor set as returned by the update upcall or the neighborSet call. Some implementations may have multiple, disjoint ranges of keys for which a given node is responsible (Pastry has two). The parameter key allows the caller to specify which range should be returned. If the node referenced by n is the r-root for key, then the resulting range includes key. Otherwise, the result is the nearest range clockwise from key for which n is responsible.

Specified by:

range in interface Endpoint

Parameters:

n - nodeHandle of the node whose range is being queried

r - the rank

key - the key

Returns:

the range of keys, or null if range could not be determined for the given node and rank

getLocalNodeHandle

public NodeHandle getLocalNodeHandle()

Returns a handle to the local node below this endpoint.

Specified by:

getLocalNodeHandle in interface Endpoint

Returns:

A NodeHandle referring to the local node.

messageForAppl

public final void messageForAppl(Message msg)

Description copied from class: PastryAppl

Called by pastry when a message arrives for this application.

Specified by:

messageForAppl in class PastryAppl

Parameters:

msg - the message that is arriving.

enrouteMessage

public final boolean enrouteMessage(Message msg,
                                    Id key,
                                    NodeId nextHop,
                                    SendOptions opt)

leafSetChange

public void leafSetChange(NodeHandle nh,
                          boolean wasAdded)

Description copied from class: PastryAppl

Called by pastry when the leaf set changes.

Overrides:

leafSetChange in class PastryAppl

Parameters:

nh - the handle of the node that was added or removed.

wasAdded - true if the node was added, false if the node was removed.

getCredentials

public Credentials getCredentials()

Returns the credentials of this application.

Specified by:

getCredentials in class PastryAppl

Returns:

the credentials.

receiveMessage

public void receiveMessage(Message msg)

Called by pastry to deliver a message to this client. Not to be overridden.

Specified by:

receiveMessage in interface MessageReceiver

Overrides:

receiveMessage in class PastryAppl

Parameters:

msg - the message that is arriving.