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.

Configuring

This section provides guidance on how to create a configuration schema in Kaa and use it for loading data into applications.

Configuration schema

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

Refer to Admin UI or REST API guides for instructions on uploading the configuration schema to the server.

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.

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:

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.

To upload a new configuration for each group, use Admin UI or REST API. Don't forget to activate each configuration as described in the Edit configuration data for All group section.

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.

Coding

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.

Configuration traversal

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 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.

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.