== Topology Processing Framework Developer Guide

=== Overview
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.

=== Topology Processing Framework Architecture
Contains of topoprocessing-api, topoprocessing-spi and topoprocessing-impl 
bundles.

* topoprocessing-api - contains correlation definitions
* topoprocessing-spi - entry point for topoprocessing service (start and close)
* topoprocessing-impl - contains implemented handlers, listeners and aggregators

*Typical usecase*

. TopoProcessingProvider instance is created, DataBroker dependency is set
. TopoProcessingProvider registers TopologyRequestListener (into configuration datastore)
    - TopologyRequestListener listens on any topology creation or deletion and checks if it contains CorrelationAugment augmentation
. TopologyRequestListener creates TopologyRequestHandler on new topology request
    - TopologyRequestHandler translates paths from correlation into InstanceIdentifiers
. TopologyRequestHandler creates TopologyFiltrator and/or TopologyAggregator (depending on correlation)
. This step shows, that we can create filtered views on aggregated topologies
. TopologyRequestHandler registers needed UnderlayTopologyListener(s) (into operational datastore)
. Data change events are passed for aggregation and/or filtering
. Overlay topology is passed to TopologyWriter
. TopologyWriter writes the overlay topology into operational datastore

.architecture schema
image::topoprocessing/architecture.png["architecture", width=500]

=== Key APIs and Interfaces
Basic Provider class is TopoProcessingProvider which provides startup and shutdown
methods. Otherwise the framework communicates via requests and outputs stored 
in DataStores.

//=== API Reference Documentation
//Provide links to JavaDoc, REST API documentation, etc. [TBD]