$darkmode
Qore ConnectionProvider Module Reference 1.11
AbstractConnection.qc.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
2 // Qore AbstractConnection class definition
3 
4 /* AbstractConnection.qc Copyright 2016 - 2023 Qore Technologies, s.r.o.
5 
6  Permission is hereby granted, free of charge, to any person obtaining a
7  copy of this software and associated documentation files (the "Software"),
8  to deal in the Software without restriction, including without limitation
9  the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  and/or sell copies of the Software, and to permit persons to whom the
11  Software is furnished to do so, subject to the following conditions:
12 
13  The above copyright notice and this permission notice shall be included in
14  all copies or substantial portions of the Software.
15 
16  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  DEALINGS IN THE SOFTWARE.
23 */
24 
26 
28 namespace ConnectionProvider {
30 
34 class AbstractConnection : public Qore::Serializable, public Logger::LoggerWrapper {
35 
36 public:
38  string name;
39 
41  string desc;
42 
44  string url;
45 
47  string safe_url;
48 
50  *hash<auto> orig_opts;
51 
53  *hash<auto> opts;
54 
56  hash<auto> urlh;
57 
60 
62  string status = "not checked";
63 
65  bool up = True;
66 
68  bool monitor;
69 
72 
74  bool loopback = False;
75 
77 
79  static *code post_processing;
80 
82  bool enabled = True;
83 
85  bool locked = False;
86 
88  bool debug_data = False;
89 
91  hash<auto> tags = {};
92 
95 
98 
101 
104 
107 
109  hash<auto> internal_info;
110 
112  transient hash<auto> transient_info;
113 
115 
117  const CF_LOGGER = "logger";
118 
120 
126  const CF_UPDATE_OPTIONS = "update-options";
127 
129 
139  deprecated
140  constructor(string name, string desc, string url, bool monitor, *hash opts, hash urlh, *string safe_url, *bool enabled);
141 
142 
144 
162  constructor(string name, string description, string url, hash<auto> attributes = {}, hash<auto> options = {}, *LoggerInterface logger) ;
163 
164 
166 
170  string getName();
171 
172 
174 
178  string getDescription();
179 
180 
182 
186  string getUrl();
187 
188 
190 
194  string getSafeUrl();
195 
196 
198 
202  hash<PingInfo> ping(bool throw_exception = False);
203 
204 
206 protected:
207  hash<PingInfo> pingIntern(hash<PingInfo> rv);
208 public:
209 
210 
212 
218  hash<ConnectionInfo> getInfo(bool with_password = False);
219 
220 
222 
227  hash<ConnectionInfo> getInfo(*hash<auto> opts);
228 
229 
231 
233  *hash<string, bool> getFeatures();
234 
235 
237 
241  hash<auto> getExtendedInfo(*hash<auto> opts);
242 
243 
245 
247  hash<ConfigInfo> getConfigHash();
248 
249 
251  hash<ConnectionSchemeInfo> getConnectionSchemeInfo();
252 
253 
255  hash<ConnectionSchemeInfo> getConnectionSchemeInfoImpl();
256 
257 
259  *hash<auto> getOptions();
260 
261 
263  *hash<auto> getRuntimeOptions();
264 
265 
267  *hash<auto> getDefaultOptions();
268 
269 
271  *hash<auto> getRealOptions();
272 
273 
275 
277  object get(bool connect = True, *hash<auto> rtopts);
278 
279 
281 
285 
286 
288  hash<auto> getTags();
289 
290 
292  auto getTag(string tag);
293 
294 
296 
298  auto getTagEx(string tag);
299 
300 
302 
313  AbstractDataProvider getDataProvider();
314 
315 
317 
327 
328 
330 
342 
343 
345 
354 
355 
357 
361  object getPollImpl();
362 
363 
366 
367 
369  handlePingFailed(date delta, hash<ExceptionInfo> ex);
370 
371 
373  handlePingFailed(date delta, string err);
374 
375 
377 
379 protected:
381 public:
382 
383 
385 
393 protected:
394  hash<UrlInfo> parseUrl(string url);
395 public:
396 
397 
399 
412 protected:
413  string getSafeUrl(hash<auto> urlh);
414 public:
415 
416 
418 
425 protected:
426  hash<auto> validateOptions(hash<auto> options);
427 public:
428 
429 
431 
434 private:
435  constructorInit(string name, string description, string url, hash<auto> attributes, hash<auto> options);
436 public:
437 
438 
440 
444 protected:
445  *hash<string, bool> getFeaturesImpl();
446 public:
447 
448 
450 protected:
452 public:
453 
454 
456  abstract string getType();
457 
459 
465 protected:
466  abstract object getImpl(bool connect = True, *hash<auto> rtopts);
467 public:
468 };
469 }; // ConnectionProvider namespace
abstract base class for connections
Definition: AbstractConnection.qc.dox.h:34
string desc
connection description
Definition: AbstractConnection.qc.dox.h:41
hash< ConnectionSchemeInfo > getConnectionSchemeInfoImpl()
Override in subclasses to return a native ConnectionSchemeInfo hash.
bool locked
locked/unlocked flag
Definition: AbstractConnection.qc.dox.h:85
string getName()
Returns the connection name.
hash< ConnectionSchemeInfo > getConnectionSchemeInfo()
Returns a default ConnectionSchemeInfo hash.
pingImpl()
performs the internal ping
bool hasDataProvider()
returns True if the connection returns a data provider with the getDataProvider() method
bool children_can_support_transactions
if the data provider or any of its children support transaction management
Definition: AbstractConnection.qc.dox.h:106
*hash< auto > opts
connection options
Definition: AbstractConnection.qc.dox.h:53
object getPollImpl()
Returns an unconnected object for a non-blocking poll operation.
object get(bool connect=True, *hash< auto > rtopts)
returns the underlying connection object
hash< ConnectionInfo > getInfo(bool with_password=False)
returns a ConnectionInfo hash of information about the connection
const CF_LOGGER
Connection feature: Logger support.
Definition: AbstractConnection.qc.dox.h:117
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 > internal_info
internal tags (serializable)
Definition: AbstractConnection.qc.dox.h:109
*hash< auto > orig_opts
original connection options
Definition: AbstractConnection.qc.dox.h:50
string url
connection URL (potentially with password info)
Definition: AbstractConnection.qc.dox.h:44
bool children_can_support_messages
if the data provider or any of its children support messages
Definition: AbstractConnection.qc.dox.h:103
constructor(string name, string description, string url, hash< auto > attributes={}, hash< auto > options={}, *LoggerInterface logger)
creates the AbstractConnection object
hash< UrlInfo > parseUrl(string url)
Parse the URL to a hash.
hash< ConfigInfo > getConfigHash()
returns a ConfigInfo hash of static configuration information about the connection
bool monitor
monitoring flag
Definition: AbstractConnection.qc.dox.h:68
string safe_url
"safe" URL (password information removed)
Definition: AbstractConnection.qc.dox.h:47
setChildCapabilities()
Override to set child data provider capabilities once per child class.
Qore::AbstractPollOperation startPollConnect()
Called to start the connection polling operation.
hash< auto > tags
connection tags; user-defined key-value pairs
Definition: AbstractConnection.qc.dox.h:91
string getSafeUrl(hash< auto > urlh)
creates a "safe" URL string with password information removed
bool enabled
enabled/disabled indicator flag
Definition: AbstractConnection.qc.dox.h:82
AbstractDataProvider getDataProvider()
returns a data provider object for this connection, if supported
*hash< string, bool > getFeatures()
Returns a list of connection-defined features.
date last_check
date/time of last check/ping
Definition: AbstractConnection.qc.dox.h:59
*hash< auto > getDefaultOptions()
returns default options
bool up
connection status flag; set by monitoring or explicit pings/connections
Definition: AbstractConnection.qc.dox.h:65
string getDescription()
Returns the connection description.
hash< PingInfo > pingIntern(hash< PingInfo > rv)
performs the ping by executing get(); returns a PingInfo hash
const CF_UPDATE_OPTIONS
Connection feature: Update Options support.
Definition: AbstractConnection.qc.dox.h:126
bool supportsPollingApi()
returns True if the connection supports the Qore Socket-based polling API
bool debug_data
debug data flag; to be used an an indication for a higher-level implementation
Definition: AbstractConnection.qc.dox.h:88
constructorInit(string name, string description, string url, hash< auto > attributes, hash< auto > options)
Common construtor implementation.
string name
connection name
Definition: AbstractConnection.qc.dox.h:38
transient hash< auto > transient_info
internal transient tags (non-serializable)
Definition: AbstractConnection.qc.dox.h:112
abstract object getImpl(bool connect=True, *hash< auto > rtopts)
this method must return the connection object corresponding to the object's configuration
deprecated constructor(string name, string desc, string url, bool monitor, *hash opts, hash urlh, *string safe_url, *bool enabled)
creates the AbstractConnection object
handlePingFailed(date delta, hash< ExceptionInfo > ex)
Handles a failed ping operation on the connection.
string getSafeUrl()
Returns the connection safe URL (without password info)
string getUrl()
Returns the connection URL.
hash< auto > getExtendedInfo(*hash< auto > opts)
Returns connection info plus any extended information returned by the connection.
auto getTag(string tag)
returns the value of the given tag or NOTHING if not present
string status
status string; in case of a connection error this string will be the error string
Definition: AbstractConnection.qc.dox.h:62
parseTextOptions()
this method is called when parsing connection file definitions from text files when loading into the ...
date updated
date/time of last update
Definition: AbstractConnection.qc.dox.h:71
bool children_can_support_apis
if the data provider or any of its children support requests (APIs)
Definition: AbstractConnection.qc.dox.h:94
static *code post_processing
optional code for default post-processing of objects created by getImpl()
Definition: AbstractConnection.qc.dox.h:79
bool loopback
set to True for loopback connections
Definition: AbstractConnection.qc.dox.h:74
*hash< auto > getRuntimeOptions()
returns runtime options
bool children_can_support_observers
if the data provider or any of its children support events
Definition: AbstractConnection.qc.dox.h:100
*hash< string, bool > getFeaturesImpl()
Returns a hash of connection-defined features.
bool children_can_support_records
if the data provider or any of its children support records
Definition: AbstractConnection.qc.dox.h:97
abstract string getType()
returns the string type name for the connection object
hash< auto > validateOptions(hash< auto > options)
performs options validation in the constructor
*hash< auto > getRealOptions()
returns options for saving the connection's configuration information
handlePingFailed(date delta, string err)
Handles a failed ping operation on the connection.
*hash< auto > getOptions()
returns static / initialization options
hash< auto > urlh
broken down URL hash (as returned by Qore::parse_url())
Definition: AbstractConnection.qc.dox.h:56
hash< auto > getTags()
returns all tags associated with the connection
hash< PingInfo > ping(bool throw_exception=False)
returns a hash with the results of the ping operation
handlePingSuccess(date delta)
Handles a successful ping operation on the connection.
hash< ConnectionInfo > getInfo(*hash< auto > opts)
returns a ConnectionInfo hash of information about the connection
const True
const False
date date(date dt)
hash< auto > hash(object obj)
The ConnectionProvider namespace.
Definition: AbstractConnection.qc.dox.h:28