MySQL 8.1.0
Source Code Documentation
plugin_config.h
Go to the documentation of this file.
1/*
2 Copyright (c) 2015, 2023, Oracle and/or its affiliates.
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License, version 2.0,
6 as published by the Free Software Foundation.
7
8 This program is also distributed with certain software (including
9 but not limited to OpenSSL) that is licensed under separate terms,
10 as designated in a particular file or component or in included license
11 documentation. The authors of MySQL hereby grant you an additional
12 permission to link the program and your derivative works with the
13 separately licensed software that they have included with MySQL.
14
15 This program is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License for more details.
19
20 You should have received a copy of the GNU General Public License
21 along with this program; if not, write to the Free Software
22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
23*/
24
25#ifndef MYSQL_HARNESS_PLUGIN_CONFIG_INCLUDED
26#define MYSQL_HARNESS_PLUGIN_CONFIG_INCLUDED
27
28#include <chrono>
29#include <limits>
30#include <optional>
31#include <string>
32
33#include "harness_export.h"
36
37namespace mysql_harness {
38
39/** Exception that gets thrown when the configuration option is missing
40 */
41class option_not_present : public std::invalid_argument {
42 public:
43 using std::invalid_argument::invalid_argument;
44};
45
46/** Exception that gets thrown when the configuration option is present
47 * but it is empty value
48 */
49class option_empty : public std::invalid_argument {
50 public:
51 using std::invalid_argument::invalid_argument;
52};
53
54/**
55 * Retrieve and manage plugin configuration.
56 *
57 * BasePluginConfig is an abstract class which can be used to by plugins
58 * to derive their own class retrieving configuration from, for example,
59 * Harness `ConfigSection instances`.
60 */
61class HARNESS_EXPORT BasePluginConfig {
62 public:
63 BasePluginConfig() = default;
64
67
70
71 /**
72 * destructor
73 */
74 virtual ~BasePluginConfig() = default;
75
76 /**
77 * get description of the option.
78 *
79 * For example, option wait_timeout in section [routing:homepage] will
80 * return a prefix (without quotes):
81 *
82 * option wait_timeout in [routing:homepage]
83 *
84 * @param section configuration section
85 * @param option Name of the option
86 *
87 * @return Prefix as std::string
88 */
89 std::string get_option_description(
90 const mysql_harness::ConfigSection *section,
91 const std::string &option) const;
92
93 /**
94 * Gets the default for the given option.
95 *
96 * Gets the default value of the given option. If no default option
97 * is available, an empty string is returned.
98 *
99 * @param option name of the option
100 * @return default value for given option as std::string
101 */
102 virtual std::string get_default(const std::string &option) const = 0;
103
104 /**
105 * Returns whether the given option is required.
106 *
107 * @return bool
108 */
109 virtual bool is_required(const std::string &option) const = 0;
110
111 /**
112 * get option value.
113 *
114 * gets the option from a config-section (or its default value if it doesn't
115 * exist) and converts it with a transformation function.
116 *
117 * @param section configuration section
118 * @param option name of the option
119 * @param transformer transformation function. The signature of the
120 * transformation function should be equivalent to:
121 * @c (const std::string &value, const std::string &option_description)
122 * and returns the transformed value.
123 * @returns return value of the the transformation function.
124 */
125 template <class Func>
126 decltype(auto) get_option(const mysql_harness::ConfigSection *section,
127 const std::string &option,
128 Func &&transformer) const {
129 const auto value = get_option_string_or_default_(section, option);
130
131 return transformer(value, get_option_description(section, option));
132 }
133
134 /**
135 * get option value.
136 *
137 * gets the option from a config-section and converts it with a transformation
138 * function.
139 *
140 * does not call get_default().
141 *
142 * @param section configuration section
143 * @param option name of the option
144 * @param transformer transformation function. The signature of the
145 * transformation function should be equivalent to:
146 * @c (const std::string &value, const std::string &option_description)
147 * and returns the transformed value.
148 * @returns transformed value.
149 */
150 template <class Func>
151 decltype(auto) get_option_no_default(
152 const mysql_harness::ConfigSection *section, const std::string &option,
153 Func &&transformer) const {
154 const auto value = get_option_string_(section, option);
155
156 return transformer(value, get_option_description(section, option));
157 }
158
159 /**
160 * Gets value of given option as string.
161 *
162 * @throws option_not_present if the required option is missing
163 * @throws option_empty if the required option is present but empty
164 *
165 * @param section Instance of ConfigSection
166 * @param option name of the option
167 * @return Option value as std::string
168 *
169 */
170 [[deprecated("use get_option(..., StringOption{}) instead")]]
171 // line-break
172 std::string
174 const std::string &option) const {
175 return get_option(section, option,
176 [](auto const &value, auto const &) { return value; });
177 }
178
179 /**
180 * Gets an unsigned integer using the given option.
181 *
182 * Gets an unsigned integer using the given option. The type can be
183 * any unsigned integer type such as uint16_t.
184 *
185 * The min_value argument can be used to set a minimum value for
186 * the option. For example, when 0 (zero) is not allowed, min_value
187 * can be set to 0. The maximum value is whatever the maximum of the
188 * use type is.
189 *
190 * Throws std::invalid_argument on errors.
191 *
192 * @param section Instance of ConfigSection
193 * @param option Option name in section
194 * @param min_value Minimum value
195 * @param max_value Maximum value
196 * @return value read from the configuration
197 */
198 template <class T>
199 [[deprecated("used get_option(..., IntOption<T>{}) instead")]]
200 // line-break
202 const std::string &option, T min_value = 0,
203 T max_value = std::numeric_limits<T>::max()) const {
204 return get_option(section, option, IntOption<T>{min_value, max_value});
205 }
206
207 /**
208 * Gets a number of milliseconds using the given option.
209 *
210 * The expected option value is a string with floating point number in seconds
211 * (with '.' as a decimal separator) in standard or scientific notation
212 *
213 * - for value = "1.0" expected result is std::chrono:milliseconds(1000)
214 * - for value = "0.01" expected result is std::chrono:milliseconds(10)
215 * - for value = "1.6E-2" expected result is std::chrono:milliseconds(16)
216 *
217 * @param section Instance of ConfigSection
218 * @param option Option name in section
219 * @param min_value Minimum value
220 * @param max_value Maximum value
221 *
222 * @return value converted to milliseconds
223 * @throws std::invalid_argument on errors
224 */
225 [[deprecated("used get_option(..., MilliSecondsOption{}) instead")]]
226 // line-break
227 std::chrono::milliseconds
229 const mysql_harness::ConfigSection *section, const std::string &option,
230 double min_value = 0.0,
231 double max_value = std::numeric_limits<double>::max()) const {
232 return get_option(section, option,
233 MilliSecondsOption{min_value, max_value});
234 }
235
236 protected:
237 /**
238 * Constructor for derived classes.
239 */
241 : section_name_{get_section_name(section)} {}
242
243 /**
244 * Generate the name for this configuration.
245 *
246 * @param section Instance of ConfigSection
247 * @return the name for this configuration
248 */
249 static std::string get_section_name(
250 const mysql_harness::ConfigSection *section);
251
252 private:
253 /**
254 * Name of the section
255 */
256 std::string section_name_;
257
258 /**
259 * get value of an option from a config-section.
260 *
261 * does not call get_default()
262 *
263 * @return a value of the option if it exists.
264 */
265 std::optional<std::string> get_option_string_(
266 const mysql_harness::ConfigSection *section,
267 const std::string &option) const;
268
269 /**
270 * get value of an option from a config-section.
271 *
272 * gets value from get_default() if the option-value
273 * is not present or empty.
274 *
275 * @return a value of the option if it exists.
276 */
277 std::string get_option_string_or_default_(
278 const mysql_harness::ConfigSection *section,
279 const std::string &option) const;
280};
281
282} // namespace mysql_harness
283
284#endif // MYSQL_HARNESS_PLUGIN_CONFIG_INCLUDED
Retrieve and manage plugin configuration.
Definition: plugin_config.h:61
std::chrono::milliseconds get_option_milliseconds(const mysql_harness::ConfigSection *section, const std::string &option, double min_value=0.0, double max_value=std::numeric_limits< double >::max()) const
Gets a number of milliseconds using the given option.
Definition: plugin_config.h:228
T get_uint_option(const mysql_harness::ConfigSection *section, const std::string &option, T min_value=0, T max_value=std::numeric_limits< T >::max()) const
Gets an unsigned integer using the given option.
Definition: plugin_config.h:201
BasePluginConfig(const mysql_harness::ConfigSection *section)
Constructor for derived classes.
Definition: plugin_config.h:240
std::string get_option_string(const mysql_harness::ConfigSection *section, const std::string &option) const
Gets value of given option as string.
Definition: plugin_config.h:173
decltype(auto) get_option_no_default(const mysql_harness::ConfigSection *section, const std::string &option, Func &&transformer) const
get option value.
Definition: plugin_config.h:151
BasePluginConfig & operator=(BasePluginConfig &&)=default
BasePluginConfig(BasePluginConfig &&)=default
virtual bool is_required(const std::string &option) const =0
Returns whether the given option is required.
BasePluginConfig(const BasePluginConfig &)=default
std::string section_name_
Name of the section.
Definition: plugin_config.h:256
decltype(auto) get_option(const mysql_harness::ConfigSection *section, const std::string &option, Func &&transformer) const
get option value.
Definition: plugin_config.h:126
virtual std::string get_default(const std::string &option) const =0
Gets the default for the given option.
virtual ~BasePluginConfig()=default
destructor
BasePluginConfig & operator=(const BasePluginConfig &)=default
Configuration section.
Definition: config_parser.h:140
Definition: config_option.h:167
Definition: config_option.h:107
Exception that gets thrown when the configuration option is present but it is empty value.
Definition: plugin_config.h:49
Exception that gets thrown when the configuration option is missing.
Definition: plugin_config.h:41
static std::string get_option(const mysql_harness::ConfigSection *section, const std::string &key, const std::string &def_value)
Definition: metadata_cache_plugin.cc:106
Definition: common.h:41