From b3236e1118007170a12c387a4077c92a0922e9fc Mon Sep 17 00:00:00 2001 From: =?utf8?q?=C5=A0imon=20Uku=C5=A1?= Date: Wed, 22 Mar 2023 15:43:40 +0100 Subject: [PATCH] Add docs for model registration with OSGi MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit JIRA: MDSAL-9 Change-Id: Id0c6c2071c14977caad31743253bbae8b6436755 Signed-off-by: Šimon Ukuš --- docs/index.rst | 1 + docs/model-registration.rst | 133 ++++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+) create mode 100644 docs/model-registration.rst diff --git a/docs/index.rst b/docs/index.rst index 0756710325..8b000d14ec 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -127,3 +127,4 @@ Table of Contents incremental-backup binding-query-user-guide query-binding-language-developer-guide + model-registration diff --git a/docs/model-registration.rst b/docs/model-registration.rst new file mode 100644 index 0000000000..3667f00793 --- /dev/null +++ b/docs/model-registration.rst @@ -0,0 +1,133 @@ + +############################ +Registering Models with OSGi +############################ + +The OSGi framework activates the *OSGiModelRuntime* component, who initiates: + +* **YangModuleInfoScanner** - tracks bundles and attempts to retrieve *YangModuleInfo*, which it then feeds to *YangModuleInfoRegistry* +* **YangModuleInfoRegistry** - updates *SchemaContext* each time new *YangModuleInfo* is added/removed + +The diagram below shows the process of registering the modules found in a recently tracked bundle. +The **YangModuleInfoScanner** collects the *ModuleInfo*-s from that bundle and forwards them to the **YangModuleInfoRegistry**. +From there the **ModuleInfoSnapshotResolver** checks for existing registration of each *YangModuleInfo* +and if exists, it reuses, otherwise creates a fresh registration with the help of *YangTextSchemaContextResolver*. + +After each *ModuleInfo* is registered, the **YangModuleInfoScanner** initiates a snapshot update +on the **YangModuleInfoRegistry**. During the snapshot capture, the *EffectiveSchemaContext* +is updated and preserved within that snapshot. + +.. uml:: + + @startuml + boundary " " <> + participant OSGiModelRuntime as "OSGiModelRuntime" + participant YangModuleInfoScanner as "YangModuleInfoScanner" + participant YangModuleInfoRegistry as "YangModuleInfoRegistry" + participant ModuleInfoSnapshotResolver as "ModuleInfoSnapshotResolver" + participant YangTextSchemaContextResolver as "YangTextSchemaContextResolver" + + -> OSGiModelRuntime : OSGi Component activation + activate OSGiModelRuntime + + OSGiModelRuntime -> YangModuleInfoScanner: Initialize YangModuleInfoScanner as BundleTracker + activate YangModuleInfoScanner + + OSGiModelRuntime -> YangModuleInfoRegistry: Initialize YangModuleInfoRegistry + activate YangModuleInfoRegistry + + deactivate OSGiModelRuntime + deactivate YangModuleInfoScanner + deactivate YangModuleInfoRegistry + + " " -> YangModuleInfoScanner : Bundle registered + activate YangModuleInfoScanner + + YangModuleInfoScanner -> YangModuleInfoScanner: Load the services \nfrom the bundle \nthat was recently tracked. + + YangModuleInfoScanner -> YangModuleInfoScanner: Collect YangModuleInfo-s \nfrom loaded services + + YangModuleInfoScanner -> YangModuleInfoRegistry: Register collected ModuleInfos + activate YangModuleInfoRegistry + + YangModuleInfoRegistry -> ModuleInfoSnapshotResolver: Register ModuleInfos + activate ModuleInfoSnapshotResolver + + alt No previous Registration for the ModuleInfo => create a fresh Registration + ModuleInfoSnapshotResolver -> YangTextSchemaContextResolver : Register provided ModuleInfo + activate YangTextSchemaContextResolver + + YangTextSchemaContextResolver --> ModuleInfoSnapshotResolver: Return fresh Registration + deactivate YangTextSchemaContextResolver + + ModuleInfoSnapshotResolver -> YangModuleInfoRegistry: Return fresh Registration + else Registration for provided ModuleInfo exists + ModuleInfoSnapshotResolver -> YangModuleInfoRegistry : Return existing Registration + deactivate ModuleInfoSnapshotResolver + end + + YangModuleInfoRegistry -> YangModuleInfoScanner: Return Registration + + YangModuleInfoScanner -> YangModuleInfoRegistry : Scanner update + + YangModuleInfoRegistry -> ModuleInfoSnapshotResolver : Take a snapshot + activate ModuleInfoSnapshotResolver + + ModuleInfoSnapshotResolver -> YangTextSchemaContextResolver : Ask for new schema context + activate YangTextSchemaContextResolver + + YangTextSchemaContextResolver -> YangTextSchemaContextResolver : Create EffectiveModelContext \nfrom registered sources + + YangTextSchemaContextResolver -> ModuleInfoSnapshotResolver : Return created schema context + deactivate YangTextSchemaContextResolver + + ModuleInfoSnapshotResolver -> YangModuleInfoRegistry : Return a snapshot with the created schema context + deactivate ModuleInfoSnapshotResolver + + YangModuleInfoRegistry -> YangModuleInfoRegistry : Save the snapshot + + YangModuleInfoRegistry -> YangModuleInfoScanner : Done + deactivate YangModuleInfoRegistry + + YangModuleInfoScanner -> " " : Return Registration + deactivate YangModuleInfoRegistry + + + deactivate YangModuleInfoRegistry + deactivate YangModuleInfoScanner + @enduml + +The diagram below shows all relevant components and their relations. + +.. uml:: + + @startuml + class "OSGiModuleRuntime" as runtime { + void deactivate() + } + class "YangModuleInfoScanner" as bundleTracker { + Registration addingBundle() + void modifiedBundle() + void removedBundle() + } + class "YangModuleInfoRegistry" as registry { + Registration registerBundle() + void scanerUpdate() + void enableScannerAndUpdate() + void scannerShutdown() + } + class "ModuleInfoSnapshotResolver" as resolver { + List registerModuelInfos() + ModuleInfoSnapshot takeSnapshot() + } + class "YangTextSchemaContextResolver" as textResolver { + YangTextSchemaSourceRegistration registerSource() + EffectiveModelContext getEffectiveModelContext() + } + + runtime -- bundleTracker : initiates + runtime -- registry : initiates + + registry -- resolver + resolver -- textResolver + @enduml -- 2.36.6