| Qore ConnectionProvider Module Reference 2.0.1

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions | Private Member Functions | List of all members
ConnectionProvider::AbstractConnection Class Reference

Abstract base class for connections. More...

`#include <AbstractConnection.qc.dox.h>`

Inheritance diagram for ConnectionProvider::AbstractConnection:
[legend]

## 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
| persistInfo (AbstractConnection old)
| Called after a new connection object is created from an existing connection.
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.

## 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/3]

ConnectionProvider::AbstractConnection::constructor | ( | hash< auto > | config,
|  | *hash< auto > | attr )

creates the AbstractConnection object

Parameters

  config | with the following keys: name (required string): the connection name display_name (optional string): the display name short_desc (optional string): a short description in plain text desc (optional string): a long description with markdown formatting url (required string): the connection URL opts (optional hash): connection options logger (optional LoggerInterface object): logger for the connection
  attr | optional connection attributes monitor (optional bool): should the connection be monitored? Default: True enabled (optional bool): is the connection enabled? Default: True locked (optional bool): is the connection locked? Default: False debug_data (optional bool): debug data? Default: False tags (optional hash): tags for the connection; no default value

Exceptions

  CONNECTION-OPTION-ERROR | missing or invalid connection option or attribute
  CONNECTION-URL-ERROR | URL is invalid, because it contains control characters

## ◆ constructor() [2/3]

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

Parameters

  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

