Rice Pastry API

rice.p2p.commonapi
Interface Endpoint

All Superinterfaces:
NodeHandleReader
All Known Implementing Classes:
GCEndpoint, MultiringEndpoint, PastryEndpoint

public interface Endpoint
extends NodeHandleReader

Version:
$Id: Endpoint.java 3274 2006-05-15 16:17:47Z jeffh $
Author:
Alan Mislove, Peter Druschel

Method Summary
 void accept(AppSocketReceiver receiver)
          Set's the acceptor for this application.
 void connect(NodeHandle handle, AppSocketReceiver receiver, int timeout)
          Opens a connection to this application on a remote node.
 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.
 NodeHandleSet localLookup(Id id, int num, boolean safe)
          This call produces a list of nodes that can be used as next hops on a route towards the given id, such that the resulting route satisfies the overlay protocol's bounds on the number of hops taken.
 NodeHandleSet neighborSet(int num)
          This methods returns an unordered set of nodehandles on which are neighbors of the local node in the id space.
 void process(Executable task, Continuation command)
          Schedules a job for processing on the dedicated processing thread.
 IdRange range(NodeHandle handle, int rank, Id lkey)
          This operation provides information about ranges of keys for which the node is currently a rank-root.
 IdRange range(NodeHandle handle, int rank, Id lkey, boolean cumulative)
          This operation provides information about ranges of keys for which the node is currently a rank-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
 NodeHandleSet readNodeHandleSet(InputBuffer buf, short type)
          DESCRIBE THE METHOD
 void register()
          DESCRIBE THE METHOD
 NodeHandleSet replicaSet(Id id, int maxRank)
          This method returns an ordered set of nodehandles on which replicas of an object with a given id 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 id, Message message, NodeHandle hint)
          This method makes an attempt to route the message to the root of the given id.
 void route(Id id, RawMessage message, NodeHandle hint)
          Same as the other call, but uses the Raw serialization rather than java serialization.
 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 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.
 void setDeserializer(MessageDeserializer md)
          To use a more efficient serialization format than Java Serialization
 
Methods inherited from interface rice.p2p.commonapi.rawserialization.NodeHandleReader
coalesce, readNodeHandle
 

Method Detail

getId

public Id getId()
Returns this node's id, which is its identifier in the namespace.

Returns:
The local node's id

route

public void route(Id id,
                  Message message,
                  NodeHandle hint)
This method makes an attempt to route the message to the root of the given id. The hint handle will be the first hop in the route. If the id field is null, then the message is routed directly to the given node, and delivers the message there. If the hint field is null, then this method makes an attempt to route the message to the root of the given id. Note that one of the id and hint fields can be null, but not both.

Parameters:
id - The destination Id of the message.
message - The message to deliver
hint - The first node to send this message to, optional

route

public void route(Id id,
                  RawMessage message,
                  NodeHandle hint)
Same as the other call, but uses the Raw serialization rather than java serialization.

Parameters:
id -
message -
hint -

localLookup

public NodeHandleSet localLookup(Id id,
                                 int num,
                                 boolean safe)
This call produces a list of nodes that can be used as next hops on a route towards the given id, such that the resulting route satisfies the overlay protocol's bounds on the number of hops taken. If the safe flag is specified, then the fraction of faulty nodes returned is no higher than the fraction of faulty nodes in the overlay.

Parameters:
id - The destination id.
num - The number of nodes to return.
safe - Whether or not to return safe nodes.
Returns:
DESCRIBE THE RETURN VALUE

neighborSet

public NodeHandleSet neighborSet(int num)
This methods returns an unordered set of nodehandles on which are neighbors of the local node in the id space. Up to num handles are returned.

Parameters:
num - The number of desired handle to return.
Returns:
DESCRIBE THE RETURN VALUE

replicaSet

public NodeHandleSet replicaSet(Id id,
                                int maxRank)
This method 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 method is equivalent to calling replicaSet(id, maxRank, getLocalNodeHandle(), neighborSet(Integer.MAX_VALUE));

Parameters:
id - The object's id.
maxRank - The number of desired replicas.
Returns:
DESCRIBE THE RETURN VALUE

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.

Parameters:
id - The object's id.
maxRank - The number of desired replicas.
set - The set of other nodes around the root handle
root - DESCRIBE THE PARAMETER
Returns:
DESCRIBE THE RETURN VALUE

range

public IdRange range(NodeHandle handle,
                     int rank,
                     Id lkey)
              throws RangeCannotBeDeterminedException
This operation provides information about ranges of keys for which the node is currently a rank-root. The operations returns null if the range could not be determined, the range otherwise. It is an error to query the range of a node not present in the neighbor set as returned bythe update upcall or the neighborSet call. Certain implementations may return an error if rank is greater than zero. Some protocols may have multiple, disjoint ranges of keys for which a given node is responsible. The parameter lkey allows the caller to specify which region should be returned. If the node referenced by is responsible for key lkey, then the resulting range includes lkey. Otherwise, the result is the nearest range clockwise from lkey for which is responsible.

