planet.commonapi
Interface EndPoint

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

EndPointImpl

public interface EndPoint

extends java.io.Serializable

Interface which represents a node in a peer-to-peer system, regardless of the underlying protocol. This represents the *local* node, upon which applications can call methods.

Any implementation must include the no argument constructor.

Author:

Jordi Pujol 07-jul-2005

Method Summary

void	broadcast(Id id, Message message) Sends a broadcast message to all nodes in the network.
void	byStep() An upcall to inform to each Application for a new step.
boolean	forward(RouteMessage message) Forwarding the message to the Application
java.util.Set	getAllLinks() Gets all node connections to other nodes as its NodeHandles.
Application	getApplication() Gets the associated Application.
java.lang.String	getApplicationId() Returns the Application's identification.
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.
java.util.Vector	localLookup(Id key, int max, boolean safe) Returns a list of nodes that can be used as next hops on a route towards key.
java.util.Vector	neighborSet(int max) Obtains an unordered list of up to max nodes that are neighbors of the local node.
boolean	range(NodeHandle node, Id rank, Id leftKey, Id rightkey) This operation provides information about ranges of keys for which the node is currently a root.
java.util.Vector	replicaSet(Id key, int maxRank) Returns an ordered set of nodes on which replicas of the object with this key 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	scheduleMessage(RouteMessage message, long delay) Schedules a message to be delivered to this application after the provided number of milliseconds.
EndPoint	setValues(Application app, Node node) Sets the initial values for this EndPoint.

Method Detail

getId

public Id getId()

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

Returns:

The local node's id

getApplicationId

public java.lang.String getApplicationId()

Returns the Application's identification.

Returns:

Application's identification.

getApplication

public Application getApplication()

Gets the associated Application.

Returns:

The associated application.

byStep

public void byStep()

An upcall to inform to each Application for a new step. This method is invoked at the end of each simulation step. Before this, may arrive any number of application Messages, depending on your own main application.

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 void scheduleMessage(RouteMessage 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

broadcast

public void broadcast(Id id,
                      Message message)

Sends a broadcast message to all nodes in the network.

Parameters:

id - Key from the message to be broadcast.

message - Message to be routed to all nodes in the network.

forward

public boolean forward(RouteMessage message)

Forwarding the message to the Application

Parameters:

message - RouteMessage to deliver to the application level.

Returns:

true if the NodeImpl must forward the message.

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 - NodeHandle to be used to route the message. If it is null, the message must be routed as the overlay network establish it.

localLookup

public java.util.Vector localLookup(Id key,
                                    int max,
                                    boolean safe)

Returns a list of nodes that can be used as next hops on a route towards key. If is safe, the expected fraction of faulty nodes in the list is guaranteed to be no higher than the fraction of faulty nodes in the overlay.

Parameters:

key - Target key

max - Number of next hops.

safe - If true, the expected fraction of faulty nodes are the same of the nodes in the overlay.

Returns:

Until a maximum of max nodes to use as next hop.

neighborSet

public java.util.Vector neighborSet(int max)

Obtains an unordered list of up to max nodes that are neighbors of the local node.

Parameters:

max - Maximum of nodes to return.

Returns:

Neighbor nodes.

replicaSet

public java.util.Vector replicaSet(Id key,
                                   int maxRank)

Returns an ordered set of nodes on which replicas of the object with this key can be stored. The maximum number of nodes is maxRank. If the implementation's maximum replica set size is lower, then its maximum replica set is returned.

Parameters:

key - Id for which we find the replica set.

maxRank - Maximum number of members in replica set.

Returns:

An array of nodes with the replica set.

range

public boolean range(NodeHandle node,
                     Id rank,
                     Id leftKey,
                     Id rightkey)

This operation provides information about ranges of keys for which the node is currently a root. Returns false if the range could not be determined, true otherwise.

It is an error to query the range of a node not present in the neighbor set.

The [leftKey,rightKey] denotes the inclusive range of key values.

Parameters:

node - Node that is currently a root of some range of keys.

rank - Number of keys that is root the node (rank=rightKey-leftKey).

leftKey - The value that appears in the invokation is the candidate left key of the range. It may be modified to reflect the correct left margin once invokation has finished.

rightkey - Shows once the invokation has finished the left margin of the range.

Returns:

true if the range chold be determined; false otherwise, including the case of node is not present in the neighbor set returned by neighborSet.

getAllLinks

public java.util.Set getAllLinks()

Gets all node connections to other nodes as its NodeHandles. The order of NodeHandles is unexpected.

Returns:

A set with all connections as NodeHandles.

setValues

public EndPoint setValues(Application app,
                          Node node)

Sets the initial values for this EndPoint.

Parameters:

app - Uplying application.

node - Underlaying node.

Returns:

The same instance, once it has been updated.