IviConfigurationGeneratorConfig
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 intoStaticConfiguration
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". Seecom.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 intoDynamicConfiguration
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"
}
]
}
]
}