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-services4-components-node"
Not available 
import (
	conf "github.com/pip-services4/pip-services4-go/pip-services4-components-go/config"
)
Not available 
from pip_services3_commons.config import NameResolver
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);
Not available 
// 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)
Not available 
# Example: create a ConfigParams object containing {'section1.key1': 'AAA', 'section1.key2': '123', 'section2.key1': 'True'}

from pip_services4_components.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"));
Not available 
// Add a new section
config := conf.NewConfigParamsFromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true)
config.AddSection("section3", conf.NewConfigParamsFromTuples("key1", "ABCDE"))
Not available 
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'}
Not available 
// Get section
config := conf.NewConfigParamsFromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true)
section1 := config.GetSection("section1") // Returns {'key1': 'AAA', 'key2': '123'}
Not available 
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']
Not available 
config := conf.NewConfigParamsFromTuples("section1.key1", "AAA", "section1.key2", 123, "section2.key1", true)
config.GetSectionNames() // Returns ['section1', 'section2']
Not available 
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.

// 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'}
Not available 
import (
	"fmt"

	conf "github.com/pip-services4/pip-services4-go/pip-services4-components-go/config"
)

func main() {
	additionalConfig1 := conf.NewConfigParamsFromTuples(
		"my_store1.user", "jdoe",
		"my_store1.password", "pass123",
		"my_store1.pin", "321",
	)

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

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

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

	fmt.Println(config)
}
Not available 
from pip_services4_components.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.

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);
Not available 
import (
	"fmt"

	conf "github.com/pip-services4/pip-services4-go/pip-services4-components-go/config"
)
Not available 
from pip_services4_components.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:

import { NameResolver } from "pip-services4-components-node"
Not available 
// 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
Not available 
# name
config = ConfigParams.from_tuples("name", "myservice:connector:aws:connector1:1.0",
                                         "param1", "ABC",
                                         "param2", 123)
name1 = 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)
name2 = NameResolver.resolve(config) # Returns None
name3 = 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)
name4 = 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.

// 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
Not available 
import (
	conf "github.com/pip-services4/pip-services4-go/pip-services4-components-go/config"
)
Not available 
from pip_services4_components.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.

import { OptionResolver } from "pip-services4-components-node"
Not available 
// 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'}
Not available 
# 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.