Note
  use constructor(hash<auto> config, *hash<auto> attr instead

Exceptions

  CONNECTION-OPTION-ERROR | missing or invalid connection option or attribute
  CONNECTION-URL-ERROR | URL is invalid, because it contains control characters

## ◆ constructor() [3/3]

deprecated ConnectionProvider::AbstractConnection::constructor | ( | string | name,
|  | string | description,
|  | string | url,
|  | hash< auto > | attributes = {},
|  | hash< auto > | options = {},
|  | *LoggerInterface | logger )

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
  logger | any logger interface to use for the connection

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 or attribute
  CONNECTION-URL-ERROR | URL is invalid, because it contains control characters

Note
  use constructor(hash<auto> config, *hash<auto> attr instead

## ◆ constructorInit()

ConnectionProvider::AbstractConnection::constructorInit | ( | hash< auto > | config,
|  | *hash< auto > | attr )
| private

Common construtor implementation.

Parameters

  config | with the following keys: name (required string): the connection name display_name (optional string): the display name short_desc (optional string): a short description in plain text desc (optional string): a long description with markdown formatting url (required string): the connection URL opts (optional hash): connection options logger (optional LoggerInterface object): logger for the connection
  attr | optional connection attributes monitor (optional bool): should the connection be monitored? enabled (optional bool): is the connection enabled? locked (optional bool): is the connection locked? debug_data (optional bool): debug data? tags (optional hash): tags for the connection

Exceptions

  CONNECTION-OPTION-ERROR | missing or invalid connection option
  CONNECTION-URL-ERROR | URL is invalid, because it contains control characters

## ◆ get()

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

returns the underlying connection object

calls getImpl() to actually acquire the connection object

## ◆ getAppName()

*string ConnectionProvider::AbstractConnection::getAppName | ( |  | ) |

Returns the data provider application name this connection serves, if any.

Returns
  the data provider application name this connection serves, if any

Since
  ConnectionProvider 2.0

## ◆ 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() [1/2]

AbstractDataProvider ConnectionProvider::AbstractConnection::getDataProvider | ( | *hash< auto > | constructor_options | ) |

returns a data provider object for this connection, if supported

Parameters

  constructor_options | any additional constructor options for the data provider

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
  - ConnectionProvider 2.0 added the optional `constructor_options` argument

## ◆ getDataProvider() [2/2]

AbstractDataProvider ConnectionProvider::AbstractConnection::getDataProvider | ( | string | subtype,
|  | *hash< auto > | constructor_options )

Returns a data provider object for the connection and subtype passed as an argument.

Parameters

  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

Returns
  a data provider object for the connection and subtype passed as an argument

Exceptions

  DATA-PROVIDER-ERROR | this object does not support the data provider API or the given subtype is not valid

See also
  - hasDataProvider()
  - getDataProviderSubtypes()

Since
  ConnectionProvider 2.0

## ◆ getDataProviderConstructorOptions()

*hash< string, hash< DataProviderOptionInfo > > ConnectionProvider::AbstractConnection::getDataProviderConstructorOptions | ( |  | ) |

Returns a hash of data provider constructor option info, if applicable.

Returns
  a hash of data provider constructor option info for the primary data provider, if applicable

Since
  ConnectionProvider 2.0

## ◆ getDataProviderConstructorOptionsImpl()

*hash< string, hash< DataProviderOptionInfo > > ConnectionProvider::AbstractConnection::getDataProviderConstructorOptionsImpl | ( |  | ) |
| protected

Returns a hash of data provider constructor option info, if applicable.

Returns
  a hash of data provider constructor option info for the primary data provider, if applicable

Since
  ConnectionProvider 2.0

## ◆ getDataProviderImpl()

AbstractDataProvider ConnectionProvider::AbstractConnection::getDataProviderImpl | ( | string | subtype,
|  | *hash< auto > | constructor_options )
| protected

returns a data provider object for the connection and subtype passed as an argument

Parameters

  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

Returns
  a data provider object for the connection and subtype passed as an argument

Exceptions

  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

See also
  - hasDataProvider()
  - getDataProviderSubtypes()

Since
  ConnectionProvider 2.0

## ◆ getDataProviderSubtypes()

*hash< string, *hash< string, hash< DataProviderOptionInfo > > > ConnectionProvider::AbstractConnection::getDataProviderSubtypes | ( |  | ) |

Returns a hash of supported data provider subtypes and constructor option info.

Returns
  a hash of supported data provider subtypes and constructor option info; top-level keys are data provider subtypes supported by this connection, values are hashes of data provider constructor option information

Since
  ConnectionProvider 2.0

## ◆ getDataProviderSubtypesImpl()

*hash< string, *hash< string, hash< DataProviderOptionInfo > > > ConnectionProvider::AbstractConnection::getDataProviderSubtypesImpl | ( |  | ) |
| protected

Returns a hash of supported data provider subtypes.

Returns
  a hash of supported data provider subtypes

Since
  ConnectionProvider 2.0

## ◆ getDescription()

string ConnectionProvider::AbstractConnection::getDescription | ( |  | ) |

Returns the connection description.

Returns
  the connection description

Since
  ConnectionProvider 1.7

## ◆ getDisplayName()

string ConnectionProvider::AbstractConnection::getDisplayName | ( |  | ) |

Returns the connection display name.

Returns
  the connection display name

Since
  ConnectionProvider 2.0

## ◆ 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>)

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
  Connection info plus any extended information returned by the connection

Note
  Some of the information in this hash may be non-serializable objects, for a method that returns only serializable information about the connection, see getExtendedInfoAsData()

Since
  ConnectionProvider 1.5

## ◆ getExtendedInfoAsData()

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>)

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
  Connection info plus any extended information returned by the connection

Note
  All the information in this hash is data; some info in the output of getExtendedInfo() may be objects

Since
  ConnectionProvider 2.0

## ◆ getFeatures()

*hash< string, bool > ConnectionProvider::AbstractConnection::getFeatures | ( |  | ) |

Returns a list of connection-defined features.

Since
  ConnectionProvider 1.10

## ◆ getFeaturesImpl()

*hash< string, bool > ConnectionProvider::AbstractConnection::getFeaturesImpl | ( |  | ) |
| protected

Returns a hash of connection-defined features.

This method returns no value; override in child classes to return features

Since
  ConnectionProvider 1.10

## ◆ getImpl()

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

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

## ◆ 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

Note
  Some of the information in this hash may be non-serializable objects, for a method that returns only serializable information about the connection, see getInfoAsData()

## ◆ 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

## ◆ getInfoAsData()

hash< ConnectionDataInfo > ConnectionProvider::AbstractConnection::getInfoAsData | ( | *hash< auto > | opts | ) |

Returns a ConnectionDataInfo 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 ConnectionDataInfo hash of information about the connection

Note
  All the information in this hash is data; some info in the output of getInfo() may be objects

Since
  ConnectionProvider 2.0

## ◆ getName()

string ConnectionProvider::AbstractConnection::getName | ( |  | ) |

Returns the connection name.

Returns
  the connection name

Since
  ConnectionProvider 1.7

## ◆ getPollImpl()

object ConnectionProvider::AbstractConnection::getPollImpl | ( |  | ) |

Returns an unconnected object for a non-blocking poll operation.

Returns
  an unconnected object for a non-blocking poll operation

Since
  ConnectionProvider 1.7.1

## ◆ getSafeUrl() [1/2]

string ConnectionProvider::AbstractConnection::getSafeUrl | ( |  | ) |

Returns the connection safe URL (without password info)

Returns
  the connection safe URL (without password info)

Since
  ConnectionProvider 1.7

## ◆ getSafeUrl() [2/2]

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

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())

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:

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

