From: Robert Varga Date: Thu, 27 Jul 2023 17:05:12 +0000 (+0200) Subject: Remove Config Subsystem documentation X-Git-Tag: v8.0.1~9 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=commitdiff_plain;h=ede9e277127f744422090193415e36488c9232c0 Remove Config Subsystem documentation The configuration subsystem is long-gone. Remove its documentation from developer guide. Change-Id: I0da59ec514f9f9208d099f05702c95d9c1e83eb9 Signed-off-by: Robert Varga --- diff --git a/docs/dev-guide.rst b/docs/dev-guide.rst index 3718125ce9..a5e0e3fc58 100644 --- a/docs/dev-guide.rst +++ b/docs/dev-guide.rst @@ -28,11 +28,6 @@ The OpenDaylight Controller relies on the following technologies: 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 ` - 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 @@ -1370,230 +1365,3 @@ Something practical 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.). diff --git a/docs/images/Transaction.jpg b/docs/images/Transaction.jpg deleted file mode 100644 index 258710ae56..0000000000 Binary files a/docs/images/Transaction.jpg and /dev/null differ diff --git a/docs/images/configuration.jpg b/docs/images/configuration.jpg deleted file mode 100644 index 3b07a2b55e..0000000000 Binary files a/docs/images/configuration.jpg and /dev/null differ