MySQL 8.0.30
Source Code Documentation
plugin_config.h
Go to the documentation of this file.
1/*
2 Copyright (c) 2015, 2022, 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 configuarion 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 configuarion 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 /**
64 * destructor
65 */
66 virtual ~BasePluginConfig() = default;
67
68 /**
69 * get description of the option.
70 *
71 * For example, option wait_timeout in section [routing:homepage] will
72 * return a prefix (without quotes):
73 *
74 * option wait_timeout in [routing:homepage]
75 *
76 * @param section configuration section
77 * @param option Name of the option
78 *
79 * @return Prefix as std::string
80 */
81 std::string get_option_description(
82 const mysql_harness::ConfigSection *section,
83 const std::string &option) const;
84
85 /**
86 * Gets the default for the given option.
87 *
88 * Gets the default value of the given option. If no default option
89 * is available, an empty string is returned.
90 *
91 * @param option name of the option
92 * @return default value for given option as std::string
93 */
94 virtual std::string get_default(const std::string &option) const = 0;
95
96 /**
97 * Returns whether the given option is required.
98 *
99 * @return bool
100 */
101 virtual bool is_required(const std::string &option) const = 0;
102
103 /**
104 * get option value.
105 *
106 * gets the option from a config-section (or its default value if it doesn't
107 * exist) and converts it with a transformation function.
108 *
109 * @param section configuration section
110 * @param option name of the option
111 * @param transformer transformation function. The signature of the
112 * transformation function should be equivalent to:
113 * @c (const std::string &value, const std::string &option_description)
114 * and returns the transformed value.
115 * @returns return value of the the transformation function.
116 */
117 template <class Func>
118 decltype(auto) get_option(const mysql_harness::ConfigSection *section,
119 const std::string &option,
120 Func &&transformer) const {
121 const auto value = get_option_string_or_default_(section, option);
122
123 return transformer(value, get_option_description(section, option));
124 }
125
126 /**
127 * get option value.
128 *
129 * gets the option from a config-section and converts it with a transformation
130 * function.
131 *
132 * does not call get_default().
133 *
134 * @param section configuration section
135 * @param option name of the option
136 * @param transformer transformation function. The signature of the
137 * transformation function should be equivalent to:
138 * @c (const std::string &value, const std::string &option_description)
139 * and returns the transformed value.
140 * @returns transformed value.
141 */
142 template <class Func>
143 decltype(auto) get_option_no_default(
144 const mysql_harness::ConfigSection *section, const std::string &option,
145 Func &&transformer) const {
146 const auto value = get_option_string_(section, option);
147
148 return transformer(value, get_option_description(section, option));
149 }
150
151 /**
152 * Gets value of given option as string.
153 *
154 * @throws option_not_present if the required option is missing
155 * @throws option_empty if the required option is present but empty
156 *
157 * @param section Instance of ConfigSection
158 * @param option name of the option
159 * @return Option value as std::string
160 *
161 */
162 [[deprecated("use get_option(..., StringOption{}) instead")]]
163 // line-break
164 std::string
166 const std::string &option) const {
167 return get_option(section, option,
168 [](auto const &value, auto const &) { return value; });
169 }
170
171 /**
172 * Gets an unsigned integer using the given option.
173 *
174 * Gets an unsigned integer using the given option. The type can be
175 * any unsigned integer type such as uint16_t.
176 *
177 * The min_value argument can be used to set a minimum value for
178 * the option. For example, when 0 (zero) is not allowed, min_value
179 * can be set to 0. The maximum value is whatever the maximum of the
180 * use type is.
181 *
182 * Throws std::invalid_argument on errors.
183 *
184 * @param section Instance of ConfigSection
185 * @param option Option name in section
186 * @param min_value Minimum value
187 * @param max_value Maximum value
188 * @return value read from the configuration
189 */
190 template <class T>
191 [[deprecated("used get_option(..., IntOption<T>{}) instead")]]
192 // line-break
194 const std::string &option, T min_value = 0,
195 T max_value = std::numeric_limits<T>::max()) const {
196 return get_option(section, option, IntOption<T>{min_value, max_value});
197 }
198
199 /**
200 * Gets a number of milliseconds using the given option.
201 *
202 * The expected option value is a string with floating point number in seconds
203 * (with '.' as a decimal separator) in standard or scientific notation
204 *
205 * - for value = "1.0" expected result is std::chrono:milliseconds(1000)
206 * - for value = "0.01" expected result is std::chrono:milliseconds(10)
207 * - for value = "1.6E-2" expected result is std::chrono:milliseconds(16)
208 *
209 * @param section Instance of ConfigSection
210 * @param option Option name in section
211 * @param min_value Minimum value
212 * @param max_value Maximum value
213 *
214 * @return value converted to milliseconds
215 * @throws std::invalid_argument on errors
216 */
217 [[deprecated("used get_option(..., MilliSecondsOption{}) instead")]]
218 // line-break
219 std::chrono::milliseconds
221 const mysql_harness::ConfigSection *section, const std::string &option,
222 double min_value = 0.0,
223 double max_value = std::numeric_limits<double>::max()) const {
224 return get_option(section, option,
225 MilliSecondsOption{min_value, max_value});
226 }
227
228 protected:
229 /**
230 * Constructor for derived classes.
231 */
233 : section_name_{get_section_name(section)} {}
234
235 /**
236 * Generate the name for this configuration.
237 *
238 * @param section Instance of ConfigSection
239 * @return the name for this configuration
240 */
241 static std::string get_section_name(
242 const mysql_harness::ConfigSection *section);
243
244 private:
245 /**
246 * Name of the section
247 */
248 std::string section_name_;
249
250 /**
251 * get value of an option from a config-section.
252 *
253 * does not call get_default()
254 *
255 * @return a value of the option if it exists.
256 */
257 std::optional<std::string> get_option_string_(
258 const mysql_harness::ConfigSection *section,
259 const std::string &option) const;
260
261 /**
262 * get value of an option from a config-section.
263 *
264 * gets value from get_default() if the option-value
265 * is not present or empty.
266 *
267 * @return a value of the option if it exists.
268 */
269 std::string get_option_string_or_default_(
270 const mysql_harness::ConfigSection *section,
271 const std::string &option) const;
272};
273
274} // namespace mysql_harness
275
276#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:220
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:193
BasePluginConfig(const mysql_harness::ConfigSection *section)
Constructor for derived classes.
Definition: plugin_config.h:232
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:165
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:143
virtual bool is_required(const std::string &option) const =0
Returns whether the given option is required.
std::string section_name_
Name of the section.
Definition: plugin_config.h:248
decltype(auto) get_option(const mysql_harness::ConfigSection *section, const std::string &option, Func &&transformer) const
get option value.
Definition: plugin_config.h:118
virtual std::string get_default(const std::string &option) const =0
Gets the default for the given option.
virtual ~BasePluginConfig()=default
destructor
Configuration section.
Definition: config_parser.h:140
Definition: config_option.h:167
Definition: config_option.h:107
Exception that gets thrown when the configuarion option is present but it is empty value.
Definition: plugin_config.h:49
Exception that gets thrown when the configuarion 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