Loading...
Searching...
No Matches
AbstractConnection.qc.dox.h
// -*- mode: c++; indent-tabs-mode: nil -*-
// Qore AbstractConnection class definition
/* AbstractConnection.qc Copyright 2016 - 2024 Qore Technologies, s.r.o.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
*/
namespace ConnectionProvider {
const PF_THROW_EXCEPTION = (1 << 0);
const PF_AUTOMATIC_PING = (1 << 1);
const CCS_UNSUPPORTED = "unsupported";
const CCS_UNCUSTOMIZED = "uncustomized";
const CCS_IN_PROGRESS = "in-progress";
const CCS_CUSTOMIZED = "customized";
class AbstractConnection : public Qore::Serializable, public Logger::LoggerWrapper, public OptionHelper {
public:
string name;
string display_name;
*string short_desc;
string desc;
string url;
string safe_url;
string real_url;
*hash<auto> orig_opts;
*hash<auto> opts;
hash<auto> urlh;
*date last_check;
string status = "not checked";
bool up = True;
bool monitor;
date updated;
bool loopback = False;
bool supports_customization = False;
string customization_status = CCS_UNSUPPORTED;
*date customization_timestamp;
static *code post_processing;
bool enabled = True;
bool locked = False;
bool debug_data = False;
hash<auto> tags = {};
bool children_can_support_apis = False;
bool children_can_support_records = False;
bool children_can_support_observers = False;
bool children_can_support_messages = False;
bool children_can_support_transactions = False;
hash<auto> internal_info;
bool disable_automatic_pings;
transient hash<auto> transient_info;
const CF_LOGGER = "logger";
const CF_UPDATE_OPTIONS = "update-options";
const DefaultDescription = "n/a; update connection to use the `AbstractConnectionWithInfo` class instead";
const CommonConnectionKeys = ...;
deprecated
constructor(string name, string desc, string url, bool monitor, *hash opts, hash urlh, *string safe_url, *bool enabled);
deprecated constructor(string name, string description, string url, hash<auto> attributes = {}, hash<auto> options = {}, *LoggerInterface logger) ;
constructor(hash<auto> config, *hash<auto> attr);
string getName();
string getDisplayName();
string getShortDescription();
string getDescription();
string getUrl();
string getSafeUrl();
bool needsAuth();
*string getAppName();
hash<PingInfo> ping(bool throw_exception);
hash<PingInfo> ping(int ping_flags = 0);
startCustomization(*bool restart);
protected:
hash<PingInfo> pingIntern(hash<PingInfo> rv);
public:
hash<ConnectionInfo> getInfo(bool with_password = False);
hash<ConnectionInfo> getInfo(*hash<auto> opts);
hash<ConnectionDataInfo> getInfoAsData(*hash<auto> opts);
*hash<string, bool> getFeatures();
hash<auto> getExtendedInfo(*hash<auto> opts);
hash<auto> getExtendedInfoAsData(*hash<auto> opts);
hash<ConfigInfo> getConfigHash();
hash<ConnectionSchemeInfo> getConnectionSchemeInfo();
hash<ConnectionSchemeInfo> getConnectionSchemeInfoImpl();
*hash<auto> getOptions();
*hash<auto> getRuntimeOptions();
*hash<auto> getDefaultOptions();
*hash<auto> getRealOptions();
*hash<auto> getConnectionOptions(*hash<auto> rtopts);
object get(bool connect = True, *hash<auto> rtopts);
parseTextOptions();
hash<auto> getTags();
auto getTag(string tag);
auto getTagEx(string tag);
bool hasDataProvider();
AbstractDataProvider getDataProvider(*hash<auto> constructor_options);
AbstractDataProvider getDataProvider(string subtype, *hash<auto> constructor_options);
*hash<string, hash<DataProviderOptionInfo>> getDataProviderConstructorOptions();
*hash<string, *hash<string, hash<DataProviderOptionInfo>>> getDataProviderSubtypes();
bool supportsPollingApi();
Qore::AbstractPollOperation startPollConnect(*Logger::LoggerInterface logger);
object getPollImpl();
handlePingSuccess(date delta);
handlePingFailed(date delta, hash<ExceptionInfo> ex);
handlePingFailed(date delta, string err);
static hash<ConnectionOptionInfo> getConnectionOptionInfo(hash<DataProviderOptionInfo> dinfo);
static hash<string, hash<ConnectionOptionInfo>> getConnectionOptionInfo( hash<string, hash<DataProviderOptionInfo>> dinfo);
static string getRealUrl(string url, hash<ConnectionSchemeInfo> info, string type);
protected:
startCustomizationImpl();
public:
protected:
AbstractDataProvider getDataProviderImpl(string subtype, *hash<auto> constructor_options);
public:
protected:
*hash<string, hash<DataProviderOptionInfo>> getDataProviderConstructorOptionsImpl();
public:
protected:
*hash<string, *hash<string, hash<DataProviderOptionInfo>>> getDataProviderSubtypesImpl();
public:
protected:
*hash<auto> getSubtypeOptions(*hash<string, hash<DataProviderOptionInfo>> subtype_options, *hash<auto> constructor_options);
public:
protected:
pingImpl();
public:
protected:
hash<UrlInfo> parseUrl(string url);
public:
protected:
string getSafeUrl(hash<auto> urlh);
public:
protected:
hash<auto> validateOptions(hash<auto> options, bool check_required = True);
public:
private:
constructorInit(hash<auto> config, *hash<auto> attr);
public:
protected:
setRealUrl(*string url);
public:
protected:
*hash<string, bool> getFeaturesImpl();
public:
protected:
setChildCapabilities();
public:
abstract string getType();
protected:
abstract object getImpl(bool connect = True, *hash<auto> rtopts);
public:
};
}; // ConnectionProvider namespace
ConnectionProvider::AbstractConnection
Abstract base class for connections.
Definition AbstractConnection.qc.dox.h:69
ConnectionProvider::AbstractConnection::desc
string desc
Connection description with markdown formatting.
Definition AbstractConnection.qc.dox.h:82
ConnectionProvider::AbstractConnection::locked
bool locked
locked/unlocked flag
Definition AbstractConnection.qc.dox.h:138
ConnectionProvider::AbstractConnection::display_name
string display_name
Display name.
Definition AbstractConnection.qc.dox.h:76
ConnectionProvider::AbstractConnection::getName
string getName()
Returns the connection name.
ConnectionProvider::AbstractConnection::pingImpl
pingImpl()
performs the internal ping
ConnectionProvider::AbstractConnection::getInfo
hash< ConnectionInfo > getInfo(*hash< auto > opts)
returns a ConnectionInfo hash of information about the connection
ConnectionProvider::AbstractConnection::getInfo
hash< ConnectionInfo > getInfo(bool with_password=False)
returns a ConnectionInfo hash of information about the connection
ConnectionProvider::AbstractConnection::hasDataProvider
bool hasDataProvider()
returns True if the connection returns a data provider with the getDataProvider() method
ConnectionProvider::AbstractConnection::DefaultDescription
const DefaultDescription
Default option description.
Definition AbstractConnection.qc.dox.h:185
ConnectionProvider::AbstractConnection::children_can_support_transactions
bool children_can_support_transactions
if the data provider or any of its children support transaction management
Definition AbstractConnection.qc.dox.h:159
ConnectionProvider::AbstractConnection::opts
*hash< auto > opts
connection options
Definition AbstractConnection.qc.dox.h:97
ConnectionProvider::AbstractConnection::getPollImpl
object getPollImpl()
Returns an unconnected object for a non-blocking poll operation.
ConnectionProvider::AbstractConnection::get
object get(bool connect=True, *hash< auto > rtopts)
returns the underlying connection object
ConnectionProvider::AbstractConnection::CF_LOGGER
const CF_LOGGER
Connection feature: Logger support.
Definition AbstractConnection.qc.dox.h:173
ConnectionProvider::AbstractConnection::getDataProviderConstructorOptionsImpl
*hash< string, hash< DataProviderOptionInfo > > getDataProviderConstructorOptionsImpl()
Returns a hash of data provider constructor option info, if applicable.
ConnectionProvider::AbstractConnection::getTagEx
auto getTagEx(string tag)
returns the value of the given tag or throws an exception if the tag is not set with a value
ConnectionProvider::AbstractConnection::CommonConnectionKeys
const CommonConnectionKeys
Connection info keys mapped 1:1 to DataProviderOptionInfo keys.
Definition AbstractConnection.qc.dox.h:188
ConnectionProvider::AbstractConnection::needsAuth
bool needsAuth()
Returns True if the connection requires OAuth2 authorization before it can be used.
ConnectionProvider::AbstractConnection::internal_info
hash< auto > internal_info
internal tags (serializable)
Definition AbstractConnection.qc.dox.h:162
ConnectionProvider::AbstractConnection::orig_opts
*hash< auto > orig_opts
original connection options
Definition AbstractConnection.qc.dox.h:94
ConnectionProvider::AbstractConnection::getRuntimeOptions
*hash< auto > getRuntimeOptions()
returns runtime options
ConnectionProvider::AbstractConnection::url
string url
Connection URL (potentially with password info)
Definition AbstractConnection.qc.dox.h:85
ConnectionProvider::AbstractConnection::children_can_support_messages
bool children_can_support_messages
if the data provider or any of its children support messages
Definition AbstractConnection.qc.dox.h:156
ConnectionProvider::AbstractConnection::getDataProvider
AbstractDataProvider getDataProvider(string subtype, *hash< auto > constructor_options)
Returns a data provider object for the connection and subtype passed as an argument.
ConnectionProvider::AbstractConnection::getFeaturesImpl
*hash< string, bool > getFeaturesImpl()
Returns a hash of connection-defined features.
ConnectionProvider::AbstractConnection::getExtendedInfo
hash< auto > getExtendedInfo(*hash< auto > opts)
Returns connection info plus any extended information returned by the connection.
ConnectionProvider::AbstractConnection::startPollConnect
Qore::AbstractPollOperation startPollConnect(*Logger::LoggerInterface logger)
Called to start the connection polling operation.
ConnectionProvider::AbstractConnection::monitor
bool monitor
monitoring flag
Definition AbstractConnection.qc.dox.h:112
ConnectionProvider::AbstractConnection::safe_url
string safe_url
"safe" URL (password information removed)
Definition AbstractConnection.qc.dox.h:88
ConnectionProvider::AbstractConnection::getConnectionOptionInfo
static hash< ConnectionOptionInfo > getConnectionOptionInfo(hash< DataProviderOptionInfo > dinfo)
Returns a ConnectionOptionInfo hash from a DataProviderOptionInfo hash.
ConnectionProvider::AbstractConnection::getRealUrl
static string getRealUrl(string url, hash< ConnectionSchemeInfo > info, string type)
Returns the real URL for a connection URL.
ConnectionProvider::AbstractConnection::setChildCapabilities
setChildCapabilities()
Override to set child data provider capabilities once per child class.
ConnectionProvider::AbstractConnection::tags
hash< auto > tags
connection tags; user-defined key-value pairs
Definition AbstractConnection.qc.dox.h:144
ConnectionProvider::AbstractConnection::getSafeUrl
string getSafeUrl(hash< auto > urlh)
creates a "safe" URL string with password information removed
ConnectionProvider::AbstractConnection::enabled
bool enabled
enabled/disabled indicator flag
Definition AbstractConnection.qc.dox.h:135
ConnectionProvider::AbstractConnection::ping
hash< PingInfo > ping(bool throw_exception)
returns a hash with the results of the ping operation
ConnectionProvider::AbstractConnection::real_url
string real_url
A string containing the real URL using a non-abstract / technical scheme.
Definition AbstractConnection.qc.dox.h:91
ConnectionProvider::AbstractConnection::getConnectionOptions
*hash< auto > getConnectionOptions(*hash< auto > rtopts)
returns options for creating a new connection
ConnectionProvider::AbstractConnection::up
bool up
connection status flag; set by monitoring or explicit pings/connections
Definition AbstractConnection.qc.dox.h:109
ConnectionProvider::AbstractConnection::getDescription
string getDescription()
Returns the connection description.
ConnectionProvider::AbstractConnection::getConnectionSchemeInfo
hash< ConnectionSchemeInfo > getConnectionSchemeInfo()
Returns a default ConnectionSchemeInfo hash.
ConnectionProvider::AbstractConnection::getConnectionOptionInfo
static hash< string, hash< ConnectionOptionInfo > > getConnectionOptionInfo(hash< string, hash< DataProviderOptionInfo > > dinfo)
Returns a hash of ConnectionOptionInfo hashes from a hash of DataProviderOptionInfo hashes.
ConnectionProvider::AbstractConnection::CF_UPDATE_OPTIONS
const CF_UPDATE_OPTIONS
Connection feature: Update Options support.
Definition AbstractConnection.qc.dox.h:182
ConnectionProvider::AbstractConnection::getConnectionSchemeInfoImpl
hash< ConnectionSchemeInfo > getConnectionSchemeInfoImpl()
Override in subclasses to return a native ConnectionSchemeInfo hash.
ConnectionProvider::AbstractConnection::pingIntern
hash< PingInfo > pingIntern(hash< PingInfo > rv)
performs the ping by executing get(); returns a PingInfo hash
ConnectionProvider::AbstractConnection::supportsPollingApi
bool supportsPollingApi()
returns True if the connection supports the Qore Socket-based polling API
ConnectionProvider::AbstractConnection::customization_status
string customization_status
Customization status.
Definition AbstractConnection.qc.dox.h:124
ConnectionProvider::AbstractConnection::ping
hash< PingInfo > ping(int ping_flags=0)
returns a hash with the results of the ping operation
ConnectionProvider::AbstractConnection::debug_data
bool debug_data
debug data flag; to be used an an indication for a higher-level implementation
Definition AbstractConnection.qc.dox.h:141
ConnectionProvider::AbstractConnection::name
string name
Connection name.
Definition AbstractConnection.qc.dox.h:73
ConnectionProvider::AbstractConnection::parseUrl
hash< UrlInfo > parseUrl(string url)
Parse the URL to a hash.
ConnectionProvider::AbstractConnection::getConfigHash
hash< ConfigInfo > getConfigHash()
returns a ConfigInfo hash of static configuration information about the connection
ConnectionProvider::AbstractConnection::getDataProviderSubtypesImpl
*hash< string, *hash< string, hash< DataProviderOptionInfo > > > getDataProviderSubtypesImpl()
Returns a hash of supported data provider subtypes.
ConnectionProvider::AbstractConnection::startCustomization
startCustomization(*bool restart)
Starts customization for the object.
ConnectionProvider::AbstractConnection::setRealUrl
setRealUrl(*string url)
Called by the constructor to set the real URL.
ConnectionProvider::AbstractConnection::transient_info
transient hash< auto > transient_info
internal transient tags (non-serializable)
Definition AbstractConnection.qc.dox.h:168
ConnectionProvider::AbstractConnection::constructor
deprecated constructor(string name, string description, string url, hash< auto > attributes={}, hash< auto > options={}, *LoggerInterface logger)
creates the AbstractConnection object
ConnectionProvider::AbstractConnection::getAppName
*string getAppName()
Returns the data provider application name this connection serves, if any.
ConnectionProvider::AbstractConnection::getOptions
*hash< auto > getOptions()
returns static / initialization options
ConnectionProvider::AbstractConnection::getTags
hash< auto > getTags()
returns all tags associated with the connection
ConnectionProvider::AbstractConnection::getImpl
abstract object getImpl(bool connect=True, *hash< auto > rtopts)
this method must return the connection object corresponding to the object's configuration
ConnectionProvider::AbstractConnection::constructor
deprecated constructor(string name, string desc, string url, bool monitor, *hash opts, hash urlh, *string safe_url, *bool enabled)
creates the AbstractConnection object
ConnectionProvider::AbstractConnection::handlePingFailed
handlePingFailed(date delta, hash< ExceptionInfo > ex)
Handles a failed ping operation on the connection.
ConnectionProvider::AbstractConnection::validateOptions
hash< auto > validateOptions(hash< auto > options, bool check_required=True)
performs options validation in the constructor
ConnectionProvider::AbstractConnection::getSafeUrl
string getSafeUrl()
Returns the connection safe URL (without password info)
ConnectionProvider::AbstractConnection::constructorInit
constructorInit(hash< auto > config, *hash< auto > attr)
Common construtor implementation.
ConnectionProvider::AbstractConnection::getUrl
string getUrl()
Returns the connection URL.
ConnectionProvider::AbstractConnection::getDefaultOptions
*hash< auto > getDefaultOptions()
returns default options
ConnectionProvider::AbstractConnection::getTag
auto getTag(string tag)
returns the value of the given tag or nothing if not present
ConnectionProvider::AbstractConnection::getShortDescription
string getShortDescription()
Returns the connection short description.
ConnectionProvider::AbstractConnection::getDataProviderImpl
AbstractDataProvider getDataProviderImpl(string subtype, *hash< auto > constructor_options)
returns a data provider object for the connection and subtype passed as an argument
ConnectionProvider::AbstractConnection::status
string status
status string; in case of a connection error this string will be the error string
Definition AbstractConnection.qc.dox.h:106
ConnectionProvider::AbstractConnection::parseTextOptions
parseTextOptions()
this method is called when parsing connection file definitions from text files when loading into the ...
ConnectionProvider::AbstractConnection::getInfoAsData
hash< ConnectionDataInfo > getInfoAsData(*hash< auto > opts)
Returns a ConnectionDataInfo hash of information about the connection.
ConnectionProvider::AbstractConnection::updated
date updated
date/time of last update
Definition AbstractConnection.qc.dox.h:115
ConnectionProvider::AbstractConnection::getDisplayName
string getDisplayName()
Returns the connection display name.
ConnectionProvider::AbstractConnection::children_can_support_apis
bool children_can_support_apis
if the data provider or any of its children support requests (APIs)
Definition AbstractConnection.qc.dox.h:147
ConnectionProvider::AbstractConnection::post_processing
static *code post_processing
optional code for default post-processing of objects created by getImpl()
Definition AbstractConnection.qc.dox.h:132
ConnectionProvider::AbstractConnection::loopback
bool loopback
set to True for loopback connections
Definition AbstractConnection.qc.dox.h:118
ConnectionProvider::AbstractConnection::children_can_support_observers
bool children_can_support_observers
if the data provider or any of its children support events
Definition AbstractConnection.qc.dox.h:153
ConnectionProvider::AbstractConnection::customization_timestamp
*date customization_timestamp
Customization timestamp.
Definition AbstractConnection.qc.dox.h:127
ConnectionProvider::AbstractConnection::children_can_support_records
bool children_can_support_records
if the data provider or any of its children support records
Definition AbstractConnection.qc.dox.h:150
ConnectionProvider::AbstractConnection::getType
abstract string getType()
returns the string type name for the connection object
ConnectionProvider::AbstractConnection::handlePingFailed
handlePingFailed(date delta, string err)
Handles a failed ping operation on the connection.
ConnectionProvider::AbstractConnection::supports_customization
bool supports_customization
Customization support?
Definition AbstractConnection.qc.dox.h:121
ConnectionProvider::AbstractConnection::urlh
hash< auto > urlh
broken down URL hash (as returned by Qore::parse_url())
Definition AbstractConnection.qc.dox.h:100
ConnectionProvider::AbstractConnection::getDataProviderConstructorOptions
*hash< string, hash< DataProviderOptionInfo > > getDataProviderConstructorOptions()
Returns a hash of data provider constructor option info, if applicable.
ConnectionProvider::AbstractConnection::constructor
constructor(hash< auto > config, *hash< auto > attr)
creates the AbstractConnection object
ConnectionProvider::AbstractConnection::startCustomizationImpl
startCustomizationImpl()
Starts customization for the object.
ConnectionProvider::AbstractConnection::getSubtypeOptions
*hash< auto > getSubtypeOptions(*hash< string, hash< DataProviderOptionInfo > > subtype_options, *hash< auto > constructor_options)
Returns options for each data provider subtype.
ConnectionProvider::AbstractConnection::short_desc
*string short_desc
Connection short description in plain text.
Definition AbstractConnection.qc.dox.h:79
ConnectionProvider::AbstractConnection::getRealOptions
*hash< auto > getRealOptions()
returns options for saving the connection's configuration information
ConnectionProvider::AbstractConnection::getExtendedInfoAsData
hash< auto > getExtendedInfoAsData(*hash< auto > opts)
Returns connection info plus any extended information returned by the connection.
ConnectionProvider::AbstractConnection::getDataProvider
AbstractDataProvider getDataProvider(*hash< auto > constructor_options)
returns a data provider object for this connection, if supported
ConnectionProvider::AbstractConnection::getDataProviderSubtypes
*hash< string, *hash< string, hash< DataProviderOptionInfo > > > getDataProviderSubtypes()
Returns a hash of supported data provider subtypes and constructor option info.
ConnectionProvider::AbstractConnection::getFeatures
*hash< string, bool > getFeatures()
Returns a list of connection-defined features.
ConnectionProvider::AbstractConnection::disable_automatic_pings
bool disable_automatic_pings
If automatic pings are disabled.
Definition AbstractConnection.qc.dox.h:165
ConnectionProvider::AbstractConnection::handlePingSuccess
handlePingSuccess(date delta)
Handles a successful ping operation on the connection.
ConnectionProvider::AbstractConnection::last_check
*date last_check
date/time of last check/ping
Definition AbstractConnection.qc.dox.h:103
ConnectionProvider::OptionHelper
Class with helper methods to options in a hash.
Definition OptionHelper.qc.dox.h:30
ConnectionProvider::CCS_IN_PROGRESS
const CCS_IN_PROGRESS
Customization status: in-progress.
Definition AbstractConnection.qc.dox.h:56
ConnectionProvider::CCS_CUSTOMIZED
const CCS_CUSTOMIZED
Customization status: customized.
Definition AbstractConnection.qc.dox.h:61
ConnectionProvider::CCS_UNSUPPORTED
const CCS_UNSUPPORTED
Definition AbstractConnection.qc.dox.h:46
ConnectionProvider::CCS_UNCUSTOMIZED
const CCS_UNCUSTOMIZED
Customization status: uncustomized.
Definition AbstractConnection.qc.dox.h:51
ConnectionProvider::PF_THROW_EXCEPTION
const PF_THROW_EXCEPTION
Definition AbstractConnection.qc.dox.h:33
ConnectionProvider::PF_AUTOMATIC_PING
const PF_AUTOMATIC_PING
Ping flag: automatic / scheduled ping.
Definition AbstractConnection.qc.dox.h:39
ConnectionProvider
The ConnectionProvider namespace.
Definition AbstractConnection.qc.dox.h:28