Configurations

How to create and read configuration information.

Key takeaways

ConfigParams A container for configuration parameters in the form of a dictionary.
NameResovler Helper class that can be used to extract the value related to a parameter called "name" or "id".
OptionsResolver Helper class that can be used to obtain all the names of the parameters under the "options" section of a ConfigParams object.

Introduction

In this tutorial, we will see how to create configurations using the ConfigParams class, and how to read those configurations when they contain a parameter called “name” or “id”, and when they have an “options” section.

ConfigParams

This class provides a container for configuration parameters in the form of a dictionary. The configuration parameters can be broken into sections and subsections using dot notation, such as section1.subsection1.param1".

Pre-requisites

To use the ConfigParams class we need to import it with the following command.

import { ConfigParams } from "pip-services3-commons-nodex"


using PipServices3.Commons.Config;


import (
	conf "github.com/pip-services3-gox/pip-services3-commons-gox/config"
)

import 'package:pip_services3_commons/pip_services3_commons.dart';


from pip_services3_commons.config import ConfigParams
Not available

Create

There are several ways to create a ConfigParams object such as from the class' constructor, a tuple, a string, or an object containing key:value pairs. The examples below show how to do this.

// Example: create a ConfigParams object containing {'section1.key1': 'AAA', 'section1.key2': '123', 'section2.key1': 'True'}

// Constructor

let myDict = { "section1.key1": "AAA", "section1.key2": 123, "section2.key1": true };
let config1 = new ConfigParams(myDict);

// Tuple
let config2 = ConfigParams.fromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true);

// String
let config3 = ConfigParams.fromString("section1.key1=AAA;section1.key2=123;section2.key1=True");

// Object containing key:value pairs
myDict = { "section1.key1": "AAA", "section1.key2": 123, "section2.key1": true };
let config4 = ConfigParams.fromValue(myDict);


// Example: create a ConfigParams object containing {'section1.key1': 'AAA', 'section1.key2': '123', 'section2.key1': 'True'}

// Constructor

var myDict = new Dictionary<string, string> { { "section1.key1", "AAA"}, { "section1.key2", "123" }, { "section2.key1", "true " } };
var config1 = new ConfigParams(myDict);

// Tuple
var config2 = ConfigParams.FromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true);

// String
var config3 = ConfigParams.FromString("section1.key1=AAA;section1.key2=123;section2.key1=True");

// Object containing key:value pairs
myDict = new Dictionary<string, string> { { "section1.key1", "AAA"}, { "section1.key2", "123"}, { "section2.key1", "true"}};
var config4 = ConfigParams.FromValue(myDict);


// Example: create a ConfigParams object containing {'section1.key1': 'AAA', 'section1.key2': '123', 'section2.key1': 'True'}

// Constructor

myDict := map[string]string{"section1.key1": "AAA", "section1.key2": "123", "section2.key1": "true"}
config1 := conf.NewConfigParams(myDict)

// Tuple
config2 := conf.NewConfigParamsFromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true)

// String
config3 := conf.NewConfigParamsFromString("section1.key1=AAA;section1.key2=123;section2.key1=true")

// Object containing key:value pairs
myDict = map[string]string{"section1.key1": "AAA", "section1.key2": "123", "section2.key1": "true"}
config4 := conf.NewConfigParamsFromValue(myDict)

// Example: create a ConfigParams object containing {'section1.key1': 'AAA', 'section1.key2': '123', 'section2.key1': 'True'}

// Constructor

var myDict = {
  'section1.key1': 'AAA',
  'section1.key2': 123,
  'section2.key1': true
};
var config1 = ConfigParams(myDict);

// Tuple
var config2 = ConfigParams.fromTuples(['section1.key1', 'AAA', 'section1.key2', 123, 'section2.key1', true]);

// String
var config3 = ConfigParams.fromString('section1.key1=AAA;section1.key2=123;section2.key1=True');

// Object containing key:value pairs
myDict = {
  'section1.key1': 'AAA',
  'section1.key2': 123,
  'section2.key1': true
};
var config4 = ConfigParams.fromValue(myDict);


