abstract base class for connections More...

Inheritance diagram for ConnectionProvider::AbstractConnection:

[legend]

Public Member Methods
deprecated	constructor (string n_name, string n_desc, string n_url, bool n_monitor, hash n_opts, hash n_urlh, string n_safe_url, *bool n_enabled)
	creates the AbstractConnection object More...

	constructor (string name, string description, string url, hash< auto > attributes={}, hash< auto > options={})
	creates the AbstractConnection object More...

object	get (bool connect=True, *hash< auto > rtopts)
	returns the underlying connection object More...

hash< ConfigInfo >	getConfigHash ()
	returns a ConfigInfo hash of static configuration information about the connection More...

hash< ConnectionSchemeInfo >	getConnectionSchemeInfo ()
	Returns a default ConnectionSchemeInfo hash.

AbstractDataProvider	getDataProvider ()
	returns a data provider object for this connection, if supported More...

*hash< auto >	getDefaultOptions ()
	returns default options

hash< auto >	getExtendedInfo (*hash< auto > opts)
	Returns connection info plus any extended information returned by the connection. More...

hash< ConnectionInfo >	getInfo (*hash< auto > opts)
	returns a ConnectionInfo hash of information about the connection More...

hash< ConnectionInfo >	getInfo (bool with_password=False)
	returns a ConnectionInfo hash of information about the connection More...

*hash< auto >	getOptions ()
	returns static / initialization options

*hash< auto >	getRealOptions ()
	returns options for saving the connection's configuration information

*hash< auto >	getRuntimeOptions ()
	returns runtime options

auto	getTag (string tag)
	returns the value of the given tag or NOTHING if not present

auto	getTagEx (string tag)
	returns the value of the given tag or throws an exception if the tag is not set with a value More...

hash< auto >	getTags ()
	returns all tags associated with the connection

abstract string	getType ()
	returns the string type name for the connection object

bool	hasDataProvider ()
	returns True if the connection returns a data provider with the getDataProvider() method More...

	parseTextOptions ()
	this method is called when parsing connection file definitions from text files when loading into the database More...

hash< PingInfo >	ping (bool throw_exception=False)
	returns a hash with the results of the ping operation More...

Public Attributes
bool	debug_data = False
	debug data flag; to be used an an indication for a higher-level implementation

string	desc
	connection description

bool	enabled = True
	enabled/disabled indicator flag

hash< auto >	internal_info
	internal tags

date	last_check
	date/time of last check/ping

bool	locked = False
	locked/unlocked flag

bool	loopback = False
	set to True for loopback connections

bool	monitor
	monitoring flag

string	name
	connection name

*hash< auto >	opts
	connection options

*hash< auto >	orig_opts
	original connection options

string	safe_url
	"safe" URL (password information removed)

string	status = "not checked"
	status string; in case of a connection error this string will be the error string

hash< auto >	tags = {}
	connection tags; user-defined key-value pairs

bool	up = False
	connection status flag; set by monitoring or explicit pings/connections

date	updated
	date/time of last update

string	url
	connection URL (potentially with password info)

hash< auto >	urlh
	broken down URL hash (as returned by Qore::parse_url())

Static Public Attributes
static *code	post_processing
	optional code for default post-processing of objects created by getImpl(); must take the connection object and the object created as arguments

Private Member Methods
abstract object	getImpl (bool connect=True, *hash< auto > rtopts)
	this method must return the connection object corresponding to the object's configuration More...

string	getSafeUrl (hash< auto > urlh)
	creates a "safe" URL string with password information removed More...

hash< UrlInfo >	parseUrl (string url)
	Parse the URL to a hash. More...

hash< PingInfo >	pingIntern (hash< PingInfo > rv)
	performs the ping by executing get(); returns a PingInfo hash

hash< auto >	validateOptions (hash< auto > options)
	performs options validation in the constructor More...

Private:Internal Member Methods
	constructorInit (string name, string description, string url, hash< auto > attributes, hash< auto > options)
	Common construtor implementation. More...

Detailed Description

abstract base class for connections

this class can be specialized to provide for user-defined connection types

Deprecated:: use AbstractConnectionWithInfo instead

Member Function Documentation

◆ constructor() [1/2]

deprecated ConnectionProvider::AbstractConnection::constructor	(	string	n_name,
		string	n_desc,
		string	n_url,
		bool	n_monitor,
		*hash	n_opts,
		hash	n_urlh,
		*string	n_safe_url,
		*bool	n_enabled
	)

creates the AbstractConnection object

Parameters

n_name	the name of the connection
n_desc	connection description
n_url	connection URL (potentially with password info)
n_monitor	monitoring flag
n_opts	connection options
n_urlh	broken down URL hash (as returned by Qore::parse_url())
n_safe_url	"safe" URL (password information removed); if not set this will be set automatically by calling getSafeUrl()
n_enabled	enabled/disabled flag

◆ constructor() [2/2]

ConnectionProvider::AbstractConnection::constructor	(	string	name,
		string	description,
		string	url,
		hash< auto >	attributes = `{}`,
		hash< auto >	options = `{}`
	)

creates the AbstractConnection object

Parameters

name	the name of the connection
description	connection description
url	connection URL (potentially with password info)
attributes	various attributes; see below
options	connection options

Attributes

Attributes are special flags for given connection - stored as public attributes of the object instance. For now there are:

enabled (bool), default True
monitor (bool), default True
locked (bool), default False
tags (hash), no default value

Exceptions

CONNECTION-OPTION-ERROR missing or invalid connection option

◆ constructorInit()

