ConnectionProvider Module

# ConnectionProvider Module Introduction

The ConnectionProvider module provides an API for providing pluggable network connections objects to Qore. This module can also be used to provide URL strings from identifiers from registered connection providers as well.

To use this module, use `"%requires ConnectionProvider"` in your code.

All the public symbols in the module are defined in the ConnectionProvider namespace.

Class:

- AbstractConnection

Hashdecls:

- ConfigInfo
- ConnectionInfo
- PingInfo

Functions:

- get_connection()
- get_connection_hash()
- get_connections()
- get_connection_url()

## Connection Provider Modules

This module uses the `"QORE_CONNECTION_PROVIDERS"` environment variable to load connection provider modules. Each connection provider module must provide two public functions with the following signatures:

# returns a ConnectionProvider::AbstractConnection object for the given identifier or throws an exception
public ConnectionProvider::AbstractConnection sub get_mod_connection(string str) {}
# returns a hash keyed by connection identifiers with values as ConnectionProvider::AbstractConnection objects for all connections known to the connection provider
public *hash sub get_mod_connections() {}

Connection provider modules declared in the `"QORE_CONNECTION_PROVIDERS"` environment variable must be separated by the platform-specific PathSep character as in the following examples:

Unix Example

      export QORE_CONNECTION_PROVIDERS=MyConnectionProvider:OtherConnectionProvider

Windows CMD.EXE Example

      set QORE_CONNECTION_PROVIDERS=MyConnectionProvider;OtherConnectionProvider

Windows PowerShell Example

      $env:QORE_CONNECTION_PROVIDERS="MyConnectionProvider;OtherConnectionProvider"

# Release Notes

## ConnectionProvider 1.5

- updated the AbstractConnection::getInfo() method
- added the AbstractConnection::getExtendedInfo() method

## ConnectionProvider 1.4.1

- connection path options are subjected to environment variable substitution (issue 4236)

## ConnectionProvider 1.4

- implemented support for a data provider scheme cache and rich option information for connections (issue 4025)

## ConnectionProvider 1.3

- implemented support for serializing connections and removed the `AbstractConnection::getConstructorInfo()` and `AbstractConnection::getConstructorInfoImpl()` methods (issue 3696)
- implemented support for the data provider API (issue 3545)

## ConnectionProvider 1.2.1

- implemented support for connection tags as the attribute `"tags"` (issue 3486)

## ConnectionProvider 1.2

- the AbstractConnection::constructor() refactoring
- all connection clases have unified constructor
- old constructors and static make() constructors are deprecated
- ConnectionProvider::AbstractConnection::parseUrl() is introduced
- ConnectionProvider::AbstractConnection::getSafeUrl() is not static anymore
- it allows their reimplementation in the inherited class. It can be used to parse strange and unexpected URLs like eg. pure json strings, or Datasource connection strings.

## ConnectionProvider 1.1

- the AbstractConnection::getConstructorInfo() method (and supporting declarations) was added to allow connections to be created dynamically, potentially in another process from a network call (issue 2628)

## ConnectionProvider 1.0.1

- removed unnecessary serialization from ConnectionProvider::AbstractConnection::get() "AbstractConnection::get()" (issue 2880)

## ConnectionProvider 1.0

- the initial version of the ConnectionProvider module