rice.pastry.commonapi
Class PastryEndpoint

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

All Implemented Interfaces:

Endpoint, NodeHandleReader

public class PastryEndpoint
extends PastryAppl
implements Endpoint

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

Version:

$Id: PastryEndpoint.java 3621 2007-03-01 17:19:43Z jeffh $

Author:

Alan Mislove, Peter Druschel

Field Summary

protected Application

application

Fields inherited from class rice.pastry.client.PastryAppl

address, deserializer, instance, logger, receiver, thePastryNode

Constructor Summary

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

PastryEndpoint(PastryNode pn, Application application, java.lang.String instance, int address, boolean register)
Constructor.

Method Summary

NodeHandle	coalesce(NodeHandle newHandle)
void	destroy() Called when PastryNode is destroyed.
boolean	enrouteMessage(Message msg, Id key, NodeHandle nextHop, SendOptions opt) Called by pastry when a message is enroute and is passing through this node.
int	getAppId()
MessageDeserializer	getDeserializer() Returns the deserializer.
Environment	getEnvironment() Returns the environment.
Id	getId() Returns this node's id, which is its identifier in the namespace.
java.lang.String	getInstance() Returns a unique instance name of this endpoint, sort of a mailbox name for this application.
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.
java.util.List	networkNeighbors(int num) Returns an ordered list of the nearest known neighbors.
void	process(Executable task, Continuation command) Schedules a job for processing on the dedicated processing thread.
int	proximity(NodeHandle nh) This replaces NodeHandle.proximity(), so that you don't have to have a "coalesced" NodeHandle.
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.
Id	readId(InputBuffer buf, short type) To use a more efficient serialization format than Java Serialization
IdRange	readIdRange(InputBuffer buf) To use Raw Serialization
NodeHandle	readNodeHandle(InputBuffer buf) To use Raw Serialization
NodeHandleSet	readNodeHandleSet(InputBuffer buf, short type)
void	receiveMessage(Message msg) Called by pastry to deliver a message to this client.
NodeHandleSet	replicaSet(Id id, int maxRank) This method returns an ordered set of nodehandles on which replicas of the object with key can be stored.
NodeHandleSet	replicaSet(Id id, int maxRank, NodeHandle root, NodeHandleSet set) This methods returns an ordered set of nodehandles on which replicas of an object with a given id can be stored.
void	route(Id key, Message msg, NodeHandle hint) This operation forwards a message towards the root of key.
void	route(Id key, RawMessage msg, NodeHandle hint) This duplication of the above code is to make a fast path for the RawMessage.
CancellableTask	scheduleMessage(Message message, long delay) Schedules a message to be delivered to this application after the provided number of milliseconds.
CancellableTask	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.
CancellableTask	scheduleMessageAtFixedRate(Message msg, long delay, long period) Schedule the specified message for repeated fixed-rate delivery to the local node, beginning after the specified delay.
void	setDeserializer(MessageDeserializer md) To use a more efficient serialization format than Java Serialization
java.lang.String	toString()

Methods inherited from class rice.pastry.client.PastryAppl

accept, connect, deliverWhenNotReady, getAddress, getLeafSet, getNodeHandle, getNodeId, getRoutingTable, isClosest, notifyReady, receiveMessageInternal, receiveSocket, register, routeMsg, routeMsgDirect, routeSetChange

Methods inherited from class java.lang.Object

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

Methods inherited from interface rice.p2p.commonapi.Endpoint

accept, connect, register

Field Detail

application

protected Application application

Constructor Detail

PastryEndpoint

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

Constructor.

Parameters:

pn - the pastry node that the application attaches to.

PastryEndpoint

public PastryEndpoint(PastryNode pn,
                      Application application,
                      java.lang.String instance,
                      int address,
                      boolean register)

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

route

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

This duplication of the above code is to make a fast path for the RawMessage. Though the codeblock looks identical, it is acually calling a different PEM constructor.

Specified by:

route in interface Endpoint

scheduleMessage

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

delay - The number of milliseconds to wait before delivering subsequent messages

scheduleMessageAtFixedRate

public CancellableTask scheduleMessageAtFixedRate(Message msg,
                                                  long delay,
                                                  long period)

Schedule the specified message for repeated fixed-rate delivery to the local node, beginning after the specified delay. Subsequent executions take place at approximately regular intervals, separated by the specified period.

Specified by:

scheduleMessageAtFixedRate in interface Endpoint

Parameters:

msg - a message that will be delivered to the local node after the specified delay

delay - time in milliseconds before message is to be delivered

period - time in milliseconds between successive message deliveries