# Example: create a ConfigParams object containing {'section1.key1': 'AAA', 'section1.key2': '123', 'section2.key1': 'True'}

from pip_services3_commons.config import ConfigParams

# Constructor

my_dict = {"section1.key1": "AAA", "section1.key2": 123, "section2.key1": True}
config1 = ConfigParams(my_dict)  

# Tuple
config2 = ConfigParams.from_tuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", True)

# String
config3 = ConfigParams.from_string("section1.key1=AAA;section1.key2=123;section2.key1=True")

# Object containing key:value pairs
my_dict = {"section1.key1": "AAA", "section1.key2": 123, "section2.key1": True} 
config4 = ConfigParams. from_value(my_dict)
Not available

Add a new section

Once we have created a ConfigParams object, we can add a new section with the add_section() method. This method takes two parameters: the name of the new section and a ConfigParams object containing the key:value pairs for the added section. The example below shows how to use this method.

// Add a new section 
let config = ConfigParams.fromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true);
config.addSection("section3", ConfigParams.fromTuples("key1", "ABCDE"));



// Add a new section 
var config = ConfigParams.FromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true);
config.AddSection("section3", ConfigParams.FromTuples("key1", "ABCDE"));



// Add a new section
config := conf.NewConfigParamsFromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true)
config.AddSection("section3", conf.NewConfigParamsFromTuples("key1", "ABCDE"))


// Add a new section
var config = ConfigParams.fromTuples(['section1.key1', 'AAA', 'section1.key2', 123, 'section2.key1', true]);
config.addSection('section3', ConfigParams.fromTuples(['key1', 'ABCDE']));



# Add a new section 
config = ConfigParams.from_tuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", True)
config.add_section("section3", ConfigParams.from_tuples("key1", "ABCDE"))
Not available

As a result, the config object will now contain the following items:

figure 1

Get a section’s parameters

We can get a section’s parameters with the get_section() method, which requires the section’s name as input parameter. The following example shows how to use it.

let config = ConfigParams.fromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true);
let section1 = config.getSection("section1");      // Returns {'key1': 'AAA', 'key2': '123'} 


var config = ConfigParams.FromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true);
var section1 = config.GetSection("section1");      // Returns {'key1': 'AAA', 'key2': '123'} 


// Add a new section
config := conf.NewConfigParamsFromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true)
section1 := config.GetSection("section1") // Returns {'key1': 'AAA', 'key2': '123'}

var config = ConfigParams.fromTuples(['section1.key1', 'AAA', 'section1.key2', 123, 'section2.key1', true]);
var section1 = config.getSection('section1'); // Returns {'key1': 'AAA', 'key2': '123'}


config = ConfigParams.from_tuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", True)                   
section1 = config.get_section("section1")       # Returns {'key1': 'AAA', 'key2': '123'}
Not available

List all sections

To list the names of all the sections contained in a ConfigParams object, we can use the get_section_names() method. The following example shows how to use it.

let config = ConfigParams.fromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true);
config.getSectionNames();      // Returns ['section1', 'section2']


var config = ConfigParams.FromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true);
config.GetSectionNames();      // Returns ['section1', 'section2']


config := conf.NewConfigParamsFromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true)
config.GetSectionNames() // Returns ['section1', 'section2']

var config = ConfigParams.fromTuples(['section1.key1', 'AAA', 'section1.key2', 123, 'section2.key1', true]);
config.getSectionNames(); // Returns ['section1', 'section2']


config = ConfigParams.from_tuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", True)
config.get_section_names()      # Returns ['section1', 'section2']
Not available

Merge configurations

We can also merge different configuration sets via the mergeConfigs() method, which accepts two or more ConfigParams objects as input, and merges them into one ConfigParams object. In the following example, we merge three different ConfigParams objects into one containing the configuration sets stored in the three merged objects.

let additionalConfig1 = ConfigParams.fromTuples(
    "my_store1.user", "jdoe",
    "my_store1.password", "pass123",
    "my_store1.pin", "321"
);

