planet.commonapi
Interface Node

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

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

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

getRegisteredApplications

public 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

public Id getId()
Returns the Id of this node

Returns:
This node's Id

getIdFactory

public 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

public 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

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

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

leave

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


fail

public 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

public 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

public 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

public 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

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

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

printNode

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


prettyPrintNode

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


broadcast

public 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

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

Returns:
NodeHandle for the actual Node.

getPred

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

Returns:
predeccesor NodeHandle of this Node

getSucc

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

Returns:
successor NodeHandle of this Node

isAlive

public boolean isAlive()
Informs if this node is alive.

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

getSuccList

public 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

public 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

public 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

public 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

public 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

public 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

public 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

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

getNewE

public 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

public 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

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.