## org.apache.hadoop.net
Class NetworkTopology

    java.lang.Object
      org.apache.hadoop.net.NetworkTopology

Direct Known Subclasses:
  NetworkTopologyWithNodeGroup

    public class NetworkTopology

extends Object

The class represents a cluster of computer with a tree hierarchical network topology. For example, a cluster may be consists of many data centers filled with racks of computers. In a network topology, leaves represent data nodes (computers) and inner nodes represent switches/routers that manage traffic in/out of data centers or racks.

Nested Class Summary
`static class` `NetworkTopology.InvalidTopologyException`

Field Summary
`static int` `DEFAULT_HOST_LEVEL`
`static String` `DEFAULT_RACK`
`static org.apache.commons.logging.Log` `LOG`
`protected ReadWriteLock` `netlock`
`protected int` `numOfRacks`
`protected static Random` `r`

Constructor Summary
`NetworkTopology()`

Method Summary
`void` `add(Node node)` Add a leaf node Update node counter & rack counter if neccessary
`Node` `chooseRandom(String scope)` randomly choose one node from scope if scope starts with ~, choose one from the all nodes except for the ones in scope; otherwise, choose one from scope
`boolean` `contains(Node node)` Check if the tree contains node node
`int` `countNumOfAvailableNodes(String scope, Collection<Node> excludedNodes)` return the number of leaves in scope but not in excludedNodes if scope starts with ~, return the number of nodes that are not in scope and excludedNodes;
`int` `getDistance(Node node1, Node node2)` Return the distance between two nodes It is assumed that the distance from one node to its parent is 1 The distance between two nodes is calculated by summing up their distances to their closest common ancestor.
`static String` `getFirstHalf(String networkLocation)` Divide networklocation string into two parts by last separator, and get the first part here.
`static NetworkTopology` `getInstance(Configuration conf)` Get an instance of NetworkTopology based on the value of the configuration parameter net.topology.impl.
`static String` `getLastHalf(String networkLocation)` Divide networklocation string into two parts by last separator, and get the second part here.
`List<Node>` `getLeaves(String scope)` return leaves in scope
`Node` `getNode(String loc)` Given a string representation of a node, return its reference
`protected Node` `getNodeForNetworkLocation(Node node)` Return a reference to the node given its string representation.
`int` `getNumOfLeaves()` Return the total number of nodes
`int` `getNumOfRacks()` Return the total number of racks
`String` `getRack(String loc)` Given a string representation of a rack for a specific network location To be overridden in subclasses for specific NetworkTopology implementations, as alternative to overriding the full `getRack(String)` method.
`boolean` `isNodeGroupAware()` Check if network topology is aware of NodeGroup
`boolean` `isOnSameNodeGroup(Node node1, Node node2)` Return false directly as not aware of NodeGroup, to be override in sub-class
`boolean` `isOnSameRack(Node node1, Node node2)` Check if two nodes are on the same rack
`protected boolean` `isSameParents(Node node1, Node node2)` Compare the parents of each node for equality
`void` `pseudoSortByDistance(Node reader, Node[] nodes)` Sort nodes array by their distances to reader It linearly scans the array, if a local node is found, swap it with the first element of the array.
`void` `remove(Node node)` Remove a node Update node counter & rack counter if neccessary
`protected static void` `swap(Node[] nodes, int i, int j)`
`String` `toString()` convert a network tree to a string

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### DEFAULT_RACK

    public static final String DEFAULT_RACK

See Also:
  Constant Field Values

### DEFAULT_HOST_LEVEL

    public static final int DEFAULT_HOST_LEVEL

See Also:
  Constant Field Values

### LOG

    public static final org.apache.commons.logging.Log LOG

### numOfRacks

    protected int numOfRacks

### netlock

    protected ReadWriteLock netlock

### r

    protected static final Random r

Constructor Detail

### NetworkTopology

    public NetworkTopology()

Method Detail

### getInstance

    public static NetworkTopology getInstance(Configuration conf)

  Get an instance of NetworkTopology based on the value of the configuration parameter net.topology.impl.

  Parameters:
    `conf` - the configuration to be used
  Returns:
    an instance of NetworkTopology

### add

    public void add(Node node)

  Add a leaf node Update node counter & rack counter if neccessary

  Parameters:
    `node` - node to be added
  Throws:
    `IllegalArgumentException` - if add a node to a leave or node to be added is not a leaf

