IviConfigurationGeneratorConfig

data class IviConfigurationGeneratorConfig(var enabled: Boolean = false)

Config for the configuration generator that generates static and dynamic configurations from JSON files input.

By default, IVI applications use com.tomtom.ivi.platform.framework.api.configuration.providers.ResourceStaticConfigurationProvider for static configurations, and com.tomtom.ivi.platform.framework.api.configuration.providers.JsonDynamicConfigurationProvider for dynamic configurations. The configuration generator generates input for these providers.

The configuration generator can be enabled for any module in the Gradle build configuration by using the ivi extension.

ivi {
configurationGenerator {
enabled = true
}
}

The configuration framework is an experimental API. To opt-in for an this API, enable the optInToExperimentalApis flag in the ivi extension.

ivi {
optInToExperimentalApis = true
}

Static configurations

Input files

When the configuration generator is enabled, it looks for JSON input files in the configurations/static directory of the source set. For example: <moduleRoot>/src/main/configurations/static.

It is recommended to name the configuration files after the package that the static configuration belongs to. For example: com.tomtom.ivi.platform.framework.api.configuration.providers.json.

The JSON input file schema

The JSON input file must contain an object with the following mandatory fields:

  • "packageName": a string with a fully-qualified name of the package that the configurations belong to. The generated static configuration keys will be in that package.

  • "keys": an array of value objects.

A value object must contain the following mandatory fields:

  • "name": a string with the identifier of a configuration value. It must be suitable to use as a Kotlin property name, and be unique within the package. It must end with a "ConfigKey" suffix.

  • "type": a string with the name of the value type: "Boolean", "Double", "Float", "Int", "Long", or "String".

  • "value": a value in the JSON format, corresponding to "type": boolean, number, or string, or an array of values of these types.

You can create an optional static configuration key if a value object has an "optional" field that is set to true. Its value may then also be set to null or "null".

The optional field "description" may contain the description of the configuration value. It is used as KDoc for generated configuration key variables.

Note: All other fields in the input JSON are ignored.

The output files

For each input file and for each Android build variant, the configuration generator creates two files:

  • A Kotlin source file StaticConfigurationKeys.kt, with static configuration key variables in the package of the name specified by the "packageName" field. The variables are wrapped into StaticConfiguration object to avoid pollution of the package namespace.

  • An Android resource file res/values/values.xml with static configuration values.

These files are placed inside the module's build/generated subfolder per build variant. The plugin configures the project to include these files in the corresponding source sets, and makes the symbols resolvable for Android Studio.

Examples

The input JSON file com.tomtom.ivi.platform.framework.api.configuration.providers.json.

{
"packageName": "com.tomtom.ivi.platform.framework.api.configuration.providers",
"keys": [
{
"description": "Optional field with the description of a configuration",
"name": "apiEndpointConfigKey",
"type": "String",
"value": "https://example.com/"
},
{
"name": "demoFeaturesConfigKey",
"type": "Boolean",
"optional": true,
"value": [false, true, false]
}
]
}

The generated Kotlin source file StaticConfigurationKeys.kt.

// BUILD TIME GENERATED FILE. DO NOT EDIT.
// Generated based on: <package>.json
//
package <package>

import com.tomtom.ivi.platform.framework.api.configuration.api.StringStaticConfigurationKey
import com.tomtom.ivi.platform.framework.api.configuration.api.OptBooleanListStaticConfigurationKey

public object StaticConfiguration {
/**
* Optional field with the description of a configuration
*/
val apiEndpointConfigKey = IntStaticConfigurationKey("apiEndpointConfigKey")

val demoFeaturesConfigKey = OptBooleanListStaticConfigurationKey("demoFeaturesConfigKey")
}

The generated resource file values/<package>.xml.

<?xml version="1.0" encoding="utf-8"?>
<!--
BUILD TIME GENERATED FILE. DO NOT EDIT.
Generated based on: <package>.json
--><resources>
<string name="apiEndpointConfgiKey">https://example.com/</integer>
<array name="demoFeaturesConfigKey">
<item>false</item>
<item>true</item>
<item>false</item>
</array>
</resources>

Dynamic configurations

Input files

When the configuration generator is enabled, it looks for JSON input files in the configurations/dynamic directory of the source set. For example: <moduleRoot>/src/main/configurations/dynamic.

It is recommended to name the configuration files after the package that the dynamic configuration belongs to. For example: com.tomtom.ivi.platform.framework.api.configuration.providers.json.

The JSON input file schema

