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

   1 == Topology Processing Framework Developer Guide
   2
   3 === Overview
   4 Purpose of Topology processing framework is to allow developers to agregate and filter topologies according to defined correlations. It also provides functionality, which you can use to make your own topology model rendering (translation from one model to another, for example from inventory to pure network-topology).
   5
   6 === Topology Processing Framework Architecture
   7 Topology processing framework consists from several karaf features:
   8
   9 * odl-topoprocessing-framework
  10 * odl-topoprocessing-inventory
  11 * odl-topoprocessing-network-topology
  12 //* odl-topoprocessing-i2rs [TBD when i2rs will be merged to controller]
  13 * odl-topoprocessing-inventory-rendering
  14 * odl-topoprocessing-link-computation
  15
  16 Feature odl-topoprocessing-framework contains of topoprocessing-api, topoprocessing-spi and topoprocessing-impl
  17 bundles. This feature is the core of topology processing framework and is required by all others features.
  18
  19 * topoprocessing-api - contains correlation definitions and definitions required by rendering
  20 * topoprocessing-spi - entry point for topoprocessing service (start and close)
  21 * topoprocessing-impl - contains base implementation of handlers, listeners and aggregators
  22
  23 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.
  24
  25 === Aggregation and Filtration
  26
  27 ==== Terminology
  28 We use the term underlay item (Physical Node) for items (nodes, links, termination-points) from underlay and overlay item (Logical Node) for items from overlay topologies regardless of whether those are actually physical network elements.
  29
  30 ==== Introduction
  31 The Topology Processing Framework allows creation of aggregated topologies and filtered views over existing topologies. Currently, aggregation and filtration is supported for topologies that follow https://github.com/opendaylight/yangtools/blob/master/model/ietf/ietf-topology/src/main/yang/network-topology%402013-10-21.yang[network-topology] or opendaylight-inventory model. When a request to create aggregated or filtered topology is received, the framework creates one listener per underlay topology. Whenever any specified underlay topology is changed, appropriate listener is triggered with the change and the change is processed. Two types of correlations (functionalities) are currently supported:
  32
  33 * Aggregation
  34 ** Unification
  35 ** Equality
  36 * Filtration
  37 ** NodeIpFiltration
  38
  39 ==== Aggregation
  40 Aggregation is an operation which creates an aggregated item from two or more items in the underlay topology if the aggregation condition 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 item that the framework will check for equality.
  41
  42 ===== Create overlay node
  43 First, each new underlay item is inserted into proper topology store. Once the item is stored, the framework compares it (using the target field value) with all stored underlay items from underlay topologies. If there is a target-field match, a new overlay item is created containing pointers to all 'equal' underlay items. The reference to newly created overlay item is set into referenced underlay items.
  44
  45 .Equality case
  46 If a item doesn't fulfill the equality condition with any other items, processing finishes after adding the item into topology store. It will stay there, for future use, ready to create aggregated item with a new underlay item, with which it would satisfy condition to create overlay item.
  47
  48 .Unification case
  49 An overlay item is created for all underlay items, even those which don't fulfill the equality condition with any other items. This means than an overlay item is created for every underlay item, but for items which satisfy the equality condition, an aggregated item is created.
  50
  51 ===== Update node
  52 Processing of updated underlay items depends on whether the target field has been modified. If yes, then:
  53
  54 * if the underlay item belonged to some overlay item, it is removed from that item. Next, if the aggregation condition on target field is satisfied, the item is inserted into other overlay item. If the condition isn't met then:
  55 ** in equality case - the item will not be present in overlay topology.
  56 ** in unification case - the item will create overlay item with single underlay item and this will be written into overlay topology.
  57 * if the item didn't belong to some overlay item, it is checked again for aggregation with other underlay items.
  58
  59 ===== Remove node
  60 The underlay item is removed from corresponding topology store, from it's overlay item (if it belongs to one) and this way it is also removed from overlay topology.
  61
  62 .Equality case
  63 If there is only one underlay item left in the overlay item, the overlay item is removed.
  64
  65 .Unification case
  66 The overlay item is removed once it refers to no underlay item.
  67
  68 ==== Filtration
  69 Filtration is an operation which results in creation of overlay topology containing only items fulfilling conditions set in the topoprocessing request.
  70
  71 ===== Create undrelay item
  72 If created item passes all filtrators and their conditions, then it is stored in TopologyStore and creation notification is delivered into topology manager. No operation otherwise.
  73
  74 ===== Update underlay item
  75 If the item is checked for presence in topology store:
  76
  77 * if it is present in topology store:
  78 ** if item meets filtering conditions then processUpdatedData notification is triggered
  79 ** else processRemovedData notification is triggered
  80 * if item isn't present in topology store
  81 ** if item meets filtering conditions then processCreatedData notification is triggered
  82 ** else it is ignored
  83
  84 ===== Remove underlay item
  85 If underlay node is part of some overlay node, the overlay node is simply removed.
  86
  87 ===== Default filter types
  88 There are seven types of default filtrators defined in the framework:
  89
  90 * Ipv4-address filtrator - checks if specified field is meets ipv4 address + mask criteria
  91 * Ipv6-address filtrator - checks if specified field is meets ipv6 address + mask criteria
  92 * Specific number filtrator - check for specific number
  93 * Specific string filtrator - checks for specific string
  94 * Range number filtrator - checks if specified field is higher than provided minimum and lower than provided maximum
  95 * Range string filtrator - checks if specified field is alphabetically greater than provided minimum and alphabetically lower than provided maximum
  96 * Script filtrator - allows user / application to implement his own Filtrator
  97
  98 ===== Register custom filtrator
  99 There might be some usecase that can't get by with default filtrators. For this case the framework offers the possibility to register custom filtrator.
 100
 101 ==== Pre-filtration / filtration & aggregation
 102 This feature was introduced in order to lower memory and performance demands. Basically it is combination of filtration & aggregation operations. First, uninteresting items are filtered out and then aggregation is performed only on items that passed filtration. This way the framework saves on computer time. PreAggregationFiltrator and TopologyAggregator share the same TopoStoreProvider (and thus topology store) which results in lower memory demands (as underlay items are stored only in one topology store - they aren't stored twice).
 103
 104 === Wrapper, RPC republishing, writing mechanism
 105
 106 During the process of aggregation and filtration, overlay items (so called Logical Nodes) were created from underlay items (Physical Nodes). In topology manager, overlay items 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 items - which permits grouping of overlay items (into wrappers).
 107
 108 .Wrapper
 109 image::topoprocessing/wrapper.png[width=500]
 110
 111 PN1, PN2, PN3 = Physical Node
 112
 113 LN1, LN2 = Logical Node
 114
 115 ==== RPC republishing
 116 All RPC underlay items are re-registered under their corresponding wrapper ID. RPCs of underlay items (belonging to an overlay item) are gathered, and registered under ID of their wrapper.
 117
 118 ===== RPC Call
 119 When RPC is called on overlay item, this call is delegated to it's underlay items, it means this RPC is called on all underlay items of this overlay item.
 120
 121 ==== Writing mechanism
 122 When a wrapper (containing overlay item(s) with it's underlay item(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.
 123 In order to use resources responsibly, writing operation 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.
 124
 125 === Classes relationships
 126
 127 [1] TopologyRequestHandler instantiates TopologyWriter, TopologyManager. Then according to request initializes either TopologyAggregator or Topology filtrator.
 128
 129 [2] It creates as many instances of UnderlayTopologyListener as there are underlay topologies
 130
 131 [3] PhysicalNodes are created for relevant income nodes (those having node ID)
 132
 133 [4a] Performs aggregation and creates Logical Nodes
 134
 135 [4b] Performs filtration and creates Logical Nodes
 136
 137 [5] Logical Nodes are put into wrapper
 138
 139 [6] Wrapper is translated into adequate format and written into Datastore
 140
 141 .Class relationship
 142 image::topoprocessing/TopologyRequestHandler_classesRelationship.png[width=500]
 143
 144 === Key APIs and Interfaces
 145 Basic Provider class is TopoProcessingProvider which provides startup and shutdown
 146 methods. Otherwise the framework communicates via requests and outputs stored
 147 in DataStores.
 148
 149 //=== API Reference Documentation
 150 //Provide links to JavaDoc, REST API documentation, etc. [TBD]
 151
 152 === Model Specific Aproach
 153 Topology Processing Framework consists from several modules and karaf features, which provide support for different input models. Currently we support network-topology and opendaylight-inventory (we have also prepared support for i2rs once it will be supported by controller). For each of these input models, topoprocessing framework has one module and one Karaf feature.
 154
 155 ==== How it works
 156 .User point of view:
 157 When you start odl-topoprocessing-framework feature, Topology Processing Framework starts without knowledge how to work with any input model. In order to allow Topology Processing Framework to process some kind of input model, you have to install one (or more) model specific features (these features also start odl-topoprocessing-framework feature if it is not already running). These features inject appropriate logic into odl-topoprocessing-framework feature. From that point, Topology Processing Framework is able to process different kinds of input model (those you install features for).
 158
 159 .Developer point of view:
 160 Module topoprocessing-impl contains (among other things) classes and interfaces, which are common for every model specific topoprocessing module. These classes and interfaces are implemented and extended by classes in particular model specific module.
 161 Model specific modules have also one dependency from topoprocessing-spi module - TopoProcessingProvider class. This dependency is injected during installation of model specific feature in Karaf. When model specific feature is started, it calls registerAdapters(adapters) method of injected TopoProcessingProvider object. After this step, Topology Processing Framework is able to use registered model adapters to work with input models.
 162
 163 To achieve described functionality we created ModelAdapter interface. It represents installed feature and provides methods for creating crucial structures specific to each model.
 164
 165 .ModelAdapter interface
 166 image::topoprocessing/ModelAdapter.png[width=500]
 167
 168 ==== Features
 169
 170 * odl-topoprocessing-network-topology - this feature contains logic to work with network-topology model
 171 * odl-topoprocessing-inventory - this feature contains logic to work with network-topology model
 172
 173 === Link Computation
 174 include::odl-topoprocessing-link-computation-dev.adoc[]
 175
 176 === Topology Rendering Guide - Inventory Rendering
 177 include::odl-topoprocessing-inventory-rendering-dev.adoc[]