Configuration Manager - Android

Overview

The Core module can be used to manage the configuration for other modules within the Oracle CX Mobile SDK. This section will guide you on adding the configuration for a new module in the SDK. The Core module contains the base capability required for all modules within the Oracle CX Mobile SDK such as storing, transmitting events to data collection servers and so on. So any new module in the Oracle CX Mobile SDK must add the Core module as a dependency.

Following the instructions guide you on creating the configuration for a new module and adding it to the Core module.

Creating a new module configuration

Depending on your mobile app project structure, you can create a new configuration by the following steps

  1. Create a configuration ENUM by implementing IORAConfigSetting interface

  2. Extend the ORABaseDataContainer class

Create a configuration ENUM by implementing IORAConfigSetting interface

You need to create an ENUM class and implement with the IORAConfigSetting interface. This stores your configurations in the persistent layer and can be loaded using oracle.json. This process is detailed in the following section with the help of two configuration options.

Session time out

The key for this config is "key_session_time_out" and the value for this config should be greater than 0 and less than 10,000

Debug mode

The key for this config is "key_debug_mode" and the value for this config should be "true" or "false".

enum MyModuleConfig implements IORAConfigSetting {
 
SESSION_TIME_OUT("key_session_time_out","Session Time Out","5000",new ConfigValidator() {
@Override
public boolean isValid(String value) {
int intVal = Integer.parseInt(value);
return (intVal > 0 && intVal < 10000);
}
}),
DEBUG_MODE("key_debug_mode","Debug Mode","false",new ConfigValidator() {
@Override
public boolean isValid(String value) {
try {
Boolean.parseBoolean(value);
return true;
} catch (Exception e) {
return false;
}
}
});
 
private String keyName;
private String keyDescription;
private String defaultValue;
private ConfigValidator configValidator;
 
MyModuleConfig(String keyName, String keyDescription, String defaultValue, ConfigValidator configValidator) {
this.keyName = keyName;
this.keyDescription = keyDescription;
this.defaultValue = defaultValue;
this.configValidator = configValidator;
}
 
@Override
public boolean isValid(String value) {
return configValidator.isValid(value);
}
 
@Override
public String getDefault(Context context) {
return defaultValue;
}
 
@Override
public String keyName() {
return keyName;
}
 
@Override
public String keyDescription() {
return keyDescription;
}
}
 
interface ConfigValidator {
boolean isValid(final String value);
}

Extend the ORABaseDataContainer class

The Core module provides an abstract class ORABaseDataContainer to create the class required to store and retrieve the module configuration. The class has two abstract methods that can be used for this purpose.

Implement getModuleID()

Every module needs a module ID as a unique identifier. This module ID is used to store configurations for the module. This method should return an alphanumeric string. Failure to implement this method returns a ORAModuleIDException

For this example let the module ID be MY_MODULE

Implement getConfig(String key)

This method helps to parse the oracle.json file. The input for the method is a key string of the configuration. The method should return relevant config based on the passed key string.

You can implement the above two methods as shown in the following section.

public MyModuleDataContainer(Context context) {
super(context);
}
 
@Override
public String getModuleID() {
return "MY_MODULE";
}
 
@Override
public IORAConfigSetting getConfig(String key) {
if (key.equalsIgnoreCase("key_session_time_out")) {
return MyModuleConfig.SESSION_TIME_OUT;
} else if (key.equalsIgnoreCase("key_debug_mode")) {
return MyModuleConfig.DEBUG_MODE;
} else {
return null;
}
}
}

Add / Update config

Storing configuration in the module.

1. Using oracle.json file

Once you implemented MyModuleDataContainer, now you can use oracle.json to add the configuration. You can add your module specific configuration data to json file under your module id. Below is the sample json file to store your module config data.

{
"config_version": "1.0",
"ORACORE": {
...
"ora_dc_send_interval_millis": "24000",
"ora_dc_enabled": "true",
...
},
 
"MY_MODULE": {
"key_session_time_out": "5000",
"key_debug_mode": "true"
}
}

As you can see in above example, we added our configurations under MY_MODULE. This module id should match with the module id which is returned in getModuleID() method.

To load this configuration for oracle.json, you need to call loadFromConfigFile().

MyModuleDataContainer moduleDataContainer = new MyModuleDataContainer(this);
moduleDataContainer.loadFromConfigFile();

If you want to update any configuration value, update its value and increment the config_version value. You can find more details on how the config_version works in this section.

2. Using putValue() and getValue() methods

The other way to update the configuration is to use putValue() method. You can access the them by using getValue() method.

MyModuleDataContainer moduleDataContainer = new MyModuleDataContainer(this);
boolean isSuccess = moduleDataContainer.putValue(MyModuleConfig.SESSION_TIME_OUT, "6000");
if(isSuccess) {
Log.d(TAG, "Config updated successfully");
}
MyModuleDataContainer moduleDataContainer = new MyModuleDataContainer(this);
String value = moduleDataContainer.getValue(MyModuleConfig.SESSION_TIME_OUT);
Log.d(TAG, "Session time out value is " + value);

Important: The Module ID allows only alphanumeric characters. No special characters are allowed. If there are any invalid module IDs (empty or nil), the app will be terminated.

Difference between oracle.json and putValue() method

The oracle.json file is provided to store all modules config data at a centralized place. The config data in this file will be loaded based on the config_version value. The new values updated in the config file will be stored if the config_version value is greater than previous version. At the same time putValue() method also can be used to modify the config value at run time.

Here putValue() method has the highest priority than oracle.json. Which means, if any config value which is presented in oracle.json file is updated using putValue() method, the oracle.json file value will be overridden with new value.