The JSON input file must contain an object with the following mandatory fields:

  • "packageName": a string with a fully-qualified name of the package that the configurations belong to. The generated dynamic configuration keys will be in that package.

  • "keys": an array of configuration entry objects.

  • "version": a version number of the configuration.

A configuration entry object must contain the following mandatory fields:

  • "name": a string with the identifier of a configuration value. It must be suitable to use as a Kotlin property name, and be unique within the package. It must end with a "ConfigKey" suffix.

  • "type": a string with the name of the value type: "Boolean", "Double", "Enum", "Float", "Int", "Long", or "String". If the type is "Enum" then the entry object must contain "enumClass" field with a fully-qualified name of the enum class.

  • "values": an array of configuration value objects.

The optional field "description" may contain the description of the configuration entry. It is used as KDoc for generated configuration key variables.

A configuration value object must contain the following mandatory fields:

  • "value": a configuration value in JSON format, corresponding to "type": boolean, number, or string, or an array of these.

  • "fromVersion": a number that specifies the version when this entry was introduced.

  • "updateStrategy": a string with the name of the update strategy that specifies the way to update the existing setting value: "always", "never", and "defaultOnly". See com.tomtom.ivi.platform.framework.api.configuration.api.ConfigurationUpdateStrategy.

Note: All other fields in the input JSON are ignored.

The output files

For each input file and for each Android build variant, the configuration generator creates two files:

  • A Kotlin source file DynamicConfigurationKeys.kt with dynamic configuration key variables in the package with the name specified by "packageName" field. Variables are wrapped into DynamicConfiguration object to avoid pollution of the package namespace.

  • A JSON file with configuration values in Android assets in configurations directory.

These files are placed inside the module's build/generated subfolder per build variant. The plugin configures the project to include these files in the corresponding source sets, and makes the symbols resolvable for Android Studio.

Examples

The input JSON file com.tomtom.ivi.platform.framework.api.configuration.providers.json.

{
"version": 3,
"packageName": "com.tomtom.ivi.platform.framework.api.configuration.providers",
"keys": [
{
"name": "isDemoEnabledConfigKey",
"description": "A boolean value for demo",
"type": "Boolean",
"values": [
{
"value": false,
"fromVersion": 1,
"updateStrategy": "always"
},
{
"value": true,
"fromVersion": 3,
"updateStrategy": "never"
}
]
},
{
"name": "demoFeaturesConfigKey",
"type": "Enum",
"enumClass": "com.tomtom.ivi.demo.DemoFeatures",
"values": [
{
"value": "ALL_FEATURES",
"fromVersion": 1,
"updateStrategy": "always"
},
{
"value": "STABLE_FEATURES",
"fromVersion": 2
"updateStrategy": "defaultOnly"
}
]
}
]
}

The generated Kotlin source file DynamicConfigurationKeys.kt.

// BUILD TIME GENERATED FILE. DO NOT EDIT
// Generated based on: <package>.json
//
package <package>

import com.tomtom.ivi.platform.framework.api.configuration.api.BooleanDynamicConfigurationKey
import com.tomtom.ivi.platform.framework.api.configuration.api.EnumDynamicConfigurationKey
import com.tomtom.ivi.demo.DemoFeatures

public object DynamicConfiguration {
val settingKeyPrefix = "com.tomtom.ivi.platform.framework.api.configuration.providers"

val group = DynamicConfigurationGroup(settingKeyPrefix)

/**
* A boolean value for demo
*/
val isDemoEnabledConfigKey = BooleanDynamicConfigurationKey(group, "isDemoEnabledConfigKey")

val demoFeaturesConfigKey =
EnumDynamicConfigurationKey(group, "demoFeaturesConfigKey", DemoFeatures::class)
}

The generated asset file configurations/com.tomtom.ivi.platform.framework.api.configuration.providers.json.

{
"version": 3,
"configuration": [
{
"name": "isDemoEnabledConfigKey",
"values": [
{
"value": false,
"fromVersion": 1,
"updateStrategy": "always"
},
{
"value": true,
"fromVersion": 3,
"updateStrategy": "never"
}
]
},
{
"name": "demoFeaturesConfigKey",
"values": [
{
"value": "ALL_FEATURES",
"fromVersion": 1,
"updateStrategy": "always"
},
{
"value": "STABLE_FEATURES",
"fromVersion": 2
"updateStrategy": "defaultOnly"
}
]
}
]
}

Constructors

Link copied to clipboard
constructor(enabled: Boolean = false)

Properties

Link copied to clipboard

Enables the configuration generator for the module. If enabled, the configuration generator looks up for JSON input files and generates source code that allows using the configurations specified there in the product.