1/* 2 * Copyright (c) 2015, 2021, 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, 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 23 * 02110-1301 USA 24 */ 25syntax = "proto2"; 26 27// ifdef PROTOBUF_LITE: option optimize_for = LITE_RUNTIME; 28 29// Expect operations 30package Mysqlx.Expect; 31option java_package = "com.mysql.cj.x.protobuf"; 32 33// Pipelining messages is a core feature of the Mysqlx Protocol. It 34// sends messages to the server without waiting for a response to 35// save latency. 36// 37// * in case of success the time to wait and check the result as been saved 38// and the latency is reduced. 39// 40// * in the case of an error a mechanism is need to ensure that the following 41// messages are not executed, but skipped with an error instead. 42// 43// :: 44// 45// Mysqlx.Crud::PrepareFind(stmt_id=1,...) 46// Mysqlx.Expect::Open([no_error]) // if a execute fails 47// Mysqlx.PreparedStmt::Execute(stmt_id=1,...) 48// Mysqlx.PreparedStmt::Execute(stmt_id=1,...) 49// Mysqlx.Expect::Close() 50// Mysqlx.PreparedStmt::Close(stmt_id=1,...) 51// 52// This basic mechanism is extended to carry a arbitrary set of conditions that are 53// checked before executing message: 54// 55// :: 56// 57// Mysqlx.Expect::Open([+no_error, +gtid_executed_contains = "...", +max_stmt_exec_time_ms = 10]) 58// 59// Mysqlx.Expect::Close() 60// 61// Expect blocks can be nested to increase/change the restrictions for a subset of the 62// messages. At the end of the Expect block the previous restrictions are restored. 63// 64// :: 65// 66// Mysqlx.Expect::Open([+no_error]) // if preparing the Find fails, don't try to close it 67// Mysqlx.Crud::PrepareFind(stmt_id=1,...) 68// Mysqlx.Expect::Open([+no_error]) // if a Execute fails, skip the rest of them and continue with Close 69// Mysqlx.PreparedStmt::Execute(stmt_id=1,...) 70// Mysqlx.PreparedStmt::Execute(stmt_id=1,...) 71// Mysqlx.Expect::Close() 72// Mysqlx.PreparedStmt::Close(stmt_id=1,...) 73// Mysqlx.Expect::Close() 74 75// open an Expect block and set/unset the conditions that have to be fulfilled 76// 77// if any of the conditions fail, all enclosed messages will fail with 78// a Mysqlx.Error message. 79// 80// :returns: :protobuf:msg:`Mysqlx::Ok` on success, :protobuf:msg:`Mysqlx::Error` on error 81// 82message Open { 83 message Condition { 84 enum ConditionOperation { 85 // set the condition 86 // 87 // set, if not set 88 // overwrite, if set 89 EXPECT_OP_SET = 0; 90 // unset the condition 91 EXPECT_OP_UNSET = 1; 92 }; 93 required uint32 condition_key = 1; 94 optional bytes condition_value = 2; 95 optional ConditionOperation op = 3 [ default = EXPECT_OP_SET ]; 96 }; 97 enum CtxOperation { 98 // copy the operations from the parent Expect-block 99 EXPECT_CTX_COPY_PREV = 0; 100 // start with a empty set of operations 101 EXPECT_CTX_EMPTY = 1; 102 }; 103 optional CtxOperation op = 1 [ default = EXPECT_CTX_COPY_PREV ]; 104 repeated Condition cond = 2; 105} 106 107// close a Expect block 108// 109// closing a Expect block restores the state of the previous Expect block 110// for the following messages 111// 112// :returns: :protobuf:msg:`Mysqlx::Ok` on success, :protobuf:msg:`Mysqlx::Error` on error 113message Close { 114} 115 116