Architecture
The slee-patch-generator tool is intended to create patches for SLEE applications. Internally it uses the Rhino Management Interface to get information about the components installed in Rhino.
The tool receives a list of SLEE components that will be installed and checks the dependencies of other components and creates a set of actions that will be used by the slee-patch-runner.
On how to create a patch see Creating a patch. To apply the patch see Applying patches to non live system.
The high level algorithm is:
-
Detect the target components to be updated
-
Assert that
-
The replacement components have the same SLEE component IDs
-
The replacement DUs have the same set structure as those they’re replacing
-
Any relevant bindings are only for SBBs / SBB parts
-
-
Detect all Rhino deployment state which depends on those target components
-
Detect all the dependencies between components and other state
-
Calculate a dependency graph
-
Convert the dependency graph into a list (ordered from most downstream to most upstream)
-
Create a set of pre-conditions to assert based on the target & downstream components & state
-
Create a series of actions from downstream to upstream which disassembles / uninstalls
-
Create a series of actions from upstream to downstream which re-assembles / installs
-
Create a set of post-conditions to assert based on the target & downstream components & state
-
Create the metadata that will hold the patch history
-
Generate a reverse patch to do the reverse of the above
For each step the tool generates logs used to identify problems and causes of failure.
SLEE components dependencies
SLEE components have a hierarchy of dependencies shown in the picture below.
![slee dependencies](../images/patches/slee-dependencies.png)
In order to be able to install a component it is necessary to remove the dependency between the patched component and the other components. It is equivalent to the rhino-console command "unverify".
To patch profile specifications it is also necessary to remove any profile table that depends on the profile specification being patched.
The patch.yaml
The patch.yaml
contains the information used by the slee-patch-runner to apply the patch.
The model contains a set of actions, some of which are directional: forwardAction
or reverseAction
. The former is
used when uninstalling the patch.
The file is divided in the higher level sections as follows:
commonConditions
Common conditions are conditions that are checked in pre-conditions and post-conditions. For example assert the service state.
-
AssertServiceExists
-
AssertInstallLevel
preconditions
Pre conditions are actions to be executed before changing any state in the target system.
-
AssertDeployableUnitInstalled
disassemblyActions
Those are actions that remove the target component from the system before installing the new one. Actions are:
-
SaveServiceActivationState
-
SaveTraceLevels
-
DeactivateService
-
AwaitServiceDeactivation
-
RemoveBindings
-
UninstallDeployableUnit
The metadata file
When generating a patch the user can specify a properties file containing information that will be propagated to the documentation.
The properties are:
-
patchName
-
productName
-
productVersion
-
patchVersion
-
ticket
-
description
The file is in yaml format. Example:
patchName: 'customer-name-VOLTE-1234'
productName: 'Volte'
productVersion: '2.7.0.7'
patchVersion: '1'
ticket: 'VOLTE-1234'
description: 'Fix crash on call teardown'
The document template
The patch generator also generates the README.txt included in each patch.
The file is generated based on a template file as part of the slee-patch-generator package.
Each section of the README.txt is based on a token substitution, where a token has the format of !word!
.
The current template is:
1. PATCH DETAILS Patch name: !patch.name! Date: !patch.date! Product to apply: !product.name! Product version: !product.version! Reference ticket: !ticket! Patch description: !description! It will install new versions of the following components: !components! 2. HOW TO APPLY THE PATCH The patch requires: - A running Rhino with an installed product and version expected by the patch. - A client Rhino able to connect to the running rhino. - JAVA_HOME variable set To apply the patch run the command apply-patch.sh -c <absolute-path-to-rhino-client> NOTE: The patch checks for the correct component based on the component name and the checksum. To force the patch to be applied use the option --allow-checksum-mismatch. Beware that it will skip the checksum and will remove the installed component. The patch DOES NOT MAKE a copy of the component. The original component is shipped with the patch, meaning that if the patch is reverted the shipped component is installed. 3. LOGS GENERATED The patch generates logs of the actions executed and also collects the rhino logs. In case of failure the logs will give the indication of the problem. 4. UNINSTALL THE PATCH To revert the patch execute the following command apply-patch.sh -c <absolute-path-to-rhino-client> -r NOTE: the revert patch will reinstall the expected original component shipped with the patch. The component will be the same as the previous installed one, unless the patch was applied with the option --allow-checksum-mismatch. 5. ACTIONS EXECUTED BY THE PATCH 5.1. Pre conditions to check !pre.conditions! 5.2. Actions !actions! 5.3. Post conditions to check !post.conditions!