ConnectionProvider::AbstractConnection::constructorInit	(	string	name,
		string	description,
		string	url,
		hash< auto >	attributes,
		hash< auto >	options
	)

private:internal

Common construtor implementation.

Exceptions

CONNECTION-OPTION-ERROR missing or invalid connection option

◆ get()

object ConnectionProvider::AbstractConnection::get	(	bool	connect = `True`,
		*hash< auto >	rtopts
	)

returns the underlying connection object

calls getImpl() to actually acquire the connection object

◆ getConfigHash()

hash<ConfigInfo> ConnectionProvider::AbstractConnection::getConfigHash ( )

returns a ConfigInfo hash of static configuration information about the connection

Returns: a ConfigInfo hash of static configuration information about the connection

◆ getDataProvider()

AbstractDataProvider ConnectionProvider::AbstractConnection::getDataProvider ( )

returns a data provider object for this connection, if supported

Returns: a data provider object for this connection, if supported

Exceptions

DATA-PROVIDER-ERROR this object does not support the data provider API

This base class method throws a DATA-PROVIDER-ERROR exception by default; to support the data provider API, override this method in child classes

See also: hasDataProvider()

Since: ConnectionProvider 1.3

◆ getExtendedInfo()

hash<auto> ConnectionProvider::AbstractConnection::getExtendedInfo ( *hash< auto > opts )

Returns connection info plus any extended information returned by the connection.

The default implementation in the base class returns the same value as getInfo(*hash<auto>)

Since: ConnectionProvider 1.5

◆ getImpl()

abstract object ConnectionProvider::AbstractConnection::getImpl	(	bool	connect = `True`,
		*hash< auto >	rtopts
	)

privatepure virtual

this method must return the connection object corresponding to the object's configuration

Parameters

connect	if True then the connection should be returned connected (and if possible a round-trip "ping" of the server should be made)
rtopts	if the object acquisition requires any runtime options, then these are passed here

Returns: the connection object

Implemented in ConnectionProvider::HttpConnection.

◆ getInfo() [1/2]

hash<ConnectionInfo> ConnectionProvider::AbstractConnection::getInfo ( *hash< auto > opts )

returns a ConnectionInfo hash of information about the connection

Parameters

opts	connection information options; options are connection-specific; the only universal option is `with_passwords:` if True, then passwords are returned in the info hash

Returns: a ConnectionInfo hash of information about the connection

◆ getInfo() [2/2]

hash<ConnectionInfo> ConnectionProvider::AbstractConnection::getInfo ( bool with_password = False )

returns a ConnectionInfo hash of information about the connection

Parameters

with_password determines if the password is returned or not

Returns: a ConnectionInfo hash of information about the connection

Deprecated:: use getInfo(*hash<auto> opts) instead

◆ getSafeUrl()

string ConnectionProvider::AbstractConnection::getSafeUrl ( hash< auto > urlh )

private

creates a "safe" URL string with password information removed

Parameters

urlh	a parsed hash (as returned from parseUrl()

Returns: string with safe URL

This base/default implementation expects the urlh as returned by Qore::parse_url())

Public attribute safe_url is created from the url calling AbstractConnection::getSafeUrl(). Reimplement this method if your connection does not follow standard URL in form:

scheme://user:pass@hostname:port/path

◆ getTagEx()

auto ConnectionProvider::AbstractConnection::getTagEx ( string tag )

returns the value of the given tag or throws an exception if the tag is not set with a value

Exceptions

TAG-ERROR the given tag is not set on the connection

◆ hasDataProvider()

bool ConnectionProvider::AbstractConnection::hasDataProvider ( )

returns True if the connection returns a data provider with the getDataProvider() method

Returns: True if the connection returns a data provider with the getDataProvider() method

This base class method returns False; to support the data provider API, override this method in child classes

See also: getDataProvider()

Since: ConnectionProvider 1.3

◆ parseTextOptions()

ConnectionProvider::AbstractConnection::parseTextOptions ( )

this method is called when parsing connection file definitions from text files when loading into the database

reimplement this method in subclasses to parse the option hash as set from a text file if needed (for special option formats, etc)

◆ parseUrl()

hash<UrlInfo> ConnectionProvider::AbstractConnection::parseUrl ( string url )

private

Parse the URL to a hash.

Parameters

url	a string with url

Returns: hash untyped, depends on the parsing method

The base implementation calls Qore::parse_url().

Reimplement parseUrl() if your connection uses different URL scheme. Like eg. Qore::Datasource connection string.

◆ ping()

hash<PingInfo> ConnectionProvider::AbstractConnection::ping ( bool throw_exception = False )

returns a hash with the results of the ping operation

Parameters

throw_exception throw an exception if a connection error occurs

Returns: a PingInfo hash

◆ validateOptions()

hash<auto> ConnectionProvider::AbstractConnection::validateOptions ( hash< auto > options )

private

performs options validation in the constructor

Parameters

options a hash with options from the constructor

Returns: validated option hash

This method can be overloaded in connections where are options created dynamically for example

Exceptions

CONNECTION-OPTION-ERROR missing or invalid connection option

Public Member Methods

Public Attributes

Static Public Attributes

Private Member Methods

Private:Internal Member Methods

Detailed Description

Member Function Documentation

◆ constructor() [1/2]

◆ constructor() [2/2]

◆ constructorInit()

◆ get()

◆ getConfigHash()

◆ getDataProvider()

◆ getExtendedInfo()

◆ getImpl()

◆ getInfo() [1/2]

◆ getInfo() [2/2]

◆ getSafeUrl()

◆ getTagEx()

◆ hasDataProvider()

◆ parseTextOptions()

◆ parseUrl()

◆ ping()

◆ validateOptions()