let additionalConfig2 = ConfigParams.fromTuples(
    "my_store2.user", "David",
    "my_store2.password", "another_pass",
    "my_store2.pin", "0000"
);

let additionalConfig3 = ConfigParams.fromTuples(
    "param1", "value1"
);
    
let config = ConfigParams.mergeConfigs(additionalConfig1, additionalConfig2, additionalConfig3);
console.log(config);


using System;
using PipServices3.Commons.Config;

var additionalConfig1 = ConfigParams.FromTuples(
    "my_store1.user", "jdoe",
    "my_store1.password", "pass123",
    "my_store1.pin", "321"
);

var additionalConfig2 = ConfigParams.FromTuples(
    "my_store2.user", "David",
    "my_store2.password", "another_pass",
    "my_store2.pin", "0000"
);

var additionalConfig3 = ConfigParams.FromTuples(
    "param1", "value1"
);

var config = ConfigParams.MergeConfigs(additionalConfig1, additionalConfig2, additionalConfig3);    

Console.WriteLine(config);


import (
	"fmt"

	cconf "github.com/pip-services3-gox/pip-services3-commons-gox/config"
)

additionalConfig1 := cconf.NewConfigParamsFromTuples(
	"my_store1.user", "jdoe",
	"my_store1.password", "pass123",
	"my_store1.pin", "321",
)

additionalConfig2 := cconf.NewConfigParamsFromTuples(
	"my_store2.user", "David",
	"my_store2.password", "another_pass",
	"my_store2.pin", "0000",
)

additionalConfig3 := cconf.NewConfigParamsFromTuples(
	"param1", "value1",
)

config := cconf.NewConfigParamsFromMaps(additionalConfig1.Value(), additionalConfig2.Value(), additionalConfig3.Value())

fmt.Println(config)


import 'package:pip_services3_commons/pip_services3_commons.dart';

var additionalConfig1 = ConfigParams.fromTuples([
  'my_store1.user', 'jdoe',
  'my_store1.password', 'pass123',
  'my_store1.pin', '321'
]);

var additionalConfig2 = ConfigParams.fromTuples([
  'my_store2.user', 'David',
  'my_store2.password', 'another_pass',
  'my_store2.pin', '0000'
]);

var additionalConfig3 = ConfigParams.fromTuples(['param1', 'value1']);
var config = ConfigParams.mergeConfigs([additionalConfig1, additionalConfig2, additionalConfig3]);

print(config);


from pip_services3_commons.config import ConfigParams

additional_config1 = ConfigParams.from_tuples("my_store1.user", "jdoe",
                                              "my_store1.password", "pass123",
                                              "my_store1.pin", "321")

additional_config2 = ConfigParams.from_tuples("my_store2.user", "David",
                                              "my_store2.password", "another_pass",
                                              "my_store2.pin", "0000")

additional_config3 = ConfigParams.from_tuples('param1', 'value1')

config = ConfigParams.merge_configs(additional_config1, additional_config2, additional_config3)

config
Not available

figure 2

Resolvers

Pip.Services offers two helper classes that can be used to extract the value associated with the “name” and “id” parameters, and the key:value pairs of an “options” section. These classes are NameResolver and OptionsResolvers. This section explains their usage.

Name resolver

This is a helper class that can be used to extract the value related to a parameter called “name” or “id”.

Pre-requisites

In order to use this class, we must first import it. The following command shows how to do this.

import { NameResolver } from "pip-services3-commons-nodex"

using PipServices3.Commons.Config;

import (
	conf "github.com/pip-services3-gox/pip-services3-commons-gox/config"
)

import 'package:pip_services3_commons/pip_services3_commons.dart';

from pip_services3_commons.config import NameResolver
Not available
Resolve

This class has only one method named resolve(), which returns the value of a parameter called “named” or “id” from a ConfigParams object. If both parameters exist in the same object, it returns the value of the “name” parameter. In addition, given a parameter named “descriptor” containing a string with a Descriptor form, it returns the value of the “name” parameter of such descriptor. Examples of its usage are:

