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