### getNodeForNetworkLocation

    protected Node getNodeForNetworkLocation(Node node)

  Return a reference to the node given its string representation. Default implementation delegates to `getNode(String)`.

  To be overridden in subclasses for specific NetworkTopology implementations, as alternative to overriding the full `add(Node)` method.

  Parameters:
    `node` - The string representation of this node's network location is used to retrieve a Node object.
  Returns:
    a reference to the node; null if the node is not in the tree
  See Also:
    `add(Node)`, `getNode(String)`

### remove

    public void remove(Node node)

  Remove a node Update node counter & rack counter if neccessary

  Parameters:
    `node` - node to be removed

### contains

    public boolean contains(Node node)

  Check if the tree contains node node

  Parameters:
    `node` - a node
  Returns:
    true if node is already in the tree; false otherwise

### getNode

    public Node getNode(String loc)

  Given a string representation of a node, return its reference

  Parameters:
    `loc` - a path-like string representation of a node
  Returns:
    a reference to the node; null if the node is not in the tree

### getRack

    public String getRack(String loc)

  Given a string representation of a rack for a specific network location To be overridden in subclasses for specific NetworkTopology implementations, as alternative to overriding the full `getRack(String)` method.

  Parameters:
    `loc` - a path-like string representation of a network location
  Returns:
    a rack string

### getNumOfRacks

    public int getNumOfRacks()

  Return the total number of racks

### getNumOfLeaves

    public int getNumOfLeaves()

  Return the total number of nodes

### getDistance

    public int getDistance(Node node1,
                           Node node2)

  Return the distance between two nodes It is assumed that the distance from one node to its parent is 1 The distance between two nodes is calculated by summing up their distances to their closest common ancestor.

  Parameters:
    `node1` - one node
    `node2` - another node
  Returns:
    the distance between node1 and node2 node1 or node2 do not belong to the cluster

### isOnSameRack

    public boolean isOnSameRack(Node node1,
                                Node node2)

  Check if two nodes are on the same rack

  Parameters:
    `node1` - one node
    `node2` - another node
  Returns:
    true if node1 and node2 are pm the same rack; false otherwise
  Throws:
    `IllegalArgumentException` - when either node1 or node2 is null, or node1 or node2 do not belong to the cluster

### isNodeGroupAware

    public boolean isNodeGroupAware()

  Check if network topology is aware of NodeGroup

### isOnSameNodeGroup

    public boolean isOnSameNodeGroup(Node node1,
                                     Node node2)

  Return false directly as not aware of NodeGroup, to be override in sub-class

### isSameParents

    protected boolean isSameParents(Node node1,
                                    Node node2)

  Compare the parents of each node for equality

  To be overridden in subclasses for specific NetworkTopology implementations, as alternative to overriding the full `isOnSameRack(Node, Node)` method.

  Parameters:
    `node1` - the first node to compare
    `node2` - the second node to compare
  Returns:
    true if their parents are equal, false otherwise
  See Also:
    `isOnSameRack(Node, Node)`

### chooseRandom

    public Node chooseRandom(String scope)

  randomly choose one node from scope if scope starts with ~, choose one from the all nodes except for the ones in scope; otherwise, choose one from scope

  Parameters:
    `scope` - range of nodes from which a node will be choosen
  Returns:
    the choosen node

### getLeaves

    public List<Node> getLeaves(String scope)

  return leaves in scope

  Parameters:
    `scope` - a path string
  Returns:
    leaves nodes under specific scope

### countNumOfAvailableNodes

    public int countNumOfAvailableNodes(String scope,
                                        Collection<Node> excludedNodes)

  return the number of leaves in scope but not in excludedNodes if scope starts with ~, return the number of nodes that are not in scope and excludedNodes;

  Parameters:
    `scope` - a path string that may start with ~
    `excludedNodes` - a list of nodes
  Returns:
    number of available nodes

### toString

    public String toString()

  convert a network tree to a string

  Overrides:
    `toString` in class `Object`

### getFirstHalf

    public static String getFirstHalf(String networkLocation)

  Divide networklocation string into two parts by last separator, and get the first part here.

  Parameters:
    `networkLocation` -
  Returns:

### getLastHalf

    public static String getLastHalf(String networkLocation)

  Divide networklocation string into two parts by last separator, and get the second part here.

  Parameters:
    `networkLocation` -
  Returns:

### swap

    protected static void swap(Node[] nodes,
                               int i,
                               int j)

### pseudoSortByDistance

    public void pseudoSortByDistance(Node reader,
                                     Node[] nodes)

  Sort nodes array by their distances to reader It linearly scans the array, if a local node is found, swap it with the first element of the array. If a local rack node is found, swap it with the first element following the local node. If neither local node or local rack node is found, put a random replica location at postion 0. It leaves the rest nodes untouched.

Copyright © 2009 The Apache Software Foundation