Merge pull request #485 from openBackhaul/ap_v2.n.m

Specification of ApplicationPattern v2.0.0

.github/CODEOWNERS

@@ -1 +1,3 @@
           @openBackhaul
+/server/  @PrathibaJee
+/docs/    @openBackhaul @PrathibaJee @IswaryaaS @Rajithapitta

.github/workflows/linter.yaml

@@ -0,0 +1,24 @@
+name: Linter
+on:
+  pull_request:
+    branches: [develop]
+jobs:
+  yaml:
+    name: YAML
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: yaml-lint
+        uses: ibiqlik/action-yamllint@v3
+        with:
+          format: github
+          config_data: |
+            extends: default
+            rules:
+              line-length: disable
+              document-start: disable
+              truthy:
+                ignore: |
+                  .github/
+            ignore: |
+              server/

README.md

@@ -1,54 +1,30 @@
 # ApplicationPattern
 
-- Pattern for REST applications on top of the SDN Controller
-- Thorsten Heinze ([email protected])
+### Location
+The ApplicationPattern is inherent part of all applications in the application layer.  
 
-### Documentation
+### Description
+The ApplicationPattern provides a basic set of operations that are common to all applications.  
 
-- [ApplicationPattern Guidelines](./doc/Main.md)
+In its service section:  
+- It facilitates the automated embedding and upgrade processes.  
+- It automates the registering at the RegistryOffice.  
+- It supports the centralized management functions for logging, tracing, OaM access management, inventory and service access management.  
+- And it assures availability of documentation about the application and its REST API.  
 
-### ServiceList
+In its OaM section:
+- It provides direct configuration of the applications' interfaces, internal connections and parameters of their individual algorithms.  
 
-- [ApplicationPattern+services](./ApplicationPattern+services.yaml)
+The ApplicationPattern is not just a specification.  
+Its implementation is publicly available and can be copied into every individual implementation of an application.  
 
-### ProfileList and ProfileInstanceList
+### Relevance
+The ApplicationPattern is base of the application layer running in the live network at Telefonica Germany.
 
-- [ApplicationPattern+profiles](./ApplicationPattern+profiles.yaml)
-- [ApplicationPattern+profileInstances](./ApplicationPattern+profileInstances.yaml)
-
-### ForwardingList
-
-- [ApplicationPattern+forwardings](./ApplicationPattern+forwardings.yaml)
-
-### Open API specification (Swagger)
-
-- [ApplicationPattern](./ApplicationPattern.yaml)
-
-### CONFIGfile (JSON)
-
-- to be provided
-
-### Test Cases (Postman Export) and DATAfile
-
-- [ApplicationPattern+testcases](./ApplicationPattern%2Btestcases.json)
-- [ApplicationPattern+data](./ApplicationPattern+data.json)
-
-### NodeJS Implementation
-
-- [ApplicationPattern_0.0.2_tsi.211216.1425+nodejs.1](./ApplicationPattern_0.0.2_tsi.211216.1425+nodejs.1.zip)
-
-### Publication
-
-- No official publication planned
-
-### Aspired Classification
-
-- Live Network
-
-### Open Issue List
-
-- [ApplicationPattern/issues](../../issues)
+### Resources
+- [Specification](./spec/)
+- [TestSuite](./testing/)
+- [Implementation](./server/)
 
 ### Comments
-
 ./.

doc/ElementsApplicationPattern/Names/StructureOfUuids/StructureOfUuids.md

@@ -48,7 +48,7 @@ Within the respective layers the following types of objects are defined:
 - p = Profile  
 
 **ApiSegment**  
-The ApiSegment is contained in the UUIDs of Servers, Clients and FCs.
+The ApiSegment is contained in the UUIDs of OperationServers, OperationClients and FCs.
 Basically, identical letters are used, but there is a slight divergence in the deep details of the semantical meanings.
 
 The **OperationServers** are categorized according to the following two aspects:  
@@ -61,7 +61,7 @@ This results in four categories:
 - bs = Basic Service: Offering a service, which must be provided by all applications  
 - is = Individual Service: Offering a services, which is individual to this application  
 
-After categorizing all OperationServers, **HttpServer** and **TcpServer** are inheriting the highest category (e.g. bm) represented in the group of supported OperationServers.  
+UUIDs of **HttpServer** and **TcpServer** don't contain an ApiSegment.  
 
 The **OperationClients** are categorized according to the following two aspects:  
 - Executed Management (giving advice) vs. Consumed Services (receiving support)  
@@ -73,11 +73,11 @@ This results in four categories:
 - bs = Basic Services: All applications are consuming this service from the same application
 - is = Individual Services: Consuming this service is individual to this application
 