Parameters:
handle - The handle whose range to check.
rank - The root rank.
lkey - An "index" in case of multiple ranges.
Returns:
DESCRIBE THE RETURN VALUE
Throws:
RangeCannotBeDeterminedException - DESCRIBE THE EXCEPTION

range

public IdRange range(NodeHandle handle,
                     int rank,
                     Id lkey,
                     boolean cumulative)
              throws RangeCannotBeDeterminedException
This operation provides information about ranges of keys for which the node is currently a rank-root. The operations returns null if the range could not be determined, the range otherwise. It is an error to query the range of a node not present in the neighbor set as returned bythe update upcall or the neighborSet call. Certain implementations may return an error if rank is greater than zero. Some protocols may have multiple, disjoint ranges of keys for which a given node is responsible. The parameter lkey allows the caller to specify which region should be returned. If the node referenced by is responsible for key lkey, then the resulting range includes lkey. Otherwise, the result is the nearest range clockwise from lkey for which is responsible.

Parameters:
handle - The handle whose range to check.
rank - The root rank.
lkey - An "index" in case of multiple ranges.
cumulative - Whether to return the cumulative or single range
Returns:
DESCRIBE THE RETURN VALUE
Throws:
RangeCannotBeDeterminedException - DESCRIBE THE EXCEPTION

getLocalNodeHandle

public NodeHandle getLocalNodeHandle()
Returns a handle to the local node below this endpoint. This node handle is serializable, and can therefore be sent to other nodes in the network and still be valid.

Returns:
A NodeHandle referring to the local node.

scheduleMessage

public CancellableTask scheduleMessage(Message message,
                                       long delay)
Schedules a message to be delivered to this application after the provided number of milliseconds.

Parameters:
message - The message to be delivered
delay - The number of milliseconds to wait before delivering the message
Returns:
DESCRIBE THE RETURN VALUE

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.

Parameters:
message - The message to be delivered
delay - The number of milliseconds to wait before delivering the fist message
period - DESCRIBE THE PARAMETER
Returns:
DESCRIBE THE RETURN VALUE

scheduleMessageAtFixedRate

public CancellableTask scheduleMessageAtFixedRate(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.

Parameters:
message - The message to be delivered
delay - The number of milliseconds to wait before delivering the fist message
period - DESCRIBE THE PARAMETER
Returns:
DESCRIBE THE RETURN VALUE

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.

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.

Returns:
The unique instance name of this application

getEnvironment

public Environment getEnvironment()
Returns the environment. This allows the nodes to be virtualized within the JVM

Returns:
the environment for this node/app.

accept

public void accept(AppSocketReceiver receiver)
Set's the acceptor for this application. If no acceptor is set, then when a remote node's application opens a socket here, they will get an *Exception*

Parameters:
receiver - calls receiveSocket() when a new AppSocket is opened to this application from a remote node. Note that you must call accept() again after each socket is received to properly handle socket backlogging

connect

public void connect(NodeHandle handle,
                    AppSocketReceiver receiver,
                    int timeout)
Opens a connection to this application on a remote node. If no acceptor is set, then receiver will get an *Exception*

Parameters:
receiver - calls receiveSocket() when a new AppSocket is opened to this application on a remote node.
handle - DESCRIBE THE PARAMETER
timeout - DESCRIBE THE PARAMETER

setDeserializer

public void setDeserializer(MessageDeserializer md)
To use a more efficient serialization format than Java Serialization

Parameters:
md -

getDeserializer

public MessageDeserializer getDeserializer()
Returns the deserializer. The default deserializer can deserialize rice.p2p.util.JavaSerializedMessage

Returns:

readId

public Id readId(InputBuffer buf,
                 short type)
          throws java.io.IOException
To use a more efficient serialization format than Java Serialization

Parameters:
buf - DESCRIBE THE PARAMETER
type - DESCRIBE THE PARAMETER
Returns:
DESCRIBE THE RETURN VALUE
Throws:
java.io.IOException - DESCRIBE THE EXCEPTION

readIdRange

public IdRange readIdRange(InputBuffer buf)
                    throws java.io.IOException
To use Raw Serialization

Parameters:
buf -
Returns:
Throws:
java.io.IOException

readNodeHandleSet

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

Parameters:
buf - DESCRIBE THE PARAMETER
type - DESCRIBE THE PARAMETER
Returns:
DESCRIBE THE RETURN VALUE
Throws:
java.io.IOException - DESCRIBE THE EXCEPTION

register

public void register()
DESCRIBE THE METHOD


Rice Pastry API

Copyright © 2001-2005 - Rice Pastry.


Imprint-Dataprotection