Qore ConnectionProvider Module Reference  1.5
ConnectionProvider::AbstractConnection Class Referenceabstract

abstract base class for connections More...

Inheritance diagram for ConnectionProvider::AbstractConnection:

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< ConfigInfogetConfigHash ()
 returns a ConfigInfo hash of static configuration information about the connection More...
 
hash< ConnectionSchemeInfogetConnectionSchemeInfo ()
 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< ConnectionInfogetInfo (*hash< auto > opts)
 returns a ConnectionInfo hash of information about the connection More...
 
hash< ConnectionInfogetInfo (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< PingInfoping (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< PingInfopingIntern (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 
)
inline

creates the AbstractConnection object

Parameters
n_namethe name of the connection
n_descconnection description
n_urlconnection URL (potentially with password info)
n_monitormonitoring flag
n_optsconnection options
n_urlhbroken 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_enabledenabled/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
namethe name of the connection
descriptionconnection description
urlconnection URL (potentially with password info)
attributesvarious attributes; see below
optionsconnection 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-ERRORmissing 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-ERRORmissing 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-ERRORthis 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
connectif True then the connection should be returned connected (and if possible a round-trip "ping" of the server should be made)
rtoptsif 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
optsconnection 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_passworddetermines 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
urlha 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-ERRORthe 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
urla 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_exceptionthrow 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
optionsa 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-ERRORmissing or invalid connection option