Qore ConnectionProvider Module Reference  1.0.1
ConnectionProvider.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
2 // @file ConnectionProvider.qm Qore user module providing an API for providing connections to %Qore
3 
4 /* ConnectionProvider.qm Copyright 2016 - 2018 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 
25 // this module requires Qore 0.8.13 or better
26 
27 
28 
29 
98 namespace ConnectionProvider {
101  public struct ConnectionInfo {
102  string name;
103  string desc;
105  bool loopback;
106  bool monitor;
108  string status;
109  string type;
110  bool up = False;
112  string url;
114  };
115 
117  public struct ConfigInfo {
118  string name;
119  string desc;
120  string url;
122  };
123 
125  public struct PingInfo {
126  string name;
127  string desc;
129  string url;
130  bool ok;
132  string info;
134  };
135 
137 
152  string get_connection_url(string str);
153 
154 
156 
171  AbstractConnection get_connection(string conn);
172 
173 
175 
190  *hash<string, AbstractConnection> get_connections(*bool verbose);
191 
192 
194 
209  *hash<string, hash<ConnectionInfo>> get_connection_hash(*bool verbose);
210 
211 
213 
216 
217 public:
218  public :
220  string name;
221 
223  string desc;
224 
226  string url;
227 
229  string safe_url;
230 
233 
236 
239 
242 
244  string status = "not checked";
245 
247  bool up = False;
248 
250  bool monitor;
251 
254 
256  bool loopback = False;
257 
259  static *code post_processing;
260 
261 public:
262 
264 
272  constructor(string n_name, string n_desc, string n_url, bool n_monitor, *hash n_opts, hash n_urlh, *string n_safe_url);
273 
274 
276 
281 private:
282  static string getSafeUrl(hash urlh);
283 public:
284 
285 
287 
291  hash<PingInfo> ping(bool throw_exception = False);
292 
293 
295 
296 private:
297  hash<PingInfo> pingIntern(hash<PingInfo> rv);
298 public:
299 
300 
302 
306  hash<ConnectionInfo> getInfo(bool with_password = False);
307 
308 
310 
312  hash<ConfigInfo> getConfigHash();
313 
314 
316  *hash getOptions();
317 
318 
321 
322 
325 
326 
328  *hash getRealOptions();
329 
330 
332 
334  object get(bool connect = True, *hash rtopts);
335 
336 
338 
341 
342 
344 
350 private:
351  abstract object getImpl(bool connect = True, *hash rtopts);
352 public:
353 
355  abstract string getType();
356  };
357 
360 
361 public:
362  private :
363  string error;
364 
365 public:
366 
368  constructor(string n_name, string n_desc, string n_url, *hash n_opts, string n_error, hash urlh) ;
369 
370 
372  object getImpl (bool connect=True, *hash rtopts);
373 
374 
376  string getType();
377 
378  };
379 
382 
383 public:
384  public :
385  string real_url;
386 
387 public:
388 
389  constructor(string name, string desc, string url, bool monitor, *hash opts, hash urlh) ;
390 
391  };
392 
394 
399 
400 public:
402 
409  constructor(string name, string desc, string url, bool monitor, *hash opts, hash urlh) ;
410 
411 
413  string getType();
414 
415 
417 
422 
423 
425 
429 private:
430  FtpClient getImpl(bool connect = True, *hash rtopts);
431 public:
432 
433 
435  static FtpConnection make(string name, string desc, string url, bool monitor, *hash opts, hash urlh);
436  };
437 
439 
453 
454 public:
455  public :
457  const Options = (
458  "http_version": True,
459  "max_redirects": True,
460  "proxy": True,
461  "timeout": True,
462  "connect_timeout": True,
463  "ssl_cert_path": True,
464  "ssl_key_password": True,
465  "ssl_key_path": True,
466  "ssl_verify_cert": True,
467  );
468 
470  const DefaultOptions = (
471  "timeout": 45s,
472  "connect_timeout": 45s,
473  );
474 
475  const OptionList = Options.keys();
476 
477 public:
478 
480 
487  constructor(string name, string desc, string url, bool monitor, *hash opts, hash urlh) ;
488 
489 
491 
495 private:
496  Qore::HTTPClient getImpl(bool connect = True, *hash rtopts);
497 public:
498 
499 
501 
514  hash getOptions();
515 
516 
518 
523 
524 
526  string getType();
527 
528 
530  static HttpConnection make(string name, string desc, string url, bool monitor, *hash opts, hash urlh);
531  };
532 
534 
538 
539 public:
540  public :
542  const Options = (
543  "readonly": True,
544  );
545 
547  const OptionList = Options.keys();
548 
549 public:
550 
552 
559  constructor(string name, string desc, string url, bool monitor, *hash opts, hash n_urlh) ;
560 
561 
563  string getType();
564 
565 
567 
573 private:
574  Dir getImpl(bool connect = True, *hash rtopts);
575 public:
576 
577 
579 
582  hash getOptions();
583 
584 
586  static FilesystemConnection make(string name, string desc, string url, bool monitor, *hash opts, hash urlh);
587  };
588 };
589 
590 // private, non-exported namespace
591 namespace Priv {
592  *hash priv_try_get_connections(string mod);
593 
594 
595  ConnectionProvider::AbstractConnection priv_try_get_connection(string mod, string conn);
596 
597 };
parseTextOptions()
this method is called when parsing connection file definitions from text files when loading into the ...
*hash getRuntimeOptions()
returns runtime options
string getType()
returns "http"
*hash< string, AbstractConnection > get_connections(*bool verbose)
returns all known connections as a hash keyed by connection identifier; values are AbstractConnection...
bool monitor
monitoring flag
Definition: ConnectionProvider.qm.dox.h:250
date date(date dt)
*hash opts
the options set on the connection
Definition: ConnectionProvider.qm.dox.h:121
base class for HTTP-based connections that need their URLs rewritten to create the real connection ob...
Definition: ConnectionProvider.qm.dox.h:381
date last_check
date/time of last check/ping
Definition: ConnectionProvider.qm.dox.h:241
hash< ConnectionInfo > getInfo(bool with_password=False)
returns a ConnectionInfo hash of information about the connection
constructor(string name, string desc, string url, bool monitor, *hash opts, hash n_urlh)
creates the FilesystemConnection object
*date last_check
the date/time value of the last connection check (or NOTHING if not checked)
Definition: ConnectionProvider.qm.dox.h:104
class for filesystem connections; returns an object of type Qore::Dir; this can be used to monitor fi...
Definition: ConnectionProvider.qm.dox.h:537
const Options
FilesystemConnection object connection options.
Definition: ConnectionProvider.qm.dox.h:542
string name
the connection name
Definition: ConnectionProvider.qm.dox.h:102
abstract object getImpl(bool connect=True, *hash rtopts)
this method must return the connection object corresponding to the object&#39;s configuration ...
constructor(string name, string desc, string url, bool monitor, *hash opts, hash urlh)
creates the FtpConnection object
*hash opts
connection options
Definition: ConnectionProvider.qm.dox.h:235
class for HTTP connections; returns Qore::HTTPClient objects
Definition: ConnectionProvider.qm.dox.h:452
string status
a string giving the connection&#39;s status
Definition: ConnectionProvider.qm.dox.h:108
static string getSafeUrl(hash urlh)
creates a "safe" URL string with password information removed
string info
a string giving the result of the ping ("OK" or an error message)
Definition: ConnectionProvider.qm.dox.h:132
const True
static FilesystemConnection make(string name, string desc, string url, bool monitor, *hash opts, hash urlh)
static constructor
string name
connection name
Definition: ConnectionProvider.qm.dox.h:220
*hash getDefaultOptions()
returns default options
string url
the full URL (including any username & password)
Definition: ConnectionProvider.qm.dox.h:120
AbstractConnection get_connection(string conn)
returns an AbstractConnection object if the identifier is known to a registered connection provider ...
*date updated
the date/time value of the update (or NOTHING if not updated)
Definition: ConnectionProvider.qm.dox.h:111
Dir getImpl(bool connect=True, *hash rtopts)
returns a Qore::Dir object
*hash getRuntimeOptions()
returns runtime options
bool up
a boolean vaue indicating the connection is known to be up (will be False if not checked) ...
Definition: ConnectionProvider.qm.dox.h:110
hash urlh
broken down URL hash (as returned by Qore::parse_url())
Definition: ConnectionProvider.qm.dox.h:238
static *code post_processing
optional code for default post-processing of objects created by getImpl(); must take the object creat...
Definition: ConnectionProvider.qm.dox.h:259
hash< PingInfo > ping(bool throw_exception=False)
returns a hash with the results of the ping operation
const False
const OptionList
FilesystemConnection object connection option list.
Definition: ConnectionProvider.qm.dox.h:547
string status
status string; in case of a connection error this string will be the error string ...
Definition: ConnectionProvider.qm.dox.h:244
*hash orig_opts
original connection options
Definition: ConnectionProvider.qm.dox.h:232
static FtpConnection make(string name, string desc, string url, bool monitor, *hash opts, hash urlh)
static constructor
abstract base class for connections
Definition: ConnectionProvider.qm.dox.h:215
*hash getOptions()
returns static / initialization options
string safe_url
"safe" URL (password information removed)
Definition: ConnectionProvider.qm.dox.h:229
Qore::HTTPClient getImpl(bool connect=True, *hash rtopts)
returns an Qore::HTTPClient object
static HttpConnection make(string name, string desc, string url, bool monitor, *hash opts, hash urlh)
static constructor
ping response info as returned by AbstractConnection::ping()
Definition: ConnectionProvider.qm.dox.h:125
string name
the name of the connection
Definition: ConnectionProvider.qm.dox.h:118
FtpClient getImpl(bool connect=True, *hash rtopts)
returns an Qore::FtpClient object
constructor(string n_name, string n_desc, string n_url, bool n_monitor, *hash n_opts, hash n_urlh, *string n_safe_url)
creates the AbstractConnection object
object getImpl(bool connect=True, *hash rtopts)
throws an exception because the object is invalid
string type
the connection type
Definition: ConnectionProvider.qm.dox.h:109
string url
a safe version of the URL (without passwords)
Definition: ConnectionProvider.qm.dox.h:129
this class is used to mark invalid connections so they can be loaded and reported as invalid ...
Definition: ConnectionProvider.qm.dox.h:359
bool monitor
a boolean vaue indicating if the connection should be monitored or not
Definition: ConnectionProvider.qm.dox.h:106
*hash getDefaultOptions()
returns default options
*hash opts
the options set on the connection
Definition: ConnectionProvider.qm.dox.h:128
config informaton as returned by AbstractConnection::getConfigHash()
Definition: ConnectionProvider.qm.dox.h:117
const DefaultOptions
HttpConnection default options.
Definition: ConnectionProvider.qm.dox.h:470
hash url_hash
a hash of URL information as returned by parse_url()
Definition: ConnectionProvider.qm.dox.h:113
bool loopback
a boolean vaue indicating if the connection is a loopback connection
Definition: ConnectionProvider.qm.dox.h:105
abstract string getType()
returns the string type name for the connection object
*hash getRealOptions()
returns options for saving the connection&#39;s configuration information
constructor(string name, string desc, string url, bool monitor, *hash opts, hash urlh)
creates the HttpConnection object
string desc
the description
Definition: ConnectionProvider.qm.dox.h:119
date time
a relative date/time value giving the elapsed time of the ping operation
Definition: ConnectionProvider.qm.dox.h:131
*hash opts
the original options used to create the object
Definition: ConnectionProvider.qm.dox.h:107
hash< ConfigInfo > getConfigHash()
returns a ConfigInfo hash of static configuration information about the connection ...
string url
the URL for the connection including the password (if any present and the with_password argument is T...
Definition: ConnectionProvider.qm.dox.h:112
string desc
the description
Definition: ConnectionProvider.qm.dox.h:127
string desc
connection description
Definition: ConnectionProvider.qm.dox.h:223
date updated
date/time of last update
Definition: ConnectionProvider.qm.dox.h:253
string name
the name of the connection
Definition: ConnectionProvider.qm.dox.h:126
Definition: ConnectionProvider.qm.dox.h:591
string get_connection_url(string str)
returns a URL string for the given identifier if the identifier is known to a registered connection p...
connection information hash as returned by AbstractConnection::getInfo()
Definition: ConnectionProvider.qm.dox.h:101
class for FTP connections; returns Qore::FtpClient objects
Definition: ConnectionProvider.qm.dox.h:398
bool up
connection status flag; set by monitoring or explicit pings/connections
Definition: ConnectionProvider.qm.dox.h:247
const Options
HttpConnection object connection options.
Definition: ConnectionProvider.qm.dox.h:457
bool ok
a boolean value giving the result of the ping
Definition: ConnectionProvider.qm.dox.h:130
*hash< string, hash< ConnectionInfo > > get_connection_hash(*bool verbose)
returns a hash of connection information keyed by connection identifier; values are ConnectionInfo ha...
*hash ping_info
an optional free-form hash giving additional info regarding ping operation or the remote system ...
Definition: ConnectionProvider.qm.dox.h:133
string url
connection URL (potentially with password info)
Definition: ConnectionProvider.qm.dox.h:226
hash hash(object obj)
constructor(string n_name, string n_desc, string n_url, *hash n_opts, string n_error, hash urlh)
creates the invalid connection object
string desc
the connection description
Definition: ConnectionProvider.qm.dox.h:103
hash< PingInfo > pingIntern(hash< PingInfo > rv)
performs the ping by executing get(); returns a PingInfo hash
bool loopback
set to True for loopback connections
Definition: ConnectionProvider.qm.dox.h:256
the ConnectionProvider namespace contains all the objects in the ConnectionProvider module ...
Definition: ConnectionProvider.qm.dox.h:99
string getType()
returns "ftp"
string getType()
returns "invalid"