The OpenDaylight Controller provides following model-driven subsystems
as a foundation for Java applications:
-- :ref:`config_subsystem` - an activation,
- dependency-injection and configuration framework, which allows
- two-phase commits of configuration and dependency-injection, and
- allows for run-time rewiring.
-
- :ref:`MD-SAL <mdsal_dev_guide>` - messaging and data storage
functionality for data, notifications and RPCs modeled by application
developers. MD-SAL uses YANG as the modeling for both interface and
Status: 200 OK
-.. _config_subsystem:
-
-Config Subsystem
-----------------
-
-Overview
-~~~~~~~~
-
-The Controller configuration operation has three stages:
-
-- First, a Proposed configuration is created. Its target is to replace
- the old configuration.
-
-- Second, the Proposed configuration is validated, and then committed.
- If it passes validation successfully, the Proposed configuration
- state will be changed to Validated.
-
-- Finally, a Validated configuration can be Committed, and the affected
- modules can be reconfigured.
-
-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. If one or more validations
-fail, the transaction can be reconfigured. Upon success, the second
-phase commit is invoked. 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.
-
-.. figure:: ./images/configuration.jpg
- :alt: Configuration states
-
- Configuration states
-
-.. figure:: ./images/Transaction.jpg
- :alt: Transaction states
-
- Transaction states
-
-Validation
-~~~~~~~~~~
-
-To secure the consistency and safety of the new configuration and to
-avoid conflicts, the configuration validation process is necessary.
-Usually, validation checks the input parameters of a new configuration,
-and mostly verifies module-specific relationships. The validation
-procedure results in a decision on whether the proposed configuration is
-healthy.
-
-Dependency resolver
-~~~~~~~~~~~~~~~~~~~
-
-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. The
-Dependency Resolver acts in a manner similar to dependency injectors.
-Basically, a dependency tree is built.
-
-APIs and SPIs
-~~~~~~~~~~~~~
-
-This section describes configuration system APIs and SPIs.
-
-SPIs
-^^^^
-
-**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. 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.
-
-**Module creation**
-
-1. The module needs to be configured, set with all required attributes.
-
-2. 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. A module instance is identified by ModuleIdentifier,
- consisting of the factory name and instance name.
-
-| **ModuleFactory** org.opendaylight.controller.config.spi. The
- ModuleFactory interface must be implemented by each module factory.
-| A module factory can create a new module instance in two ways:
-
-- From an existing module instance
-
-- | An entirely new instance
- | ModuleFactory can also return default modules, useful for
- populating registry with already existing configurations. A module
- factory implementation must have a globally unique name.
-
-APIs
-^^^^
-
-+--------------------------------------+--------------------------------------+
-| ConfigRegistry | Represents functionality provided by |
-| | a configuration transaction (create, |
-| | destroy module, validate, or abort |
-| | transaction). |
-+--------------------------------------+--------------------------------------+
-| ConfigTransactionController | Represents functionality for |
-| | manipulating with configuration |
-| | transactions (begin, commit config). |
-+--------------------------------------+--------------------------------------+
-| RuntimeBeanRegistratorAwareConfiBean | The module implementing this |
-| | interface will receive |
-| | RuntimeBeanRegistrator before |
-| | getInstance is invoked. |
-+--------------------------------------+--------------------------------------+
-
-Runtime APIs
-^^^^^^^^^^^^
-
-+--------------------------------------+--------------------------------------+
-| RuntimeBean | Common interface for all runtime |
-| | beans |
-+--------------------------------------+--------------------------------------+
-| RootRuntimeBeanRegistrator | Represents functionality for root |
-| | runtime bean registration, which |
-| | subsequently allows hierarchical |
-| | registrations |
-+--------------------------------------+--------------------------------------+
-| HierarchicalRuntimeBeanRegistration | Represents functionality for runtime |
-| | bean registration and |
-| | unreregistration from hierarchy |
-+--------------------------------------+--------------------------------------+
-
-JMX APIs
-^^^^^^^^
-
-| JMX API is purposed as a transition between the Client API and the JMX
- platform.
-
-+--------------------------------------+--------------------------------------+
-| ConfigTransactionControllerMXBean | Extends ConfigTransactionController, |
-| | executed by Jolokia clients on |
-| | configuration transaction. |
-+--------------------------------------+--------------------------------------+
-| ConfigRegistryMXBean | Represents entry point of |
-| | configuration management for |
-| | MXBeans. |
-+--------------------------------------+--------------------------------------+
-| 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". |
-+--------------------------------------+--------------------------------------+
-
-Use case scenarios
-^^^^^^^^^^^^^^^^^^
-
-| A few samples of successful and unsuccessful transaction scenarios
- follow:
-
-**Successful commit scenario**
-
-1. The user creates a transaction calling creteTransaction() method on
- ConfigRegistry.
-
-2. ConfigRegisty creates a transaction controller, and registers the
- transaction as a new bean.
-
-3. Runtime configurations are copied to the transaction. The user can
- create modules and set their attributes.
-
-4. The configuration transaction is to be committed.
-
-5. The validation process is performed.
-
-6. After successful validation, the second phase commit begins.
-
-7. Modules proposed to be destroyed are destroyed, and their service
- instances are closed.
-
-8. Runtime beans are set to registrator.
-
-9. The transaction controller invokes the method getInstance on each
- module.
-
-10. The transaction is committed, and resources are either closed or
- released.
-
-| **Validation failure scenario**
-| The transaction is the same as the previous case until the validation
- process.
-
-1. If validation fails, (that is to day, illegal input attributes values
- or dependency resolver failure), the validationException is thrown
- and exposed to the user.
-
-2. The user can decide to reconfigure the transaction and commit again,
- or abort the current transaction.
-
-3. On aborted transactions, TransactionController and JMXRegistrator are
- properly closed.
-
-4. Unregistration event is sent to ConfigRegistry.
-
-Default module instances
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-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
-configuration subsystem, for example, its bundle is activated in the
-OSGi environment). By default, no default instances are produced.
-
-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. The
-module has to acquire the configuration for these instances on its own.
-It can be acquired from, for example, environment variables. 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.).
Code Review / controller.git / commitdiff
