docs/developer-guide/federation-developer-guide.rst

   1 ######################################
   2 federation-with-rabbit Developer Guide
   3 ######################################
   4
   5 Overview
   6 ========
   7
   8 The federation service is a project that facilitates the exchange of state between multiple
   9 OpenDaylight deployments (henceforth 'sites'). These sites may be single node deployments or cluster deployments. The 'federation-with-rabbit' feature is a specific implementation of the federation service, based on Rabbit MQ broker. Federation service currently only supports the Rabbit MQ implementation.
  10
  11 federation-with-rabbit Architecture
  12 ===================================
  13
  14 In the context of federation, each site can wear two hats. A site can be a producer of messages and/or a consumer or messages. This is why each component is logically divided to two parts: Egress(Producer) part and Ingress(Consumer) part.
  15
  16 High-Level Components
  17 ---------------------
  18 Federation Plugin SPI
  19 ^^^^^^^^^^^^^^^^^^^^^
  20 This plugin SPI is implemented by applications that want to use the federation capabilities.
  21 The plugin declares which entities in the MD-SAL it wants the federation infrastructure to listen to, and it gets notified when the state of the entity in the MD-SAL changes. Upon a notification, the plugin can decide to do what ever it wants with the entity -> Send it to the other site, filter it out, transform it and even send a completely different entity.
  22
  23 In each site, the amount of instances of the plugin is equal to the amount of remote connected sites.
  24
  25 Federation Service Infrastructure
  26 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  27 This layer hosts the Federation Plugins. In the producer side, it is responsible for the creation and destruction of the plugins, listening to the MD-SAL and passing of the modification notifications to the plugin themselves, and the tunnel for publishing remote messages by the plugins.
  28
  29 In the consumer side, it is responsible for consuming the remote sites messages and passing them to the corresponding plugins.
  30
  31 Rabbit MQ Infrastructure
  32 ^^^^^^^^^^^^^^^^^^^^^^^^
  33 This layer is used by the Federation Service Infrastructure for sending and receiving messages from other sites. It also exposes the ability to create and destroy queues for the messages themselves. This component communicates directly with the Rabbit Broker. A prerequisite for the federation service is the existence of at least one Rabbit Broker that each site can reach, and all the exchanging of messages happens through this broker/s.
  34
  35 Lifecycle
  36 ---------
  37
  38 Subscription
  39 ^^^^^^^^^^^^
  40 To establish the initial connection between sites, a subscribe() must be invoked on the Federation Service Infrastructure. A subscription is a request between a consumer-site to a producer-site. This means that in order connect Site A with Site B, Site A will have to subscribe to Site B, and Site B will have to subscribe to Site A.
  41
  42 Stages of State Synchronization
  43 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  44 After the initial connection, the sites transition into Full Sync stage.
  45
  46 In Full Sync stage, the producer site sends all the existing relevant state to the consumer site. The Full Sync stage start with a StartFullSyncFederationMessage, follows with all the entity messages, and ends with a EndFullSyncFederationMessage. When the Full Sync stage is over, the sites transition into the next stage - Steady Sync.
  47
  48 In the Steady Sync stage, ongoing MD-SAL updates for the relevant state are notified in the producer site to the instances of the plugins. The plugins then send the interesting state to the consumer sites using the federation infrastructure.
  49
  50
  51 Key APIs and Interfaces
  52 =======================
  53
  54 Introduction
  55 ------------
  56
  57 When observing the federation service in a perspective of Egress and Ingress, the classes and interfaces responsible for each task are divided in the following way.
  58
  59 Egress/Producer
  60 ^^^^^^^^^^^^^^^
  61 * Federation plugin SPI - IFederationPluginEgress
  62 * Federation service infrastructure - FederationProducerMgr
  63 * Rabbit MQ infrastructure - RabbitMessageBus.sendMsg()
  64
  65 Ingress/Consumer
  66 ^^^^^^^^^^^^^^^^
  67 * Federation plugin SPI - IFederationPluginIngress
  68 * Federation service infrastructure - FederationConsumerMgr
  69 * Rabbit MQ infrastructure - RabbitMessageBus.attachHandler()
  70
  71 API Reference Documentation
  72 ===========================
  73 IFederationPluginEgress
  74 -----------------------
  75 JavaDocs link
  76
  77 IFederationPluginIngress
  78 ------------------------
  79 JavaDocs link
  80
  81 FederationProducerMgr
  82 ---------------------
  83 JavaDocs link
  84
  85 FederationConsumerMgr
  86 ---------------------
  87 JavaDocs link
  88
  89 RabbitMessageBus
  90 ---------------------
  91 JavaDocs link
  92
  93
  94