Returns:

the scheduled event object; can be used to cancel the 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 id,
                                int maxRank)

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

replicaSet

public NodeHandleSet replicaSet(Id id,
                                int maxRank,
                                NodeHandle root,
                                NodeHandleSet set)

This methods returns an ordered set of nodehandles on which replicas of an object with a given id can be stored. The call returns nodes up to and including a node with maxRank. This call also allows the application to provide a remote "center" node, as well as other nodes in the vicinity.

Specified by:

replicaSet in interface Endpoint

Parameters:

id - The object's id.

maxRank - The number of desired replicas.

handle - The root handle of the remove set

set - The set of other nodes around the root handle

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,
                                    NodeHandle nextHop,
                                    SendOptions opt)

Description copied from class: PastryAppl

Called by pastry when a message is enroute and is passing through this node. If this method is not overridden, the default behaviour is to let the message pass through.

Overrides:

enrouteMessage in class PastryAppl

Parameters:

msg - the message that is passing through.

key - the key

nextHop - the default next hop for the message.

opt - the send options the message was sent with.

Returns:

true if the message should be routed, false if the message should be cancelled.

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.

receiveMessage

public void receiveMessage(Message msg)

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

Overrides:

receiveMessage in class PastryAppl

Parameters:

msg - the message that is arriving.

process

public void process(Executable task,
                    Continuation command)

Schedules a job for processing on the dedicated processing thread. CPU intensive jobs, such as encryption, erasure encoding, or bloom filter creation should never be done in the context of the underlying node's thread, and should only be done via this method.

Specified by:

process in interface Endpoint

Parameters:

task - The task to run on the processing thread

command - The command to return the result to once it's done

getInstance

public java.lang.String getInstance()

Returns a unique instance name of this endpoint, sort of a mailbox name for this application.

Specified by:

getInstance in interface Endpoint

Returns:

The unique instance name of this application

getEnvironment

public Environment getEnvironment()

Description copied from interface: Endpoint

Returns the environment. This allows the nodes to be virtualized within the JVM

Specified by:

getEnvironment in interface Endpoint

Returns:

the environment for this node/app.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

setDeserializer

public void setDeserializer(MessageDeserializer md)

Description copied from interface: Endpoint

To use a more efficient serialization format than Java Serialization

Specified by:

setDeserializer in interface Endpoint

Overrides:

setDeserializer in class PastryAppl

getDeserializer

public MessageDeserializer getDeserializer()

Description copied from interface: Endpoint

Returns the deserializer. The default deserializer can deserialize rice.p2p.util.JavaSerializedMessage

Specified by:

getDeserializer in interface Endpoint

Returns:

readId

public Id readId(InputBuffer buf,
                 short type)
          throws java.io.IOException

Description copied from interface: Endpoint

To use a more efficient serialization format than Java Serialization

Specified by:

readId in interface Endpoint

Throws:

java.io.IOException

readNodeHandle

public NodeHandle readNodeHandle(InputBuffer buf)
                          throws java.io.IOException

Description copied from interface: NodeHandleReader

To use Raw Serialization

Specified by:

readNodeHandle in interface NodeHandleReader

Returns:

Throws:

java.io.IOException

readIdRange

public IdRange readIdRange(InputBuffer buf)
                    throws java.io.IOException

Description copied from interface: Endpoint

To use Raw Serialization

Specified by:

readIdRange in interface Endpoint

Returns:

Throws:

java.io.IOException

coalesce

public NodeHandle coalesce(NodeHandle newHandle)

Specified by:

coalesce in interface NodeHandleReader

readNodeHandleSet

public NodeHandleSet readNodeHandleSet(InputBuffer buf,
                                       short type)
                                throws java.io.IOException

Specified by:

readNodeHandleSet in interface Endpoint

Throws:

java.io.IOException

networkNeighbors

public java.util.List networkNeighbors(int num)

Description copied from interface: Endpoint

Returns an ordered list of the nearest known neighbors. Note that proximity is usually an estimate, and can quickly become stale.

Specified by:

networkNeighbors in interface Endpoint

Returns:

List of NodeHandle

destroy

public void destroy()

Description copied from class: PastryAppl

Called when PastryNode is destroyed. Can be overloaded by applications.

Overrides:

destroy in class PastryAppl

proximity

public int proximity(NodeHandle nh)

Description copied from interface: Endpoint

This replaces NodeHandle.proximity(), so that you don't have to have a "coalesced" NodeHandle.

Specified by:

proximity in interface Endpoint

Returns:

getAppId

public int getAppId()