-After categorizing all OperationClients, **HttpClient** and **TcpClient** are inheriting the highest category (e.g. bm) represented in the group of supported OperationClients.  
+UUIDs of **HttpClient** and **TcpClient** don't contain an ApiSegment.  
 
 **FCs** are inheriting the ApiSegment from the connected OperationClients.
 
-UUIDs of Profile, ForwardingDomain and Link don't contain an ApiSegment.  
+UUIDs of **Profile**, **FD** and **Link** don't contain an ApiSegment.  
 
 **TargetApplicationID**  
 This application identifier relates to the application that is connected by the described client interface object.  
@@ -97,7 +97,7 @@ Counting is decimal.
 | ---- | ------------------ |
 | ro-1-0-0-op-s-bm-004 | OperationServer (for /v1/end-subscription) inside the RegistryOffice release 1.0.0 |  
 | ol-1-0-0-op-c-bm-ro-1-0-0-010 | OperationClient (for /v1/relay-server-replacement) that is addressing the RegistryOffice release 1.0.0 inside the OamLog release 1.0.0 |  
-| eatl-2-0-0-es-c-is-es-1-0-0-000 | ElasticSearchClient for connecting ExecutionAndTraceLog release 2.0.0 with its database |  
-| ol-1-0-0-http-c-bm-alt-1-0-0-000 | HttpClient that is addressing the ApplicationLayerTopology release 1.0.0 inside the OamLog release 1.0.0 |  
-| aa-1-0-0-op-fc-bm-003 | ForwardingConstruct for basic management tasks on the OperationLayer inside the AdministratorAdministration release 1.0.0 |  
+| eatl-2-0-0-es-c-es-1-0-0-000 | ElasticSearchClient for connecting ExecutionAndTraceLog release 2.0.0 with its database |  
+| ol-1-0-0-http-c-alt-1-0-0-000 | HttpClient that is addressing the ApplicationLayerTopology release 1.0.0 inside the OamLog release 1.0.0 |  
+| aa-1-0-0-op-fc-003 | ForwardingConstruct for basic management tasks on the OperationLayer inside the AdministratorAdministration release 1.0.0 |  
 | eatl-1-0-1-integer-p-000 | Profile storing an Integer value inside the ExecutionAndTraceLog release 1.0.1 |  

doc/ImplementingApplications/ConceptOfUnderstandingTheConfigFile/ConceptOfUnderstandingTheConfigFile.md

@@ -2,6 +2,10 @@
 
 - [What is this CONFIGfile ?](../../ElementsApplicationPattern/Principles/ConfigFile/ConfigFile.md)
 - Entities of Load files
