Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "SensiNact/AppManager"
(Added data model image) |
(→How to use) |
||
Line 138: | Line 138: | ||
== How to use == | == How to use == | ||
+ | |||
+ | === Base === | ||
The AppManager is accessible as any resources in the sensiNact Gateway. Thus, it is accessible using the REST Northbound bridge. At start, the AppManager holds only the AdminService. To install/uninstall an application, you have to perform an ACT on the INSTALL/UNINSTALL resources in the AdminService of the AppManager. | The AppManager is accessible as any resources in the sensiNact Gateway. Thus, it is accessible using the REST Northbound bridge. At start, the AppManager holds only the AdminService. To install/uninstall an application, you have to perform an ACT on the INSTALL/UNINSTALL resources in the AdminService of the AppManager. | ||
Line 144: | Line 146: | ||
You can also uses a REST client (e.g., [https://www.getpostman.com/ POSTMAN]) to send JSON files to the AppManager but you will send a valid JSON file. | You can also uses a REST client (e.g., [https://www.getpostman.com/ POSTMAN]) to send JSON files to the AppManager but you will send a valid JSON file. | ||
+ | |||
+ | |||
+ | === Persistent Applications === | ||
+ | |||
+ | The default behavior of an SNA application is to live as long as the Gateway instance is up and running, not persistent during during after Reboot. | ||
+ | |||
+ | Eventhough this is the default behavior, it is possible to indicated to the AppManager to persist the application in a storage system. Native implementation of the storage system is to persist the SNA Application in the gateway filesystem. | ||
+ | |||
+ | Application Manager itself alow the administrator to customize a certain number of properties, the currently available configurable properties. | ||
+ | |||
+ | * directory: optional field, this property defines which directory will be watched in order to load (at startup) and monitor the file modification in order to reload the application in the gateway. The value of this property is an ''alphanumeric'' value. | ||
+ | * applicationPersist: mandatory field, this field specify if the Application Manager should persist the application in the filesystem and reload those applications in case of the Sensinact Gateway restart. This is a ''boolean'' type field | ||
+ | * applicationFileExtension: optional field, with default value set to ''json'', this means that the application persistence monitor will target only file with the ".json" extention. You may change this extention by modifying this property. This is an ''alphanumeric'' value. | ||
+ | |||
+ | The Application Manager will take into consideration the configuration file deployed in ''cfgs'' directory in the gateway base directory named ''application-manager.properties'' | ||
+ | |||
+ | Below is an example of a property configuration file: | ||
+ | |||
+ | <pre> | ||
+ | directory=application | ||
+ | applicationPersist=true | ||
+ | updateFileCheck=2000 | ||
+ | applicationFileExtention=json | ||
+ | </pre> | ||
+ | |||
+ | This configuration file is deployed on the designed directory to configure Sensinact service bundles. | ||
== Known issues == | == Known issues == | ||
No issues for now. | No issues for now. |
Revision as of 04:24, 23 April 2018
Contents
AppManager
The AppManager aims at creating higher level applications based on the resources provided by the sensiNact gateway. The AppManager provides a way to develop event driven applications, i.e., based on the Event-Condition-Actions (ECA) axiom. Thus, the application is only triggered when the required events occur. Then, if all conditions are satisfied, the actions are done. Events are created from sNa sensors and the actions are performed using the sNa actuators available in the environment.
Data model and JSON format
The AppManager assumes that an application is a set of bound components. Each component processes a single function (e.g., addition, comparison, action). The result of this function is stored in a variable in the current instance of the application. The components using this result as input listen to the corresponding variable. When the variable changes, they are notified and can process their own function leading to a new result.
Data model of a component
The component is the atomic element of an application, thus an application can consider a single component to perform an action. It holds the minimal requirements to create an ECA application:
- Identifier: the unique name of the component in the application ;
- Events: events that trigger the process of a component. Trigger can be conditioned to a specific event or a specific value of the event (e.g., when the value of the sensor reach a threshold) ;
- Function: function wrapped in the component (e.g., addition, comparison, action). The acquisition of the parameters is realized in the transition block before the function block. This object includes the name of the function and the parameters of the function that are not available in the event (e.g., static value, sensors values) ;
- Properties: nonfunctional properties of the component (e.g., register the result as a new resource in sNa).
The AppManager is a sNa service provider, thus it provides an Install and an Uninstall resources, enabling a client to install/uninstall an application. These resources are accessible using different bridges.
A sNa application is described using a JSON file. We developed a specific Architecture Description Language (ADL) to describe the components used in an application and the bindings between the components. Below you will find the data model of the ADL of a component. The dotted line box are optional information in the component.
Component example
The following JSON code example corresponds to the code of a single component:
{ "identifier": "identifier", "events": [ { "value": "resource1", "type": "resource", "conditions": [{ "operator": ">=", "value": 100, "type": "integer", "complement": false }] }], "function": { "name": "function_name", "runparameters": [ { "value": "ON", "type": "string" } }, "properties": {} }
This component specifies that when the resource1
is greater or equals to 100
, the function_name
is called with the string
parameter "ON"
. The result of the function is stored in the fixed output
variable, available at the URI: /application_name/component_name/output
in the OSGi registry, and triggers a new event that may be used by others components.
Description of the fields of the JSON
Access to a parameter
The variable or resources present in the component must be provided with their full URI. For a sNa resource you must provide: /provider/service/resource
. For a variable you must provide /application_name/component_name/output
, where the application_name
is the name of the application, component_name
is the identifier of the component, i.e., the field identifier
and output
is a fixed name.
Types of parameters
Supported types are:
- Primitives types:
integer
,boolean
,long
,double
,float
,string
. This is used to described a static variable; - Resource type:
resource
. This is used to refer to a resource. If this is set in the JSON Event section of the JSON, a SUBSCRIBE is done on the resource. If this is done in any JSON Parameters section, a GET is done on the resource and returns the current value; - Variable type:
variable
. This is used to refer to the output of a previously processed component;
Here after is a synthesis of the type that can be used in the different parts of the JSON file.
Primitive types | Resource type | Variable type | |
In event type | No | Yes | Yes |
In event/condition type | Yes | Yes | Yes |
In parameters type | Yes | Yes | Yes |
Function field
The function object in the JSON requires to provide at least the name of the function that is called in the component (field name
) and the runtime parameters associated to the function (field runparameters
) which are defined for each function and are available in the JSON schema of each function.
The field buildparameters
might be required to instantiate the component before the processing of the first event. This field is optional and you have to refer to the JSON schema of each function to determine if you have to specify it or not.
Properties field
This optional field aims at providing various properties associated to the component. For now, the available properties are:
-
register
(boolean): enable to share publicly the result of the component. It enable to create virtual resources that can be used by others applications. Default is false.
JSON validation
The AppManager supports the validation of the JSON files against a JSON schema. Schemas exist in the plugins and may be used by the developers of the applications. In order to provide a validation of the application during the installation phase, a JSON validator has been integrated.
Architecture
The AppManager is designed to be used as any sNa service provider. Thus it provides an Install and an Uninstall resources, enabling a client to install/uninstall an application. These resources are accessible using different bridges, such as any actuators.
The AppManager architecture is also designed to easily add new functions and to handle the lifecycle of applications in order to perform checks.
Plugins
Plugins enable to add new function to the AppManager. New plugins require to implements the mandatory interfaces Java interface to be found in the OSGi registry and thus be used by the AppManager. The AppManager is currently supporting the following functions.
Plugin | Functions supported |
Basic Plugin | various operators (e.g., equals, greater than, lesser than, different), addition, subtraction, division, multiplication, modulo, concatenation, substring, ACT and SET methods on resources |
Lifecycle
The AppManager provides a lifecycle to manage the applications. It enables to process various checks during different steps of the lifecycle of the application (e.g., ADL consistency, resources permissions). The first step is to install the application, i.e., send the ADL of the application. If there is a problem, the AppManager returns an error. Once the application is installed, it can be started and its state changes to “Resolving”. If there is a problem during this step, the application enters in the “Unresolved” state. Otherwise, the application is active until it is stopped or an exception occurs.
Instances
The AppManager allows multiple instances of the same application to run in parallel. When an event occurs, the InstanceFactory
of the application instantiates a new set of components and passes the event to the first component. The number of instances can be set in the application properties. If, there is more events than available instances, events are stored and processed when an instance ends.
Installation
To install the AppManager, you just need to copy the JAR in the sNa Gateway. Usually, it is copied in the $SNA_HOME/load/application. No dependencies are required for this bundle.
How to use
Base
The AppManager is accessible as any resources in the sensiNact Gateway. Thus, it is accessible using the REST Northbound bridge. At start, the AppManager holds only the AdminService. To install/uninstall an application, you have to perform an ACT on the INSTALL/UNINSTALL resources in the AdminService of the AppManager.
To send JSON files, it is recommanded to use the sensiNact Studio that will format the JSON ADL from the sNa language.
You can also uses a REST client (e.g., POSTMAN) to send JSON files to the AppManager but you will send a valid JSON file.
Persistent Applications
The default behavior of an SNA application is to live as long as the Gateway instance is up and running, not persistent during during after Reboot.
Eventhough this is the default behavior, it is possible to indicated to the AppManager to persist the application in a storage system. Native implementation of the storage system is to persist the SNA Application in the gateway filesystem.
Application Manager itself alow the administrator to customize a certain number of properties, the currently available configurable properties.
- directory: optional field, this property defines which directory will be watched in order to load (at startup) and monitor the file modification in order to reload the application in the gateway. The value of this property is an alphanumeric value.
- applicationPersist: mandatory field, this field specify if the Application Manager should persist the application in the filesystem and reload those applications in case of the Sensinact Gateway restart. This is a boolean type field
- applicationFileExtension: optional field, with default value set to json, this means that the application persistence monitor will target only file with the ".json" extention. You may change this extention by modifying this property. This is an alphanumeric value.
The Application Manager will take into consideration the configuration file deployed in cfgs directory in the gateway base directory named application-manager.properties
Below is an example of a property configuration file:
directory=application applicationPersist=true updateFileCheck=2000 applicationFileExtention=json
This configuration file is deployed on the designed directory to configure Sensinact service bundles.
Known issues
No issues for now.