"Fossies" - the Fresh Open Source Software Archive

Member "kea-1.6.2/src/lib/database/database_connection.h" (21 Feb 2020, 8981 Bytes) of package /linux/misc/kea-1.6.2.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "database_connection.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.6.1_vs_1.6.2.

    1 // Copyright (C) 2015-2020 Internet Systems Consortium, Inc. ("ISC")
    2 //
    3 // This Source Code Form is subject to the terms of the Mozilla Public
    4 // License, v. 2.0. If a copy of the MPL was not distributed with this
    5 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
    6 
    7 #ifndef DATABASE_CONNECTION_H
    8 #define DATABASE_CONNECTION_H
    9 
   10 #include <cc/data.h>
   11 #include <boost/noncopyable.hpp>
   12 #include <boost/function.hpp>
   13 #include <boost/shared_ptr.hpp>
   14 #include <exceptions/exceptions.h>
   15 #include <map>
   16 #include <string>
   17 
   18 namespace isc {
   19 namespace db {
   20 
   21 /// @brief Exception thrown if name of database is not specified
   22 class NoDatabaseName : public Exception {
   23 public:
   24     NoDatabaseName(const char* file, size_t line, const char* what) :
   25         isc::Exception(file, line, what) {}
   26 };
   27 
   28 /// @brief Exception thrown on failure to open database
   29 class DbOpenError : public Exception {
   30 public:
   31     DbOpenError(const char* file, size_t line, const char* what) :
   32         isc::Exception(file, line, what) {}
   33 };
   34 
   35 /// @brief Exception thrown on failure to execute a database function
   36 class DbOperationError : public Exception {
   37 public:
   38     DbOperationError(const char* file, size_t line, const char* what) :
   39         isc::Exception(file, line, what) {}
   40 };
   41 
   42 /// @brief Exception thrown when connectivity has been lost and
   43 /// cannot be recovered.
   44 class DbUnrecoverableError : public Exception {
   45 public:
   46     DbUnrecoverableError(const char* file, size_t line, const char* what) :
   47         isc::Exception(file, line, what) {}
   48 };
   49 
   50 /// @brief Invalid type exception
   51 ///
   52 /// Thrown when the factory doesn't recognize the type of the backend.
   53 class InvalidType : public Exception {
   54 public:
   55     InvalidType(const char* file, size_t line, const char* what) :
   56         isc::Exception(file, line, what) {}
   57 };
   58 
   59 /// @brief Invalid Timeout
   60 ///
   61 /// Thrown when the timeout specified for the database connection is invalid.
   62 class DbInvalidTimeout : public Exception {
   63 public:
   64     DbInvalidTimeout(const char* file, size_t line, const char* what) :
   65         isc::Exception(file, line, what) {}
   66 };
   67 
   68 /// @brief Invalid 'readonly' value specification.
   69 ///
   70 /// Thrown when the value of the 'readonly' boolean parameter is invalid.
   71 class DbInvalidReadOnly : public Exception {
   72 public:
   73     DbInvalidReadOnly(const char* file, size_t line, const char* what) :
   74         isc::Exception(file, line, what) {}
   75 };
   76 
   77 /// @brief Warehouses DB reconnect control values
   78 ///
   79 /// When a DatabaseConnection loses connectivity to its backend, it
   80 /// creates an instance of this class based on its configuration parameters and
   81 /// passes the instance into connection's DB lost callback.  This allows
   82 /// the layer(s) above the connection to know how to proceed.
   83 ///
   84 class ReconnectCtl {
   85 public:
   86     /// @brief Constructor
   87     /// @param backend_type type of the caller backend.
   88     /// @param max_retries maximum number of reconnect attempts to make
   89     /// @param retry_interval amount of time to between reconnect attempts
   90     ReconnectCtl(const std::string& backend_type, unsigned int max_retries,
   91                  unsigned int retry_interval)
   92         : backend_type_(backend_type), max_retries_(max_retries),
   93           retries_left_(max_retries), retry_interval_(retry_interval) {}
   94 
   95     /// @brief Returns the type of the caller backend.
   96     std::string backendType() const {
   97         return (backend_type_);
   98     }
   99 
  100     /// @brief Decrements the number of retries remaining
  101     ///
  102     /// Each call decrements the number of retries by one until zero is reached.
  103     /// @return true the number of retries remaining is greater than zero.
  104     bool checkRetries() {
  105         return (retries_left_ ? --retries_left_ : false);
  106     }
  107 
  108     /// @brief Returns the maximum number of retries allowed.
  109     unsigned int maxRetries() {
  110         return (max_retries_);
  111     }
  112 
  113     /// @brief Returns the number for retries remaining
  114     unsigned int retriesLeft() {
  115         return (retries_left_);
  116     }
  117 
  118     /// @brief Returns the amount of time to wait between reconnect attempts
  119     unsigned int retryInterval() {
  120         return (retry_interval_);
  121     }
  122 
  123 private:
  124     /// @brief Caller backend type.
  125     const std::string backend_type_;
  126 
  127     /// @brief Maximum number of retry attempts to make
  128     unsigned int max_retries_;
  129 
  130     /// @brief Number of attempts remaining
  131     unsigned int retries_left_;
  132 
  133     /// @brief The amount of time to wait between reconnect attempts
  134     unsigned int retry_interval_;
  135 };
  136 
  137 /// @brief Pointer to an instance of ReconnectCtl
  138 typedef boost::shared_ptr<ReconnectCtl> ReconnectCtlPtr;
  139 
  140 /// @brief Common database connection class.
  141 ///
  142 /// This class provides functions that are common for establishing
  143 /// connection with different types of databases; enables operations
  144 /// on access parameters strings. In particular, it provides a way
  145 /// to parse parameters in key=value format. This class is expected
  146 /// to be a base class for all @ref isc::dhcp::LeaseMgr and possibly
  147 /// @ref isc::dhcp::BaseHostDataSource derived classes.
  148 class DatabaseConnection : public boost::noncopyable {
  149 public:
  150 
  151     /// @brief Defines maximum value for time that can be reliably stored.
  152     ///
  153     /// @todo: Is this common for MySQL and Postgres? Maybe we should have
  154     /// specific values for each backend?
  155     ///
  156     /// If I'm still alive I'll be too old to care. You fix it.
  157     static const time_t MAX_DB_TIME;
  158 
  159     /// @brief Database configuration parameter map
  160     typedef std::map<std::string, std::string> ParameterMap;
  161 
  162     /// @brief Constructor
  163     ///
  164     /// @param parameters A data structure relating keywords and values
  165     ///        concerned with the database.
  166     DatabaseConnection(const ParameterMap& parameters)
  167         :parameters_(parameters) {
  168     }
  169 
  170     /// @brief Destructor
  171     virtual ~DatabaseConnection(){};
  172 
  173     /// @brief Instantiates a ReconnectCtl based on the connection's
  174     /// reconnect parameters
  175     /// @return pointer to the new ReconnectCtl object
  176     virtual ReconnectCtlPtr makeReconnectCtl() const;
  177 
  178     /// @brief Returns value of a connection parameter.
  179     ///
  180     /// @param name Name of the parameter which value should be returned.
  181     /// @return Value of one of the connection parameters.
  182     /// @throw BadValue if parameter is not found
  183     std::string getParameter(const std::string& name) const;
  184 
  185     /// @brief Parse database access string
  186     ///
  187     /// Parses the string of "keyword=value" pairs and separates them
  188     /// out into the map.
  189     ///
  190     /// @param dbaccess Database access string.
  191     ///
  192     /// @return @ref ParameterMap of keyword/value pairs.
  193     static ParameterMap parse(const std::string& dbaccess);
  194 
  195     /// @brief Redact database access string
  196     ///
  197     /// Takes the database parameters and returns a database access string
  198     /// passwords replaced by asterisks. This string is used in log messages.
  199     ///
  200     /// @param parameters Database access parameters (output of "parse").
  201     ///
  202     /// @return Redacted database access string.
  203     static std::string redactedAccessString(const ParameterMap& parameters);
  204 
  205     /// @brief Convenience method checking if database should be opened with
  206     /// read only access.
  207     ///
  208     /// @return true if "readonly" parameter is specified and set to true;
  209     /// false if "readonly" parameter is not specified or it is specified
  210     /// and set to false.
  211     bool configuredReadOnly() const;
  212 
  213     /// @brief Defines a callback prototype for propogating events upward
  214     typedef boost::function<bool (ReconnectCtlPtr db_retry)> DbLostCallback;
  215 
  216     /// @brief Invokes the connection's lost connectivity callback
  217     ///
  218     /// This function may be called by derivations when the connectivity
  219     /// to their data server is lost.  If connectivity callback was specified,
  220     /// this function will instantiate a ReconnectCtl and pass it to the
  221     /// callback.
  222     ///
  223     /// @return Returns the result of the callback or false if there is no
  224     /// callback.
  225     bool invokeDbLostCallback() const;
  226 
  227     /// @brief Unparse a parameter map
  228     ///
  229     /// @param params the parameter map to unparse
  230     /// @return a pointer to configuration
  231     static isc::data::ElementPtr toElement(const ParameterMap& params);
  232 
  233     /// @brief Unparse an access string
  234     ///
  235     /// @param dbaccess the database access string
  236     /// @return a pointer to configuration
  237     static isc::data::ElementPtr toElementDbAccessString(const std::string& dbaccess);
  238 
  239     /// @brief Optional call back function to invoke if a successfully
  240     /// open connection subsequently fails
  241     static DbLostCallback db_lost_callback;
  242 
  243 private:
  244 
  245     /// @brief List of parameters passed in dbconfig
  246     ///
  247     /// That will be mostly used for storing database name, username,
  248     /// password and other parameters required for DB access. It is not
  249     /// intended to keep any DHCP-related parameters.
  250     ParameterMap parameters_;
  251 
  252 };
  253 
  254 }  // namespace db
  255 }  // namespace isc
  256 
  257 #endif // DATABASE_CONNECTION_H