Overview

The purpose of this document is to guide you on adding a new module configuration. The time the document is written it contains only Core and Infinity modules, where

Core contains the main functionality for storing and sending events to Infinity Data Collection server and any new module should add it as a dependency to communicate to Infinity Data Collector.
Infinity is a module Oracle should provide to the customers as part of Oracle CX Core SDK(based on the agreement made). It has Core as a build dependency and implements main functionalities for Infinity Mobile Analytics.

Following the instructions described below you can add your own module (similar to Infinity) keeping Oracle CX Core principles.

Creating a new module configuration

A new module can have set of different classes with different features & configurations. If you would like to use the oracle.json file to load your configurations, you must follow Oracle CX Core SDK configuration pattern. Below steps guide you to create your own configurations.

1. Implement IORAConfigSetting to define configurations

For the core to store your configurations in persistent layer, all the configurations should be of type IORAConfigSetting. So all your configurations should implement IORAConfigSetting interface.

Assuming you have 2 configurations:

1. Session time out

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

2. Debug mode

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

Now let's see how to implement these configs.

enum MyModuleConfig implements IORAConfigSetting {

                                                                        
    SESSION_TIME_OUT("key_session_time_out",
"Session Time Out",
"5000",
new ConfigValidator() {
                @Override
publicboolean isValid(String value) {
int intVal = Integer.parseInt(value);
return (intVal > 0 && intVal < 10000);
                }
            }),
    DEBUG_MODE("key_debug_mode",
"Debug Mode",
"false",
new ConfigValidator() {
                @Override
publicboolean isValid(String value) {
try {
                        Boolean.parseBoolean(value);
returntrue;
                    } catch (Exception e) {
returnfalse;
                    }
                }
            });

                                                                        

                                                                        
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
publicboolean 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);
}

In the above example code, we used enums for code simplicity. But you can also use normal classes based on your project structure.

2. Create a container by extending ORABaseDataContainer

In above steps we have created configurations which are required for the project. Now we need to create a container to store/retrieve those configurations. Oracle CX Core SDK provides an abstract class ORABaseDataContainer to create our own container class. This class having two abstract methods getModuleID() and getConfig(String key).

Implement getModuleID()

Module id is the unique identifier for the module. This module id is used to store configurations in module level persistent layer. This method should return alpha numeric string. Failing to implement this method leads to ORAModuleIDException

Lets assume, our module id is MY_MODULE

Implement getConfig(String key)

This method plays an important role in parsing 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.

Now lets see how can we implement those two methods in our own container.

class MyModuleDataContainer extends ORABaseDataContainer {

                                                                        
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;
        } elseif (key.equalsIgnoreCase("key_debug_mode")) {
return MyModuleConfig.DEBUG_MODE;
        } else {
return null;
        }
    }
}

3. Add / Update config

Now we are read store our configurations in the persistent layer. There are two ways to store the configurations:

1. Using oracle.json file

Once you implemented MyModuleDataContainer, now you can user 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_end_point_config": [
      {
        "ora_dc_collection_url": "https://dc.oracleinfinity.io/v3/",
        "ora_dc_account_guid": "abcd1234xy",
        "ora_dc_retry_count": 2
      }
    ],
    "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. Below is the sample code.

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);

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

Configuration Guide