Qore ConnectionProvider Module Reference 2.0
Loading...
Searching...
No Matches
ConnectionProvider::HttpConnection Class Reference

class for HTTP connections; returns Qore::HTTPClient objects More...

#include <HttpConnection.qc.dox.h>

Inheritance diagram for ConnectionProvider::HttpConnection:
[legend]

Public Member Methods

 constructor (hash< auto > config, *hash< auto > attr)
 Creates the HttpConnection object.
 
 constructor (string name, string desc, string url, hash< auto > attributes={}, hash< auto > options={}, *Logger logger)
 Creates the HttpConnection object.
 
*hash< auto > getConnectionOptions (*hash< auto > rtopts)
 Returns options for creating a new connection.
 
DataProvider::AbstractDataProvider getDataProvider (*hash< auto > constructor_options)
 Returns an HttpDataProvider object for this connection.
 
string getType ()
 Returns "http".
 
bool hasDataProvider ()
 Returns True, as the connection returns a data provider with the getDataProvider() method.
 
Qore::AbstractPollOperation startPollConnect ()
 Called to start the connection if the connection supports the polling API.
 
bool supportsPollingApi ()
 returns True, since this connection type supports the Qore Socket-based polling API
 
- Public Member Methods inherited from ConnectionProvider::AbstractConnectionWithInfo
 constructor (hash< auto > config, *hash< auto > attr)
 creates the AbstractConnectionWithInfo object
 
 constructor (string name, string description, string url, hash< auto > attributes={}, hash< auto > options={}, *Logger logger)
 creates the AbstractConnectionWithInfo object
 
hash< ConnectionSchemeInfogetConnectionSchemeInfo ()
 Returns the ConnectionSchemeInfo hash for this object.
 
*hash< auto > getDefaultOptions ()
 returns default options
 
*hash< auto > getOptions ()
 returns static / initialization options
 
- Public Member Methods inherited from ConnectionProvider::AbstractConnection
 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
 
hash< ConfigInfogetConfigHash ()
 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< ConnectionSchemeInfogetConnectionSchemeInfo ()
 Returns a default ConnectionSchemeInfo hash.
 
hash< ConnectionSchemeInfogetConnectionSchemeInfoImpl ()
 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< ConnectionInfogetInfo (*hash< auto > opts)
 returns a ConnectionInfo hash of information about the connection
 
hash< ConnectionInfogetInfo (bool with_password=False)
 returns a ConnectionInfo hash of information about the connection
 
hash< ConnectionDataInfogetInfoAsData (*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< PingInfoping (bool throw_exception)
 returns a hash with the results of the ping operation
 
hash< PingInfoping (int ping_flags=0)
 returns a hash with the results of the ping operation
 
Qore::AbstractPollOperation startPollConnect ()
 Called to start the connection polling operation.
 
bool supportsPollingApi ()
 returns True if the connection supports the Qore Socket-based polling API
 

Public Attributes

const ConnectionScheme = ...
 Connection entry info.
 
const Options = map {$1: True}
 HttpConnection object connection options.
 
- Public Attributes inherited from ConnectionProvider::AbstractConnection
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.
 
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 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
 
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())
 

Private Member Methods

hash< ConnectionSchemeInfogetConnectionSchemeInfoImpl ()
 Returns the ConnectionSchemeInfo hash for this object.
 
Qore::HTTPClient getImpl (bool connect=True, *hash< auto > rtopts)
 returns an Qore::HTTPClient object
 
 setChildCapabilities ()
 Sets child data provider capabilities.
 
- Private Member Methods inherited from ConnectionProvider::AbstractConnectionWithInfo
abstract hash< ConnectionSchemeInfogetConnectionSchemeInfoImpl ()
 Returns the ConnectionSchemeInfo hash for this object.
 
