Configuring connections

How to configure connections using Pip.Services.

Key takeaways

ConnectionParams Component used to store connection parameters and their values.
ConfigParams Parent class of ConnectionParams, which provides several useful methods.
StringValueMap Class that defines the output format of the ConnectionParams class.

Introduction

In this tutorial, you will learn how to configure connections with the ConnectionParams component and perform CRUD operations with them. First, we will see different ways to create connections, including using a constructor, a tuple, a string, and a ConfigParams object. Then, we will see how to extract, modify and delete different fields in those connections.

Pre-requisites

In order to use the ConnectionParams component, we must first import it. This can be done with the following command:

import { ConnectionParams } from "pip-services4-config-node"
Not available
import (
	conn "github.com/pip-services4/pip-services4-go/pip-services4-config-go/connect"
)
Not available
from pip_services4_config.connect import ConnectionParams
Not available

CRUD operations

The functionality of a ConnectionParams component can be described as CRUD operations. The following sections explain each of them.

Create

There are several ways to create a ConnectionParams object, such as using a constructor, a tuple, a string and a ConfigParams object.

a) Using the constructor

A ConnectionParams object can be created via its constructor in two different ways. The first is by creating an instance of the ConnectionParams class using as input a ConfigParams object that has the connection parameters and their values. The following example explains how to do this:

import { ConnectionParams } from "pip-services4-config-node"
import { ConfigParams } from "pip-services4-components-node"

let config = ConfigParams.fromTuples("protocol", "http34343", "host", "host123", "uri", "uri321");
let connection = new ConnectionParams(config); // Returns {'protocol': 'http34343', 'host': 'host123', 'uri': 'uri321'}

Not available
import (
	conn "github.com/pip-services4/pip-services4-go/pip-services4-config-go/connect"
)

config := conn.NewConnectionParamsFromTuples(
	"protocol", "http34343", "host", "host123", "uri", "uri321",
)

connection := conn.NewConnectionParams(config.Value()) // Returns {'protocol': 'http34343', 'host': 'host123', 'uri': 'uri321'}

``

Not available
from pip_services4_components.config import ConfigParams

config = ConfigParams.from_tuples("protocol",  "http34343", "host", "host123", "uri", "uri321")
connection = ConnectionParams(config) # Returns {'protocol': 'http34343', 'host': 'host123', 'uri': 'uri321'}
Not available

In the second approach, we instantiate this class without any input and then we set the values of the most common parameters via their respective set methods. For example:

let connection = new ConnectionParams();

connection.setDiscoveryKey("discovery key 1");
connection.setHost("localhost");
connection.setPort(8080);
connection.setProtocol("http");
connection.setUri("abc.com");

console.log(connection);  // Returns {'discovery_key': 'discovery key 1', 'host': 'localhost', 'port': '8080', 'protocol': 'http', 'uri': 'abc.com'}


Not available
connection := conn.NewEmptyConnectionParams()

connection.SetDiscoveryKey("discovery key 1")
connection.SetHost("localhost")
connection.SetPort(8080)
connection.SetProtocol("http")
connection.SetUri("abc.com")

fmt.Println(connection)  // Returns {'discovery_key': 'discovery key 1', 'host': 'localhost', 'port': '8080', 'protocol': 'http', 'uri': 'abc.com'}
Not available
connection = ConnectionParams()

connection.set_discovery_key("discovery key 1")
connection.set_host("localhost")
connection.set_port("8080")
connection.set_protocol("http")
connection.set_uri("abc.com")

connection  # Returns {'discovery_key': 'discovery key 1', 'host': 'localhost', 'port': '8080', 'protocol': 'http', 'uri': 'abc.com'}
Not available

Or, we can add new parameters and their values using the put() method from the StringValueMap class.

connection.put("parameter_name", "paramter_value");
// connection: {'discovery_key': 'discovery key 1',
// 'host': 'localhost',
// 'port': '8080',
// 'protocol': 'http',
// 'uri': 'abc.com',
// 'parameter_name': 'paramter_value'}

Not available
connection.Put("parameter_name", "paramter_value")
// connection: {'discovery_key': 'discovery key 1',
// 'host': 'localhost',
// 'port': '8080',
// 'protocol': 'http',
// 'uri': 'abc.com',
// 'parameter_name': 'paramter_value'}
Not available
connection.put('parameter_name', 'paramter_value') 
# connection: {'discovery_key': 'discovery key 1',
# 'host': 'localhost',
# 'port': '8080',
# 'protocol': 'http',
# 'uri': 'abc.com',
# 'parameter_name': 'paramter_value'}
Not available
b) Using a tuple