// name
let config = ConfigParams.fromTuples("name", "myservice:connector:aws:connector1:1.0",
    "param1", "ABC",
    "param2", 123);
let name = NameResolver.resolve(config); // Returns myservice:connector:aws:connector1:1.0

// id
config = ConfigParams.fromTuples("id", "myservice:connector:aws:connector1:1.0",
    "param1", "ABC",
    "param2", 123);
let id = NameResolver.resolve(config);  // Returns myservice:connector:aws:connector1:1.0

// If name cannot be determined

config = ConfigParams.fromTuples("param1", "ABC", "param2", 123);
name = NameResolver.resolve(config); // Returns null
name = NameResolver.resolve(config, "default name"); //Returns "default name"

// name and id
config = ConfigParams.fromTuples("name", "my_name", "id", "my id",
    "param1", "ABC",
    "param2", 123);
let result = NameResolver.resolve(config); // Returns "my_name"

// descriptor
// Note: A descriptor class has the following parameters: "group", "type", "kind", "name", "version"
//       Name resolver will extract the value of the "name" parameter.

config = ConfigParams.fromTuples("descriptor", "myservice:connector:aws:connector1:1.0",
    "param1", "ABC",
    "param2", 123);
name = NameResolver.resolve(config); // Returns connector1


// name
var config = ConfigParams.FromTuples("name", "myservice:connector:aws:connector1:1.0",
                                         "param1", "ABC",
                                         "param2", 123);
var name = NameResolver.Resolve(config); // Returns myservice:connector:aws:connector1:1.0

// id
config = ConfigParams.FromTuples("id", "myservice:connector:aws:connector1:1.0",
                             "param1", "ABC",
                             "param2", 123);
var id = NameResolver.Resolve(config);  // Returns myservice:connector:aws:connector1:1.0

// If name cannot be determined

config = ConfigParams.FromTuples("param1", "ABC",
                                         "param2", 123);
name = NameResolver.Resolve(config); // Returns null
name = NameResolver.Resolve(config, "default name"); //Returns "default name"

// name and id
config = ConfigParams.FromTuples("name", "my_name", "id", "my id",
                                         "param1", "ABC",
                                         "param2", 123);
var result = NameResolver.Resolve(config); // Returns "my_name"

// descriptor
// Note: A descriptor class has the following parameters: "group", "type", "kind", "name", "version"
//       Name resolver will extract the value of the "name" parameter.

config = ConfigParams.FromTuples("descriptor", "myservice:connector:aws:connector1:1.0",
                                 "param1", "ABC",
                                 "param2", 123);
name = NameResolver.Resolve(config); // Returns connector1


// name
config := conf.NewConfigParamsFromTuples("name", "myservice:connector:aws:connector1:1.0",
	"param1", "ABC",
	"param2", 123)
name := conf.NameResolver.Resolve(config) // Returns myservice:connector:aws:connector1:1.0

// id
config = conf.NewConfigParamsFromTuples("id", "myservice:connector:aws:connector1:1.0",
	"param1", "ABC",
	"param2", 123)
id := conf.NameResolver.Resolve(config) // Returns myservice:connector:aws:connector1:1.0

// If name cannot be determined

config = conf.NewConfigParamsFromTuples("param1", "ABC",
	"param2", 123)
name = conf.NameResolver.Resolve(config)                            // Returns ""
name = conf.NameResolver.ResolveWithDefault(config, "default name") //Returns "default name"

// name and id
config = conf.NewConfigParamsFromTuples("name", "my_name", "id", "my id",
	"param1", "ABC",
	"param2", 123)
result := conf.NameResolver.Resolve(config) // Returns "my_name"

// descriptor
// Note: A descriptor class has the following parameters: "group", "type", "kind", "name", "version"
//       Name resolver will extract the value of the "name" parameter.

config = conf.NewConfigParamsFromTuples("descriptor", "myservice:connector:aws:connector1:1.0",
	"param1", "ABC",
	"param2", 123)
name = conf.NameResolver.Resolve(config) // Returns connector1

