1 module odl-mdsal-lowlevel-control {
4 namespace "tag:opendaylight.org,2017:controller:yang:lowlevel:control";
7 import odl-mdsal-lowlevel-common {
8 revision-date "2017-02-15";
12 organization "OpenDaylight";
13 contact "Vratko Polak <vrpolak@cisco.com>";
14 description "Control RPCs used to dynamically register, unregister, start or stop
15 the operations under test, which are defined in odl-mdsal-lowlevel-target (llt).
16 Control RPCs are backed by an implementation upon feature instalation.
17 Their registration shall only affect the local member,
18 but their invocation can interact with Entity Ownership or Singleton.
20 The 'mdsal' in the module name refers to the component which defines most APIs
21 accessed by the agent implementation. The intent is to test clustering behavior,
22 but most RPCs do not access APIs from clustering component of Controller project.
24 TODO: Unify grammar: present or future tense, or imperative mood.";
26 revision "2017-02-15" {
27 description "Initial revision for Carbon clustering testing.";
30 rpc register-constant {
31 description "Upon receiving this, the member has to create llt:get-constant
32 implementation (global RPC). If the registration fails for any reason,
33 propagate the corresponding error.";
35 uses llc:constant-grouping;
40 rpc unregister-constant {
41 description "Upon receiving this, the member has to unregister
42 any llt:get-constant implementations it has registered.
43 If no implementation has been registered, do nothing.";
48 rpc register-bound-constant {
49 description "Upon receiving this, the member has to create and register
50 a bound llt:get-contexted-constant implementation (routed RPC).
51 If the registration fails for any reason, propagate the corresponding error.";
53 uses llc:context-grouping;
54 uses llc:constant-grouping;
59 rpc unregister-bound-constant {
60 description "Upon receiving this, the member has to unregister
61 any llt:get-contexted-constant implementations bound to the context.
62 If no bound implementation for the context has been registered, do nothing.";
64 uses llc:context-grouping;
69 rpc register-singleton-constant {
70 description "Upon receiving this, the member checks whether it has already registered
71 a singleton application, and fails if yes. If no, the member creates
72 an application implementation based on the given constant
73 and registers the implementation as a singleton application.
74 If the registration fails for any reason, propagate the corresponding error.
75 If the application is instantiated, it creates and registers
76 a llt:get-singleton-constant implementation, which returns the given costant.
77 When the application instance is closed, it unregisters that
78 llt:get-singleton-constant implementation.";
80 uses llc:constant-grouping;
85 rpc unregister-singleton-constant {
86 description "Upon receiving this, the member checks whether it has currently registered
87 a singleton application, and fails if no. If yes, the member shall unregister
88 the application, presumably causing application instantiation on other member,
89 and closing of the local application instance (unregistering llt:get-singleton-constant).
90 If the unregistration fails for any reason, propagate the corresponding error.";
95 rpc register-flapping-singleton {
96 description "Upon receiving this, the member checks whether it has already created
97 a 'flapping' application implementation and 'active' flag is set, and fails if yes.
98 If no, the member (creates a flapping application implementation,)
99 sets the active flag, initializes local variable flap-count to 0,
100 and registers the implementation as a singleton application.
101 If the registration fails for any reason, propagate the corresponding error.
102 If the application is instantiated, it immediatelly un-registers itself.
103 When the application instance is closed, it increments flap-count
104 and if active flag is set, re-registers the application implementation as a singleton.
105 If either un-registration or re-registration fails, 'active' flag is unset,
106 flap-count is set to negative of its previous value (minus one in case of un-registration)
107 to signal a failure has happened.";
112 rpc unregister-flapping-singleton {
113 description "Upon receiving this, the member checks whether it has created
114 a flapping application, and fails if no. If yes, the member shall
115 set the active flag to false and return the current flap-count value.";
119 description "Number of successful re-registrations. If negative,
120 (minus) cycle number when a failure occured.";
127 rpc publish-notifications {
128 description "Upon receiving this, the member shall start publishing llt:id-sequence
129 notifications with the given id and sequence numbers, increasing, from 1.
130 The RPC shall not return until all publishes are successful,
131 or an exception is raised (the exception should propagate to restconf response).";
133 uses llc:id-grouping;
135 description "This RPC has to work (roughly) this long.";
139 leaf notifications-per-second {
140 description "An upper limit of publishes per second this RPC shall try to achieve.";
149 description "Upon receiving this, the member checks whether it has already subscribed
150 a yang listener for the given id, and fails if yes.
151 If no, the member subscribes a Yang notification listener to listen for
152 llt:id-sequence notifications. The member also creates a local variable
153 (called local-number) for the sequence number and initialize that to 0.
154 Also three local counters are initialized to 0: all-not, id-not, err-not.
155 Upon receiving any id-sequence notification, all-not is incremented.
156 Each id-sequence notification of matching id shall increment id-not.
157 If local-number was one less than the sequence number (from a notification matching id),
158 increment local-number, else increment err-not.";
160 uses llc:id-grouping;
165 rpc unsubscribe-ynl {
166 description "Upon receiving this, the member checks whether it has currently subscribed
167 a yang listener for the given id, and fails if no. If yes, the member
168 shall unsubscribe the listener and return values of the local variables.";
170 uses llc:id-grouping;
174 description "Number of received id-sequence notifications of any id.";
179 description "Number of received id-sequence notifications of matching id
180 and any sequence number.";
185 description "Number of received id-sequence notifications of matching id,
186 but out-of-order sequence number.";
191 description "Value of the local number, should be equal to
192 the sequence number of the last compatible id-sequence notification received.";
199 rpc write-transactions {
200 description "Upon receiving this, the member shall make sure the outer list item
201 of llt:id-ints exists for the given id, and then start creating (one by one)
202 and submitting transactions to randomly add or delete items on the inner list for that id.
203 The randomness should avoid creating conflicting writes (at least for non-chained
204 transactions). The recommended way is to require the random number
205 has low significant bits different than the past ~100k numbers.
206 To ensure balanced number of deletes, the first write can create
207 a random set of numbers. Other writes shall be one per number.
208 The writes shall use the old API, transaction (chains) created directly on datastore
209 (as opposed to DOMDataTreeProducer).
210 .get with a timeout on currently earliest non-complete Future (from .submit)
211 shall be used as the primary wait method to throttle the submission rate.
212 This RPC shall not return until all transactions are confirmed successful,
213 or an exception is raised (the exception should propagate to restconf response).
214 OptimisticLockException is always considered an error.";
216 uses llc:id-grouping;
218 description "This RPC has to work (roughly) this long.";
222 leaf transactions-per-second {
223 description "An upper limit of transactions per second this RPC shall try to achieve.";
227 leaf chained-transactions {
228 description "If true, write transactions shall be created on a transaction chain,
229 (created at start of the RPC call, and deleted at at its end).
230 If false, write transactions shall be created separately.";
237 description "Number of all transactions executed.";
242 description "Number of transactions that inserted data.";
247 description "Number of transactions that deleted data.";
254 rpc produce-transactions {
255 description "Upon receiving this, the member shall make sure the outer list item
256 of llt:in-ints exists for the given id, make sure a shard for
257 the whole (config) id-ints is created (by creating and closing producer
258 for the whole id-ints), and create a DOMDataTreeProducer for that item (using that shard).
260 FIXME: Is the above the normal way of creating prefix-based chards?
262 Then start creating (one by one) and submitting transactions
263 to randomly add or delete items on the inner list for that id.
264 To ensure balanced number of deletes, the first write can create
265 a random set of random numbers. Other writes shall be one per number.
266 The writes shall use DOMDataTreeProducer API, as opposed to transaction (chains)
267 created directly on datastore.
268 .get with a timeout on currently earliest non-complete Future (from .submit)
269 shall be used as the primary wait method to throttle the submission rate.
270 This RPC shall not return until all transactions are confirmed successful,
271 or an exception is raised (the exception should propagate to restconf response).
272 OptimisticLockException is always considered an error.
273 In either case, the producer should be closed before returning,
274 but the shard and the whole id item shall be kept as they are.";
276 uses llc:id-grouping;
278 description "This RPC has to work (roughly) this long.";
282 leaf transactions-per-second {
283 description "An upper limit of transactions per second this RPC shall try to achieve.";
287 leaf isolated-transactions {
288 description "The value for DOMDataTreeProducer#createTransaction argument.";
296 rpc become-prefix-leader {
297 description "Upon receiving this, the member shall ask the appropriate API
298 to become Leader of the given shard (presumably the llt:list-ints one,
299 created by produce-transactions) and return immediatelly.";
304 FIXME: Ask Java implementation developer about the format needed.";
312 rpc become-module-leader {
313 description "Upon receiving this, the member shall ask appropriate API
314 to become Leader of given config shard and return immediatelly.";
319 FIXME: Ask Java implementation developer about the format needed.
320 TODO: Perhaps the names are compatible and one 'become-leader' would suffice?";
328 rpc remove-shard-replica {
329 description "A specialised copy of cluster-admin:remove-shard-replica.
331 FIXME: Is this really needed for prefix shards, or even module shards
332 (or is the cluster-admin RPC sufficient)?";
335 description "The name of the config shard for which
336 to remove the replica on the current member.";
344 rpc add-shard-replica {
345 description "A specialised copy of cluster-admin:add-shard-replica.
347 FIXME: Is this really needed for prefix shards, or even module shards
348 (or is the cluster-admin RPC sufficient)?";
351 description "The name of the config shard for which
352 to add the replica on the current member.";
360 rpc is-client-aborted {
361 description "Return state of cds-access-client.
363 FIXME: Is an input needed?";
366 description "True if the local client is aborted (or unreachable), false otherwise.";
374 description "Upon receiving this, the member checks whether it has already subscribed
375 and fails if yes. If no, the member subscribes a Data Tree Change Listener
376 to listen for changes on whole llt:id-ints, and stores the state
377 from the initial notification to a local variable (called the local copy).
378 Each Data Tree Change from further Notifications shall be applied
379 to the local copy if it is compatible
380 (the old state from notification is equal to the local copy state).
381 If a notification is not compatible, it shall be ignored.";
386 rpc unsubscribe-dtcl {
387 description "Upon receiving this, the member checks whether it has currently subscribed
388 a Data Tree Change Listener for llt:id-ints changes, and fails if no. If yes, the member
389 shall unsubscribe the listener, read state of id-ints, compare that
390 to the local copy, and return whether the local copy is the same.";
396 description "True if and only if the read id-ints is equal to the local copy.";
402 description "Upon receiving this, the member checks whether it has already subscribed
403 and fails if yes. If no, the member subscribes a DOMDataTreeListener
404 to listen for changes on whole llt:id-ints, and stores
405 the state from the initial notification to a local variable (called the local copy).
406 Each Data Tree Change from further notifications shall be applied
407 to the local copy if it is compatible
408 (the old state from notification is equal to the local copy state).
409 If a notification is not compatible, it shall be ignored.";
414 rpc unsubscribe-ddtl {
415 description "Upon receiving this, the member checks whether it has currently subscribed
416 a DOMDataTreeListener for llt:id-ints changes, and fails if no. If yes, the member
417 shall unsubscribe the listener, read state of id-ints (by briefly subscribing
418 and ubsubscribing again), compare that to the local copy,
419 and return whether the local copy is the same.";
423 description "True if and only if the read id-ints is equal to the local copy.";
430 // The following calls are not required for Carbon testing.
432 rpc deconfigure-id-ints-shard {
433 description "Upon receiving this, the member shall ask the appropriate API
434 to remove the llt:id-ints shard (presumably created by produce-transactions)
435 and return immediatelly.
436 It is expected the data would move to the root prefix shard seamlessly.
438 TODO: Make shard name configurable by input?";
443 rpc register-default-constant {
444 description "Upon receiving this, the member has to create and register
445 a default llt:get-contexted-constant implementation (routed RPC).
446 If the registration fails for any reason, propagate the corresponding error.";
448 uses llc:constant-grouping;
453 rpc unregister-default-constant {
454 description "Upon receiving this, the member has to unregister
455 any llt:get-contexted-constant default implementations it has registered.
456 If no default implementation has been registered, do nothing.";