planet.commonapi
Interface Node

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

public interface Node
extends java.io.Serializable

Author:
Jordi Pujol

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.
 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.
 NodeHandle getPred()
          Returns the NodeHandle of the present predecessor of the node
 Application[] getRegisteredApplications()
          Returns all references of the applications that mantains this 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.
 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.
 Queue outMessages()
          Returns the outgoing queue with message to be send.
 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 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:
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.
Returns:
A RouteMessage with the correctly initialized values.

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

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.

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