// name
var config = ConfigParams.fromTuples([
  'name',
  'myservice:connector:aws:connector1:1.0',
  'param1',
  'ABC',
  'param2',
  123
]);
var name = NameResolver.resolve(config); // Returns myservice:connector:aws:connector1:1.0

// id
config = ConfigParams.fromTuples([
  'id',
  'myservice:connector:aws:connector1:1.0',
  'param1',
  'ABC',
  'param2',
  123
]);
var id = NameResolver.resolve(config); // Returns myservice:connector:aws:connector1:1.0

// If name cannot be determined

config = ConfigParams.fromTuples(['param1', 'ABC', 'param2', 123]);
name = NameResolver.resolve(config); // Returns null
name = NameResolver.resolve(config, 'default name'); //Returns "default name"

// name and id
  config = ConfigParams.fromTuples(['name', 'my_name', 'id', 'my id', 'param1', 'ABC', 'param2', 123]);
  var result = NameResolver.resolve(config); // Returns "my_name"

// descriptor
// Note: A descriptor class has the following parameters: "group", "type", "kind", "name", "version"
//       Name resolver will extract the value of the "name" parameter.

config = ConfigParams.fromTuples([
  'descriptor',
  'myservice:connector:aws:connector1:1.0',
  'param1',
  'ABC',
  'param2',
  123
]);
name = NameResolver.resolve(config); // Returns connector1


# name
config = ConfigParams.from_tuples("name", "myservice:connector:aws:connector1:1.0",
                                         "param1", "ABC",
                                         "param2", 123)
name = NameResolver.resolve(config) # Returns myservice:connector:aws:connector1:1.0

# id
config = ConfigParams.from_tuples("id", "myservice:connector:aws:connector1:1.0",
                                         "param1", "ABC",
                                         "param2", 123)
id = NameResolver.resolve(config)  # Returns myservice:connector:aws:connector1:1.0

# If name cannot be determined

config = ConfigParams.from_tuples("param1", "ABC",
                                         "param2", 123)
name = NameResolver.resolve(config) # Returns None
name = NameResolver.resolve(config,"default name") #Returns "default name"

# name and id
config = ConfigParams.from_tuples("name", "my_name", "id", "my id",
                                         "param1", "ABC",
                                         "param2", 123)
result = NameResolver.resolve(config) # Returns "my_name"

# descriptor
# Note: A descriptor class has the following parameters: "group", "type", "kind", "name", "version"
#       Name resolver will extract the value of the "name" parameter.

config = ConfigParams.from_tuples("descriptor", "myservice:connector:aws:connector1:1.0",
                                 "param1", "ABC",
                                 "param2", 123)
name = NameResolver.resolve(config) # Returns connector1
Not available

Options resolver

This is a helper class that can be used to obtain all the names of the parameters under a section called “options” of a CongifParams object.

Pre-requisites

In order to use this class, we must first import it. The following command shows how to do this.

import { OptionResolver } from "pip-services3-commons-nodex"

using PipServices3.Commons.Config;

import (
	conf "github.com/pip-services3-gox/pip-services3-commons-gox/config"
)

import 'package:pip_services3_commons/pip_services3_commons.dart';

from pip_services3_commons.config import OptionsResolver
Not available
Resolve

This class has only one method named resolve. This method returns the names of the parameters belonging to the “options” section. If the ConfigParams object doesn’t contain an options section and the config_as_defaul parameter is set to False (default value), it returns an empty ConfigParams object. And, if the config_as_default parameter is set to True, it returns the entire parameter set. The examples below show how to use it.

// ConfigParams objec contains an option section

var config = ConfigParams.fromTuples(
    "section1.key1", "AAA",
    "section1.key2", 123,
    "options.param1", "ABC",
    "options.param2", 234);

var options = OptionResolver.resolve(config); // Returns {'param1': 'ABC', 'param2': '234'}

// ConfigParams object doesn't contain an "options" section
config = ConfigParams.fromTuples(
    "section1.key1", "AAA",
    "section1.key2", 123
);

options = OptionResolver.resolve(config, false); // Returns null

