2a5299d761e328624019d9ac021fc1c5accb9df8
[controller.git] / opendaylight / md-sal / samples / clustering-test-app / model / src / main / yang / odl-mdsal-lowlevel-control.yang
1 module odl-mdsal-lowlevel-control {
2
3     yang-version 1;
4     namespace "tag:opendaylight.org,2017:controller:yang:lowlevel:control";
5     prefix ll;
6
7     import odl-mdsal-lowlevel-common {
8         revision-date "2017-02-15";
9         prefix llc;
10     }
11
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.
19
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.
23
24         TODO: Unify grammar: present or future tense, or imperative mood.";
25
26     revision "2017-02-15" {
27         description "Initial revision for Carbon clustering testing.";
28     }
29
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.";
34         input {
35             uses llc:constant-grouping;
36         }
37         // No output.
38     }
39
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.";
44         // No input.
45         // No output.
46     }
47
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.";
52         input {
53             uses llc:context-grouping;
54             uses llc:constant-grouping;
55         }
56         // No output.
57     }
58
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.";
63         input {
64             uses llc:context-grouping;
65         }
66         // No output.
67     }
68
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.";
79         input {
80             uses llc:constant-grouping;
81         }
82         // No output.
83     }
84
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.";
91         // No input.
92         // No output.
93     }
94
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.";
108         // No input.
109         // No output.
110     }
111
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.";
116         // No input.
117         output {
118             leaf flap-count {
119                 description "Number of successful re-registrations. If negative,
120                     (minus) cycle number when a failure occured.";
121                 mandatory true;
122                 type int64;
123             }
124         }
125     }
126
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).";
132         input {
133             uses llc:id-grouping;
134             leaf seconds {
135                 description "This RPC has to work (roughly) this long.";
136                 mandatory true;
137                 type uint32;
138             }
139             leaf notifications-per-second {
140                 description "An upper limit of publishes per second this RPC shall try to achieve.";
141                 mandatory true;
142                 type uint32;
143             }
144         }
145         // No output.
146     }
147
148     rpc subscribe-ynl {
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.";
159         input {
160             uses llc:id-grouping;
161         }
162         // No output.
163     }
164
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.";
169         input {
170             uses llc:id-grouping;
171         }
172         output {
173             leaf all-not {
174                 description "Number of received id-sequence notifications of any id.";
175                 mandatory true;
176                 type int64;
177             }
178             leaf id-not {
179                 description "Number of received id-sequence notifications of matching id
180                     and any sequence number.";
181                 mandatory true;
182                 type int64;
183             }
184             leaf err-not {
185                 description "Number of received id-sequence notifications of matching id,
186                     but out-of-order sequence number.";
187                 mandatory true;
188                 type int64;
189             }
190             leaf local-number {
191                 description "Value of the local number, should be equal to
192                     the sequence number of the last compatible id-sequence notification received.";
193                 mandatory true;
194                 type int64;
195             }
196         }
197     }
198
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.";
215         input {
216             uses llc:id-grouping;
217             leaf seconds {
218                 description "This RPC has to work (roughly) this long.";
219                 mandatory true;
220                 type uint32;
221             }
222             leaf transactions-per-second {
223                 description "An upper limit of transactions per second this RPC shall try to achieve.";
224                 mandatory true;
225                 type uint32;
226             }
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.";
231                 mandatory true;
232                 type boolean;
233             }
234         }
235         output {
236             leaf all-tx {
237                 description "Number of all transactions executed.";
238                 type int64;
239                 mandatory true;
240             }
241             leaf insert-tx {
242                 description "Number of transactions that inserted data.";
243                 type int64;
244                 mandatory true;
245             }
246             leaf delete-tx {
247                 description "Number of transactions that deleted data.";
248                 type int64;
249                 mandatory true;
250             }
251         }
252     }
253
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).
259
260             FIXME: Is the above the normal way of creating prefix-based chards?
261
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.";
275         input {
276             uses llc:id-grouping;
277             leaf seconds {
278                 description "This RPC has to work (roughly) this long.";
279                 mandatory true;
280                 type uint32;
281             }
282             leaf transactions-per-second {
283                 description "An upper limit of transactions per second this RPC shall try to achieve.";
284                 mandatory true;
285                 type uint32;
286             }
287             leaf isolated-transactions {
288                 description "The value for DOMDataTreeProducer#createTransaction argument.";
289                 mandatory true;
290                 type boolean;
291             }
292         }
293         // No output.
294     }
295
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.";
300         input {
301             leaf shard-name {
302                 description "TBD.
303
304                 FIXME: Ask Java implementation developer about the format needed.";
305                 mandatory true;
306                 type string;
307             }
308         }
309         // No output.
310     }
311
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.";
315         input {
316             leaf shard-name {
317                 description "TBD.
318
319                 FIXME: Ask Java implementation developer about the format needed.
320                 TODO: Perhaps the names are compatible and one 'become-leader' would suffice?";
321                 mandatory true;
322                 type string;
323             }
324         }
325         // No output.
326     }
327
328     rpc remove-shard-replica {
329         description "A specialised copy of cluster-admin:remove-shard-replica.
330
331             FIXME: Is this really needed for prefix shards, or even module shards
332                 (or is the cluster-admin RPC sufficient)?";
333         input {
334             leaf shard-name {
335                 description "The name of the config shard for which
336                     to remove the replica on the current member.";
337                 mandatory true;
338                 type string;
339             }
340         // No output.
341         }
342     }
343
344     rpc add-shard-replica {
345         description "A specialised copy of cluster-admin:add-shard-replica.
346
347             FIXME: Is this really needed for prefix shards, or even module shards
348                 (or is the cluster-admin RPC sufficient)?";
349         input {
350             leaf shard-name {
351                 description "The name of the config shard for which
352                     to add the replica on the current member.";
353                 mandatory true;
354                 type string;
355             }
356         // No output.
357         }
358     }
359
360     rpc is-client-aborted {
361         description "Return state of cds-access-client.
362
363             FIXME: Is an input needed?";
364         output {
365             leaf aborted {
366                 description "True if the local client is aborted (or unreachable), false otherwise.";
367                 mandatory true;
368                 type boolean;
369             }
370         }
371     }
372
373     rpc subscribe-dtcl {
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.";
382         // No input.
383         // No output.
384     }
385
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.";
391         // No input.
392         output {
393             leaf copy-matches {
394                 type boolean;
395                 mandatory true;
396                 description "True if and only if the read id-ints is equal to the local copy.";
397             }
398         }
399     }
400
401     rpc subscribe-ddtl {
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.";
410         // No input.
411         // No output.
412     }
413
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.";
420         // No input.
421         output {
422             leaf copy-matches {
423                 description "True if and only if the read id-ints is equal to the local copy.";
424                 mandatory true;
425                 type boolean;
426             }
427         }
428     }
429
430     // The following calls are not required for Carbon testing.
431
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.
437
438             TODO: Make shard name configurable by input?";
439         // No input.
440         // No output.
441     }
442
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.";
447         input {
448             uses llc:constant-grouping;
449         }
450         // No output.
451     }
452
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.";
457         // No input.
458         // No output.
459     }
460
461 }