MySQL 9.1.0
Source Code Documentation
archive.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_ARCHIVE_H
25#define MYSQL_SERIALIZATION_ARCHIVE_H
26
30
31/// @file
32/// Experimental API header
33
34/// @addtogroup GroupLibsMysqlSerialization
35/// @{
36
38
39/// @brief Interface for archives (file archive, byte vector archive,
40/// string archive etc.), available only to instances implementing Serializable
41/// interface and Archive interface
42/// @details Archive is responsible for primitive types byte-level formatting
43/// and data storage. It also provides implementation of separation between
44/// serializable types, serializable type fields, separate entries in
45/// containers (repeated fields). Derived class should implement
46/// all methods of provided interface (except methods for error handling).
47/// @tparam Archive_derived_type Archive derived that is implementing Archive
48/// interface (CRTP)
49template <class Archive_derived_type>
50class Archive {
51 public:
52 /// @brief Ingests argument into this archive
53 /// @tparam Type type of the argument
54 /// @param [in] arg Argument to read data from
55 /// @return This archive reference
56 /// @note To be implemented in Archive_derived_type
57 template <typename Type>
58 Archive_derived_type &operator<<(Type &&arg) {
59 return get_derived()->operator<<(std::forward<Type>(arg));
60 }
61
62 /// @brief Reads argument from this archive
63 /// @tparam Type type of the argument
64 /// @param [in] arg Argument to store data into
65 /// @return This archive reference
66 /// @note To be implemented in Archive_derived_type
67 template <typename Type>
68 Archive_derived_type &operator>>(Type &&arg) {
69 return get_derived()->operator>>(std::forward<Type>(arg));
70 }
71
72 /// @brief Function for the API user to access data in the archive
73 /// @returns Archive data, defined in the Archive (e.g. pointer to bytes ...)
74 /// @note To be implemented in Archive_derived_type
75 decltype(auto) get_raw_data() { return get_derived()->get_raw_data(); }
76
77 /// @brief Function returns size of serialized argument
78 /// @tparam Type type of the argument
79 /// @param [in] arg serialized argument
80 /// @return size of serialized argument
81 /// @note To be implemented in Archive_derived_type
82 template <typename Type>
83 static std::size_t get_size(Type &&arg) {
84 return Archive_derived_type::template get_size(std::forward<Type>(arg));
85 }
86
87 /// @brief Returns archive size - size of data written to the archive
88 /// @return archive size - size of data written to the archive
89 /// @note To be implemented in Archive_derived_type
90 inline std::size_t get_size_written() const {
91 return Archive_derived_type::template get_size_written();
92 }
93
94 /// @brief Function returns maximum size of the Type
95 /// @tparam Type serialized type
96 /// @return maximum size of the Type in the stream
97 /// @note To be implemented in Archive_derived_type
98 template <typename Type>
99 static constexpr std::size_t get_max_size() {
100 return Archive_derived_type::template get_max_size<Type>();
101 }
102
103 // used to access the protected API of an archive (peek/seek_to/error methods)
104 // by any implementation of a Serializer class
105 template <class Serializer_derived_current_type, class Archive_current_type>
106 friend class Serializer;
107
108 // available for serializers
109
110 /// @brief This method needs to define field separator to be inserted
111 /// after the field, note that some formats won't contain separators
112 /// Used mainly for text formatters
113 /// @details Field is defined a a single field in object of serializable class
114 // which is identified by an unique id within this object
115 virtual void put_field_separator() {}
116
117 /// @brief This method needs to define field entry separator to be inserted
118 /// after the field entry, note that some formats won't contain separators
119 /// Used mainly for text formatters
120 /// @details Each field may have a several entries (e.g. vector)
121 virtual void put_entry_separator() {}
122
123 /// @brief This method needs to define level separator to be inserted
124 /// after the level, note that some formats won't contain separators
125 /// Used mainly for text formatters
126 /// @details Each field that is an object of serializable class creates a new
127 /// level
128 virtual void put_level_separator() {}
129
130 /// @brief This method needs to define how to process field separator during
131 /// decoding. Used mainly for text formatters
132 /// @details Field is defined a a single field in object of serializable class
133 // which is identified by an unique id within this object
134 virtual void process_field_separator() {}
135
136 /// @brief This method needs to define how to process field entry separator
137 /// during decoding. Used mainly for text formatters
138 /// @details Each field may have a several entries (e.g. vector)
139 virtual void process_entry_separator() {}
140
141 /// @brief This method needs to define how to process level separator during
142 /// decoding. Used mainly for text formatters
143 /// @details Each field that is an object of serializable class creates a new
144 /// level
145 virtual void process_level_separator() {}
146
147 protected:
148 /// @brief Casts this to derived type
149 /// @return Derived class pointer to this
150 /// @note To be implemented in Archive_derived_type
151 const Archive_derived_type *get_derived_const() {
152 return static_cast<const Archive_derived_type *>(this);
153 }
154
155 /// @brief Casts this to derived type
156 /// @return Derived class pointer to this
157 /// @note To be implemented in Archive_derived_type
158 Archive_derived_type *get_derived() {
159 return static_cast<Archive_derived_type *>(this);
160 }
161
162 /// @brief This method decodes field id, without moving stream positions
163 /// @returns Serialized field id
164 /// @note To be implemented in Archive_derived_type
166 return get_derived()->peek_type_field_id();
167 }
168
169 /// @brief Peeks selected field wrapper (reads data without updating
170 /// read stream position)
171 /// @note To be implemented in Archive_derived_type
172 template <class Field_type>
173 void peek(Field_type &&field) {
174 return get_derived()->peek(std::forward<Field_type>(field));
175 }
176
177 /// @brief Moves the current read position to current position + size
178 /// @param[in] num_pos Number of positions to be skipped
179 /// @note To be implemented in Archive_derived_type
180 void seek_to(std::size_t num_pos) { get_derived()->seek_to(num_pos); }
181
182 /// @brief Gets current read pos
183 /// @return Current read pos
184 /// @note To be implemented in Archive_derived_type
185 std::size_t get_read_pos() const {
186 return get_derived_const()->get_read_pos();
187 }
188
189 bool is_error() const { return m_error.is_error(); }
190 bool is_good() const { return !m_error.is_error(); }
193
194 /// @brief Destructor
195 /// @note Cannot create an object of 'abstract' Archive type
196 virtual ~Archive() = default;
197 Serialization_error m_error; ///< Holds information about error
198};
199
200} // namespace mysql::serialization
201
202/// @}
203
204#endif // MYSQL_SERIALIZATION_ARCHIVE_H
Interface for archives (file archive, byte vector archive, string archive etc.), available only to in...
Definition: archive.h:50
virtual void put_field_separator()
This method needs to define field separator to be inserted after the field, note that some formats wo...
Definition: archive.h:115
const Archive_derived_type * get_derived_const()
Casts this to derived type.
Definition: archive.h:151
std::size_t get_size_written() const
Returns archive size - size of data written to the archive.
Definition: archive.h:90
virtual void process_level_separator()
This method needs to define how to process level separator during decoding.
Definition: archive.h:145
virtual ~Archive()=default
Destructor.
bool is_good() const
Definition: archive.h:190
decltype(auto) get_raw_data()
Function for the API user to access data in the archive.
Definition: archive.h:75
const Serialization_error & get_error()
Definition: archive.h:191
void seek_to(std::size_t num_pos)
Moves the current read position to current position + size.
Definition: archive.h:180
Serialization_error m_error
Holds information about error.
Definition: archive.h:197
Archive_derived_type & operator>>(Type &&arg)
Reads argument from this archive.
Definition: archive.h:68
virtual void put_entry_separator()
This method needs to define field entry separator to be inserted after the field entry,...
Definition: archive.h:121
static constexpr std::size_t get_max_size()
Function returns maximum size of the Type.
Definition: archive.h:99
Archive_derived_type & operator<<(Type &&arg)
Ingests argument into this archive.
Definition: archive.h:58
void peek(Field_type &&field)
Peeks selected field wrapper (reads data without updating read stream position)
Definition: archive.h:173
Archive_derived_type * get_derived()
Casts this to derived type.
Definition: archive.h:158
static std::size_t get_size(Type &&arg)
Function returns size of serialized argument.
Definition: archive.h:83
virtual void process_entry_separator()
This method needs to define how to process field entry separator during decoding.
Definition: archive.h:139
bool is_error() const
Definition: archive.h:189
virtual void put_level_separator()
This method needs to define level separator to be inserted after the level, note that some formats wo...
Definition: archive.h:128
std::size_t get_read_pos() const
Gets current read pos.
Definition: archive.h:185
Field_id_type peek_type_field_id()
This method decodes field id, without moving stream positions.
Definition: archive.h:165
void clear_error()
Definition: archive.h:192
virtual void process_field_separator()
This method needs to define how to process field separator during decoding.
Definition: archive.h:134
Error used internally in serialization framework.
Definition: serialization_error.h:43
Interface for serializer.
Definition: serializer.h:62
bool is_error() const
Function that indicates whether error occurred.
Definition: error.h:76
Experimental API header.
Definition: archive.h:37
uint64_t Field_id_type
Type for field_id assigned to each field in the.
Definition: serialization_types.h:42
Type
Definition: resource_group_basic_types.h:33
Experimental API header.
Experimental API header.
Definition: sql_resultset.h:36