In this case, we declare our parameters and their values in a tuple and use the fromTuples() method. The following example shows how to do this:

let connection = ConnectionParams.fromTuples("protocol", "http", "host", "localhost", "port", "8080", "cluster", "mycluster");
// Returns {'protocol': 'http', 'host': 'localhost', 'port': '8080', 'cluster': 'mycluster'}

Not available
connection := conn.NewConnectionParamsFromTuples(
	"protocol", "http", 
	"host", "localhost", 
	"port", "8080", 
	"cluster", "mycluster",
)
// Returns {'protocol': 'http', 'host': 'localhost', 'port': '8080', 'cluster': 'mycluster'}
Not available
connection = ConnectionParams.from_tuples("protocol", "http", "host", "localhost", "port", "8080", "cluster", "mycluster")
# Returns {'protocol': 'http', 'host': 'localhost', 'port': '8080', 'cluster': 'mycluster'}
Not available
c) Using a string

Similar to the previous one, here we define the parameters and their values with a string and use the fromString() method.

The syntax of the string is:

parameterName = parameterValue

where different parameters are separated by commas.

An example is:

let connection = ConnectionParams.fromString("uri=abc2.com;protocol=http123"); // Returns {'uri': 'abc2.com', 'protocol': 'http123'}

Not available
connection := conn.NewConnectionParamsFromString("uri=abc2.com;protocol=http123") // Returns {'uri': 'abc2.com', 'protocol': 'http123'}
Not available
connection = ConnectionParams.from_string("uri=abc2.com;protocol=http123") # Returns {'uri': 'abc2.com', 'protocol': 'http123'}
Not available
d) Using a ConfigParams object

In this case, we use a ConfigParams object to define the different parameters and their values. Besides, to differentiate the connection parameters from others, we need to use a connection section.

The syntax is

connection.parameterName

And, an example of its usage is:

let config = ConfigParams.fromTuples(
    "connection.protocol", "http34343", 
    "connection.host", "host123", 
    "connection.uri", "uri321"
);
let connection = ConnectionParams.fromConfig(config); // Returns {'protocol': 'http34343', 'host': 'host123', 'uri': 'uri321'}

Not available
import (
	conf "github.com/pip-services4/pip-services4-go/pip-services4-components-go/config"
	conn "github.com/pip-services4/pip-services4-go/pip-services4-config-go/connect"
)


config := conf.NewConfigParamsFromTuples(
	"connection.protocol", "http34343",
	"connection.host", "host123",
	"connection.uri", "uri321",
)
connection := conn.NewConnectionParamsFromConfig(config) // Returns {'protocol': 'http34343', 'host': 'host123', 'uri': 'uri321'}

Not available
from pip_services4_components.config import ConfigParams

config = ConfigParams.from_tuples("connection.protocol",  "http34343", 
                                   "connection.host", "host123", 
                                   "connection.uri", "uri321")
connection = ConnectionParams.from_config(config) # Returns {'protocol': 'http34343', 'host': 'host123', 'uri': 'uri321'}
Not available

Similar to the above, the manyFromConfig() method allows us to manage more than one set of connection parameters. To do this, we define the different connection sets in a section named connections. The syntax is:

connections.connectionName.parameterName

As we can see in the next example, the ConfigParam object can also include other types of parameters, such as credentials. Once, instantiated, the ConnectionParams object only takes the parameters under the connections section and creates a list containing them and their values.

let config = ConfigParams.fromTuples(
    // use connection if one connection and connections if more than one connection
    "connections.connection1.uri", "http://www.example1.com",
    "connections.connection1.protocol", "http",
    "connections.connection1.host", "host152",
    "connections.connection1.my_conn_parameter", "value1",
    "connections.connection2.uri", "http://www.example2.com",
    "connections.connection2.protocol", "http",
    "connections.connection2.host", "host153",
    "connections.connection2.my_conn_parameter", "value3",
    // use credential if one credential and credentials if more than one credential
    "credentials.database1.username", "user1",
    "credentials.database1.password", "userpass123",
    "credentials.database2.username", "user2",
    "credentials.database2.password", "userpass457",
    "credentials.database2.my_custom_credential_param", "myvalue"
);

