Config Guide

Background

In a large system, we may encounter configurations from different sources. For example, we can store configurations in custom settings, or some custom SObjects. Even we can read configurations from external web services. So configurations are grouped by where they come from, and when we want to use the configs, we need to know their sources. However, what we ideally want is that our configurations are grouped by features and functions, and we don't want to be disturbed by where the configs come from and how we should access the configs. Under this background, we have the idea of building a config system, which provides a unified API that gives a consistent access to our configurations.

Config Service

With the purpose above, we built the Config Service, which behaves pretty much like the http service.

Here are the factors involved in Config Service:

• Config URL A config service provider is bound to a specific config url. A config URL may be an exact String, or a pattern that matches a range of Strings, with variables starting with '$ and ending with '.

• Config Request A request for retrieving or updating the value of the configuration url. Like http requests, we can request a config url like this:

/System/version?type=String

Additional parameters may be specified. Also when it comes to the requests for updating, we can send the data of Map.

Config requests are divided into two types: read(get) and write(put).

• Config Response For read config request, we respond with the value of the config. For write config request, the response is not used.

• Config Handler A config handler is a Func used to process the logic for config requests. Usually we need to specify a config handler for each type of the config request.

Config Service Setup

Config service uses CacheStore to improve performance, so we need an instance of CacheStore to build the config service.

CacheStore store = new CacheStore('PARTITION');
Config configService = new Config(store);

It's recommended that for one application, we use one global config service like this:

public class MyConfig {
    private static Config configService;

    public static Config getConfig() {
        if(configService == null) {
            CacheStore store = new CacheStore('PARTITION_NAME');
            configService = new Config(store);

            // set up the config service
        }

        return configService;
    }
}

During the setup, we need register config handlers.

configService.onRead('/System/version', new SystemVersionFunc());
configService.onWrite('/System/version', new SystemVersionWriteFunc());

Config Handlers

A config handler is actuall a Func.

Here is how we implement a onRead handler.

public class OnReadFunc extends Func {
    public override Object exec(Object arg) {
        Map params = (Map)arg;
        // Custom logic
        return 'config value';
    }
}

The params are collected from the config request. For example, for a config request like this,

Config request
/System/version/1?type=String

params will be collected as:

{ 'number' => '1', 'type' => 'String' }

Here is how we implement a onWrite handler.

public class OnWriteFunc extends Func {
    public override Object exec(Object arg1, Object arg2) {
        Map params = (Map)arg1;
        Map data = (Map)arg2;
        // Custom logic
        return null;
    }
}

Read Configuration

After the config service is set up, we can use it globally to read configurations.

String version = (String)configService.read('/System/version');
// equivalent to
String version = (String)configService.get('/System/version');

By default, we can even specify what kind of data type we want to get.

String version = (String)configService.read('/System/version?type=String');

Config.apex will convert the result configuration value according to the type you specified.

Write Configuration

We can write configurations too, using the config service.

configService.write('/System/version', new Map{
    'value': '1.0.0'
});
// equivalent to
configService.put('/System/version', new Map{
    'value': '1.0.0'
});

We can pass in both params from the request config url and the data of Map.

Constructors

Common Methods

Setup Methods