planet.commonapi
Interface Node

All Superinterfaces:
java.io.Serializable
All Known Implementing Classes:
BadChordNode, ChordNode, NetworkNodeImpl, NodeImpl, SymphonyNode

public interface Node
extends java.io.Serializable

Interface which represents a node in a peer-to-peer system, regardless of the underlying protocol. This represents a factory, in a sense, that will give a application an Endpoint which it can use to send and receive messages.

Author:
Jordi Pujol, Marc Sanchez

Method Summary
 void broadcast(java.lang.String appId, NodeHandle to, NodeHandle nextHop, Message msg)
          Initiating a Broadcast Message
 void fail()
          If supose TCP connections onto network layer, this method must informe with some type of error message to its connected nodes for broken connection.
 java.util.Set getAllLinks()
          Gets all node connections to other nodes as its NodeHandles.
 NodeHandle getClosestNodeHandle(Id id)
          Returns the NodeHandle closest to id.
 void getEInGML(java.util.Collection E, GMLConstraint constraint)
          This method is a callback method used to collect all of the edges of a graph according to GML file format for latter visual graph performance.
 Id getId()
          Returns the Id of this node
 IdFactory getIdFactory()
          Returns a factory for Ids specific to this node's protocol.
 NodeHandle getLocalHandle()
          Returns the NodeHandle for the actual Node.
 void getNewE(java.util.Iterator it, GMLConstraint constraint, java.util.Collection E, java.lang.String color)
          Adds a new Edge to E set according to specified GMLConstraint.
 NodeHandle getPred()
          Returns the NodeHandle of the present predecessor of the node
 EndPoint getRegisteredApplication(java.lang.String instanceName)
          Get the registered application by the instanceName name.
 Application[] getRegisteredApplications()
          Returns all references of the applications that mantains this node.
 NodeHandle getSucc()
          Returns the NodeHandle of the present successor of the node
 java.util.Vector getSuccList(int max)
          Returns the successor list of the present node with max number of Ids.
 boolean isAlive()
          Informs if this node is alive.
 boolean isLocalMessage(RouteMessage msg)
          The isLocalMessage's method is an extension method for commonapi specs.
 void join(Id nodeId)
          This Node joins another node identified by nodeId.
 void leave()
          This method permits to the actual node to leave the network.
 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.
 void networkStabilized(boolean stabilized)
          The networkStabilized's method is a callback method used for the network simulator to notify to all nodes the stabilization process has finished and the topology is built up.
 Queue outMessages()
          Returns the outgoing queue with message to be send.
 boolean playsGoodRole()
          The playsGoodRole's method is an extension method for commonapi specs.
 void prettyPrintNode()
          Shows for System.out only the owner Id, its predecessor and successor.
 void printNode()
          Shows for System.out all information of the node, including finger table.
 boolean process(int actualStep)
          It permits to the node to send messages, run stabilization, etc.
 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.
 void receive(RouteMessage msg)
          This method is invoked to send a message msg to the actual Node (another ----> me).
 EndPoint registerApplication(Application app, java.lang.String instance)
          This returns a VirtualizedNode specific to the given application and instance name to the application, which the application can then use in order to send and receive messages.
 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 routeData(java.lang.String appId, NodeHandle to, NodeHandle nextHop, Message msg)
          Receive's data of the application level and sends it through de network.
 void send(RouteMessage msg)
          This method is invoked to send a message msg to another Node (me ---> another).
 void setGoodRole(boolean role)
          The setGoodRole's method is an extension method for commonapi specs.
 void setTimer(TimerTask task, long firstTime)
          Sets a new task to make only once time.
 void setTimer(TimerTask task, long firstTime, long period)
          Sets a new task to make periodicly at period time.
 

Method Detail

registerApplication

EndPoint registerApplication(Application app,
                             java.lang.String instance)
This returns a VirtualizedNode specific to the given application and instance name to the application, which the application can then use in order to send and receive messages.

Parameters:
app - The Application
instance - An identifier for a given instance
Returns:
The endpoint specific to this application, which can be used for message sending/receiving.

getRegisteredApplication

EndPoint getRegisteredApplication(java.lang.String instanceName)
Get the registered application by the instanceName name.

Parameters:
instanceName - Name of the registered application.
Returns:
null if there isn't an instance of instanceName, or the related endpoint for the application.

getRegisteredApplications

Application[] getRegisteredApplications()
Returns all references of the applications that mantains this node.

Returns:
An array with all references to the applications that they are mantained for this node.

getId

Id getId()
Returns the Id of this node

Returns:
This node's Id

getIdFactory

IdFactory getIdFactory()
                       throws InitializationException
Returns a factory for Ids specific to this node's protocol.

Returns:
A factory for creating Ids.
Throws:
InitializationException - if occurs any problem with IdFactory initialization.

routeData

void routeData(java.lang.String appId,
               NodeHandle to,
               NodeHandle nextHop,
               Message msg)
Receive's data of the application level and sends it through de network.

Parameters:
appId - String that includes the application identification.
to - Node that must receive this message. If cannot represents a real node.
nextHop - Node that must receive this message as first hop.
msg - Message to be sent. If it is null, the message must be routed.

join

void join(Id nodeId)
This Node joins another node identified by nodeId.

Parameters:
nodeId - Id of Node to join to the actual ring.