let connections = ConnectionParams.manyFromConfig(config);

// Returns a list with all connections

// [{'uri': 'http://www.example.com', 'protocol': 'http', 'host': 'host15', 'my_conn_parameter': 'value1'},
// {'uri': 'http://www.example2.com', 'protocol': 'http', 'host': 'host153', 'my_conn_parameter': 'value3'}]

Not available
config := conf.NewConfigParamsFromTuples(
	// use connection if one connection and connections if more than one connection
	"connections.connection1.uri", "http://www.example1.com",
	"connections.connection1.protocol", "http",
	"connections.connection1.host", "host152",
	"connections.connection1.my_conn_parameter", "value1",
	"connections.connection2.uri", "http://www.example2.com",
	"connections.connection2.protocol", "http",
	"connections.connection2.host", "host153",
	"connections.connection2.my_conn_parameter", "value3",
	// use credential if one credential and credentials if more than one credential
	"credentials.database1.username", "user1",
	"credentials.database1.password", "userpass123",
	"credentials.database2.username", "user2",
	"credentials.database2.password", "userpass457",
	"credentials.database2.my_custom_credential_param", "myvalue",
)

connection := conn.NewManyConnectionParamsFromConfig(config)

// Returns a list with all connections

// [{'uri': 'http://www.example.com', 'protocol': 'http', 'host': 'host15', 'my_conn_parameter': 'value1'},
// {'uri': 'http://www.example2.com', 'protocol': 'http', 'host': 'host153', 'my_conn_parameter': 'value3'}]
Not available
config = ConfigParams.from_tuples(
    # use connection if one connection and connections if more than one connection
    "connections.connection1.uri", "http://www.example1.com",
    "connections.connection1.protocol", "http",
    "connections.connection1.host", "host152",
    "connections.connection1.my_conn_parameter", "value1",
    "connections.connection2.uri", "http://www.example2.com",
    "connections.connection2.protocol", "http",
    "connections.connection2.host", "host153",
    "connections.connection2.my_conn_parameter", "value3",
    # use credential if one credential and credentials if more than one credential
    "credentials.database1.username", "user1",
    "credentials.database1.password", "userpass123",
    "credentials.database2.username", "user2",
    "credentials.database2.password", "userpass457",
    "credentials.database2.my_custom_credential_param", "myvalue"
)

connections = ConnectionParams.many_from_config(config) 

# Returns a list with all connections

# [{'uri': 'http://www.example.com', 'protocol': 'http', 'host': 'host15', 'my_conn_parameter': 'value1'},
# {'uri': 'http://www.example2.com', 'protocol': 'http', 'host': 'host153', 'my_conn_parameter': 'value3'}]
Not available
Adding sections

We can add different sections to our ConnectionParamter object by using the addSection() method, which takes the name of the new section and its components as inputs.

connections[0].addSection("sectionA", ConfigParams.fromTuples("key1", "ABCDE"));
// connection: 
// {'discovery_key': 'discovery key 1',
// 'host': 'localhost',
// 'port': '8080',
// 'protocol': 'http',
// 'uri': 'abc.com',
// 'parameter_name': 'paramter_value',
// 'sectionA.key1': 'ABCDE'}
Not available
connection.AddSection("sectionA", conf.NewConfigParamsFromTuples("key1", "ABCDE"))
// connection: 
// {'discovery_key': 'discovery key 1',
// 'host': 'localhost',
// 'port': '8080',
// 'protocol': 'http',
// 'uri': 'abc.com',
// 'parameter_name': 'paramter_value',
// 'sectionA.key1': 'ABCDE'}
Not available
connection.add_section("sectionA", ConfigParams.from_tuples("key1", "ABCDE"))
# Returns 
#{'discovery_key': 'discovery key 1',
# 'host': 'localhost',
# 'port': '8080',
# 'protocol': 'http',
# 'uri': 'abc.com',
# 'parameter_name': 'paramter_value',
# 'sectionA.key1': 'ABCDE'}
Not available

Read

Once our connection parameters have been defined, we can read them via the get methods. Pip.Services offers specific get methods for the most common parameters such as host and port. The examples below show how to use them:

