- Basic architecture
The Kaa configuration subsystem supplies endpoints with the structured configuration data of custom complexity that is managed through the Kaa server. The configuration data itself is structured according to the configuration schema specified by the user beforehand. Both a configuration schema and configuration data can be modified on the server using Admin UI or REST API and then uploaded to relevant applications.
The following diagram illustrates basic entities and data flows in scope of the configuration management:
- Configuration is generated based on the configuration schema created by the developer for the application
- The user or admin distributes new configuration using either Admin UI or
- It is also possible to distribute new configuration to all endpoint groups using the same configuration schema in one go
This section provides guidance on how to create a configuration schema in Kaa and use it for loading data into applications.
The structure of the data in Kaa is determined by the configuration schema which is created in the Avro format. See the Configuration section in the Design reference for more information on the schema format.
In this guide, we are going to use the following configuration schema for our example scenario.
This schema allows you to configure a global log level (the global_log_level field) for your project and an individual log level per each project module.
Upload configuration schema using UI/REST
Base and override schemas
After the configuration schema has been successfully uploaded, Kaa generates a base and an override schemas as described in the Configuration section of the Design reference.
The main difference between these two schemas is that using an override schema you can set some fields as unchanged rather than assigning them specific values. For the unchanged field, its value will be taken from the corresponding field in the All group, if it's possible. If not (for example, if there's a new array item which is not present in the All group), Kaa will generate the default value for the unchanged field as described in the Configuration section of the Design reference.
You can obtain all these configuration schemas using REST API.
NOTE: Admin UI currently does not allow you to obtain base and override schemas. ( KAA-208 - Add capability to retrieve the Override/Base configuration schema from the Admin UI Done tracks this issue)
The base schema generated from the configuration schema in our example looks as follows:
The override schema generated from the configuration schema in our example looks as follows:
Load default data into All group
As soon as both schemas are generated, Kaa loads the default data into the All group using the base schema. The default data is constructed according to the field types as described in the Configuration section of the Design reference. In our example, the generated data looks as follows:
Edit configuration data for All group
Use the base schema when you edit the configuration data for the All group.
To edit the configuration data for the All group, proceed as follows:
- Obtain the existing configuration data using the Admin UI (select the All endpoint group under the application, then select the endpoint group configuration) or REST API.
In our example, let's set the global_log_level field to "TRACE" .
This global log level will become default for all endpoints.
IMPORTANT: the __uuid field is reserved for Kaa needs. Never edit its value by yourself.
The resulting configuration data looks as follows:
- To save the changes, click Save in Admin UI or use REST API.
- To apply the saved changes to endpoints, activate the new configuration by clicking Activate in Admin UI or using REST API.
Load configuration data into specific group
To create an individual configuration for a specific endpoint group, use the override schema.
In the following configuration example for the Android Froyo endpoints group, we've set the global_log_level field to "unchanged" (that is, the default value from the All group will be used) and assigned the "DEBUG" level to the org.kaaproject.kaa.schema.sample.FroyoSpecificModule module.
In the following configuration example for the Android endpoints group, we've assigned the 'INFO" level to the org.kaaproject.kaa.schema.sample.AndroidModule module.
Please note that we've left the null value for all __uuid fields.
Edit configuration data for specific group
Editing process for a specific group is similar to editing for the All group described in the Edit configuration data for All group section.
Obtain the current configuration data using the Admin UI (select the endpoint group under the application, then select the endpoint group configuration) or REST API.
For the Android Froyo endpoints group, the result is presented in the following code block. It includes the data we've added in the Load configuration data into specific group section, as well as the __uuid values automatically generated by Kaa after we've uploaded our configuration to the server.
NOTE: Actual __uuid values may differ from those provided in this sample.
In our example, let's assign the "WARNING" value to the org.kaaproject.kaa.schema.sample.FroyoSpecificModule module.
Load this data back to the server and activate the new configuration.
This section provides code samples which illustrate how to use Kaa SDK to work with configuration schema/data in Kaa, for instance, how to subscribe to configuration updates and implement configuration schema persistence.
You can upload the current configuration data to the client and use this data for specific purposes.
The following example illustrates how to upload the configuration data to the client, use it for retrieving log levels of each project module, and check whether a specific module is loggable against the provided log level.
Subscribe to configuration updates
You can subscribe your own callback on any configuration update, as illustrated by the following code example.
The onConfigurationUpdated method will be invoked on any configuration update that was received from the server. The arg0 argument contains the full latest configuration data.
Subscribe to configuration updates for specific objects
You can change the client's configuration subscription to receive updates only on specific parts of configuration.
To use the partial configuration subscription, proceed as follows:
Implement the root configuration receiver using the DeltaReceiver (java) interface.
The LogLevelHandler class is a mapping to the LogConfiguration record from the schema. It consists of the global log level value and modules.
Implement the ModuleLogLevelReceiver class which represents the ModuleLogLevel record from the schema.
Objects of this class can process partial configuration updates for the individual item in the array.
To start using the partial subscription mechanism, register the root receiver in Kaa.
Configuration schema persistence
During the work, the Kaa client can receive configuration schema updates. By default, the schema is not persisted by the client. You can create your own mechanism of schema persistence by creating the instance of SchemaStorage class and passing it as a parameter to the setSchemaStorage method of the SchemaPersistetManager class.
The following code example illustrates how to persist the schema by storing it to a file.
Configuration data persistence
Similarly to the configuration schema persistence, you can persist the configuration data too. For this purpose, create the instance of ConfigurationStorage class and pass it as a parameter to the setConfigurationStorage method of the ConfigurationPersistenceManager class.
The following code example illustrates how to persist the configuration data by storing it to a file.