manuals/developer-guide/src/main/asciidoc/topoprocessing/odl-topoprocessing-framework-dev.adoc

   1 == Topology Processing Framework Developer Guide
   2
   3 === Overview
   4 TopoProcessingProvider is entry point for Topology Processing Framework. It requires DataBroker instance. DataBroker is needed for listener registrations. There is TopologyRequestListener which listens on aggregated topology requests (placed into configuration datastore) and UnderlayTopologyListeners which listen on underlay topology data changes (made in operational datastore). TopologyRequestHandler saves toporequest data and provides method for translating path to the specified leaf. When a change in topology occurs, registered UnderlayTopologyListener processes this information for further aggregation and/or filtration. Finally, after overlay topology is created, it is passed to TopologyWriter, which writes this topology into operational datastore.
   5
   6 === Topology Processing Framework Architecture
   7 Contains of topoprocessing-api, topoprocessing-spi and topoprocessing-impl
   8 bundles.
   9
  10 * topoprocessing-api - contains correlation definitions
  11 * topoprocessing-spi - entry point for topoprocessing service (start and close)
  12 * topoprocessing-impl - contains implemented handlers, listeners and aggregators
  13
  14 === Aggregation and Filtration
  15
  16 ==== Terminology
  17 We use the term Physical Node for nodes in the underlay and Logical Node for nodes in the overlay regardless of whether either is actually a physical network element.
  18
  19 ==== Introduction
  20 The Topology Processing Framework allows for the creation of aggregated topologies or filtered views of existing topologies. Currently aggregation and filtration of nodes is supported only for topologies augmenting the https://github.com/opendaylight/yangtools/blob/master/model/ietf/ietf-topology/src/main/yang/network-topology%402013-10-21.yang[topology YANG model]. When a request to build an aggregate or filtered topology is received, the framework creates one listener per underlay topology. Whenever any underlay topology changes, its listener is triggered the change is processed. Two types of correlations (functionalities) are currently supported:
  21
  22 * Aggregation
  23 ** Unification
  24 ** Equality
  25 * Filtration
  26 ** NodeIpFiltration
  27
  28 ==== Aggregation
  29 Aggregation is an operation which creates an aggregated node from two or more nodes in the underlay topology if the condition for doing so is fulfilled. Requests for aggregated topologies must specify a list of underlay topologies over which the overlay (aggregated) topology will be created and a target field in the underlay nodes that the framework will check for equality.
  30
  31 ===== Create overlay node
  32 First, each new underlay node is inserted into proper topology (specifically into topology store structure). Once notified of the new node, the framework compares it (using the target field value) with all existing nodes in the specified underlay topologies and if the equality condition is fulfilled, a new overlay node is created containing pointers to all 'equal' underlay nodes.
  33
  34 .Equality case
  35 In this case, if a node doesn't fulfill the equality condition with any other nodes, processing finishes after adding the node into topology store. It will stay there, for future use, ready to create aggregated node with a new underlay node, with which it would satisfy condition to create overlay node.
  36
  37 .Unification case
  38 In this case, an overlay node is created for all underlay nodes, even those which don't fulfill the equality condition with any other nodes. This means than an overlay node is created for every underlay node, but for nodes which satisfy the equality condition, an aggregated node is created.
  39
  40 ===== Update node
  41 Processing of updated underlay nodes depends on whether the target field has been modified. If this it has been, then:
  42
  43 * if the underlay node belonged to some overlay node, it is withdrawn from that node and then, if the condition of equality on target field is satisfied, it is inserted into another (possibly the same) overlay node.
  44 * if the node was a "singleton" node, it is put into overlay node, if the condition of equality is fulfilled on the new value of target field with some existing underlay node
  45
  46 .Unification case
  47 Every underlay node belongs to some overlay node. Either with some other underlay nodes when they have the same value of target field or otherwise there is one underlay node in an overlay node.
  48
  49 ===== Remove node
  50 The underlay node is removed from appertaining topology store and from it's overlay node if it belongs to one.
  51
  52 .Equality case
  53 If there is only one underlay node left in the overlay node, the overlay node is removed.
  54
  55 .Unification case
  56 In this case, it is allowed to have one underlay node in overlay node. However if this node is removed from its overlay node, the overlay node is removed.
  57
  58 ==== Filtration
  59 Filtration is an operation which results in creation of overlay topology containing only nodes fulfilling condition set in the request for creating this topology.
  60
  61 ===== NodeIpFiltration
  62 This is filtration is based on IP addresses. If a node's IP address fulfills mask set in the value tag of the request, this node is put into resulting overlay topology.
  63
  64 .Create node
  65 For a new node fulfilling IP address mask condition, this node is put into overlay node later written into datastore.
  66
  67 .Update node
  68 If IP address of filtered node has changed to value still fulfilling the mask's condition, a new overlay node is created and this updated node is inserted there. If the new IP address does not fit within the mask, the overlay node is simply removed.
  69
  70 .Remove node
  71 If underlay node is part of some overlay node, the overlay node is simply removed.
  72
  73 === Wrapper, RPC republishing, writing mechanism
  74
  75 During the process of aggregation and filtration, overlay nodes (so called Logical Nodes) were created from underlay nodes (Physical Nodes). In TopologyManager, overlay nodes are put into wrapper. A wrapper is identified with unique ID and contains list of Logical Nodes. Wrappers are used to deal with transitivity of underlay nodes - which permits grouping of overlay nodes (into wrappers).
  76
  77 .Class relationship
  78 image::topoprocessing/wrapper.png[width=500]
  79
  80 PN1, PN2, PN3 = Physical Node
  81
  82 LN1, LN2 = Logical Node
  83
  84 ==== RPC republishing
  85 All RPC underlay nodes are re-registered under their corresponding wrapper ID. RPCs of underlay nodes (belonging to an overlay node) are gathered, and registered under ID of their wrapper.
  86
  87 ===== RPC Call
  88 When RPC is called on overlay node, this call is delegated to it's underlay nodes, it means this RPC is called on all underlay nodes of this overlay node.
  89
  90 ==== Writing mechanism
  91 When a wrapper (containing overlay node(s) with it's underlay nodes(s)) is ready to be written into data store, it has to be converted into DOM format. After this translation is done, result is written into datastore. Physical nodes are stored as supporting-nodes.
  92 In order to use resources responsibly, writing is divided into two steps. First, a set of threads registers prepared operations (deletes and puts) and one thread makes actual write operation in batch.
  93
  94 === Classes relationships
  95
  96 [1] TopologyRequestHandler instantiates TopologyWriter, TopologyManager. Then according to request initializes either TopologyAggregator or Topology filtrator.
  97
  98 [2] It creates as many instances of UnderlayTopologyListener as there are underlay topologies
  99
 100 [3] PhysicalNodes are created for relevant income nodes (those having node ID)
 101
 102 [4a] Performs aggregation and creates Logical Nodes
 103
 104 [4b] Performs filtration and creates Logical Nodes
 105
 106 [5] Logical Nodes are put into wrapper
 107
 108 [6] Wrapper is translated into adequate format and written into Datastore
 109
 110 .Class relationship
 111 image::topoprocessing/TopologyRequestHandler_classesRelationship.png[width=500]
 112
 113 === Key APIs and Interfaces
 114 Basic Provider class is TopoProcessingProvider which provides startup and shutdown
 115 methods. Otherwise the framework communicates via requests and outputs stored
 116 in DataStores.
 117
 118 //=== API Reference Documentation
 119 //Provide links to JavaDoc, REST API documentation, etc. [TBD]