connections[0].getDiscoveryKey();                            // Returns 'discovery key 1'
connections[0].getHost();                                    // Returns 'localhost'
connections[0].getPort();                                    // Returns 8080
connections[0].getPortWithDefault(5050);                     // Returns 8080 or 0000 if port not defined
connections[0].getProtocol();                                // Returns 'http'
connections[0].getProtocolWithDefault("default protocol");   // Returns 'http' or 'default protocol' if protocol field not defined
connections[0].getUri();                                     // Returns 'abc.com'

Not available
connection.DiscoveryKey()                          // Returns "discovery key 1"
connection.Host()                                  // Returns "localhost"
connection.Port()                                  // Returns 8080
connection.PortWithDefault(5050)                   // Returns 8080 or 0000 if port not defined
connection.Protocol()                              // Returns "http"
connection.ProtocolWithDefault("default protocol") // Returns "http" or "default protocol" if protocol field not defined
connection.Uri()                                   // Returns "abc.com"
Not available
connection.get_discovery_key()                           # Returns 'discovery key 1'
connection.get_host()                                    # Returns 'localhost'
connection.get_port()                                    # Returns 8080
connection.get_port_with_default(0000)                   # Returns 8080 or 0000 if port not defined
connection.get_protocol()                                # Returns 'http'
connection.get_protocol_with_default("default protocol") # Returns 'http' or 'default protocol' if protocol field not defined
connection.get_uri()                                     # Returns 'abc.com'                                
Not available

As the ConnectionParams object has the form of a StringValueMap, we can also use the get(‘paramterName’) method, which can be used with any parameter.

connections[0].get("uri")
Not available
connection.Get("uri")
Not available
connection.get('uri')
Not available

Furthermore, we can get all the parameters from a section and their values by using the getSeccion() method. The following example illustrates how to obtain the values from “sectionA”.

let section = connections[0].getSection("sectionA"); // Returns {'key1': 'ABCDE'}
Not available
section := connection.GetSection("sectionA") // Returns {'key1': 'ABCDE'}
Not available
section = connection.get_section("sectionA")  # Returns {'key1': 'ABCDE'}
Not available

And, to get all the section names, we have the getSectionNames() method:

connections[0].getSectionNames() 
// Returns
// ['discovery_key',
// 'host',
// 'port',
// 'protocol',
// 'uri',
// 'parameter_name',
// 'sectionA']
Not available
connection.GetSectionNames()
// Returns
// ['discovery_key',
// 'host',
// 'port',
// 'protocol',
// 'uri',
// 'parameter_name',
// 'sectionA']
Not available
connection.get_section_names()   
# Returns
#['discovery_key',
# 'host',
# 'port',
# 'protocol',
# 'uri',
# 'parameter_name',
# 'sectionA']
Not available

Update

There are three main ways to update the value of a parameter previously defined. The first is to use any of the set methods available for the most common parameters with the new value as its input. For example, for the host, we could do:

connections[0].setHost("new host");
Not available
connection.SetHost("new host")
Not available
connection.set_host("new host")
Not available

The second is to use the put() method from the StringValueMap class with the updated value as its input.

connections[0].put("host", "new host");
Not available
connection.Put("host", "new host")
Not available
connection.put("host", "new host")
Not available

Finally, we can use the override() method, which returns a new instance of ConnectionParams with the old and updated values. The following example explains how to use it:

let overriden = connections[0].override(ConnectionParams.fromTuples("host", "new host"));
// Returns
// {'discovery_key': 'discovery key 1',
// 'host': 'new host',
// 'port': '8080',
// 'protocol': 'http',
// 'uri': 'abc.com'}
Not available
overriden := connection.Override(conf.NewConfigParamsFromTuples("host", "new host"))
// Returns
// {'discovery_key': 'discovery key 1',
// 'host': 'new host',
// 'port': '8080',
// 'protocol': 'http',
// 'uri': 'abc.com'}
Not available
overriden = connection.override(ConfigParams.from_tuples("host", "new host")) 
# Returns
# {'discovery_key': 'discovery key 1',
# 'host': 'new host',
# 'port': '8080',
# 'protocol': 'http',
# 'uri': 'abc.com'}
Not available

Delete

We can remove a parameter and its value from the ConnectionParams object via the remove() method inherited from StringValueMap. The following example shows how to do this:

overriden.remove('uri');
Not available
overriden.Remove("uri")
Not available
connection.remove('uri')
Not available

Wrapping up

In this tutorial, we have learned how to use the ConnectionParams component. We saw how to perform different CRUD operations using this class' methods and the methods inherited from ConfigParams and StringValueMap.