// ConfigParams object doesn't contain an "options" section, and the config_as_default parameter is set to True.
config = ConfigParams.fromTuples(
    "section1.key1", "AAA",
    "section1.key2", 123
);

options = OptionResolver.resolve(config, true); // Returns {'section1.key1': 'AAA', 'section1.key2': '123'}


// ConfigParams objec contains an option section

var config = ConfigParams.FromTuples(
          "section1.key1", "AAA",
          "section1.key2", 123,
          "options.param1", "ABC",
          "options.param2", 234);

var options = OptionsResolver.Resolve(config); // Returns {'param1': 'ABC', 'param2': '234'}

// ConfigParams object doesn't contain an "options" section
config = ConfigParams.FromTuples(
    "section1.key1", "AAA",
    "section1.key2", 123
);

options = OptionsResolver.Resolve(config, false); // Returns null

// ConfigParams object doesn't contain an "options" section, and the config_as_default parameter is set to True.
config = ConfigParams.FromTuples(
    "section1.key1", "AAA",
    "section1.key2", 123
);

options = OptionsResolver.Resolve(config, true); // Returns {'section1.key1': 'AAA', 'section1.key2': '123'}


// ConfigParams objec contains an option section

config := conf.NewConfigParamsFromTuples(
	"section1.key1", "AAA",
	"section1.key2", 123,
	"options.param1", "ABC",
	"options.param2", 234)

options := conf.OptionsResolver.Resolve(config) // Returns {'param1': 'ABC', 'param2': '234'}

// ConfigParams object doesn't contain an "options" section
config = conf.NewConfigParamsFromTuples(
	"section1.key1", "AAA",
	"section1.key2", 123,
)
options = conf.OptionsResolver.Resolve(config) // Returns {}

// ConfigParams object doesn't contain an "options" section, and the config_as_default parameter is set to True.
config = conf.NewConfigParamsFromTuples(
	"section1.key1", "AAA",
	"section1.key2", 123,
)
options = conf.OptionsResolver.ResolveWithDefault(config) // Returns {'section1.key1': 'AAA', 'section1.key2': '123'}

// ConfigParams objec contains an option section

var config = ConfigParams.fromTuples([
  'section1.key1',
  'AAA',
  'section1.key2',
  123,
  'options.param1',
  'ABC',
  'options.param2',
  234
]);

var options = OptionResolver.resolve(config); // Returns {'param1': 'ABC', 'param2': '234'}

// ConfigParams object doesn't contain an "options" section
config = ConfigParams.fromTuples(['section1.key1', 'AAA', 'section1.key2', 123]);

options = OptionResolver.resolve(config, false); // Returns null

// ConfigParams object doesn't contain an "options" section, and the config_as_default parameter is set to True.
config = ConfigParams.fromTuples(['section1.key1', 'AAA', 'section1.key2', 123]);

options = OptionResolver.resolve(config, true); // Returns {'section1.key1': 'AAA', 'section1.key2': '123'}
}


# ConfigParams objec contains an option section

config = ConfigParams.from_tuples(
          "section1.key1", "AAA",
          "section1.key2", 123,
          "options.param1", "ABC",
          "options.param2", 234)

options = OptionsResolver.resolve(config) # Returns {'param1': 'ABC', 'param2': '234'}

# ConfigParams object doesn't contain an "options" section
config = ConfigParams.from_tuples(
          "section1.key1", "AAA",
          "section1.key2", 123,
          )
options = OptionsResolver.resolve(config) # Returns {}

# ConfigParams object doesn't contain an "options" section, and the config_as_default parameter is set to True.
config = ConfigParams.from_tuples(
          "section1.key1", "AAA",
          "section1.key2", 123,
          )
options = OptionsResolver.resolve(config, True) # Returns {'section1.key1': 'AAA', 'section1.key2': '123'}
Not available

Wrapping up

In this tutorial, we have seen how to define configuration parameters by using the ConfigParams class. We have also seen how to use two helper classes namely, NameResolver and OptionsResolver, which can be used to obtain the value related to a parameter called “name” or “id” and the parameters under an “options” section respectively.