MySQL 9.1.0
Source Code Documentation
serializer.h
Go to the documentation of this file.
1// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
2//
3// This program is free software; you can redistribute it and/or modify
4// it under the terms of the GNU General Public License, version 2.0,
5// as published by the Free Software Foundation.
6//
7// This program is designed to work with certain software (including
8// but not limited to OpenSSL) that is licensed under separate terms,
9// as designated in a particular file or component or in included license
10// documentation. The authors of MySQL hereby grant you an additional
11// permission to link the program and your derivative works with the
12// separately licensed software that they have either included with
13// the program or referenced in the documentation.
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, version 2.0, 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#ifndef MYSQL_SERIALIZATION_SERIALIZER_H
25#define MYSQL_SERIALIZATION_SERIALIZER_H
26
33
34/// @file
35/// Experimental API header
36
37/// @addtogroup GroupLibsMysqlSerialization
38/// @{
39
40namespace mysql::serialization {
41
42/// @brief Interface for serializer
43/// @details This class provides functionality of encoder and decoder,
44/// storing the formatted data in the defined Archive_type.
45/// This class converts a hierarchical message (Serializable type) into a linear
46/// sequence of message boundaries and fields (with the usage of
47/// Serializable interface). To do so, it traverses the message in depth-first
48/// order and applies the user-defined predicates to determine if a field
49/// should be included in encoded message or not. Field ids are generated
50/// during iteration over fields with the usage of the Serializable interface.
51/// Particular message boundaries formatting and fields formatting is decided
52/// by the Serializer_derived_type.
53/// The methods that Serializer_derived_type shall provide are explicitly
54/// marked in methods documentation as "to be implemented by
55/// Serializer_derived_type". Derived class shall provide a specific
56/// formatting of message boundaries, specific formatting of particular
57/// fields and size calculation methods (get_size_serializable,
58/// get_size_field_def, get_max_size for simple/complex fields)
59/// @tparam Serializer_derived_type Concrete Serializer type, this is CRTP
60/// @tparam Archive_type Concrete archive type to store data
61template <class Serializer_derived_type, class Archive_type>
63 public:
66
67 bool is_error() const { return !is_good(); }
68 bool is_good() const {
69 return (m_error.is_error() == false && m_archive.is_good());
70 }
72 if (m_archive.is_error()) {
73 return m_archive.get_error();
74 }
75 return m_error;
76 }
77
78 /// @brief Function for the API user to serialize data
79 /// @tparam T Serialized type, implementing Serializable interface
80 /// @param[in] arg Data to be written into the archive
81 /// @return Updated object for chaining
82 template <typename T>
84
85 /// @brief Function for the API user to serialize data
86 /// @tparam T Serialized type, implementing Serializable interface
87 /// @param[in] arg Deserialized data will be stored in arg
88 /// @return Updated object for chaining
89 template <typename T>
91
92 /// @brief Function for the API user to access reference of the archive
93 /// @returns Reference to the archive object
94 Archive_type &get_archive();
95
96 template <typename T>
97 static std::size_t get_size(const T &arg);
98
99 protected:
100 template <typename Serializable_derived_current_type>
101 friend class Serializable;
102 template <typename Serializer_type, typename Type>
104
105 /// @brief Casts this to derived type
106 /// @return Derived class pointer to this
107 /// @note To be implemented in Archive_derived_type
108 Serializer_derived_type *get_derived() {
109 return static_cast<Serializer_derived_type *>(this);
110 }
111
112 /// @brief Function used to encode one field
113 /// @tparam Field_type Type of field
114 /// @tparam field_size_defined Defined field size in archive
115 /// @param[in] level Level of the serializable tree, may be ignored, used
116 /// mainly for text formatting
117 /// @param[in] field_id Field id
118 /// @param[in] field_definition Definition of the field
119 /// @note To be implemented in Serializer_derived_type
120 template <class Field_type, Field_size field_size_defined>
121 void encode_field(
124
125 /// @brief Function used to decode one field
126 /// @tparam Field_type Type of field
127 /// @tparam field_size_defined Defined field size in archive
128 /// @param[in] level Level of the serializable tree, may be ignored, used
129 /// mainly for text formatting
130 /// @param[in] field_id Expected field id
131 /// @param[in] serializable_end_pos End position of current serializable type
132 /// @param[in] field_definition Definition of the field
133 /// @note To be implemented in Serializer_derived_type
134 template <class Field_type, Field_size field_size_defined>
135 void decode_field(
137 std::size_t serializable_end_pos,
139
140 /// @brief Function used to encode serializable field, this function saves
141 /// serializable metadata and calls serializable encode method
142 /// @tparam Serializable_type serializable data type
143 /// @param[in] level Level of the serializable tree, may be ignored, used
144 /// mainly for text formatting
145 /// @param[in] field_id Field id
146 /// @param[in] serializable Serializable object universal reference
147 /// @param[in] skip_id Skip encoding of serializable id (for repeated fields)
148 /// @note To be implemented in Serializer_derived_type
149 template <class Serializable_type>
151 const Serializable_type &serializable, bool skip_id);
152
153 /// @brief Function used to encode fields of specializations of Serializable
154 /// class, iterates over constant fields
155 /// allowing them to be saved into an archive
156 /// @tparam Serializable_type serializable data type
157 /// @param[in] serializable Serializable object universal reference
158 /// @param[in] level Serializable tree level, serializable may contain other
159 /// serializable fields, level is used for informational purpose or
160 /// additional text formatting for nested types
161 /// @note To be implemented in Serializer_derived_type
162 template <class Serializable_type>
163 void encode_serializable_fields(const Serializable_type &serializable,
164 Level_type level);
165
166 /// @brief Function used to decode serializable field, this function loads
167 /// serializable metadata and calls serializable decode method
168 /// @tparam Serializable_type serializable data type
169 /// @param[in] level Level of the serializable tree, may be ignored, used
170 /// mainly for text formatting
171 /// @param[in] field_id Field id
172 /// @param[in] serializable_end_pos End position of current serializable type
173 /// @param[in] serializable Serializable object universal reference
174 /// @param[in] skip_id Skip decoding of serializable id.
175 /// In case a field is placed in a container, we skip encoding / decoding
176 /// of the field id. Field id encoding / decoding is skipped in case
177 /// field_id was already processed or a complex type is put in the container
178 template <class Serializable_type>
180 std::size_t serializable_end_pos,
181 Serializable_type &serializable, bool skip_id);
182
183 /// @brief Function used to decode fields of specializations of Serializable
184 /// class, iterates over non constant fields,
185 /// allowing them to be filled with data from an archive
186 /// @tparam Serializable_type serializable data type
187 /// @param[in] serializable Serializable object universal reference
188 /// @param[in] level Serializable tree level, serializable may contain other
189 /// serializable fields, level is used for informational purpose or
190 /// additional text formatting for nested types
191 /// @param[in] serializable_end_pos End position of current serializable type
192 template <class Serializable_type>
193 void decode_serializable_fields(Serializable_type &serializable,
194 Level_type level,
195 std::size_t serializable_end_pos);
196
197 /// @brief Function returns size of field object written to an
198 /// archive
199 /// @tparam Field_type Type of field
200 /// @tparam field_size_defined Defined field size in archive
201 /// @param[in] field_id Field id
202 /// @param[in] field_definition Definition of the field
203 /// @note To be implemented in Serializer_derived_type
204 template <class Field_type, Field_size field_size_defined>
205 static std::size_t get_size_field_def(
208
209 /// @brief Function returns size of serializable object written to an
210 /// archive
211 /// @tparam Serializable_concrete_type Type of serializable obj
212 /// @param[in] field_id Field id
213 /// @param[in] serializable Serializable universal reference for which size
214 /// will be calculated
215 /// @param[in] skip_id Skip serializable id (for repeated fields)
216 /// @note To be implemented in Serializer_derived_type
217 template <class Serializable_concrete_type>
218 static std::size_t get_size_serializable(
219 Field_id_type field_id, const Serializable_concrete_type &serializable,
220 bool skip_id = false);
221
222 /// @brief Function returns maximum size of the field written to an archive,
223 /// based on its type
224 /// @tparam Field_type Type of field
225 /// @tparam field_size_defined Defined field size in archive
226 template <class Field_type, Field_size field_size_defined>
227 static constexpr std::size_t get_max_size() {
228 return Serializer_derived_type::template get_max_size<Field_type,
229 field_size_defined>();
230 }
231
232 /// @brief Function returns maximum size of the Serializable_concrete_type
233 /// class object data written to an archive, based on its type
234 /// @tparam Serializable_concrete_type Type of serializable obj
235 template <class Serializable_concrete_type>
236 static constexpr std::size_t get_max_size() {
237 return Serializer_derived_type::template get_max_size<
238 Serializable_concrete_type>();
239 }
240
241 void clear_error() {
242 m_archive.clear_error();
244 }
245
246 /// @brief Destructor
247 /// @note Cannot create an object of Serializer interface
248 virtual ~Serializer() = default;
249 Level_type m_level{0}; ///< Level of the serializable tree
250 Archive_type m_archive; ///< Archive that stores the data
251 Serialization_error m_error; ///< Holds information about error
252};
253
254} // namespace mysql::serialization
255
256/// @}
257
259
260#endif // MYSQL_SERIALIZATION_SERIALIZER_H
Field definition provided by classes implementing Serializable interface.
Definition: field_definition.h:45
Interface for serializable data structures.
Definition: serializable.h:86
Error used internally in serialization framework.
Definition: serialization_error.h:43
Interface for serializer.
Definition: serializer.h:62
void encode_serializable(Level_type level, Field_id_type field_id, const Serializable_type &serializable, bool skip_id)
Function used to encode serializable field, this function saves serializable metadata and calls seria...
Definition: serializer_impl.hpp:118
void encode_field(Level_type level, Field_id_type field_id, const Field_definition< Field_type, field_size_defined > &field_definition)
Function used to encode one field.
Definition: serializer_impl.hpp:33
bool is_error() const
Definition: serializer.h:67
virtual ~Serializer()=default
Destructor.
void encode_serializable_fields(const Serializable_type &serializable, Level_type level)
Function used to encode fields of specializations of Serializable class, iterates over constant field...
Definition: serializer_impl.hpp:102
Serialization_error m_error
Holds information about error.
Definition: serializer.h:251
Serializer_derived_type * get_derived()
Casts this to derived type.
Definition: serializer.h:108
static std::size_t get_size(const T &arg)
Definition: serializer_impl.hpp:70
Level_type m_level
Level of the serializable tree.
Definition: serializer.h:249
void decode_serializable(Level_type level, Field_id_type field_id, std::size_t serializable_end_pos, Serializable_type &serializable, bool skip_id)
Function used to decode serializable field, this function loads serializable metadata and calls seria...
Definition: serializer_impl.hpp:158
void decode_field(Level_type level, Field_id_type field_id, std::size_t serializable_end_pos, Field_definition< Field_type, field_size_defined > &field_definition)
Function used to decode one field.
Definition: serializer_impl.hpp:41
Archive_type m_archive
Archive that stores the data.
Definition: serializer.h:250
void decode_serializable_fields(Serializable_type &serializable, Level_type level, std::size_t serializable_end_pos)
Function used to decode fields of specializations of Serializable class, iterates over non constant f...
Definition: serializer_impl.hpp:139
void clear_error()
Definition: serializer.h:241
const Serialization_error & get_error()
Definition: serializer.h:71
bool is_good() const
Definition: serializer.h:68
static std::size_t get_size_serializable(Field_id_type field_id, const Serializable_concrete_type &serializable, bool skip_id=false)
Function returns size of serializable object written to an archive.
Definition: serializer_impl.hpp:61
Serializer_current_type & operator>>(T &arg)
Function for the API user to serialize data.
Serializer_current_type & operator<<(const T &arg)
Function for the API user to serialize data.
static std::size_t get_size_field_def(Field_id_type field_id, const Field_definition< Field_type, field_size_defined > &field_definition)
Function returns size of field object written to an archive.
Definition: serializer_impl.hpp:51
static constexpr std::size_t get_max_size()
Function returns maximum size of the field written to an archive, based on its type.
Definition: serializer.h:227
Archive_type & get_archive()
Function for the API user to access reference of the archive.
Definition: serializer_impl.hpp:95
static constexpr std::size_t get_max_size()
Function returns maximum size of the Serializable_concrete_type class object data written to an archi...
Definition: serializer.h:236
bool is_error() const
Function that indicates whether error occurred.
Definition: error.h:76
Experimental API header.
Definition: archive.h:37
std::size_t Level_type
Type of the "level" used to indicate on which level of the nested message internal fields are defined...
Definition: serialization_types.h:40
uint64_t Field_id_type
Type for field_id assigned to each field in the.
Definition: serialization_types.h:42
Experimental API header.
Experimental API header.
Experimental API header.
Experimental API header.
Experimental API header.
static const LEX_CSTRING field_id
Definition: sql_show_processlist.cc:49
Definition: sql_resultset.h:36
Definition: serializable_size_calculator.h:44
Experimental API header.