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 start-publish-notifications {
 128         description "Upon receiving this, the member checks whether it is already in the middle of publishing,
 129             for this id, and fails if yes. If no, the member shall clear any state tracking data possibly present
 130             from the previous call wth this id, and start publishing llt:id-sequence
 131             notifications with the given id and sequence numbers increasing from 1.
 132             The RPC shall return immediatelly before the first notification is published.
 133             The publishing task stops on first error of after the given time.";
 134         input {
 135             uses llc:id-grouping;
 136             leaf seconds {
 137                 description "This RPC has to work (roughly) this long.";
 138                 mandatory true;
 139                 type uint32;
 140             }
 141             leaf notifications-per-second {
 142                 description "An upper limit of publishes per second this RPC shall try to achieve.";
 143                 mandatory true;
 144                 type uint32;
 145             }
 146         }
 147         // No output.
 148     }
 149
 150     rpc check-publish-notifications {
 151         description "Upon receiving this, the member shall immediatelly return
 152             the current tracking data related to the current (or previous) task
 153             started by start-publish-notifications with this id.";
 154         input {
 155             uses llc:id-grouping;
 156         }
 157         output {
 158             leaf active {
 159                 description "True if a publishing task for this id is running, false otherwise.";
 160                 mandatory true;
 161                 type boolean;
 162             }
 163             leaf publish-count {
 164                 description "How many notifications were published for this id since last start.
 165                     If there was no start-publish-notifications call for this id, this leaf is absent.";
 166                 mandatory false;
 167                 type int64;
 168             }
 169             leaf last-error {
 170                 description "If no task has been started by start-publish-notifications for this id,
 171                     or if the last such call has not encountered an error, this leaf is absent.
 172                     Otherwise it contains a string message from the last error, including stacktrace if possible.";
 173                 mandatory false;
 174                 type string;
 175             }
 176         }
 177     }
 178
 179     rpc subscribe-ynl {
 180         description "Upon receiving this, the member checks whether it has already subscribed
 181             a yang listener for the given id, and fails if yes.
 182             If no, the member subscribes a Yang notification listener to listen for
 183             llt:id-sequence notifications. The member also creates a local variable
 184             (called local-number) for the sequence number and initialize that to 0.
 185             Also three local counters are initialized to 0: all-not, id-not, err-not.
 186             Upon receiving any id-sequence notification, all-not is incremented.
 187             Each id-sequence notification of matching id shall increment id-not.
 188             If local-number was one less than the sequence number (from a notification matching id),
 189             increment local-number, else increment err-not.";
 190         input {
 191             uses llc:id-grouping;
 192         }
 193         // No output.
 194     }
 195
 196     rpc unsubscribe-ynl {
 197         description "Upon receiving this, the member checks whether it has currently subscribed
 198             a yang listener for the given id, and fails if no. If yes, the member
 199             shall unsubscribe the listener and return values of the local variables.";
 200         input {
 201             uses llc:id-grouping;
 202         }
 203         output {
 204             leaf all-not {
 205                 description "Number of received id-sequence notifications of any id.";
 206                 mandatory true;
 207                 type int64;
 208             }
 209             leaf id-not {
 210                 description "Number of received id-sequence notifications of matching id
 211                     and any sequence number.";
 212                 mandatory true;
 213                 type int64;
 214             }
 215             leaf err-not {
 216                 description "Number of received id-sequence notifications of matching id,
 217                     but out-of-order sequence number.";
 218                 mandatory true;
 219                 type int64;
 220             }
 221             leaf local-number {
 222                 description "Value of the local number, should be equal to
 223                     the sequence number of the last compatible id-sequence notification received.";
 224                 mandatory true;
 225                 type int64;
 226             }
 227         }
 228     }
 229
 230     rpc write-transactions {
 231         description "Upon receiving this, the member shall make sure the outer list item
 232             of llt:id-ints exists for the given id, and then start creating (one by one)
 233             and submitting transactions to randomly add or delete items on the inner list for that id.
 234             The randomness should avoid creating conflicting writes (at least for non-chained
 235             transactions). The recommended way is to require the random number
 236             has low significant bits different than the past ~100k numbers.
 237             To ensure balanced number of deletes, the first write can create
 238             a random set of numbers. Other writes shall be one per number.
 239             The writes shall use the old API, transaction (chains) created directly on datastore
 240             (as opposed to DOMDataTreeProducer).
 241             .get with a timeout on currently earliest non-complete Future (from .submit)
 242             shall be used as the primary wait method to throttle the submission rate.
 243             This RPC shall not return until all transactions are confirmed successful,
 244             or an exception is raised (the exception should propagate to restconf response).
 245             OptimisticLockException is always considered an error.";
 246         input {
 247             uses llc:id-grouping;
 248             leaf seconds {
 249                 description "This RPC has to work (roughly) this long.";
 250                 mandatory true;
 251                 type uint32;
 252             }
 253             leaf transactions-per-second {
 254                 description "An upper limit of transactions per second this RPC shall try to achieve.";
 255                 mandatory true;
 256                 type uint32;
 257             }
 258             leaf chained-transactions {
 259                 description "If true, write transactions shall be created on a transaction chain,
 260                     (created at start of the RPC call, and deleted at at its end).
 261                     If false, write transactions shall be created separately.";
 262                 mandatory true;
 263                 type boolean;
 264             }
 265         }
 266         output {
 267             leaf all-tx {
 268                 description "Number of all transactions executed.";
 269                 type int64;
 270                 mandatory true;
 271             }
 272             leaf insert-tx {
 273                 description "Number of transactions that inserted data.";
 274                 type int64;
 275                 mandatory true;
 276             }
 277             leaf delete-tx {
 278                 description "Number of transactions that deleted data.";
 279                 type int64;
 280                 mandatory true;
 281             }
 282         }
 283     }
 284
 285     rpc produce-transactions {
 286         description "Upon receiving this, the member shall make sure the outer list item
 287             of llt:in-ints exists for the given id, make sure a shard for
 288             the whole (config) id-ints is created (by creating and closing producer
 289             for the whole id-ints), and create a DOMDataTreeProducer for that item (using that shard).
 290
 291             FIXME: Is the above the normal way of creating prefix-based chards?
 292
 293             Then start creating (one by one) and submitting transactions
 294             to randomly add or delete items on the inner list for that id.
 295             To ensure balanced number of deletes, the first write can create
 296             a random set of random numbers. Other writes shall be one per number.
 297             The writes shall use DOMDataTreeProducer API, as opposed to transaction (chains)
 298             created directly on datastore.
 299             .get with a timeout on currently earliest non-complete Future (from .submit)
 300             shall be used as the primary wait method to throttle the submission rate.
 301             This RPC shall not return until all transactions are confirmed successful,
 302             or an exception is raised (the exception should propagate to restconf response).
 303             OptimisticLockException is always considered an error.
 304             In either case, the producer should be closed before returning,
 305             but the shard and the whole id item shall be kept as they are.";
 306         input {
 307             uses llc:id-grouping;
 308             leaf seconds {
 309                 description "This RPC has to work (roughly) this long.";
 310                 mandatory true;
 311                 type uint32;
 312             }
 313             leaf transactions-per-second {
 314                 description "An upper limit of transactions per second this RPC shall try to achieve.";
 315                 mandatory true;
 316                 type uint32;
 317             }
 318             leaf isolated-transactions {
 319                 description "The value for DOMDataTreeProducer#createTransaction argument.";
 320                 mandatory true;
 321                 type boolean;
 322             }
 323         }
 324         output {
 325             leaf all-tx {
 326                 description "Number of all transactions executed.";
 327                 type int64;
 328                 mandatory true;
 329             }
 330             leaf insert-tx {
 331                 description "Number of transactions that inserted data.";
 332                 type int64;
 333                 mandatory true;
 334             }
 335             leaf delete-tx {
 336                 description "Number of transactions that deleted data.";
 337                 type int64;
 338                 mandatory true;
 339             }
 340         }
 341     }
 342
 343     rpc become-prefix-leader {
 344         description "Upon receiving this, the member shall ask the appropriate API
 345             to become Leader of the given shard (presumably the llt:list-ints one,
 346             created by produce-transactions) and return immediatelly.";
 347         input {
 348             leaf shard-name {
 349                 description "TBD.
 350
 351                 FIXME: Ask Java implementation developer about the format needed.";
 352                 mandatory true;
 353                 type string;
 354             }
 355         }
 356         // No output.
 357     }
 358
 359     rpc become-module-leader {
 360         description "Upon receiving this, the member shall ask appropriate API
 361             to become Leader of given config shard and return immediatelly.";
 362         input {
 363             leaf shard-name {
 364                 description "TBD.
 365
 366                 FIXME: Ask Java implementation developer about the format needed.
 367                 TODO: Perhaps the names are compatible and one 'become-leader' would suffice?";
 368                 mandatory true;
 369                 type string;
 370             }
 371         }
 372         // No output.
 373     }
 374
 375     rpc remove-shard-replica {
 376         description "A specialised copy of cluster-admin:remove-shard-replica.
 377
 378             FIXME: Is this really needed for prefix shards, or even module shards
 379                 (or is the cluster-admin RPC sufficient)?";
 380         input {
 381             leaf shard-name {
 382                 description "The name of the config shard for which
 383                     to remove the replica on the current member.";
 384                 mandatory true;
 385                 type string;
 386             }
 387         // No output.
 388         }
 389     }
 390
 391     rpc add-shard-replica {
 392         description "A specialised copy of cluster-admin:add-shard-replica.
 393
 394             FIXME: Is this really needed for prefix shards, or even module shards
 395                 (or is the cluster-admin RPC sufficient)?";
 396         input {
 397             leaf shard-name {
 398                 description "The name of the config shard for which
 399                     to add the replica on the current member.";
 400                 mandatory true;
 401                 type string;
 402             }
 403         // No output.
 404         }
 405     }
 406
 407     rpc is-client-aborted {
 408         description "Return state of cds-access-client.
 409
 410             FIXME: Is an input needed?";
 411         output {
 412             leaf aborted {
 413                 description "True if the local client is aborted (or unreachable), false otherwise.";
 414                 mandatory true;
 415                 type boolean;
 416             }
 417         }
 418     }
 419
 420     rpc subscribe-dtcl {
 421         description "Upon receiving this, the member checks whether it has already subscribed
 422             and fails if yes. If no, the member subscribes a Data Tree Change Listener
 423             to listen for changes on whole llt:id-ints, and stores the state
 424             from the initial notification to a local variable (called the local copy).
 425             Each Data Tree Change from further Notifications shall be applied
 426             to the local copy if it is compatible
 427             (the old state from notification is equal to the local copy state).
 428             If a notification is not compatible, it shall be ignored.";
 429         // No input.
 430         // No output.
 431     }
 432
 433     rpc unsubscribe-dtcl {
 434         description "Upon receiving this, the member checks whether it has currently subscribed
 435             a Data Tree Change Listener for llt:id-ints changes, and fails if no. If yes, the member
 436             shall unsubscribe the listener, read state of id-ints, compare that
 437             to the local copy, and return whether the local copy is the same.";
 438         // No input.
 439         output {
 440             leaf copy-matches {
 441                 type boolean;
 442                 mandatory true;
 443                 description "True if and only if the read id-ints is equal to the local copy.";
 444             }
 445         }
 446     }
 447
 448     rpc subscribe-ddtl {
 449         description "Upon receiving this, the member checks whether it has already subscribed
 450             and fails if yes. If no, the member subscribes a DOMDataTreeListener
 451             to listen for changes on whole llt:id-ints, and stores
 452             the state from the initial notification to a local variable (called the local copy).
 453             Each Data Tree Change from further notifications shall be applied
 454             to the local copy if it is compatible
 455             (the old state from notification is equal to the local copy state).
 456             If a notification is not compatible, it shall be ignored.";
 457         // No input.
 458         // No output.
 459     }
 460
 461     rpc unsubscribe-ddtl {
 462         description "Upon receiving this, the member checks whether it has currently subscribed
 463             a DOMDataTreeListener for llt:id-ints changes, and fails if no. If yes, the member
 464             shall unsubscribe the listener, read state of id-ints (by briefly subscribing
 465             and ubsubscribing again), compare that to the local copy,
 466             and return whether the local copy is the same.";
 467         // No input.
 468         output {
 469             leaf copy-matches {
 470                 description "True if and only if the read id-ints is equal to the local copy.";
 471                 mandatory true;
 472                 type boolean;
 473             }
 474         }
 475     }
 476
 477     // The following calls are not required for Carbon testing.
 478
 479     rpc deconfigure-id-ints-shard {
 480         description "Upon receiving this, the member shall ask the appropriate API
 481             to remove the llt:id-ints shard (presumably created by produce-transactions)
 482             and return immediatelly.
 483             It is expected the data would move to the root prefix shard seamlessly.
 484
 485             TODO: Make shard name configurable by input?";
 486         // No input.
 487         // No output.
 488     }
 489
 490     rpc register-default-constant {
 491         description "Upon receiving this, the member has to create and register
 492             a default llt:get-contexted-constant implementation (routed RPC).
 493             If the registration fails for any reason, propagate the corresponding error.";
 494         input {
 495             uses llc:constant-grouping;
 496         }
 497         // No output.
 498     }
 499
 500     rpc unregister-default-constant {
 501         description "Upon receiving this, the member has to unregister
 502             any llt:get-contexted-constant default implementations it has registered.
 503             If no default implementation has been registered, do nothing.";
 504         // No input.
 505         // No output.
 506     }
 507
 508 }