planet.commonapi
Interface Network

All Superinterfaces:
java.io.Serializable
All Known Implementing Classes:
NetworkImpl

public interface Network
extends java.io.Serializable

This interface abstacts any ring or network of Nodes. It pretends contain all Nodes in the Network and allow to operate with the Nodes with transparent manner.

Any future implementation must contain the no argument constructor.

Author:
Jordi Pujol 07-jul-2005

Method Summary
 boolean existNode(NodeHandle node)
          Inform if exist on the network one node with NodeHandle node.
 void failNodes(NodeHandle[] nodes)
          nodes shows all nodes NodeHandle that have failed.
 int getProximity(NodeHandle nodeA, NodeHandle nodeB)
          Evaluates the proximity between the two nodes.
 Application getRandomApplication(java.lang.String appId)
          Gets a reference of some application on any node of the network.
 Node getRandomNode(java.util.Random r)
          Returns a randomly selected node of actual network.
 int getSimulatedSteps()
          Gets the actual number of simulated steps.
 java.lang.String getTopology()
          Returns the topology of the actual network.
 java.util.Iterator iterator()
          Gets an Iterator to get all nodes.
 void joinNode(Node node)
          Joins the node to the ring.
 void joinNode(Node node, NodeHandle bootstrap)
          Network joins a node with specified bootstrap.
 int joinNodes(int size)
          Generates size Nodes and joins them to the ring.
 int joinNodes(int size, NodeHandle[] bootstrap)
          Generates size new Nodes joins them by any of the bootstraps.
 void leaveNodes(NodeHandle[] nodes)
          Leave the ring the nodes which his NodeHandle appears in the array nodes.
 void prettyPrintNodes()
          Shows for each node, its Id, predecessor and successor.
 void printNodes()
          Shows for System.out all information of all nodes, including its finger table.
 int registerApplication(NodeHandle[] nodes)
          Register to all Nodes whose NodeHandle appears in array Ids of nodes the Application specified at properties file.
 void registerApplicationAll()
          Register to all Nodes in this network the Applicaton specified at properties file.
 void registerApplicationRandom(int nodes)
          Register the Application specified at properties file radomly to a maximum number of Nodes specified by nodes.
 int run(int steps)
          Runs the process to simulate a total number of steps.
 Network setValues(java.lang.String topology, NodeFactory nodeFactory)
          Sets the initial values for the new Network instance.
 boolean simulate()
          Runs the process to simulate one time step.
 int size()
          Returns the number of Nodes that contains the actual network.
 int stabilize()
          Runs the process of stabilization while the network not has been stabilized.
 

Method Detail

setValues

public Network setValues(java.lang.String topology,
                         NodeFactory nodeFactory)
                  throws InitializationException
Sets the initial values for the new Network instance.

Parameters:
topology - Desired network topology.
nodeFactory - NodeFactory implementation to be used to build the network.
Returns:
The same instance once it has been updated.
Throws:
InitializationException - if any error occurs during the initialization process.

joinNode

public void joinNode(Node node)
              throws InitializationException
Joins the node to the ring.

Parameters:
node - Node to join to the ring.
Throws:
InitializationException

joinNode

public void joinNode(Node node,
                     NodeHandle bootstrap)
              throws InitializationException
Network joins a node with specified bootstrap.

Parameters:
node - Node to join to the network.
bootstrap - Node that joins the node.
Throws:
InitializationException - if occurs any problem during the join.

joinNodes

public int joinNodes(int size)
              throws InitializationException
Generates size Nodes and joins them to the ring.

Parameters:
size - Number of Nodes to join to the ring.
Returns:
A number of actual simulated steps after join size nodes.
Throws:
InitializationException

joinNodes

public int joinNodes(int size,
                     NodeHandle[] bootstrap)
              throws InitializationException
Generates size new Nodes joins them by any of the bootstraps.

Parameters:
size - Number of nodes to joins to the network.
bootstrap - Array of NodeHandles to use as bootstrap. The implementation only must ensure the use of them, or the maximum of them if the number of nodes to join is smaller than bootstrap.length.
Returns:
A number of actual simulated steps after join size nodes.
Throws:
InitializationException - if any error has ocurred during the operation.

leaveNodes

public void leaveNodes(NodeHandle[] nodes)
                throws InitializationException
Leave the ring the nodes which his NodeHandle appears in the array nodes.

Parameters:
nodes - Node's NodeHandles that must leave the network.
Throws:
InitializationException

failNodes

public void failNodes(NodeHandle[] nodes)
               throws InitializationException
nodes shows all nodes NodeHandle that have failed.

Parameters:
nodes - Node's NodeHandles that must fail.
Throws:
InitializationException

registerApplicationAll

public void registerApplicationAll()
                            throws InitializationException
Register to all Nodes in this network the Applicaton specified at properties file.

Throws:
InitializationException
See Also:
Application, Node

registerApplication

public int registerApplication(NodeHandle[] nodes)
                        throws InitializationException
Register to all Nodes whose NodeHandle appears in array Ids of nodes the Application specified at properties file.

Parameters:
nodes - NodeHandles of Nodes that must be registered the Application.
Returns:
The number of Nodes with the Application registered.
Throws:
InitializationException
See Also:
Node, Id

registerApplicationRandom

public void registerApplicationRandom(int nodes)
                               throws InitializationException
Register the Application specified at properties file radomly to a maximum number of Nodes specified by nodes.

Parameters:
nodes - Number of Nodes to be register the Application.
Throws:
InitializationException
See Also:
Node, Id

getTopology

public java.lang.String getTopology()
Returns the topology of the actual network. It cannot be modified.

Returns:
The topology of the network.

size

public int size()
Returns the number of Nodes that contains the actual network.

Returns:
The number of Nodes that contains the actual network.

printNodes

public void printNodes()
Shows for System.out all information of all nodes, including its finger table.


prettyPrintNodes

public void prettyPrintNodes()
Shows for each node, its Id, predecessor and successor.


stabilize

public int stabilize()
Runs the process of stabilization while the network not has been stabilized. The number of steps that is running are undeterministic.

Returns:
Actual number of simulated steps after stabilization.

simulate

public boolean simulate()
Runs the process to simulate one time step. This process is composed for:
  1. Process all nodes one step.
  2. Send all messages generated at this moment.
  3. Remove specified nodes.


run

public int run(int steps)
Runs the process to simulate a total number of steps. This process is identical to the following code:
 for (int i=0; i < steps; i++) {
     simulate();
 }
 

Parameters:
steps - Number of steps to simulate.
Returns:
Number of actual stabilization steps after run steps steps.

getRandomNode

public Node getRandomNode(java.util.Random r)
Returns a randomly selected node of actual network.

Parameters:
r - Generator of random numbers.
Returns:
A node radomly selected.

existNode

public boolean existNode(NodeHandle node)
Inform if exist on the network one node with NodeHandle node.

Parameters:
node - NodeHandle of the node to be search.
Returns:
true if and only if exist one node with the same node NodeHandle.

getRandomApplication

public Application getRandomApplication(java.lang.String appId)
Gets a reference of some application on any node of the network.

Parameters:
appId - Application identification for searching it.
Returns:
A reference of an existing application on any node.

iterator

public java.util.Iterator iterator()
Gets an Iterator to get all nodes.

Returns:
An Iterator to iterate over nodes on the network.

getSimulatedSteps

public int getSimulatedSteps()
Gets the actual number of simulated steps.

Returns:
actual number of simulated steps.

getProximity

public int getProximity(NodeHandle nodeA,
                        NodeHandle nodeB)
Evaluates the proximity between the two nodes.

Returns:
The proximity between the two nodes.