+  - [UUIDs](https://github.com/openBackhaul/ApplicationPattern/blob/openBackhaul/issue454/doc/ElementsApplicationPattern/Names/StructureOfUuids/StructureOfUuids.md)
+    - All UUIDs are invariant: UUIDs get created during instantiation of a logical object. They get deleted while deleting the object. They get never changed during existence of the object.
+    - UUIDs have to be treated as fortuitous Strings: UUIDs shall not be parsed and interpreted for controlling the program flow, but taken as random Strings for identifying logical objects that hold attributes, which are containing the searched information. Navigating through the data tree has to be done based on the attributes' values.
+
   - [ControlConstruct](../../ElementsApplicationPattern/InformationModel/ControlConstruct/ControlConstruct.md) 
   - [LogicalTerminationPoint](../../ElementsApplicationPattern/InformationModel/LogicalTerminationPoint/LogicalTerminationPoint.md)
   - ForwardingDomain: The ForwardingDomain(FD) aggregates one or more ForrwardingConstruct(FC). Theoretically CC consists of a list of FDs. But practically a Microservice consists of a single FD instance. FDs are identified by a uuid.

doc/PreparingSpecifying/AddYamlLinter/Adding Yaml linter to GitHub.md

@@ -0,0 +1,80 @@
+# Adding a yaml linter to GitHub
+
+## Introduction
+
+The yaml linter is a GitHub Action which checks if the document which will be merged is yaml-conform. If the check fails, the merge can't go through. This final check helps improving readability and usability of the document.
+
+The linter follows the yamllint [default rules](https://yamllint.readthedocs.io/en/stable/configuration.html) with a few slight adjustments:
+
+- _line-length: disable_
+    Default value is 80 character per line, but that is not useful in this context due to long URLs.
+- _document-start: disable_
+    Default value is warning if no three dashes (---) at the start of the document is included. This is used for parsers which combine multiple files. However this will rarely happen in our context and probably leads to more confusion, so its disabled.
+- _truthy: ignore: .github/_
+    Yamllint fails on GitHub workflow config files, as the trigger 'on' violates the truthy rule.
+
+A full list of rules and further explanation can be found [here](https://yamllint.readthedocs.io/en/stable/rules.html).
+
+## How to add the yaml linter to your repository
+
+1. Find or create the `.github` folder in the root directory.
+2. In that folder, add a new folder named `workflows` (if not already existing).
+3. Add a new file named `linter.yaml` with following content:
+
+    ```yaml
+    name: Linter
+    on:
+      pull_request:
+        branches: [develop]
+    jobs:
+      yaml:
+        name: YAML
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v2
+          - name: yaml-lint
+            uses: ibiqlik/action-yamllint@v3
+            with:
+              format: github
+              config_data: |
+                extends: default
+                rules:
+                  line-length: disable
+                  document-start: disable
+                  truthy:
+                    ignore: |
+                      .github/
+                ignore: |
+                  server/
+    ```
+
+    This will add a GitHub action to your repository which runs every time a pull request on the develop branch is created or edited. The workflow first checks out the repository code and then runs the yaml linter. This checks all the yaml files in the repository for errors following the given rules. If the run fails, the errors needs to be adressed (see following chapter). If the run was successful, you can proceed as always.
+
+4. Commit your file and start a pull request on your develop branch. Now you should see the action working.
+
+## Where to see the errors and the result of the action
+
+As soon as you created a pull request, follow these steps:
+
+1. Check errors:
+    You can see the errors by clicking on the `details` button in the checks-section of the Pull Request:
+    ![Failed run](./img//runFailed.png)
+    Now you should see an overview of files which contain errors or warnings:
+    ![Error files](./img/errorFiles.png)
+2. Click on a file name to see its errors:
+    ![Errors](./img/error.png)
+    An error or warning is structured after following pattern:
+
+    ```diff
+    - Error|Warning: line:character: [error-name] error-message
+    ```
+
+    e.g. the first error appears in the `ApplicationPattern+profiles` file  in line 89 at charcter 22, which contains trailing spaces.
+    More about this rule [here](https://yamllint.readthedocs.io/en/stable/rules.html#module-yamllint.rules.trailing_spaces).
+
+3. Resolve the errors mentioned above. Warnings can be adressed but are not necessary for the action to suceed.
+4. Commit your changes.
+5. The check will run again and should be successful, if you would have fixed all the errors. If it fails, check the errors again.
+6. If you resolved all errors: :sparkles:Congratulations,:sparkles: all your files are now following the yaml rules.
+
+In the optimal case, the yaml linter will not fail in the first place because you have already linted your files before commiting. However thats not always the case so this additional step helps to fully assure, that every yaml file merged is correct and well formed.

doc/PreparingSpecifying/PreparingSpecifying.md

@@ -30,6 +30,7 @@ Git is available for Linux, Windows and Mac.
 **Step-by-Step Guidelines**
 * [Creating an own GitHub account](./OwnGitHubAccount/OwnGitHubAccount.md)
 * [Installing Git](./InstallingGit/InstallingGit.md)
+* [Activating YAML validation on your respository](./AddYamlLinter/Adding%20Yaml%20linter%20to%20GitHub.md)
 
 
 ### Code Collaboration

doc/TestingApplications/Infrastructure/SdnLaboratory/FakeAddresses/IpAddresses.md

@@ -2,7 +2,7 @@
 
 The following fake TCP/IP addresses have to be used in public documentation and specifications to establish a homogeneous system of unique addresses that can be replaced by actual values during later automated processing.  
 
-| Cathegory | Abbr. | Component | Release | IP_1 | TCP_1 | IP_2 | TCP_2 |
+| Cathegory | Abbr. | Component | Release | IP_1* | TCP_1* | IP_2** | TCP_2** |
 |---|---|---|---|---|---|---|---|
 | Controller |  |  |  |  |  |  |  |
 |  | C | OpenDaylight | 1.0.0 | 1.1.1.1 | 1001
@@ -31,6 +31,10 @@ The following fake TCP/IP addresses have to be used in public documentation and
 |  | MM | MediatorManager | 1.0.0 | 1.1.4.6 | 4006 | 1.2.4.6 | 4206
 |  | AIPS | AirInterfacePowerSaver  | 1.0.0 | 1.1.4.7 | 4007 | 1.2.4.7 | 4207
 |  | L2LT | Linkid2LtpTranslator | 1.0.0 | 1.1.4.8 | 4008 | 1.2.4.8 | 4208
+|  | ALA | AutomatedLinkAcceptance | 1.0.0 | 1.1.4.9 | 4009 | 1.2.4.9 | 4209
+
+\*) IP_1 + TCP_1 = address from **within** the GCP VPC (HTTP).  
+\*\*) IP_2 + TCP_2 = address from **outside** the GCP VPC (HTTP**S**).
 
 # Historical Fake IP Addresses  
 

doc/TinyApplicationController/BequeathYourDataAndDie.md

@@ -0,0 +1,90 @@
+
+# /v1/bequeath-your-data-and-die
+
+(This document describes a sample implementation, which might be out of synch with actual implementation.)
+
+Ultimate goal of this service is to perform software version or instance upgrade without(or with minimum) downtime. This service will be initiated by a new application to the old(or same) version of the same application. The functionality within this service performs a set of procedure to transfer the data from old application to new application using callbacks.
+
+Every new version will be backward compatible with its immediate previous version for a smooth integration with multiple MS. So, software version upgrades should be sequential in order to have a backward compatible version.
+
+![](./images/BequeathYourDataAndDie/Picture1.jpg)
+
+unlike others , this service is not a straightforward one. It has to perform a number of callbacks to transfer the data from old to new version.
+
+To perform upgrade(or instance change) , old and new version of the Registry office will proceed as mentioned below (in a high level),
+
+![](./images/BequeathYourDataAndDie/Picture2.jpg)
+
+The callbacks will be executed in the waterfall model. And if one callback fails, then rest of the callbacks will not be performed further.
+
+## Configuration:
+
+When the old version receives the request , to further communicate with the proper application instance of the new version , 
+the remote address and port of the "newRelease" will be noted by the old version and so the new release number.
+So in the load file of the old release , the http-client-interface and tcp-client-interface will be edited.
+
+![](./images/BequeathYourDataAndDie/Picture3.jpg)
+
+## Forwardings:
+
+After successful configuration of the layer protocols, parallel notifications will be triggered for the following forwarding-constructs that corresponds to the update happed in the load file ,
+- ServiceRequestCausesLtpUpdateRequestALT : If there is a modification to the logical-termination-point , then the details about that LTP will be updated to the Application Layer Topology application.
+- ServiceRequestCausesLoggingRequestEaTL : The service request will be recorded to the Execution and Trace log application.
+
+Apart from the above forwardings , the following callbacks will be initiated to perform the upgrade. Each callback is intended to transfer the existing data from the old release to new release.
+
+**PromptForBequeathingDataCausesNewApplicationBeingRequestedToInquireForApplicationTypeApprovals :**
+
+To make the new application aware about the current TypeApproval Application , this forwarding initiated the v1/inquire-application-type-approval request to the new version and transfers the application information and transport details. 
+ > Old application identifies the correct instance by using the "RegistrationCausesInquiryForApplicationTypeApproval" forwardingName
+
+![](./images/BequeathYourDataAndDie/Picture5.jpg)
+
+**PromptForBequeathingDataCausesNewApplicationBeingRequestedToDocumentSubscriptionsForDeregistrationNotifications :**
+
+This forwarding is to transfer the information about the applications subscribed for deregistration notification. 
+> The subscribed application information will be identified by the "DeregistrationNotification" forwardingName.
+
+![](./images/BequeathYourDataAndDie/Picture6.jpg)
+
+**PromptForBequeathingDataCausesNewApplicationBeingRequestedToDocumentSubscriptionsForApprovalNotifications:**
+
+This forwarding is to transfer the information about the applications subscribed for approval notification. 
+> The subscribed application information will be identified by the "ApprovalNotification" forwardingName.
+
+![](./images/BequeathYourDataAndDie/Picture7.jpg)
+
+**PromptForBequeathingDataCausesNewApplicationBeingRequestedToDocumentSubscriptionsForWithdrawnApprovalNotifications**
+
+This forwarding is to transfer the information about the applications subscribed for withdrawn approval notification. 
+> The subscribed application information will be identified by the "WithdrawnApprovalNotification" forwardingName.
+
+![](./images/BequeathYourDataAndDie/Picture8.jpg)
+
+**PromptForBequeathingDataCausesTransferOfListOfAlreadyRegisteredApplications :**
+
+This forwarding is to transfer the information about the registered applications. Apart from the "old" and "new" release , all the other application information will be transferred as a part of this callback.
+
+![](./images/BequeathYourDataAndDie/Picture9.jpg)
+
+**PromptForBequeathingDataCausesTARbeingRequestedToRedirectInfoAboutApprovalsToNewApplication :**
+
+This forwarding will initiate a request to the "TypeApprovalRegistry" application to redirect the application "approval status change" to the new version.
+
+![](./images/BequeathYourDataAndDie/Picture10.jpg)
+
+**PromptForBequeathingDataCausesRequestForBroadcastingInfoAboutServerReplacement:**
+
+This forwarding will initiate a request to the "old Registry office"(that is, to its own) application to broadcast about the new release to all the approved application in the SDN MS environment.
+
+![](./images/BequeathYourDataAndDie/Picture11.jpg)
+
+**PromptForBequeathingDataCausesRequestForDeregisteringOfOldRelease :**
+
+At this point of time , the old registry office might have transferred all its data to the new application. 
+And now , the new application is the active registry office.
+
+This forwarding will deregister the old Registry Office from the SDN MS environment.
+
+![](./images/BequeathYourDataAndDie/Picture12.jpg)
+