leave

void leave()
This method permits to the actual node to leave the network.


fail

void fail()
If supose TCP connections onto network layer, this method must informe with some type of error message to its connected nodes for broken connection. In other case, nothing should be required.


process

boolean process(int actualStep)
It permits to the node to send messages, run stabilization, etc.

Parameters:
actualStep - Actual step to simulate
Returns:
true if the node needs to continue the stabilization process. false if node is just stabilized.

receive

void receive(RouteMessage msg)
             throws QueueFull
This method is invoked to send a message msg to the actual Node (another ----> me).

Parameters:
msg - Message to be received for the actual Node.
Throws:
QueueFull - if the incoming queue of the actual Node is full.

send

void send(RouteMessage msg)
          throws QueueFull
This method is invoked to send a message msg to another Node (me ---> another).

Parameters:
msg - Message to be received for the remote Node.
Throws:
QueueFull - if the outgoing queue of the actual Node is full.

outMessages

Queue outMessages()
Returns the outgoing queue with message to be send.

Returns:
The queue with the outgoing messages to be send.

printNode

void printNode()
Shows for System.out all information of the node, including finger table.


prettyPrintNode

void prettyPrintNode()
Shows for System.out only the owner Id, its predecessor and successor.


broadcast

void broadcast(java.lang.String appId,
               NodeHandle to,
               NodeHandle nextHop,
               Message msg)
Initiating a Broadcast Message

Parameters:
appId - String that includes the application identification.
to - Node that must receive this message. If cannot represents a real node.
nextHop - Node that must receive this message as first hop. If it is null, the message must be routed.

getLocalHandle

NodeHandle getLocalHandle()
Returns the NodeHandle for the actual Node.

Returns:
NodeHandle for the actual Node.

getPred

NodeHandle getPred()
Returns the NodeHandle of the present predecessor of the node

Returns:
predeccesor NodeHandle of this Node

getSucc

NodeHandle getSucc()
Returns the NodeHandle of the present successor of the node

Returns:
successor NodeHandle of this Node

isAlive

boolean isAlive()
Informs if this node is alive.

Returns:
true if the node is alive. false if the node has fail or leave.

getSuccList

java.util.Vector getSuccList(int max)
Returns the successor list of the present node with max number of Ids.

Parameters:
max - number of the elements (NodeHandle's) to return
Returns:
successor list Vector that contains NodeHandle's of successors.

playsGoodRole

boolean playsGoodRole()
The playsGoodRole's method is an extension method for commonapi specs. This method is used to allow BehavioursPool decide wether the Node should run behaviours for good peers or instead run behaviours for bad peers. Moreover, this method lets the programmer the responsability of decide node's role. Even it allows a node to have a transient behaviour, sometimes behaving as a good peer and sometines behaving as a bad peer.

Returns:
True if the Node's Role is positive.

setGoodRole

void setGoodRole(boolean role)
The setGoodRole's method is an extension method for commonapi specs. This method is used to set the role of the node inside the overlay network. A true value means the node will behave according to the underlying overlay protocol. A false value means the node will misbehave.

Parameters:
role -

isLocalMessage

boolean isLocalMessage(RouteMessage msg)
The isLocalMessage's method is an extension method for commonapi specs. This method is used to allow BehavioursPool decide wether the incoming RouteMessage is for the local node or for a remote node. Remenber, this decision may only be addressed by the underlying overlay protocol. For example, for Symphony's Lookup protocol a node is responsible for all RouteMessages whose keys have as an immediate succesor the node's id or have as destination the own node.

Returns:
True if the incoming RouteMessage taken as input its for the local node.
See Also:
BehavioursPool

networkStabilized

void networkStabilized(boolean stabilized)
The networkStabilized's method is a callback method used for the network simulator to notify to all nodes the stabilization process has finished and the topology is built up.

Parameters:
stabilized - True wether the network is stable.

setTimer

void setTimer(TimerTask task,
              long firstTime)
Sets a new task to make only once time.

Parameters:
task - Job to do at the unique activation.
firstTime - First moment at which the task will be activated, in absolute representation, not relative for the actual time.

setTimer

void setTimer(TimerTask task,
              long firstTime,
              long period)
Sets a new task to make periodicly at period time.

Parameters:
task - Job to do at each activation.
firstTime - First moment at which the task will be activated, in absolute representation, not relative for the actual time
period - Number of steps or millis of the period.

localLookup

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

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

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

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().

getNewE

void getNewE(java.util.Iterator it,
             GMLConstraint constraint,
             java.util.Collection E,
             java.lang.String color)
Adds a new Edge to E set according to specified GMLConstraint.

Parameters:
it - Iterator over a collection of nodeHandles.
constraint - Specific constraints.
color - Fill color of the edge.
E - Edge set where they have to be added.

getEInGML

void getEInGML(java.util.Collection E,
               GMLConstraint constraint)
This method is a callback method used to collect all of the edges of a graph according to GML file format for latter visual graph performance.

Parameters:
E - Edge Set
constraint - Constraints for edge selection

getClosestNodeHandle

NodeHandle getClosestNodeHandle(Id id)
Returns the NodeHandle closest to id.

Parameters:
id - Id to find.
Returns:
The NodeHandle closest to id.

getAllLinks

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.