## ◆ getShortDescription()

string ConnectionProvider::AbstractConnection::getShortDescription | ( |  | ) |

Returns the connection short description.

Returns
  the connection short description

Since
  ConnectionProvider 2.0

## ◆ getSubtypeOptions()

*hash< auto > ConnectionProvider::AbstractConnection::getSubtypeOptions | ( | *hash< string, hash< DataProviderOptionInfo > > | subtype_options,
|  | *hash< auto > | constructor_options )
| protected

Returns options for each data provider subtype.

Parameters

  constructor_options | any additional constructor options required by the data provider

## ◆ 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

## ◆ getUrl()

string ConnectionProvider::AbstractConnection::getUrl | ( |  | ) |

Returns the connection URL.

Returns
  the connection URL

Since
  ConnectionProvider 1.7

## ◆ 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

## ◆ needsAuth()

bool ConnectionProvider::AbstractConnection::needsAuth | ( |  | ) |

Returns True if the connection requires OAuth2 authorization before it can be used.

Returns
  True if the connection requires OAuth2 authorization, False if already authorized, or the connection does not support authorization

This base class method returns False by default

Since
  ConnectionProvider 2.0

## ◆ 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 | ) |
| protected

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.

## ◆ persistInfo()

ConnectionProvider::AbstractConnection::persistInfo | ( | AbstractConnection | old | ) |

Called after a new connection object is created from an existing connection.

Parameters

  old | the old connection object

## ◆ ping() [1/2]

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

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

## ◆ ping() [2/2]

hash< PingInfo > ConnectionProvider::AbstractConnection::ping | ( | int | ping_flags = 0 | ) |

returns a hash with the results of the ping operation

Parameters

  ping_flags | see Ping Flags for more information

Returns
  a PingInfo hash

Since
  ConnectionProvider 2.0

## ◆ pingImpl()

ConnectionProvider::AbstractConnection::pingImpl | ( |  | ) |
| protected

performs the internal ping

By default this creates a new connection only; override in child classes to implement additional ping logic

## ◆ setRealUrl()

ConnectionProvider::AbstractConnection::setRealUrl | ( | *string | url | ) |
| protected

Called by the constructor to set the real URL.

@path the new URL

sets the real HTTP URL for HTTP-based connections

## ◆ startCustomization()

ConnectionProvider::AbstractConnection::startCustomization | ( | *bool | restart | ) |

Starts customization for the object.

@bool restart Restart any customization in progress

Exceptions

  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

## ◆ startCustomizationImpl()

ConnectionProvider::AbstractConnection::startCustomizationImpl | ( |  | ) |
| protected

Starts customization for the object.

Exceptions

  CUSTOMIZATION-UNSUPPORTED | this exception is thrown if the connection does not support customization

## ◆ startPollConnect()

Qore::AbstractPollOperation ConnectionProvider::AbstractConnection::startPollConnect | ( | *Logger::LoggerInterface | logger | ) |

Called to start the connection polling operation.

Only called if the connection supports the polling API

Parameters

  an | optional logger interface for any object used for polling

Returns
  a socket poll operation object that will allow the connection goal to be reached with polling

See also
  supportsPollingApi()

Since
  ConnectionProvider 1.7

## ◆ supportsPollingApi()

bool ConnectionProvider::AbstractConnection::supportsPollingApi | ( |  | ) |

returns True if the connection supports the Qore Socket-based polling API

Returns
  True if the connection supports the polling API where multiple connections can be polled from a single thread

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

See also
  - startConnectPoll()

Since
  ConnectionProvider 1.7

## ◆ validateOptions()

hash< auto > ConnectionProvider::AbstractConnection::validateOptions | ( | hash< auto > | options,
|  | bool | check_required = True )
| protected

performs options validation in the constructor

Parameters

  options | a hash with options from the constructor
  check_required | check that all required options are set

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

## Member Data Documentation

## ◆ CF_LOGGER

const ConnectionProvider::AbstractConnection::CF_LOGGER = "logger"

Connection feature: Logger support.

Indicates that connection objects support setting / updating a logger interface object in the connection

## ◆ CF_UPDATE_OPTIONS

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)

See also
  UpdateOptionsInterface

## ◆ post_processing

*code ConnectionProvider::AbstractConnection::post_processing
| static

optional code for default post-processing of objects created by getImpl()

must take the connection object and the object created as arguments