- Private Member Methods inherited from ConnectionProvider::AbstractConnection
*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< PingInfopingIntern (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.
 
hash< auto > validateOptions (hash< auto > options, bool check_required=True)
 performs options validation in the constructor
 

Additional Inherited Members

- Static Public Member Methods inherited from ConnectionProvider::AbstractConnection
static hash< ConnectionOptionInfogetConnectionOptionInfo (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 Methods 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.
 
- Static Public Attributes inherited from ConnectionProvider::AbstractConnection
static *code post_processing
 optional code for default post-processing of objects created by getImpl()
 

Detailed Description

class for HTTP connections; returns Qore::HTTPClient objects

Supports the following options:

  • "assume_encoding": assumes the given encoding if the server does not send a charset value
  • "connect_timeout": connection timeout to use in milliseconds (default: 45 seconds)
  • "error_passthru": if True then HTTP status codes indicating errors will not cause an HTTP-CLIENT-RECEIVE-ERROR exception to be raised, rather such responses will be passed through to the caller like any other response
  • "headers": headers to add in each outgoing request
  • "http_version": HTTP version to use ("1.0" or "1.1", defaults to "1.1")
  • "max_redirects": maximum redirects to support
  • "password": The password for authentication; only used if no username or password is set in the URL and if the username option is also used
  • "pre_encoded_urls": If True then all URI paths in URLs are assumed to be already percent encoded; if this flag is set and any unencoded characters are sent in a URL with a new request, an exception is raised
  • "proxy": proxy URL to use
  • "redirect_passthru": if True then redirect responses will be passed to the caller instead of processed
  • "ssl_cert_path": a path to an X.509 client certificate file in PEM format
  • "ssl_key_path": a path to a private key file in PEM format for the X.509 client certificate
  • "ssl_key_password": the password to the private key given with "ssl_key_path"
  • "ssl_verify_cert": if True then the server's certificate will only be accepted if it's verified
  • "timeout": transfer timeout to use in milliseconds (default: 45 seconds)
  • "username": The username for HTTP basic authentication; only used if no username or password is set in the URL and if the password option is also used
See also
HTTPClient::constructor(hash<auto> opts) for more information on the above options

Member Function Documentation

◆ constructor() [1/2]

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

Creates the HttpConnection object.

Parameters
configwith 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
attroptional 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-ERRORmissing or invalid connection option or attribute

◆ constructor() [2/2]

ConnectionProvider::HttpConnection::constructor ( string  name,
string  desc,
string  url,
hash< auto >  attributes = {},
hash< auto >  options = {},
*Logger  logger 
)

Creates the HttpConnection object.

Parameters
namethe name of the connection
descconnection description
urlconnection URL (potentially with password info)
attributesvarious attributes. See below
optionsconnection options

See AbstractConnection::constructor() for attributes and options reference.

Exceptions
CONNECTION-OPTION-ERRORmissing or invalid connection option

◆ getDataProvider()

DataProvider::AbstractDataProvider ConnectionProvider::HttpConnection::getDataProvider ( *hash< auto >  constructor_options)

Returns an HttpDataProvider object for this connection.

Parameters
constructor_optionsany additional constructor options for the data provider
Returns
an HttpDataProvider object for this connection
See also
hasDataProvider()

◆ getImpl()

Qore::HTTPClient ConnectionProvider::HttpConnection::getImpl ( bool  connect = True,
*hash< auto >  rtopts 
)
private

returns an Qore::HTTPClient object

Parameters
connectif True then a connection is made by calling Qore::HTTPClient::connect() before returning the object
rtoptsthis connection type does not accept any runtime option, so this parameter is ignored

◆ hasDataProvider()

bool ConnectionProvider::HttpConnection::hasDataProvider ( )

Returns True, as the connection returns a data provider with the getDataProvider() method.

Returns
True, as the connection returns a data provider with the getDataProvider() method
See also
getDataProvider()

◆ startPollConnect()

Qore::AbstractPollOperation ConnectionProvider::HttpConnection::startPollConnect ( )

Called to start the connection if the connection supports the polling API.

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::HttpConnection::supportsPollingApi ( )

returns True, since this connection type supports the Qore Socket-based polling API

Returns
True
Since
ConnectionProvider 1.7