manuals/developer-guide/src/main/asciidoc/controller/config.adoc

   1 === Config Subsystem
   2
   3 ==== Overview
   4 The Controller configuration operation has three stages:
   5
   6 * First, a Proposed configuration is created. Its target is to replace the old configuration.
   7 * Second, the Proposed configuration is validated, and then committed. If it passes validation successfully, the Proposed configuration state will be changed to Validated.
   8 * Finally, a Validated configuration can be Committed, and the affected modules can be reconfigured.
   9
  10 In fact, each configuration operation is wrapped in a transaction. Once a transaction is created, it can be configured, that is to say, a user can abort the transaction during this stage. After the transaction configuration is done, it is committed to the validation stage. In this stage, the validation procedures are invoked.
  11  If one or more validations fail, the transaction can be reconfigured. Upon success, the second phase commit is invoked.
  12  If this commit is successful, the transaction enters the last stage, committed. After that, the desired modules are reconfigured. If the second phase commit fails, it means that the transaction is unhealthy - basically, a new configuration instance creation failed, and the application can be in an inconsistent state.
  13
  14 .Configuration states
  15 image::configuration.jpg[width=500]
  16
  17 .Transaction states
  18 image::Transaction.jpg[width=500]
  19
  20 ==== Validation
  21 To secure the consistency and safety of the new configuration and to avoid conflicts, the configuration validation process is necessary.
  22 Usually, validation checks the input parameters of a new configuration, and mostly verifies module-specific relationships.
  23 The validation procedure results in a decision on whether the proposed configuration is healthy.
  24
  25 ==== Dependency resolver
  26 Since there can be dependencies between modules, a change in a module configuration can affect the state of other modules. Therefore, we need to verify whether dependencies on other modules can be resolved.
  27 The Dependency Resolver acts in a manner similar to dependency injectors. Basically, a dependency tree is built.
  28
  29 ==== APIs and SPIs
  30 This section describes configuration system APIs and SPIs.
  31
  32
  33 ===== SPIs
  34 *Module* org.opendaylight.controller.config.spi. Module is the common interface for all modules: every module must implement it. The module is designated to hold configuration attributes, validate them, and create instances of service based on the attributes.
  35 This instance must implement the AutoCloseable interface, owing to resources clean up. If the module was created from an already running instance, it contains an old instance of the module. A module can implement multiple services. If the module depends on other modules, setters need to be annotated with @RequireInterface.
  36
  37 *Module creation*
  38
  39 . The module needs to be configured, set with all required attributes.
  40 . The module is then moved to the commit stage for validation. If the validation fails, the module attributes can be reconfigured. Otherwise, a new instance is either created, or an old instance is reconfigured.
  41 A module instance is identified by ModuleIdentifier, consisting of the factory name and instance name.
  42
  43 *ModuleFactory* org.opendaylight.controller.config.spi. The ModuleFactory interface must be implemented by each module factory. +
  44 A module factory can create a new module instance in two ways: +
  45
  46 * From an existing module instance
  47 * An entirely new instance +
  48 ModuleFactory can also return default modules, useful for populating registry with already existing configurations.
  49 A module factory implementation must have a globally unique name.
  50
  51 ===== APIs
  52
  53 |===
  54 | ConfigRegistry | Represents functionality provided by a configuration transaction (create, destroy module, validate, or abort transaction).
  55 | ConfigTransactionController | Represents functionality for manipulating with configuration transactions (begin, commit config).
  56 | RuntimeBeanRegistratorAwareConfiBean | The module implementing this interface will receive RuntimeBeanRegistrator before getInstance is invoked.
  57 |===
  58
  59 ===== Runtime APIs
  60
  61 |===
  62 | RuntimeBean | Common interface for all runtime beans
  63 | RootRuntimeBeanRegistrator | Represents functionality for root runtime bean registration, which subsequently allows hierarchical registrations
  64 | HierarchicalRuntimeBeanRegistration | Represents functionality for runtime bean registration and unreregistration from hierarchy
  65 |===
  66
  67 ===== JMX APIs
  68
  69 JMX API is purposed as a transition between the Client API and the JMX platform. +
  70
  71 |===
  72 | ConfigTransactionControllerMXBean | Extends ConfigTransactionController, executed by Jolokia clients on configuration transaction.
  73 | ConfigRegistryMXBean | Represents entry point of configuration management for MXBeans.
  74 | Object names | Object Name is the pattern used in JMX to locate JMX beans. It consists of domain and key properties (at least one key-value pair). Domain is defined as "org.opendaylight.controller". The only mandatory property is "type".
  75 |===
  76
  77 ===== Use case scenarios
  78
  79 A few samples of successful and unsuccessful transaction scenarios follow: +
  80
  81 *Successful commit scenario*
  82
  83 . The user creates a transaction calling creteTransaction() method on ConfigRegistry.
  84 . ConfigRegisty creates a transaction controller, and registers the transaction as a new bean.
  85 . Runtime configurations are copied to the transaction. The user can create modules and set their attributes.
  86 . The configuration transaction is to be committed.
  87 . The validation process is performed.
  88 . After successful validation, the second phase commit begins.
  89 . Modules proposed to be destroyed are destroyed, and their service instances are closed.
  90 . Runtime beans are set to registrator.
  91 . The transaction controller invokes the method getInstance on each module.
  92 . The transaction is committed, and resources are either closed or released.
  93
  94 *Validation failure scenario* +
  95 The transaction is the same as the previous case until the validation process. +
  96
  97 . If validation fails, (that is to day, illegal input attributes values or dependency resolver failure), the validationException is thrown and exposed to the user.
  98 . The user can decide to reconfigure the transaction and commit again, or abort the current transaction.
  99 . On aborted transactions, TransactionController and JMXRegistrator are properly closed.
 100 . Unregistration event is sent to ConfigRegistry.
 101
 102 ===== Default module instances
 103 The configuration subsystem provides a way for modules to create default instances. A default instance is an instance of a module, that is created at the module bundle start-up (module becomes visible for
 104 configuration subsystem, for example, its bundle is activated in the OSGi environment). By default, no default instances are produced.
 105
 106 The default instance does not differ from instances created later in the module life-cycle. The only difference is that the configuration for the default instance cannot be provided by the configuration subsystem.
 107 The module has to acquire the configuration for these instances on its own. It can be acquired from, for example, environment variables.
 108 After the creation of a default instance, it acts as a regular instance and fully participates in the configuration subsystem (It can be reconfigured or deleted in following transactions.).