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