Configuring connections
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"
import (
conn "github.com/pip-services4/pip-services4-go/pip-services4-config-go/connect"
)
from pip_services4_config.connect import ConnectionParams
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'}
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'}
``
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'}
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'}
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'}
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'}
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'}
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'}
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'}
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'}
connection := conn.NewConnectionParamsFromTuples(
"protocol", "http",
"host", "localhost",
"port", "8080",
"cluster", "mycluster",
)
// Returns {'protocol': 'http', 'host': 'localhost', 'port': '8080', 'cluster': 'mycluster'}
connection = ConnectionParams.from_tuples("protocol", "http", "host", "localhost", "port", "8080", "cluster", "mycluster")
# Returns {'protocol': 'http', 'host': 'localhost', 'port': '8080', 'cluster': 'mycluster'}
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'}
connection := conn.NewConnectionParamsFromString("uri=abc2.com;protocol=http123") // Returns {'uri': 'abc2.com', 'protocol': 'http123'}
connection = ConnectionParams.from_string("uri=abc2.com;protocol=http123") # Returns {'uri': 'abc2.com', 'protocol': 'http123'}
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'}
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'}
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'}
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'}]
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'}]
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'}]
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'}
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'}
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'}
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'
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"
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'
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")
connection.Get("uri")
connection.get('uri')
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'}
section := connection.GetSection("sectionA") // Returns {'key1': 'ABCDE'}
section = connection.get_section("sectionA") # Returns {'key1': 'ABCDE'}
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']
connection.GetSectionNames()
// Returns
// ['discovery_key',
// 'host',
// 'port',
// 'protocol',
// 'uri',
// 'parameter_name',
// 'sectionA']
connection.get_section_names()
# Returns
#['discovery_key',
# 'host',
# 'port',
# 'protocol',
# 'uri',
# 'parameter_name',
# 'sectionA']
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");
connection.SetHost("new host")
connection.set_host("new host")
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");
connection.Put("host", "new host")
connection.put("host", "new host")
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'}
overriden := connection.Override(conf.NewConfigParamsFromTuples("host", "new host"))
// Returns
// {'discovery_key': 'discovery key 1',
// 'host': 'new host',
// 'port': '8080',
// 'protocol': 'http',
// 'uri': 'abc.com'}
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'}
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');
overriden.Remove("uri")
connection.remove('uri')
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.