Current File : //backups/router/usr/local/include/kea/database/backend_selector.h
// Copyright (C) 2018-2022 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
#ifndef BACKEND_SELECTOR_H
#define BACKEND_SELECTOR_H
#include <cc/data.h>
#include <cc/cfg_to_element.h>
#include <cstdint>
#include <string>
namespace isc {
namespace db {
/// @brief Config Backend selector.
///
/// Each Kea server using database as a configuration respository
/// may use multiple configuration backends simultaneously. The most
/// typical case is to use a single configuration backend per server,
/// but there are use cases when configuration information is distributed
/// accross multiple database instances. In the future, there may be
/// also caching mechanisms implemented, which will allow for storing
/// results of certain database queries in memory.
///
/// From the server perspective, the most common use of the configuration
/// backend is to fetch entire configuration information from the
/// databases (upon startup) or fetch the latest updates to the
/// configuration, e.g. new subnet added, DHCP option modified etc.
/// In those cases, it is not so important from the server which backend
/// this data come from. Therefore, the server would fetch this information
/// from all available backends.
///
/// When the server administrator wants to insert some new data into
/// the database, modify existing data or simply wants to check the
/// contents of one of the database instance, he would specify which
/// database backend he wants to direct queries to.
///
/// The @c BackendSelector class provides means to specify whether
/// the queries should be directed to any backend (see server case
/// above) or to a specific backend (data insertion case above).
/// In addition, the @c BackendSelector allows for using various
/// criteria for selecting a backend to use. Currently those criteria
/// are: database type (e.g. mysql), database host and database port.
/// In order to use a specific port, the database host must also be
/// specified. Note that in a general case multiple backends of the
/// same type can be used simultaneously, e.g. multiple MySQL backends.
/// In that case, it may be necessary to specify host (and port) to
/// issue a query to the right one.
///
/// The @c BackendSelector class may be extended in the future to provide
/// additional backend selection criteria.
class BackendSelector : public data::CfgToElement {
public:
/// @brief Supported database types.
///
/// The @c UNSPEC indicates that the database type is not specified
/// as selection criteria.
enum class Type {
MYSQL,
POSTGRESQL,
UNSPEC
};
/// @brief Default constructor.
///
/// It sets the selector to "unspecified". When this selector is used
/// the backend pool will use "any" backend. This has a different meaning
/// for each type of query. See the @c BaseConfigBackendPool for details.
explicit BackendSelector();
/// @brief Constructor specifying backend type as a selection criteria.
///
/// @param backend_type Type of the backend to be selected.
explicit BackendSelector(const Type& backend_type);
/// @brief Constructor for specifying host and optionally port as a
/// selection criteria.
///
/// @param host Hostname to be used for selecting a backend.
/// @param port Port number to be used for selecting a backend. This value
/// is optional and is ignored when set to 0. It must be used in conjunction
/// with hostname.
explicit BackendSelector(const std::string& host, const uint16_t port = 0);
/// @brief Constructor for selecting a backend using JSON access map.
///
/// The provided access map must have the same structure as an element
/// of the "config-databases" configuration parameter. However, it merely
/// takes into account: "type", "host" and "port" parameters. In addition,
/// these parameters are optional. The following are valid combinations:
///
/// @code
/// {
/// "type": "mysql"
/// }
/// @endcode
///
/// @code
/// {
/// "host": "somehost.example.org"
/// }
/// @endcode
///
/// @code
/// {
/// "host": "somehost.example.org",
/// "port": 1234
/// }
/// @endcode
///
/// @code
/// {
/// "type": "mysql"
/// "host": "somehost.example.org",
/// }
/// @endcode
///
/// @code
/// {
/// "type": "mysql"
/// "host": "somehost.example.org",
/// "port": 1234
/// }
/// @endcode
///
/// where "type" can be any of the supported backend types.
///
/// This constructor is useful for creating backend selectors from the
/// received control commands.
///
/// @param access_map Access map as provided above.
explicit BackendSelector(const data::ConstElementPtr& access_map);
/// @brief Returns instance of the "unspecified" backend selector.
static const BackendSelector& UNSPEC();
/// @brief Checks if selector is "unspecified".
///
/// @return true if backend type is @c UNSPEC, hostname is empty and
/// port number 0, false otherwise.
bool amUnspecified() const;
/// @brief Returns backend type selected.
Type getBackendType() const {
return (backend_type_);
}
/// @brief Returns host selected.
///
/// @return host if specified or empty string if host is not
/// specified.
std::string getBackendHost() const {
return (host_);
}
/// @brief Returns port selected.
///
/// @return port number of the selected backend or 0 if port number
/// is not specified.
uint16_t getBackendPort() const {
return (port_);
}
/// @brief Returns selections as text.
///
/// @return Collection of comma separated selections, e.g.
/// "type=mysql,host=somehost.example.org,port=1234".
std::string toText() const;
/// @brief Unparse a backend selector object.
///
/// The caller must ensure that the selector type is specified.
///
/// @return A pointer to unparsed backend selector configuration.
/// @throw BadValue If the backend selector type is unspecified.
virtual data::ElementPtr toElement() const;
/// @brief Converts string to backend type.
///
/// @param type Backend type as string.
static Type stringToBackendType(const std::string& type);
/// @brief Converts backend type to string.
///
/// @param type Backend type to be converted.
static std::string backendTypeToString(const Type& type);
private:
/// @brief Checks if the specified selector is valid.
///
/// It checks if the port number is specified in conjunction with
/// host.
/// @throw BadValue if selector validation fails.
void validate() const;
/// @brief Backend type selected.
Type backend_type_;
/// @brief Host selected.
std::string host_;
/// @brief Port number selected.
uint16_t port_;
};
} // end of namespace isc::db
} // end of namespace isc
#endif
Mini Shell