MySQL 8.3.0
Source Code Documentation
json_diff.h
Go to the documentation of this file.
1#ifndef JSON_DIFF_INCLUDED
2#define JSON_DIFF_INCLUDED
3
4/* Copyright (c) 2017, 2023, Oracle and/or its affiliates.
5
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License, version 2.0,
8 as published by the Free Software Foundation.
9
10 This program is also distributed with certain software (including
11 but not limited to OpenSSL) that is licensed under separate terms,
12 as designated in a particular file or component or in included license
13 documentation. The authors of MySQL hereby grant you an additional
14 permission to link the program and your derivative works with the
15 separately licensed software that they have included with MySQL.
16
17 This program is distributed in the hope that it will be useful,
18 but WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 GNU General Public License, version 2.0, for more details.
21
22 You should have received a copy of the GNU General Public License
23 along with this program; if not, write to the Free Software
24 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
25
26/**
27 @file
28
29 Header file for the Json_diff class.
30
31 The Json_diff class is used to represent a logical change in a JSON column,
32 so that a replication master can send only what has changed, instead of
33 sending the whole new value to the replication slave when a JSON column is
34 updated.
35*/
36
37#include <stddef.h>
38#include <algorithm>
39#include <memory> // std::unique_ptr
40#include <optional>
41#include <vector>
42
45
46class Json_dom;
47class Json_wrapper;
48class String;
49
50/// Enum that describes what kind of operation a Json_diff object represents.
52 /**
53 The JSON value in the given path is replaced with a new value.
54 It has the same effect as `JSON_REPLACE(col, path, value)`.
55 */
56 REPLACE,
57
58 /**
59 Add a new element at the given path.
60
61 If the path specifies an array element, it has the same effect as
62 `JSON_ARRAY_INSERT(col, path, value)`.
63
64 If the path specifies an object member, it has the same effect as
65 `JSON_INSERT(col, path, value)`.
66 */
67 INSERT,
68
69 /**
70 The JSON value at the given path is removed from an array or object.
71 It has the same effect as `JSON_REMOVE(col, path)`.
72 */
73 REMOVE,
74};
75/// The number of elements of the enumeration above.
76static const int JSON_DIFF_OPERATION_COUNT = 3;
77
78/**
79 A class that represents a logical change to a JSON document. It is used by
80 row-based replication to send information about changes in JSON documents
81 without sending the whole updated document.
82*/
83class Json_diff final {
84 /// The path that is changed.
86 /// The operation to perform on the changed path.
88 /// The new value to add to the changed path.
89 std::unique_ptr<Json_dom> m_value;
90
91 /// The length of the operation when encoded in binary format.
92 static const size_t ENCODED_OPERATION_BYTES = 1;
93
94 public:
95 /**
96 Construct a Json_diff object.
97
98 @param path the path that is changed
99 @param operation the operation to perform on the path
100 @param value the new value in the path (the Json_diff object
101 takes over the ownership of the value)
102 */
104 std::unique_ptr<Json_dom> value);
105
107 Json_diff(Json_diff &&) noexcept = default;
108 Json_diff &operator=(Json_diff &&) noexcept = default;
109 Json_diff(const Json_diff &) = delete;
110 Json_diff &operator=(const Json_diff &) = delete;
111
112 /// Get the path that is changed by this diff.
113 const Json_path &path() const { return m_path; }
114
115 /// Get the operation that is performed on the path.
117
118 /**
119 Get a Json_wrapper representing the new value to add to the path. The
120 wrapper is an alias, so the ownership of the contained Json_dom is retained
121 by the Json_diff object.
122 @see Json_wrapper::set_alias()
123 */
124 Json_wrapper value() const;
125
126 size_t binary_length() const;
127 /**
128 Serialize this Json_diff object and append to the given string
129
130 @param to The String to append to
131 @retval false Success
132 @retval true Failure, meaning out of memory
133 */
134 bool write_binary(String *to) const;
135};
136
137/**
138 Vector of logical diffs describing changes to a JSON column.
139*/
141 public:
142 /// Type of the allocator for the underlying invector.
144 /// Type of the underlying vector
145 typedef std::vector<Json_diff, allocator_type> vector;
146 /// Type of iterator over the underlying vector
147 typedef vector::iterator iterator;
148 /// Type of iterator over the underlying vector
149 typedef vector::const_iterator const_iterator;
150 /**
151 Constructor
152 @param arg Mem_root_allocator to use for the vector
153 */
154 explicit Json_diff_vector(allocator_type arg);
155 /**
156 Append a new diff at the end of this vector.
157 @param diff The diff to add.
158 */
159 void add_diff(Json_diff diff);
160 /**
161 Append a new diff at the end of this vector.
162 @param path Path to update
163 @param operation Operation
164 @param dom New value to insert
165 */
166 void add_diff(const Json_seekable_path &path,
167 enum_json_diff_operation operation,
168 std::unique_ptr<Json_dom> dom);
169 /**
170 Append a new diff at the end of this vector when operation == REMOVE.
171 @param path Path to update
172 @param operation Operation
173 */
174 void add_diff(const Json_seekable_path &path,
175 enum_json_diff_operation operation);
176 /// Clear the vector.
177 void clear();
178 /// Return the number of elements in the vector.
179 inline size_t size() const { return m_vector.size(); }
180
181 /**
182 Return the element at the given position
183 @param pos Position
184 @return the pos'th element
185 */
186 inline Json_diff &at(size_t pos) { return m_vector.at(pos); }
187
188 // Return forward iterator to the beginning
189 inline const_iterator begin() const { return m_vector.begin(); }
190
191 // Return forward iterator to the end
192 const_iterator end() const { return m_vector.end(); }
193
194 /**
195 Return the length of the binary representation of this
196 Json_diff_vector.
197
198 The binary format has this form:
199
200 +--------+--------+--------+ +--------+
201 | length | diff_1 | diff_2 | ... | diff_N |
202 +--------+--------+--------+ +--------+
203
204 This function returns the length of only the diffs, if
205 include_metadata==false. It returns the length of the 'length'
206 field plus the length of the diffs, if include_metadata=true. The
207 value of the 'length' field is exactly the return value from this
208 function when include_metadata=false.
209
210 @param include_metadata if true, include the length of the length
211 field in the computation, otherwise don't.
212
213 @return The computed length
214 */
215 size_t binary_length(bool include_metadata = true) const;
216
217 /**
218 Serialize this Json_diff_vector into the given String.
219
220 @param to String to which the vector will be appended
221
222 @retval false Success
223 @retval true Failure (out of memory)
224 */
225 bool write_binary(String *to) const;
226
227 /**
228 De-serialize Json_diff objects from the given String into this
229 Json_diff_vector.
230
231 @param[in,out] from Pointer to buffer to read from. The function
232 will move this to point to the next byte to read after those that
233 were read.
234
235 @param[in] table Table structure (used for error messages).
236
237 @param[in] field_name Field name (used for error messages).
238
239 @retval false Success
240 @retval true Failure (bad format or out of memory)
241 */
242 bool read_binary(const char **from, const struct TABLE *table,
243 const char *field_name);
244
245 /// An empty diff vector (having no diffs).
247
248 private:
249 // The underlying vector
251
252 /// Length in bytes of the binary representation, not counting the 4 bytes
253 /// length
255
256 /// The length of the field where the total length is encoded.
257 static const size_t ENCODED_LENGTH_BYTES = 4;
258};
259
260/**
261 The result of applying JSON diffs on a JSON value using apply_json_diff().
262*/
264 /**
265 The JSON diffs were applied and the JSON value in the column was updated
266 successfully.
267 */
268 SUCCESS,
269
270 /**
271 An error was raised while applying one of the diffs. The value in the
272 column was not updated.
273 */
274 ERROR,
275
276 /**
277 One of the diffs was rejected. This could happen if the path specified in
278 the diff does not exist in the JSON value, or if the diff is supposed to
279 add a new value at a given path, but there already is a value at the path.
280
281 This return code would usually indicate that the replication slave where
282 the diff is applied, is out of sync with the replication master where the
283 diff was created.
284
285 The value in the column was not updated, but no error was raised.
286 */
287 REJECTED,
288};
289
290/**
291 Apply one JSON diff to the DOM provided.
292
293 @param diff The diff which contains the path to apply it and the new value.
294 @param dom The DOM to apply the diff to.
295 @return An enum_json_diff_status value that tells if the diff was applied
296 successfully.
297 */
299
300/// The result of a call to read_json_diff().
302 /// The JSON diff that was read from the buffer.
304 /// The number of bytes read from the buffer.
306};
307
308/**
309 Read one JSON diff from a buffer.
310
311 @param pos The position to start reading from in the buffer. When the function
312 returns, it will be set to the position right after the last byte read.
313 @param length The maximum number of bytes to read from the buffer.
314
315 @return An object containing the Json_diff value and the number of bytes read,
316 if successful. An empty value if an error was raised, or if the buffer did not
317 contain a valid diff.
318 */
319std::optional<ReadJsonDiffResult> read_json_diff(const unsigned char *pos,
320 size_t length);
321
322#endif /* JSON_DIFF_INCLUDED */
Vector of logical diffs describing changes to a JSON column.
Definition: json_diff.h:140
std::vector< Json_diff, allocator_type > vector
Type of the underlying vector.
Definition: json_diff.h:145
size_t m_binary_length
Length in bytes of the binary representation, not counting the 4 bytes length.
Definition: json_diff.h:254
vector::iterator iterator
Type of iterator over the underlying vector.
Definition: json_diff.h:147
const_iterator end() const
Definition: json_diff.h:192
static const size_t ENCODED_LENGTH_BYTES
The length of the field where the total length is encoded.
Definition: json_diff.h:257
void add_diff(Json_diff diff)
Append a new diff at the end of this vector.
Definition: json_diff.cc:268
size_t binary_length(bool include_metadata=true) const
Return the length of the binary representation of this Json_diff_vector.
Definition: json_diff.cc:289
Mem_root_allocator< Json_diff > allocator_type
Type of the allocator for the underlying invector.
Definition: json_diff.h:143
size_t size() const
Return the number of elements in the vector.
Definition: json_diff.h:179
vector::const_iterator const_iterator
Type of iterator over the underlying vector.
Definition: json_diff.h:149
Json_diff_vector(allocator_type arg)
Constructor.
Definition: json_diff.cc:260
const_iterator begin() const
Definition: json_diff.h:189
Json_diff & at(size_t pos)
Return the element at the given position.
Definition: json_diff.h:186
vector m_vector
Definition: json_diff.h:250
bool write_binary(String *to) const
Serialize this Json_diff_vector into the given String.
Definition: json_diff.cc:293
static const Json_diff_vector EMPTY_JSON_DIFF_VECTOR
An empty diff vector (having no diffs).
Definition: json_diff.h:246
void clear()
Clear the vector.
Definition: json_diff.cc:284
bool read_binary(const char **from, const struct TABLE *table, const char *field_name)
De-serialize Json_diff objects from the given String into this Json_diff_vector.
Definition: json_diff.cc:315
A class that represents a logical change to a JSON document.
Definition: json_diff.h:83
size_t binary_length() const
Definition: json_diff.cc:125
Json_wrapper value() const
Get a Json_wrapper representing the new value to add to the path.
Definition: json_diff.cc:68
static const size_t ENCODED_OPERATION_BYTES
The length of the operation when encoded in binary format.
Definition: json_diff.h:92
const Json_path & path() const
Get the path that is changed by this diff.
Definition: json_diff.h:113
std::unique_ptr< Json_dom > m_value
The new value to add to the changed path.
Definition: json_diff.h:89
Json_path m_path
The path that is changed.
Definition: json_diff.h:85
bool write_binary(String *to) const
Serialize this Json_diff object and append to the given string.
Definition: json_diff.cc:171
enum_json_diff_operation m_operation
The operation to perform on the changed path.
Definition: json_diff.h:87
enum_json_diff_operation operation() const
Get the operation that is performed on the path.
Definition: json_diff.h:116
Json_diff(Json_diff &&) noexcept=default
Json_diff(const Json_seekable_path &path, enum_json_diff_operation operation, std::unique_ptr< Json_dom > value)
Construct a Json_diff object.
Definition: json_diff.cc:57
JSON DOM abstract base class.
Definition: json_dom.h:171
A JSON path expression.
Definition: json_path.h:352
A path expression which can be used to seek to a position inside a JSON value.
Definition: json_path.h:297
Abstraction for accessing JSON values irrespective of whether they are (started out as) binary JSON v...
Definition: json_dom.h:1161
Mem_root_allocator is a C++ STL memory allocator based on MEM_ROOT.
Definition: mem_root_allocator.h:67
Using this class is fraught with peril, and you need to be very careful when doing so.
Definition: sql_string.h:166
static Bigint * diff(Bigint *a, Bigint *b, Stack_alloc *alloc)
Definition: dtoa.cc:1076
enum_json_diff_status apply_json_diff(const Json_diff &diff, Json_dom *dom)
Apply one JSON diff to the DOM provided.
Definition: json_diff.cc:454
enum_json_diff_status
The result of applying JSON diffs on a JSON value using apply_json_diff().
Definition: json_diff.h:263
@ REJECTED
One of the diffs was rejected.
@ ERROR
An error was raised while applying one of the diffs.
@ SUCCESS
The JSON diffs were applied and the JSON value in the column was updated successfully.
std::optional< ReadJsonDiffResult > read_json_diff(const unsigned char *pos, size_t length)
Read one JSON diff from a buffer.
Definition: json_diff.cc:357
enum_json_diff_operation
Enum that describes what kind of operation a Json_diff object represents.
Definition: json_diff.h:51
@ REPLACE
The JSON value in the given path is replaced with a new value.
@ INSERT
Add a new element at the given path.
@ REMOVE
The JSON value at the given path is removed from an array or object.
static const int JSON_DIFF_OPERATION_COUNT
The number of elements of the enumeration above.
Definition: json_diff.h:76
This file contains interface support for the JSON path abstraction.
static char * path
Definition: mysqldump.cc:148
static PFS_engine_table_share_proxy table
Definition: pfs.cc:60
bool length(const dd::Spatial_reference_system *srs, const Geometry *g1, double *length, bool *null) noexcept
Computes the length of linestrings and multilinestrings.
Definition: length.cc:75
The result of a call to read_json_diff().
Definition: json_diff.h:301
Json_diff diff
The JSON diff that was read from the buffer.
Definition: json_diff.h:303
size_t bytes_read
The number of bytes read from the buffer.
Definition: json_diff.h:305
Definition: table.h:1403