1 Topology Processing Framework Developer Guide
2 =============================================
7 The Topology Processing Framework allows developers to aggregate and
8 filter topologies according to defined correlations. It also provides
9 functionality, which you can use to make your own topology model by
10 automating the translation from one model to another. For example to
11 translate from the opendaylight-inventory model to only using the
12 network-topology model.
20 In this chapter we describe the architecture of the Topology Processing
21 Framework. In the first part, we provide information about available
22 features and basic class relationships. In the second part, we describe
23 our model specific approach, which is used to provide support for
29 The Topology Processing Framework consists of several Karaf features:
31 - odl-topoprocessing-framework
33 - odl-topoprocessing-inventory
35 - odl-topoprocessing-network-topology
37 - odl-topoprocessing-i2rs
39 - odl-topoprocessing-inventory-rendering
41 The feature odl-topoprocessing-framework contains the
42 topoprocessing-api, topoprocessing-spi and topoprocessing-impl bundles.
43 This feature is the core of the Topology Processing Framework and is
44 required by all others features.
46 - topoprocessing-api - contains correlation definitions and definitions
47 required for rendering
49 - topoprocessing-spi - entry point for topoprocessing service (start
52 - topoprocessing-impl - contains base implementations of handlers,
53 listeners, aggregators and filtrators
55 TopoProcessingProvider is the entry point for Topology Processing
56 Framework. It requires a DataBroker instance. The DataBroker is needed
57 for listener registration. There is also the TopologyRequestListener
58 which listens on aggregated topology requests (placed into the
59 configuration datastore) and UnderlayTopologyListeners which listen on
60 underlay topology data changes (made in operational datastore). The
61 TopologyRequestHandler saves toporequest data and provides a method for
62 translating a path to the specified leaf. When a change in the topology
63 occurs, the registered UnderlayTopologyListener processes this
64 information for further aggregation and/or filtration. Finally, after an
65 overlay topology is created, it is passed to the TopologyWriter, which
66 writes this topology into operational datastore.
68 .. figure:: ./images/topoprocessing/TopologyRequestHandler_classesRelationship.png
69 :alt: Class relationship
73 [1] TopologyRequestHandler instantiates TopologyWriter and
74 TopologyManager. Then, according to the request, initializes either
75 TopologyAggregator, TopologyFiltrator or LinkCalculator.
77 [2] It creates as many instances of UnderlayTopologyListener as there
78 are underlay topologies.
80 [3] PhysicalNodes are created for relevant incoming nodes (those having
83 [4a] It performs aggregation and creates logical nodes.
85 [4b] It performs filtration and creates logical nodes.
87 [4c] It performs link computation and creates links between logical
90 [5] Logical nodes are put into wrapper.
92 [6] The wrapper is translated into the appropriate format and written
95 Model Specific Approach
96 ~~~~~~~~~~~~~~~~~~~~~~~
98 The Topology Processing Framework consists of several modules and Karaf
99 features, which provide support for different input models. Currently we
100 support the network-topology, opendaylight-inventory and i2rs models.
101 For each of these input models, the Topology Processing Framework has
102 one module and one Karaf feature.
107 **User point of view:**
109 When you start the odl-topoprocessing-framework feature, the Topology
110 Processing Framework starts without knowledge how to work with any input
111 models. In order to allow the Topology Processing Framework to process
112 some kind of input model, you must install one (or more) model specific
113 features. Installing these features will also start
114 odl-topoprocessing-framework feature if it is not already running. These
115 features inject appropriate logic into the odl-topoprocessing-framework
116 feature. From that point, the Topology Processing Framework is able to
117 process different kinds of input models, specifically those that you
118 install features for.
120 **Developer point of view:**
122 The topoprocessing-impl module contains (among other things) classes and
123 interfaces, which are common for every model specific topoprocessing
124 module. These classes and interfaces are implemented and extended by
125 classes in particular model specific modules. Model specific modules
126 also depend on the TopoProcessingProvider class in the
127 topoprocessing-spi module. This dependency is injected during
128 installation of model specific features in Karaf. When a model specific
129 feature is started, it calls the registerAdapters(adapters) method of
130 the injected TopoProcessingProvider object. After this step, the
131 Topology Processing Framework is able to use registered model adapters
132 to work with input models.
134 To achieve the described functionality we created a ModelAdapter
135 interface. It represents installed feature and provides methods for
136 creating crucial structures specific to each model.
138 .. figure:: ./images/topoprocessing/ModelAdapter.png
139 :alt: ModelAdapter interface
141 ModelAdapter interface
143 Model Specific Features
144 ^^^^^^^^^^^^^^^^^^^^^^^
146 - odl-topoprocessing-network-topology - this feature contains logic to
147 work with network-topology model
149 - odl-topoprocessing-inventory - this feature contains logic to work
150 with opendaylight-inventory model
152 - odl-topoprocessing-i2rs - this feature contains logic to work with
155 Inventory Model Support
156 ~~~~~~~~~~~~~~~~~~~~~~~
158 The opendaylight-inventory model contains only nodes, termination
159 points, information regarding these structures. This model co-operates
160 with network-topology model, where other topology related information is
161 stored. This means that we have to handle two input models at once. To
162 support the inventory model, InventoryListener and
163 NotificationInterConnector classes were introduced. Please see the flow
166 .. figure:: ./images/topoprocessing/Network_topology_model_flow_diagram.png
167 :alt: Network topology model
169 Network topology model
171 .. figure:: ./images/topoprocessing/Inventory_model_listener_diagram.png
172 :alt: Inventory model
176 Here we can see the InventoryListener and NotificationInterConnector
177 classes. InventoryListener listens on data changes in the inventory
178 model and passes these changes wrapped as an UnderlayItem for further
179 processing to NotificationInterConnector. It doesn’t contain node
180 information - it contains a leafNode (node based on which aggregation
181 occurs) instead. The node information is stored in the topology model,
182 where UnderlayTopologyListener is registered as usual. This listener
183 delivers the missing information.
185 Then the NotificationInterConnector combines the two notifications into
186 a complete UnderlayItem (no null values) and delivers this UnderlayItem
187 for further processing (to next TopologyOperator).
189 Aggregation and Filtration
190 --------------------------
195 The Topology Processing Framework allows the creation of aggregated
196 topologies and filtered views over existing topologies. Currently,
197 aggregation and filtration is supported for topologies that follow
198 `network-topology <https://github.com/opendaylight/yangtools/blob/master/model/ietf/ietf-topology/src/main/yang/network-topology%402013-10-21.yang>`__,
199 opendaylight-inventory or i2rs model. When a request to create an
200 aggregated or filtered topology is received, the framework creates one
201 listener per underlay topology. Whenever any specified underlay topology
202 is changed, the appropriate listener is triggered with the change and
203 the change is processed. Two types of correlations (functionalities) are
217 We use the term underlay item (physical node) for items (nodes, links,
218 termination-points) from underlay and overlay item (logical node) for
219 items from overlay topologies regardless of whether those are actually
220 physical network elements.
225 Aggregation is an operation which creates an aggregated item from two or
226 more items in the underlay topology if the aggregation condition is
227 fulfilled. Requests for aggregated topologies must specify a list of
228 underlay topologies over which the overlay (aggregated) topology will be
229 created and a target field in the underlay item that the framework will
235 First, each new underlay item is inserted into the proper topology
236 store. Once the item is stored, the framework compares it (using the
237 target field value) with all stored underlay items from underlay
238 topologies. If there is a target-field match, a new overlay item is
239 created containing pointers to all *equal* underlay items. The newly
240 created overlay item is also given new references to its supporting
245 If an item doesn’t fulfill the equality condition with any other items,
246 processing finishes after adding the item into topology store. It will
247 stay there for future use, ready to create an aggregated item with a new
248 underlay item, with which it would satisfy the equality condition.
250 **Unification case:**
252 An overlay item is created for all underlay items, even those which
253 don’t fulfill the equality condition with any other items. This means
254 that an overlay item is created for every underlay item, but for items
255 which satisfy the equality condition, an aggregated item is created.
260 Processing of updated underlay items depends on whether the target field
261 has been modified. If yes, then:
263 - if the underlay item belonged to some overlay item, it is removed
264 from that item. Next, if the aggregation condition on the target
265 field is satisfied, the item is inserted into another overlay item.
266 If the condition isn’t met then:
268 - in equality case - the item will not be present in overlay
271 - in unification case - the item will create an overlay item with a
272 single underlay item and this will be written into overlay
275 - if the item didn’t belong to some overlay item, it is checked again
276 for aggregation with other underlay items.
281 The underlay item is removed from the corresponding topology store, from
282 it’s overlay item (if it belongs to one) and this way it is also removed
283 from overlay topology.
287 If there is only one underlay item left in the overlay item, the overlay
290 **Unification case:**
292 The overlay item is removed once it refers to no underlay item.
297 Filtration is an operation which results in creation of overlay topology
298 containing only items fulfilling conditions set in the topoprocessing
304 If a newly created underlay item passes all filtrators and their
305 conditions, then it is stored in topology store and a creation
306 notification is delivered into topology manager. No operation otherwise.
311 First, the updated item is checked for presence in topology store:
313 - if it is present in topology store:
315 - if it meets the filtering conditions, then processUpdatedData
316 notification is triggered
318 - else processRemovedData notification is triggered
320 - if item isn’t present in topology store
322 - if item meets filtering conditions, then processCreatedData
323 notification is triggered
330 If an underlay node is supporting some overlay node, the overlay node is
333 Default Filtrator Types
334 ^^^^^^^^^^^^^^^^^^^^^^^
336 There are seven types of default filtrators defined in the framework:
338 - IPv4-address filtrator - checks if specified field meets IPv4 address
341 - IPv6-address filtrator - checks if specified field meets IPv6 address
344 - Specific number filtrator - checks for specific number
346 - Specific string filtrator - checks for specific string
348 - Range number filtrator - checks if specified field is higher than
349 provided minimum (inclusive) and lower than provided maximum
352 - Range string filtrator - checks if specified field is alphabetically
353 greater than provided minimum (inclusive) and alphabetically lower
354 than provided maximum (inclusive)
356 - Script filtrator - allows a user or application to implement their
359 Register Custom Filtrator
360 ^^^^^^^^^^^^^^^^^^^^^^^^^
362 There might be some use case that cannot be achieved with the default
363 filtrators. In these cases, the framework offers the possibility for a
364 user or application to register a custom filtrator.
366 Pre-Filtration / Filtration & Aggregation
367 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
369 This feature was introduced in order to lower memory and performance
370 demands. It is a combination of the filtration and aggregation
371 operations. First, uninteresting items are filtered out and then
372 aggregation is performed only on items that passed filtration. This way
373 the framework saves on compute time. The PreAggregationFiltrator and
374 TopologyAggregator share the same TopoStoreProvider (and thus topology
375 store) which results in lower memory demands (as underlay items are
376 stored only in one topology store - they aren’t stored twice).
384 While processing the topology request, we create overlay nodes with
385 lists of supporting underlay nodes. Because these overlay nodes have
386 completely new identifiers, we lose link information. To regain this
387 link information, we provide Link Computation functionality. Its main
388 purpose is to create new overlay links based on the links from the
389 underlay topologies and underlay items from overlay items. The required
390 information for Link Computation is provided via the Link Computation
392 (`topology-link-computation.yang <https://git.opendaylight.org/gerrit/gitweb?p=topoprocessing.git;a=blob;f=topoprocessing-api/src/main/yang/topology-link-computation.yang;hb=refs/heads/stable/boron>`__).
394 Link Computation Functionality
395 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
397 Let us consider two topologies with following components:
407 - Link: ``link:1:1`` (from ``node:1:1`` to ``node:1:2``)
409 - Link: ``link:1:2`` (from ``node:1:3`` to ``node:1:2``)
419 - Link: ``link:2:1`` (from ``node:2:1`` to ``node:2:3``)
421 Now let’s say that we applied some operations over these topologies that
422 results into aggregating together
424 - ``node:1:1`` and ``node:2:3`` (``node:1``)
426 - ``node:1:2`` and ``node:2:2`` (``node:2``)
428 - ``node:1:3`` and ``node:2:1`` (``node:3``)
430 At this point we can no longer use available links in new topology
431 because of the node ID change, so we must create new overlay links with
432 source and destination node set to new nodes IDs. It means that
433 ``link:1:1`` from topology 1 will create new link ``link:1``. Since
434 original source (``node:1:1``) is already aggregated under ``node:1``,
435 it will become source node for ``link:1``. Using same method the
436 destination will be ``node:2``. And the final output will be three
439 - ``link:1``, from ``node:1`` to ``node:2``
441 - ``link:2``, from ``node:3`` to ``node:2``
443 - ``link:3``, from ``node:3`` to ``node:1``
445 .. figure:: ./images/topoprocessing/LinkComputation.png
446 :alt: Overlay topology with computed links
448 Overlay topology with computed links
453 The main logic behind Link Computation is executed in the LinkCalculator
454 operator. The required information is passed to LinkCalculator through
455 the LinkComputation section of the topology request. This section is
456 defined in the topology-link-computation.yang file. The main logic also
457 covers cases when some underlay nodes may not pass through other
460 Link Computation Model
461 ^^^^^^^^^^^^^^^^^^^^^^
463 There are three essential pieces of information for link computations.
464 All of them are provided within the LinkComputation section. These
473 base topo-corr:model;
475 description "Desired output model for computed links.";
478 - overlay topology with new nodes
482 container node-info {
486 description "Topology that contains aggregated nodes.
487 This topology will be used for storing computed links.";
489 uses topo-corr:input-model-grouping;
492 - underlay topologies with original links
497 key "link-topology input-model";
501 description "Topology that contains underlay (base) links.";
503 leaf aggregated-links {
505 description "Defines if link computation should be based on supporting-links.";
507 uses topo-corr:input-model-grouping;
510 This whole section is augmented into ``network-topology:topology``. By
511 placing this section out of correlations section, it allows us to send
512 link computation request separately from topology operations request.
517 Taking into consideration that some of the underlay nodes may not
518 transform into overlay nodes (e.g. they are filtered out), we created
519 two possible states for links:
521 - matched - a link is considered as matched when both original source
522 and destination node were transformed to overlay nodes
524 - waiting - a link is considered as waiting if original source,
525 destination or both nodes are missing from the overlay topology
527 All links in waiting the state are stored in waitingLinks list, already
528 matched links are stored in matchedLinks list and overlay nodes are
529 stored in the storedOverlayNodes list. All processing is based only on
530 information in these lists. Processing created, updated and removed
531 underlay items is slightly different and described in next sections
534 **Processing Created Items**
536 Created items can be either nodes or links, depending on the type of
537 listener from which they came. In the case of a link, it is immediately
538 added to waitingLinks and calculation for possible overlay link
539 creations (calculatePossibleLink) is started. The flow diagram for this
540 process is shown in the following picture:
542 .. figure:: ./images/topoprocessing/LinkComputationFlowDiagram.png
543 :alt: Flow diagram of processing created items
545 Flow diagram of processing created items
547 Searching for the source and destination nodes in the
548 calculatePossibleLink method runs over each node in storedOverlayNodes
549 and the IDs of each supporting node is compared against IDs from the
550 underlay link’s source and destination nodes. If there are any nodes
551 missing, the link remains in the waiting state. If both the source and
552 destination nodes are found, the corresponding overlay nodes is recorded
553 as the new source and destination. The link is then removed from
554 waitingLinks and a new CalculatedLink is added to the matched links. At
555 the end, the new link (if it exists) is written into the datastore.
557 If the created item is an overlayNode, this is added to
558 storedOverlayNodes and we call calculatePossibleLink for every link in
561 **Processing Updated Items**
563 The difference from processing created items is that we have three
564 possible types of updated items: overlay nodes, waiting underlay links,
565 and matched underlay links.
567 - In the case of a change in a matched link, this must be recalculated
568 and based on the result it will either be matched with new source and
569 destination or will be returned to waiting links. If the link is
570 moved back to a waiting state, it must also be removed from the
573 - In the case of change in a waiting link, it is passed to the
574 calculation process and based on the result will either remain in
575 waiting state or be promoted to the matched state.
577 - In the case of a change in an overlay node, storedOverlayNodes must
578 be updated properly and all links must be recalculated in case of
581 **Processing Removed items**
583 Same as for processing updated item. There can be three types of removed
586 - In case of waiting link removal, the link is just removed from
589 - In case of matched link removal, the link is removed from
590 matchingLinks and datastore
592 - In case of overlay node removal, the node must be removed form
593 storedOverlayNodes and all matching links must be recalculated
595 Wrapper, RPC Republishing, Writing Mechanism
596 --------------------------------------------
601 During the process of aggregation and filtration, overlay items (so
602 called logical nodes) were created from underlay items (physical nodes).
603 In the topology manager, overlay items are put into a wrapper. A wrapper
604 is identified with unique ID and contains list of logical nodes.
605 Wrappers are used to deal with transitivity of underlay items - which
606 permits grouping of overlay items (into wrappers).
608 .. figure:: ./images/topoprocessing/wrapper.png
613 PN1, PN2, PN3 = physical nodes
615 LN1, LN2 = logical nodes
620 All RPCs registered to handle underlay items are re-registered under
621 their corresponding wrapper ID. RPCs of underlay items (belonging to an
622 overlay item) are gathered, and registered under ID of their wrapper.
627 When RPC is called on overlay item, this call is delegated to it’s
628 underlay items, this means that the RPC is called on all underlay items
629 of this overlay item.
634 When a wrapper (containing overlay item(s) with it’s underlay item(s))
635 is ready to be written into data store, it has to be converted into DOM
636 format. After this translation is done, the result is written into
637 datastore. Physical nodes are stored as supporting-nodes. In order to
638 use resources responsibly, writing operation is divided into two steps.
639 First, a set of threads registers prepared operations (deletes and puts)
640 and one thread makes actual write operation in batch.
642 Topology Rendering Guide - Inventory Rendering
643 ----------------------------------------------
648 In the most recent OpenDaylight release, the opendaylight-inventory
649 model is marked as deprecated. To facilitate migration from it to the
650 network-topology model, there were requests to render (translate) data
651 from inventory model (whether augmented or not) to another model for
652 further processing. The Topology Processing Framework was extended to
653 provide this functionality by implementing several rendering-specific
654 classes. This chapter is a step-by-step guide on how to implement your
655 own topology rendering using our inventory rendering as an example.
660 For the purpose of this guide we are going to render the following
661 augmented fields from the OpenFlow model:
663 - from inventory node:
677 - from inventory node-connector:
687 We also want to preserve the node ID and termination-point ID from
688 opendaylight-topology-inventory model, which is network-topology part of
694 There are two ways to implement support for your specific topology
697 - add a module to your project that depends on the Topology Processing
700 - add a module to the Topology Processing Framework itself
702 Regardless, a successful implementation must complete all of the
705 Step1 - Target Model Creation
706 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
708 Because the network-topology node does not have fields to store all
709 desired data, it is necessary to create new model to render this extra
710 data in to. For this guide we created the inventory-rendering model. The
711 picture below shows how data will be rendered and stored.
713 .. figure:: ./images/topoprocessing/Inventory_Rendering_Use_case.png
714 :alt: Rendering to the inventory-rendering model
716 Rendering to the inventory-rendering model
720 When implementing your version of the topology-rendering model in
721 the Topology Processing Framework, the source file of the model
722 (.yang) must be saved in /topoprocessing-api/src/main/yang folder so
723 corresponding structures can be generated during build and can be
724 accessed from every module through dependencies.
726 When the target model is created you have to add an identifier through
727 which you can set your new model as output model. To do that you have to
728 add another identity item to topology-correlation.yang file. For our
729 inventory-rendering model identity looks like this:
733 identity inventory-rendering-model {
734 description "inventory-rendering.yang";
738 After that you will be able to set inventory-rendering-model as output
741 Step2 - Module and Feature Creation
742 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
746 This and following steps are based on the `model specific
747 approach <#_model_specific_approach>`__ in the Topology Processing
748 Framework. We highly recommend that you familiarize yourself with
749 this approach in advance.
751 To create a base module and add it as a feature to Karaf in the Topology
752 Processing Framework we made the changes in following
753 `commit <https://git.opendaylight.org/gerrit/#/c/26223/>`__. Changes in
754 other projects will likely be similar.
756 +--------------------------------------+--------------------------------------+
758 +======================================+======================================+
759 | pom.xml | add new module to topoprocessing |
760 +--------------------------------------+--------------------------------------+
761 | features.xml | add feature to topoprocessing |
762 +--------------------------------------+--------------------------------------+
763 | features/pom.xml | add dependencies needed by features |
764 +--------------------------------------+--------------------------------------+
765 | topoprocessing-artifacts/pom.xml | add artifact |
766 +--------------------------------------+--------------------------------------+
767 | topoprocessing-config/pom.xml | add configuration file |
768 +--------------------------------------+--------------------------------------+
769 | 81-topoprocessing-inventory-renderin | configuration file for new module |
771 +--------------------------------------+--------------------------------------+
772 | topoprocessing-inventory-rendering/p | main pom for new module |
774 +--------------------------------------+--------------------------------------+
775 | TopoProcessingProviderIR.java | contains startup method which |
776 | | register new model adapter |
777 +--------------------------------------+--------------------------------------+
778 | TopoProcessingProviderIRModule.java | generated class which contains |
779 | | createInstance method. You should |
780 | | call your startup method from here. |
781 +--------------------------------------+--------------------------------------+
782 | TopoProcessingProviderIRModuleFactor | generated class. You will probably |
783 | y.java | not need to edit this file |
784 +--------------------------------------+--------------------------------------+
785 | log4j.xml | configuration file for logger |
786 | | topoprocessing-inventory-rendering-p |
787 | | rovider-impl.yang |
788 +--------------------------------------+--------------------------------------+
790 Step3 - Module Adapters Creation
791 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
793 There are seven mandatory interfaces or abstract classes that needs to
794 be implemented in each module. They are:
796 - TopoProcessingProvider - provides module registration
798 - ModelAdapter - provides model specific instances
800 - TopologyRequestListener - listens on changes in the configuration
803 - TopologyRequestHandler - processes configuration datastore changes
805 - UnderlayTopologyListener - listens for changes in the specific model
807 - LinkTransaltor and NodeTranslator - used by OverlayItemTranslator to
808 create NormalizedNodes from OverlayItems
810 The name convention we used was to add an abbreviation for the specific
811 model to the beginning of implementing class name (e.g. the
812 IRModelAdapter refers to class which implements ModelAdapter in module
813 Inventory Rendering). In the case of the provider class, we put the
814 abbreviation at the end.
818 - In the next sections, we use the terms TopologyRequestListener,
819 TopologyRequestHandler, etc. without a prepended or appended
820 abbreviation because the steps apply regardless of which specific
821 model you are targeting.
823 - If you want to implement rendering from inventory to
824 network-topology, you can just copy-paste our module and
825 additional changes will be required only in the output part.
829 This part is the starting point of the whole module. It is responsible
830 for creating and registering TopologyRequestListeners. It is necessary
831 to create three classes which will import:
833 - **TopoProcessingProviderModule** - is a generated class from
834 topoprocessing-inventory-rendering-provider-impl.yang (created in
835 previous step, file will appear after first build). Its method
836 ``createInstance()`` is called at the feature start and must be
837 modified to create an instance of TopoProcessingProvider and call its
838 ``startup(TopoProcessingProvider topoProvider)`` function.
840 - **TopoProcessingProvider** - in
841 ``startup(TopoProcessingProvider topoProvider)`` function provides
842 ModelAdapter registration to TopoProcessingProviderImpl.
844 - **ModelAdapter** - provides creation of corresponding module specific
849 This includes the creation of the classes responsible for input data
850 processing. In this case, we had to create five classes implementing:
852 - **TopologyRequestListener** and **TopologyRequestHandler** - when
853 notified about a change in the configuration datastore, verify if the
854 change contains a topology request (has correlations in it) and
855 creates UnderlayTopologyListeners if needed. The implementation of
856 these classes will differ according to the model in which are
857 correlations saved (network-topology or i2rs). In the case of using
858 network-topology, as the input model, you can use our classes
859 IRTopologyRequestListener and IRTopologyRequestHandler.
861 - **UnderlayTopologyListener** - registers underlay listeners according
862 to input model. In our case (listening in the inventory model), we
863 created listeners for the network-topology model and inventory model,
864 and set the NotificationInterConnector as the first operator and set
865 the IRRenderingOperator as the second operator (after
866 NotificationInterConnector). Same as for
867 TopologyRequestListener/Handler, if you are rendering from the
868 inventory model, you can use our class IRUnderlayTopologyListener.
870 - **InventoryListener** - a new implementation of this class is
871 required only for inventory input model. This is because the
872 InventoryListener from topoprocessing-impl requires pathIdentifier
873 which is absent in the case of rendering.
875 - **TopologyOperator** - replaces classic topoprocessing operator.
876 While the classic operator provides specific operations on topology,
877 the rendering operator just wraps each received UnderlayItem to
878 OverlayItem and sends them to write.
882 For purposes of topology rendering from inventory to
883 network-topology, there are misused fields in UnderlayItem as
886 - item - contains node from network-topology part of inventory
888 - leafItem - contains node from inventory
890 In case of implementing UnderlayTopologyListener or
891 InventoryListener you have to carefully adjust UnderlayItem creation
896 The output part of topology rendering is responsible for translating
897 received overlay items to normalized nodes. In the case of inventory
898 rendering, this is where node information from inventory are combined
899 with node information from network-topology. This combined information
900 is stored in our inventory-rendering model normalized node and passed to
903 The output part consists of two translators implementing the
904 NodeTranslator and LinkTranslator interfaces.
906 **NodeTranslator implementation** - The NodeTranslator interface has one
907 ``translate(OverlayItemWrapper wrapper)`` method. For our purposes,
908 there is one important thing in wrapper - the list of OverlayItems which
909 have one or more common UnderlayItems. Regardless of this list, in the
910 case of rendering it will always contains only one OverlayItem. This
911 item has list of UnderlayItems, but again in case of rendering there
912 will be only one UnderlayItem item in this list. In NodeTranslator, the
913 OverlayItem and corresponding UnderlayItem represent nodes from the
916 The UnderlayItem has several attributes. How you will use these
917 attributes in your rendering is up to you, as you create this item in
918 your topology operator. For example, as mentioned above, in our
919 inventory rendering example is an inventory node normalized node stored
920 in the UnderlayItem leafNode attribute, and we also store node-id from
921 network-topology model in UnderlayItem itemId attribute. You can now use
922 these attributes to build a normalized node for your new model. How to
923 read and create normalized nodes is out of scope of this document.
925 **LinkTranslator implementation** - The LinkTranslator interface also
926 has one ``translate(OverlayItemWrapper wrapper)`` method. In our
927 inventory rendering this method returns ``null``, because the inventory
928 model doesn’t have links. But if you also need links, this is the place
929 where you should translate it into a normalized node for your model. In
930 LinkTranslator, the OverlayItem and corresponding UnderlayItem represent
931 links from the translating model. As in NodeTranslator, there will be
932 only one OverlayItem and one UnderlayItem in the corresponding lists.
937 If you want to test topoprocessing with some manually created underlay
938 topologies (like in this guide), than you have to tell Topoprocessing
939 to listen for underlay topologies on Configuration datastore
940 instead of Operational.
942 | You can do this in this config file
943 | ``<topoprocessing_directory>/topoprocessing-config/src/main/resources/80-topoprocessing-config.xml``.
944 | Here you have to change
945 | ``<datastore-type>OPERATIONAL</datastore-type>``
947 | ``<datastore-type>CONFIGURATION</datastore-type>``.
950 Also you have to add dependency required to test "inventory" topologies.
952 | In ``<topoprocessing_directory>/features/pom.xml``
953 | add ``<openflowplugin.version>latest_snapshot</openflowplugin.version>``
954 to properties section
955 | and add this dependency to dependencies section
960 <groupId>org.opendaylight.openflowplugin</groupId>
961 <artifactId>features-openflowplugin</artifactId>
962 <version>${openflowplugin.version}</version>
963 <classifier>features</classifier><type>xml</type>
966 ``latest_snapshot`` in ``<openflowplugin.version>`` replace with latest snapshot, which can be found `here <https://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/openflowplugin/openflowplugin/>`__.
968 | And in ``<topoprocessing_directory>/features/src/main/resources/features.xml``
969 | add ``<repository>mvn:org.opendaylight.openflowplugin/features-openflowplugin/${openflowplugin.version}/xml/features</repository>``
970 to repositories section.
972 Now after you rebuild project and start Karaf, you can install necessary features.
974 | You can install all with one command:
975 | ``feature:install odl-restconf-noauth odl-topoprocessing-inventory-rendering odl-openflowplugin-southbound odl-openflowplugin-nsf-model``
977 Now you can send messages to REST from any REST client (e.g. Postman in
978 Chrome). Messages have to have following headers:
980 +--------------------------------------+--------------------------------------+
982 +======================================+======================================+
983 | Content-Type: | application/xml |
984 +--------------------------------------+--------------------------------------+
985 | Accept: | application/xml |
986 +--------------------------------------+--------------------------------------+
987 | username: | admin |
988 +--------------------------------------+--------------------------------------+
989 | password: | admin |
990 +--------------------------------------+--------------------------------------+
992 Firstly send topology request to
993 http://localhost:8181/restconf/config/network-topology:network-topology/topology/render:1
994 with method PUT. Example of simple rendering request:
998 <topology xmlns="urn:TBD:params:xml:ns:yang:network-topology">
999 <topology-id>render:1</topology-id>
1000 <correlations xmlns="urn:opendaylight:topology:correlation" >
1001 <output-model>inventory-rendering-model</output-model>
1003 <correlation-id>1</correlation-id>
1004 <type>rendering-only</type>
1005 <correlation-item>node</correlation-item>
1007 <underlay-topology>und-topo:1</underlay-topology>
1013 This request says that we want create topology with name render:1 and
1014 this topology should be stored in the inventory-rendering-model and it
1015 should be created from topology flow:1 by node rendering.
1017 Next we send the network-topology part of topology flow:1. So to the URL
1018 http://localhost:8181/restconf/config/network-topology:network-topology/topology/und-topo:1
1023 <topology xmlns="urn:TBD:params:xml:ns:yang:network-topology"
1024 xmlns:it="urn:opendaylight:model:topology:inventory"
1025 xmlns:i="urn:opendaylight:inventory">
1026 <topology-id>und-topo:1</topology-id>
1028 <node-id>openflow:1</node-id>
1029 <it:inventory-node-ref>
1030 /i:nodes/i:node[i:id="openflow:1"]
1031 </it:inventory-node-ref>
1034 <it:inventory-node-connector-ref>
1035 /i:nodes/i:node[i:id="openflow:1"]/i:node-connector[i:id="openflow:1:1"]
1036 </it:inventory-node-connector-ref>
1037 </termination-point>
1041 And the last input will be inventory part of topology. To the URL
1042 http://localhost:8181/restconf/config/opendaylight-inventory:nodes we
1048 xmlns="urn:opendaylight:inventory">
1052 <id>openflow:1:1</id>
1054 xmlns="urn:opendaylight:flow:inventory">1
1057 xmlns="urn:opendaylight:flow:inventory">10000000
1060 xmlns="urn:opendaylight:flow:inventory">s1-eth1
1063 xmlns="urn:opendaylight:flow:inventory">
1066 xmlns="urn:opendaylight:flow:inventory">copper ten-gb-fd
1069 xmlns="urn:opendaylight:flow:inventory">
1072 xmlns="urn:opendaylight:flow:inventory">
1075 xmlns="urn:opendaylight:flow:inventory">0
1077 <advertised-features
1078 xmlns="urn:opendaylight:flow:inventory">
1079 </advertised-features>
1081 xmlns="urn:opendaylight:flow:inventory">0E:DC:8C:63:EC:D1
1084 xmlns="urn:opendaylight:flow:inventory">
1085 <link-down>false</link-down>
1086 <blocked>false</blocked>
1089 <flow-capable-node-connector-statistics
1090 xmlns="urn:opendaylight:port:statistics">
1091 <receive-errors>0</receive-errors>
1092 <receive-frame-error>0</receive-frame-error>
1093 <receive-over-run-error>0</receive-over-run-error>
1094 <receive-crc-error>0</receive-crc-error>
1096 <transmitted>595</transmitted>
1097 <received>378</received>
1099 <receive-drops>0</receive-drops>
1102 <nanosecond>410000000</nanosecond>
1104 <transmit-errors>0</transmit-errors>
1105 <collision-count>0</collision-count>
1107 <transmitted>7</transmitted>
1108 <received>5</received>
1110 <transmit-drops>0</transmit-drops>
1111 </flow-capable-node-connector-statistics>
1114 <id>openflow:1:LOCAL</id>
1116 xmlns="urn:opendaylight:flow:inventory">4294967294
1119 xmlns="urn:opendaylight:flow:inventory">0
1122 xmlns="urn:opendaylight:flow:inventory">s1
1125 xmlns="urn:opendaylight:flow:inventory">
1128 xmlns="urn:opendaylight:flow:inventory">
1131 xmlns="urn:opendaylight:flow:inventory">
1134 xmlns="urn:opendaylight:flow:inventory">
1137 xmlns="urn:opendaylight:flow:inventory">0
1139 <advertised-features
1140 xmlns="urn:opendaylight:flow:inventory">
1141 </advertised-features>
1143 xmlns="urn:opendaylight:flow:inventory">BA:63:87:0C:76:41
1146 xmlns="urn:opendaylight:flow:inventory">
1147 <link-down>false</link-down>
1148 <blocked>false</blocked>
1151 <flow-capable-node-connector-statistics
1152 xmlns="urn:opendaylight:port:statistics">
1153 <receive-errors>0</receive-errors>
1154 <receive-frame-error>0</receive-frame-error>
1155 <receive-over-run-error>0</receive-over-run-error>
1156 <receive-crc-error>0</receive-crc-error>
1158 <transmitted>576</transmitted>
1159 <received>468</received>
1161 <receive-drops>0</receive-drops>
1164 <nanosecond>426000000</nanosecond>
1166 <transmit-errors>0</transmit-errors>
1167 <collision-count>0</collision-count>
1169 <transmitted>6</transmitted>
1170 <received>6</received>
1172 <transmit-drops>0</transmit-drops>
1173 </flow-capable-node-connector-statistics>
1176 xmlns="urn:opendaylight:flow:inventory">None
1179 xmlns="urn:opendaylight:flow:inventory">Nicira, Inc.
1182 xmlns="urn:opendaylight:flow:inventory">Open vSwitch
1185 xmlns="urn:opendaylight:flow:inventory">2.1.3
1188 xmlns="urn:opendaylight:flow:inventory">None
1191 xmlns="urn:opendaylight:flow:inventory">10.20.30.40
1194 xmlns="urn:opendaylight:meter:statistics">
1195 <max_bands>0</max_bands>
1196 <max_color>0</max_color>
1197 <max_meter>0</max_meter>
1200 xmlns="urn:opendaylight:group:statistics">
1201 <group-capabilities-supported
1202 xmlns:x="urn:opendaylight:group:types">x:chaining
1203 </group-capabilities-supported>
1204 <group-capabilities-supported
1205 xmlns:x="urn:opendaylight:group:types">x:select-weight
1206 </group-capabilities-supported>
1207 <group-capabilities-supported
1208 xmlns:x="urn:opendaylight:group:types">x:select-liveness
1209 </group-capabilities-supported>
1210 <max-groups>4294967040</max-groups>
1211 <actions>67082241</actions>
1212 <actions>0</actions>
1217 After this, the expected result from a GET request to
1218 http://127.0.0.1:8181/restconf/operational/network-topology:network-topology
1224 xmlns="urn:TBD:params:xml:ns:yang:network-topology">
1226 <topology-id>render:1</topology-id>
1228 <node-id>openflow:1</node-id>
1230 xmlns="urn:opendaylight:topology:inventory:rendering">
1231 <ip-address>10.20.30.40</ip-address>
1232 <serial-number>None</serial-number>
1233 <manufacturer>Nicira, Inc.</manufacturer>
1234 <description>None</description>
1235 <hardware>Open vSwitch</hardware>
1236 <software>2.1.3</software>
1237 </node-augmentation>
1239 <tp-id>openflow:1:1</tp-id>
1241 xmlns="urn:opendaylight:topology:inventory:rendering">
1242 <hardware-address>0E:DC:8C:63:EC:D1</hardware-address>
1243 <current-speed>10000000</current-speed>
1244 <maximum-speed>0</maximum-speed>
1245 <name>s1-eth1</name>
1247 </termination-point>
1249 <tp-id>openflow:1:LOCAL</tp-id>
1251 xmlns="urn:opendaylight:topology:inventory:rendering">
1252 <hardware-address>BA:63:87:0C:76:41</hardware-address>
1253 <current-speed>0</current-speed>
1254 <maximum-speed>0</maximum-speed>
1257 </termination-point>
1265 You can find use case examples on `this wiki page
1266 <https://wiki.opendaylight.org/view/Topology_Processing_Framework:Developer_Guide:Use_Case_Tutorial>`__.
1268 Key APIs and Interfaces
1269 -----------------------
1271 The basic provider class is TopoProcessingProvider which provides
1272 startup and shutdown methods. Otherwise, the framework communicates via
1273 requests and outputs stored in the MD-SAL datastores.
1275 API Reference Documentation
1276 ---------------------------
1278 You can find API examples on `this wiki
1279 page <https://wiki.opendaylight.org/view/Topology_Processing_Framework:Developer_Guide:REST_API_Specification>`__.