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         // No output.
 236     }
 237
 238     rpc produce-transactions {
 239         description "Upon receiving this, the member shall make sure the outer list item
 240             of llt:in-ints exists for the given id, make sure a shard for
 241             the whole (config) id-ints is created (by creating and closing producer
 242             for the whole id-ints), and create a DOMDataTreeProducer for that item (using that shard).
 243
 244             FIXME: Is the above the normal way of creating prefix-based chards?
 245
 246             Then start creating (one by one) and submitting transactions
 247             to randomly add or delete items on the inner list for that id.
 248             To ensure balanced number of deletes, the first write can create
 249             a random set of random numbers. Other writes shall be one per number.
 250             The writes shall use DOMDataTreeProducer API, as opposed to transaction (chains)
 251             created directly on datastore.
 252             .get with a timeout on currently earliest non-complete Future (from .submit)
 253             shall be used as the primary wait method to throttle the submission rate.
 254             This RPC shall not return until all transactions are confirmed successful,
 255             or an exception is raised (the exception should propagate to restconf response).
 256             OptimisticLockException is always considered an error.
 257             In either case, the producer should be closed before returning,
 258             but the shard and the whole id item shall be kept as they are.";
 259         input {
 260             uses llc:id-grouping;
 261             leaf seconds {
 262                 description "This RPC has to work (roughly) this long.";
 263                 mandatory true;
 264                 type uint32;
 265             }
 266             leaf transactions-per-second {
 267                 description "An upper limit of transactions per second this RPC shall try to achieve.";
 268                 mandatory true;
 269                 type uint32;
 270             }
 271             leaf isolated-transactions {
 272                 description "The value for DOMDataTreeProducer#createTransaction argument.";
 273                 mandatory true;
 274                 type boolean;
 275             }
 276         }
 277         // No output.
 278     }
 279
 280     rpc become-prefix-leader {
 281         description "Upon receiving this, the member shall ask the appropriate API
 282             to become Leader of the given shard (presumably the llt:list-ints one,
 283             created by produce-transactions) and return immediatelly.";
 284         input {
 285             leaf shard-name {
 286                 description "TBD.
 287
 288                 FIXME: Ask Java implementation developer about the format needed.";
 289                 mandatory true;
 290                 type string;
 291             }
 292         }
 293         // No output.
 294     }
 295
 296     rpc become-module-leader {
 297         description "Upon receiving this, the member shall ask appropriate API
 298             to become Leader of given config shard and return immediatelly.";
 299         input {
 300             leaf shard-name {
 301                 description "TBD.
 302
 303                 FIXME: Ask Java implementation developer about the format needed.
 304                 TODO: Perhaps the names are compatible and one 'become-leader' would suffice?";
 305                 mandatory true;
 306                 type string;
 307             }
 308         }
 309         // No output.
 310     }
 311
 312     rpc remove-shard-replica {
 313         description "A specialised copy of cluster-admin:remove-shard-replica.
 314
 315             FIXME: Is this really needed for prefix shards, or even module shards
 316                 (or is the cluster-admin RPC sufficient)?";
 317         input {
 318             leaf shard-name {
 319                 description "The name of the config shard for which
 320                     to remove the replica on the current member.";
 321                 mandatory true;
 322                 type string;
 323             }
 324         // No output.
 325         }
 326     }
 327
 328     rpc add-shard-replica {
 329         description "A specialised copy of cluster-admin:add-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 add the replica on the current member.";
 337                 mandatory true;
 338                 type string;
 339             }
 340         // No output.
 341         }
 342     }
 343
 344     rpc is-client-aborted {
 345         description "Return state of cds-access-client.
 346
 347             FIXME: Is an input needed?";
 348         output {
 349             leaf aborted {
 350                 description "True if the local client is aborted (or unreachable), false otherwise.";
 351                 mandatory true;
 352                 type boolean;
 353             }
 354         }
 355     }
 356
 357     rpc subscribe-dtcl {
 358         description "Upon receiving this, the member checks whether it has already subscribed
 359             and fails if yes. If no, the member subscribes a Data Tree Change Listener
 360             to listen for changes on whole llt:id-ints, and stores the state
 361             from the initial notification to a local variable (called the local copy).
 362             Each Data Tree Change from further Notifications shall be applied
 363             to the local copy if it is compatible
 364             (the old state from notification is equal to the local copy state).
 365             If a notification is not compatible, it shall be ignored.";
 366         // No input.
 367         // No output.
 368     }
 369
 370     rpc unsubscribe-dtcl {
 371         description "Upon receiving this, the member checks whether it has currently subscribed
 372             a Data Tree Change Listener for llt:id-ints changes, and fails if no. If yes, the member
 373             shall unsubscribe the listener, read state of id-ints, compare that
 374             to the local copy, and return whether the local copy is the same.";
 375         // No input.
 376         output {
 377             leaf copy-matches {
 378                 type boolean;
 379                 mandatory true;
 380                 description "True if and only if the read id-ints is equal to the local copy.";
 381             }
 382         }
 383     }
 384
 385     rpc subscribe-ddtl {
 386         description "Upon receiving this, the member checks whether it has already subscribed
 387             and fails if yes. If no, the member subscribes a DOMDataTreeListener
 388             to listen for changes on whole llt:id-ints, and stores
 389             the state from the initial notification to a local variable (called the local copy).
 390             Each Data Tree Change from further notifications shall be applied
 391             to the local copy if it is compatible
 392             (the old state from notification is equal to the local copy state).
 393             If a notification is not compatible, it shall be ignored.";
 394         // No input.
 395         // No output.
 396     }
 397
 398     rpc unsubscribe-ddtl {
 399         description "Upon receiving this, the member checks whether it has currently subscribed
 400             a DOMDataTreeListener for llt:id-ints changes, and fails if no. If yes, the member
 401             shall unsubscribe the listener, read state of id-ints (by briefly subscribing
 402             and ubsubscribing again), compare that to the local copy,
 403             and return whether the local copy is the same.";
 404         // No input.
 405         output {
 406             leaf copy-matches {
 407                 description "True if and only if the read id-ints is equal to the local copy.";
 408                 mandatory true;
 409                 type boolean;
 410             }
 411         }
 412     }
 413
 414     // The following calls are not required for Carbon testing.
 415
 416     rpc deconfigure-id-ints-shard {
 417         description "Upon receiving this, the member shall ask the appropriate API
 418             to remove the llt:id-ints shard (presumably created by produce-transactions)
 419             and return immediatelly.
 420             It is expected the data would move to the root prefix shard seamlessly.
 421
 422             TODO: Make shard name configurable by input?";
 423         // No input.
 424         // No output.
 425     }
 426
 427     rpc register-default-constant {
 428         description "Upon receiving this, the member has to create and register
 429             a default llt:get-contexted-constant implementation (routed RPC).
 430             If the registration fails for any reason, propagate the corresponding error.";
 431         input {
 432             uses llc:constant-grouping;
 433         }
 434         // No output.
 435     }
 436
 437     rpc unregister-default-constant {
 438         description "Upon receiving this, the member has to unregister
 439             any llt:get-contexted-constant default implementations it has registered.
 440             If no default implementation has been registered, do nothing.";
 441         // No input.
 442         // No output.
 443     }
 444
 445 }