![]() |
Qore ConnectionProvider Module Reference 2.0
|
Abstract base class for connections. More...
#include <AbstractConnection.qc.dox.h>
Public Member Functions | |
| constructor (hash< auto > config, *hash< auto > attr) | |
| creates the AbstractConnection object | |
| deprecated | constructor (string name, string desc, string url, bool monitor, *hash opts, hash urlh, *string safe_url, *bool enabled) |
| creates the AbstractConnection object | |
| deprecated | constructor (string name, string description, string url, hash< auto > attributes={}, hash< auto > options={}, *LoggerInterface logger) |
| creates the AbstractConnection object | |
| object | get (bool connect=True, *hash< auto > rtopts) |
| returns the underlying connection object | |
| *string | getAppName () |
| Returns the data provider application name this connection serves, if any. | |
| hash< ConfigInfo > | getConfigHash () |
| returns a ConfigInfo hash of static configuration information about the connection | |
| *hash< auto > | getConnectionOptions (*hash< auto > rtopts) |
| returns options for creating a new connection | |
| hash< ConnectionSchemeInfo > | getConnectionSchemeInfo () |
| Returns a default ConnectionSchemeInfo hash. | |
| hash< ConnectionSchemeInfo > | getConnectionSchemeInfoImpl () |
| Override in subclasses to return a native ConnectionSchemeInfo hash. | |
| AbstractDataProvider | getDataProvider (*hash< auto > constructor_options) |
| returns a data provider object for this connection, if supported | |
| AbstractDataProvider | getDataProvider (string subtype, *hash< auto > constructor_options) |
| Returns a data provider object for the connection and subtype passed as an argument. | |
| *hash< string, hash< DataProviderOptionInfo > > | getDataProviderConstructorOptions () |
| Returns a hash of data provider constructor option info, if applicable. | |
| *hash< string, *hash< string, hash< DataProviderOptionInfo > > > | getDataProviderSubtypes () |
| Returns a hash of supported data provider subtypes and constructor option info. | |
| *hash< auto > | getDefaultOptions () |
| returns default options | |
| string | getDescription () |
| Returns the connection description. | |
| string | getDisplayName () |
| Returns the connection display name. | |
| hash< auto > | getExtendedInfo (*hash< auto > opts) |
| Returns connection info plus any extended information returned by the connection. | |
| hash< auto > | getExtendedInfoAsData (*hash< auto > opts) |
| Returns connection info plus any extended information returned by the connection. | |
| *hash< string, bool > | getFeatures () |
| Returns a list of connection-defined features. | |
| hash< ConnectionInfo > | getInfo (*hash< auto > opts) |
| returns a ConnectionInfo hash of information about the connection | |
| hash< ConnectionInfo > | getInfo (bool with_password=False) |
| returns a ConnectionInfo hash of information about the connection | |
| hash< ConnectionDataInfo > | getInfoAsData (*hash< auto > opts) |
| Returns a ConnectionDataInfo hash of information about the connection. | |
| string | getName () |
| Returns the connection name. | |
| *hash< auto > | getOptions () |
| returns static / initialization options | |
| object | getPollImpl () |
| Returns an unconnected object for a non-blocking poll operation. | |
| *hash< auto > | getRealOptions () |
| returns options for saving the connection's configuration information | |
| *hash< auto > | getRuntimeOptions () |
| returns runtime options | |
| string | getSafeUrl () |
| Returns the connection safe URL (without password info) | |
| string | getShortDescription () |
| Returns the connection short description. | |
| 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 | |
| hash< auto > | getTags () |
| returns all tags associated with the connection | |
| abstract string | getType () |
| returns the string type name for the connection object | |
| string | getUrl () |
| Returns the connection URL. | |
| handlePingFailed (date delta, hash< ExceptionInfo > ex) | |
| Handles a failed ping operation on the connection. | |
| handlePingFailed (date delta, string err) | |
| Handles a failed ping operation on the connection. | |
| handlePingSuccess (date delta) | |
| Handles a successful ping operation on the connection. | |
| bool | hasDataProvider () |
| returns True if the connection returns a data provider with the getDataProvider() method | |
| bool | needsAuth () |
| Returns True if the connection requires OAuth2 authorization before it can be used. | |
| parseTextOptions () | |
| this method is called when parsing connection file definitions from text files when loading into the database | |
| hash< PingInfo > | ping (bool throw_exception) |
| returns a hash with the results of the ping operation | |
| hash< PingInfo > | ping (int ping_flags=0) |
| returns a hash with the results of the ping operation | |
| startCustomization (*bool restart) | |
| Starts customization for the object. | |
| Qore::AbstractPollOperation | startPollConnect (*Logger::LoggerInterface logger) |
| Called to start the connection polling operation. | |
| bool | supportsPollingApi () |
| returns True if the connection supports the Qore Socket-based polling API | |
Static Public Member Functions | |
| static hash< ConnectionOptionInfo > | getConnectionOptionInfo (hash< DataProviderOptionInfo > dinfo) |
| Returns a ConnectionOptionInfo hash from a DataProviderOptionInfo hash. | |
| static hash< string, hash< ConnectionOptionInfo > > | getConnectionOptionInfo (hash< string, hash< DataProviderOptionInfo > > dinfo) |
| Returns a hash of ConnectionOptionInfo hashes from a hash of DataProviderOptionInfo hashes. | |
| static string | getRealUrl (string url, hash< ConnectionSchemeInfo > info, string type) |
| Returns the real URL for a connection URL. | |
Static Public Member Functions inherited from ConnectionProvider::OptionHelper | |
| static *bool | getBool (*hash< auto > opts, string key, *bool required, *bool default_value) |
| Returns a boolean value from a hash. | |
| static *hash< auto > | getHash (*hash< auto > opts, string key, *bool required, *hash< auto > default_value) |
| Returns a hash value from a hash. | |
| static *int | getInt (*hash< auto > opts, string key, *bool required, *int default_value) |
| Gets an integer option. | |
| static auto | getOptionType (*hash< auto > opts, string key, int type_code, string type_name, *bool required, auto default_value) |
| gets an option value of the given type | |
| static *string | getString (*hash< auto > opts, string key, *bool required, *string default_value) |
| Returns a string value from a hash. | |
Public Attributes | |
| const | CF_LOGGER = "logger" |
| Connection feature: Logger support. | |
| const | CF_UPDATE_OPTIONS = "update-options" |
| Connection feature: Update Options support. | |
| bool | children_can_support_apis = False |
| if the data provider or any of its children support requests (APIs) | |
| bool | children_can_support_messages = False |
| if the data provider or any of its children support messages | |
| bool | children_can_support_observers = False |
| if the data provider or any of its children support events | |
| bool | children_can_support_records = False |
| if the data provider or any of its children support records | |
| bool | children_can_support_transactions = False |
| if the data provider or any of its children support transaction management | |
| const | CommonConnectionKeys = ... |
| Connection info keys mapped 1:1 to DataProviderOptionInfo keys. | |
| string | customization_status = CCS_UNSUPPORTED |
| Customization status. | |
| *date | customization_timestamp |
| Customization timestamp. | |
| bool | debug_data = False |
| debug data flag; to be used an an indication for a higher-level implementation | |
| const | DefaultDescription = "n/a; update connection to use the `AbstractConnectionWithInfo` class instead" |
| Default option description. | |
| string | desc |
| Connection description with markdown formatting. | |
| bool | disable_automatic_pings |
| If automatic pings are disabled. | |
| string | display_name |
| Display name. | |
| bool | enabled = True |
| enabled/disabled indicator flag | |
| hash< auto > | internal_info |
| internal tags (serializable) | |
| *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 | real_url |
| A string containing the real URL using a non-abstract / technical scheme. | |
| string | safe_url |
| "safe" URL (password information removed) | |
| *string | short_desc |
| Connection short description in plain text. | |
| string | status = "not checked" |
| status string; in case of a connection error this string will be the error string | |
| bool | supports_customization = False |
| Customization support? | |
| hash< auto > | tags = {} |
| connection tags; user-defined key-value pairs | |
| transient hash< auto > | transient_info |
| internal transient tags (non-serializable) | |
| bool | up = True |
| 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() | |
Protected Member Functions | |
| *hash< string, hash< DataProviderOptionInfo > > | getDataProviderConstructorOptionsImpl () |
| Returns a hash of data provider constructor option info, if applicable. | |
| AbstractDataProvider | getDataProviderImpl (string subtype, *hash< auto > constructor_options) |
| returns a data provider object for the connection and subtype passed as an argument | |
| *hash< string, *hash< string, hash< DataProviderOptionInfo > > > | getDataProviderSubtypesImpl () |
| Returns a hash of supported data provider subtypes. | |
| *hash< string, bool > | getFeaturesImpl () |
| Returns a hash of connection-defined features. | |
| abstract object | getImpl (bool connect=True, *hash< auto > rtopts) |
| this method must return the connection object corresponding to the object's configuration | |
| string | getSafeUrl (hash< auto > urlh) |
| creates a "safe" URL string with password information removed | |
| *hash< auto > | getSubtypeOptions (*hash< string, hash< DataProviderOptionInfo > > subtype_options, *hash< auto > constructor_options) |
| Returns options for each data provider subtype. | |
| hash< UrlInfo > | parseUrl (string url) |
| Parse the URL to a hash. | |
| pingImpl () | |
| performs the internal ping | |
| hash< PingInfo > | pingIntern (hash< PingInfo > rv) |
| performs the ping by executing get(); returns a PingInfo hash | |
| setChildCapabilities () | |
| Override to set child data provider capabilities once per child class. | |
| setRealUrl (*string url) | |
| Called by the constructor to set the real URL. | |
| startCustomizationImpl () | |
| Starts customization for the object. | |
| hash< auto > | validateOptions (hash< auto > options, bool check_required=True) |
| performs options validation in the constructor | |
Private Member Functions | |
| constructorInit (hash< auto > config, *hash< auto > attr) | |
| Common construtor implementation. | |
Abstract base class for connections.
this class can be specialized to provide for user-defined connection types
| ConnectionProvider::AbstractConnection::constructor | ( | hash< auto > | config, |
| *hash< auto > | attr ) |
creates the AbstractConnection object
| config | with the following keys:
|
| attr | optional connection attributes
|
| CONNECTION-OPTION-ERROR | missing or invalid connection option or attribute |
| CONNECTION-URL-ERROR | URL is invalid, because it contains control characters |
| deprecated ConnectionProvider::AbstractConnection::constructor | ( | string | name, |
| string | desc, | ||
| string | url, | ||
| bool | monitor, | ||
| *hash | opts, | ||
| hash | urlh, | ||
| *string | safe_url, | ||
| *bool | enabled ) |
creates the AbstractConnection object
| name | the name of the connection |
| desc | connection description |
| url | connection URL (potentially with password info) |
| monitor | monitoring flag |
| opts | connection options |
| urlh | broken down URL hash (as returned by Qore::parse_url()) |
| safe_url | "safe" URL (password information removed); if not set this will be set automatically by calling getSafeUrl() |
| enabled | enabled/disabled flag |
| CONNECTION-OPTION-ERROR | missing or invalid connection option or attribute |
| CONNECTION-URL-ERROR | URL is invalid, because it contains control characters |
| deprecated ConnectionProvider::AbstractConnection::constructor | ( | string | name, |
| string | description, | ||
| string | url, | ||
| hash< auto > | attributes = {}, | ||
| hash< auto > | options = {}, | ||
| *LoggerInterface | logger ) |
creates the AbstractConnection object
| name | the name of the connection |
| description | connection description |
| url | connection URL (potentially with password info) |
| attributes | various attributes; see below |
| options | connection options |
| logger | any logger interface to use for the connection |
enabled (bool), default True monitor (bool), default True locked (bool), default False tags (hash), no default value| CONNECTION-OPTION-ERROR | missing or invalid connection option or attribute |
| CONNECTION-URL-ERROR | URL is invalid, because it contains control characters |
|
private |
Common construtor implementation.
| config | with the following keys:
|
| attr | optional connection attributes
|
| CONNECTION-OPTION-ERROR | missing or invalid connection option |
| CONNECTION-URL-ERROR | URL is invalid, because it contains control characters |
| object ConnectionProvider::AbstractConnection::get | ( | bool | connect = True, |
| *hash< auto > | rtopts ) |
returns the underlying connection object
calls getImpl() to actually acquire the connection object
| *string ConnectionProvider::AbstractConnection::getAppName | ( | ) |
Returns the data provider application name this connection serves, if any.
| hash< ConfigInfo > ConnectionProvider::AbstractConnection::getConfigHash | ( | ) |
returns a ConfigInfo hash of static configuration information about the connection
| AbstractDataProvider ConnectionProvider::AbstractConnection::getDataProvider | ( | *hash< auto > | constructor_options | ) |
returns a data provider object for this connection, if supported
| constructor_options | any additional constructor options for the data provider |
| 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
constructor_options argument | AbstractDataProvider ConnectionProvider::AbstractConnection::getDataProvider | ( | string | subtype, |
| *hash< auto > | constructor_options ) |
Returns a data provider object for the connection and subtype passed as an argument.
| subtype | the subtype of data provider supported, in case the connection can return multiple data providers |
| constructor_options | any additional constructor options required by the data provider |
| DATA-PROVIDER-ERROR | this object does not support the data provider API or the given subtype is not valid |
| *hash< string, hash< DataProviderOptionInfo > > ConnectionProvider::AbstractConnection::getDataProviderConstructorOptions | ( | ) |
Returns a hash of data provider constructor option info, if applicable.
|
protected |
Returns a hash of data provider constructor option info, if applicable.
|
protected |
returns a data provider object for the connection and subtype passed as an argument
| subtype | the subtype of data provider supported, in case the connection can return multiple data providers |
| constructor_options | any additional constructor options required by the data provider |
| DATA-PROVIDER-ERROR | this object does not support the data provider API or the given subtype is not valid |
This base class method throws a DATA-PROVIDER-ERROR exception by default; to support the data provider API, override this method in child classes
| *hash< string, *hash< string, hash< DataProviderOptionInfo > > > ConnectionProvider::AbstractConnection::getDataProviderSubtypes | ( | ) |
Returns a hash of supported data provider subtypes and constructor option info.
|
protected |
Returns a hash of supported data provider subtypes.
| string ConnectionProvider::AbstractConnection::getDescription | ( | ) |
Returns the connection description.
| string ConnectionProvider::AbstractConnection::getDisplayName | ( | ) |
Returns the connection display name.
| 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>)
| 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 |
| hash< auto > ConnectionProvider::AbstractConnection::getExtendedInfoAsData | ( | *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 getInfoAsData(*hash<auto>)
| 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 |
| *hash< string, bool > ConnectionProvider::AbstractConnection::getFeatures | ( | ) |
Returns a list of connection-defined features.
|
protected |
Returns a hash of connection-defined features.
This method returns no value; override in child classes to return features
|
protected |
this method must return the connection object corresponding to the object's configuration
| 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 |
| hash< ConnectionInfo > ConnectionProvider::AbstractConnection::getInfo | ( | *hash< auto > | opts | ) |
returns a ConnectionInfo hash of information about the connection
| 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 |
| hash< ConnectionInfo > ConnectionProvider::AbstractConnection::getInfo | ( | bool | with_password = False | ) |
returns a ConnectionInfo hash of information about the connection
| with_password | determines if the password is returned or not |
| hash< ConnectionDataInfo > ConnectionProvider::AbstractConnection::getInfoAsData | ( | *hash< auto > | opts | ) |
Returns a ConnectionDataInfo hash of information about the connection.
| 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 |
| string ConnectionProvider::AbstractConnection::getName | ( | ) |
Returns the connection name.
| object ConnectionProvider::AbstractConnection::getPollImpl | ( | ) |
Returns an unconnected object for a non-blocking poll operation.
| string ConnectionProvider::AbstractConnection::getSafeUrl | ( | ) |
Returns the connection safe URL (without password info)
|
protected |
creates a "safe" URL string with password information removed
| urlh | a parsed hash (as returned from parseUrl() |
This base/default implementation expects the urlh as returned by Qore::parse_url())
The public attribute safe_url is created from the url calling AbstractConnection::getSafeUrl(). Reimplement this method if your connection does not follow the standard URL format like:
| string ConnectionProvider::AbstractConnection::getShortDescription | ( | ) |
Returns the connection short description.
|
protected |
Returns options for each data provider subtype.
| constructor_options | any additional constructor options required by the data provider |
| 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
| TAG-ERROR | the given tag is not set on the connection |
| string ConnectionProvider::AbstractConnection::getUrl | ( | ) |
Returns the connection URL.
| bool ConnectionProvider::AbstractConnection::hasDataProvider | ( | ) |
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
| bool ConnectionProvider::AbstractConnection::needsAuth | ( | ) |
Returns True if the connection requires OAuth2 authorization before it can be used.
This base class method returns False by default
| 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)
|
protected |
Parse the URL to a hash.
| url | a string with url |
The base implementation calls Qore::parse_url().
Reimplement parseUrl() if your connection uses different URL scheme. Like eg. Qore::Datasource connection string.
| hash< PingInfo > ConnectionProvider::AbstractConnection::ping | ( | bool | throw_exception | ) |
returns a hash with the results of the ping operation
| throw_exception | throw an exception if a connection error occurs |
| hash< PingInfo > ConnectionProvider::AbstractConnection::ping | ( | int | ping_flags = 0 | ) |
returns a hash with the results of the ping operation
| ping_flags | see Ping Flags for more information |
|
protected |
performs the internal ping
By default this creates a new connection only; override in child classes to implement additional ping logic
|
protected |
Called by the constructor to set the real URL.
@path the new URL
sets the real HTTP URL for HTTP-based connections
| ConnectionProvider::AbstractConnection::startCustomization | ( | *bool | restart | ) |
Starts customization for the object.
@bool restart Restart any customization in progress
| CUSTOMIZATION-UNSUPPORTED | this exception is thrown if the connection does not support customization |
| CUSTOMIZATION-IN-PROGRESS | this exception is thrown if customization is already in progress and restart is not True |
|
protected |
Starts customization for the object.
| CUSTOMIZATION-UNSUPPORTED | this exception is thrown if the connection does not support customization |
| Qore::AbstractPollOperation ConnectionProvider::AbstractConnection::startPollConnect | ( | *Logger::LoggerInterface | logger | ) |
Called to start the connection polling operation.
Only called if the connection supports the polling API
| an | optional logger interface for any object used for polling |
| bool ConnectionProvider::AbstractConnection::supportsPollingApi | ( | ) |
returns True if the connection supports the Qore Socket-based polling API
This base class method returns False; to support the new polling API, override this method in child classes
|
protected |
performs options validation in the constructor
| options | a hash with options from the constructor |
| check_required | check that all required options are set |
This method can be overloaded in connections where are options created dynamically for example
| CONNECTION-OPTION-ERROR | missing or invalid connection option |
| const ConnectionProvider::AbstractConnection::CF_LOGGER = "logger" |
Connection feature: Logger support.
Indicates that connection objects support setting / updating a logger interface object in the connection
| const ConnectionProvider::AbstractConnection::CF_UPDATE_OPTIONS = "update-options" |
Connection feature: Update Options support.
Returned as a connection feature indicating that the connection object inherits UpdateOptionsInterface and therefore supports setting a closure to update connection options in external systems (in blocking I/O calls)
|
static |
optional code for default post-processing of objects created by getImpl()
must take the connection object and the object created as arguments