--- /dev/null
+// Source: https://ask.opendaylight.org/question/99/how-does-request-routing-works/
+=== MD-SAL RPC routing
+
+The MD-SAL provides a way to deliver Remote Procedure Calls (RPCs) to a
+particular implementation based on content in the input as it is modeled in
+YANG. This part of the the RPC input is referred to as a *context reference*.
+
+The MD-SAL does not dictate the name of the leaf which is used for this RPC
+routing, but provides necessary functionality for YANG model author to define
+their *context reference* in their model of RPCs.
+
+MD-SAL routing behavior is modeled using following terminology and its
+application to YANG models:
+
+Context Type::
+ Logical type of RPC routing. Context type is modeled as YANG `identity`
+ and is referenced in model to provide scoping information.
+Context Instance::
+ Conceptual location in data tree, which represents context in which RPC
+ could be executed. Context instance usually represent logical point
+ to which RPC execution is attached.
+Context Reference::
+ Field of RPC input payload which contains Instance Identifier referencing
+ *context instance* in which the RPC should be executed.
+
+==== Modeling a routed RPC
+
+In order to define routed RPCs, the YANG model author needs to declare (or
+reuse) a *context type*, set of possible *context instances* and finally RPCs
+which will contain *context reference* on which they will be routed.
+
+===== Declaring a routing context type
+
+[source,yang]
+----
+identity node-context {
+ description "Identity used to mark node context";
+}
+----
+
+This declares an identity named `node-context`, which is used as marker
+for node-based routing and is used in other places to reference that routing
+type.
+
+===== Declaring possible context instances
+
+In order to define possible values of *context instances* for routed RPCs, we
+need to model that set accordingly using `context-instance` extension from the
+`yang-ext` model.
+
+[source,yang]
+----
+import yang-ext { prefix ext; }
+
+/** Base structure **/
+container nodes {
+ list node {
+ key "id";
+ ext:context-instance "node-context";
+ // other node-related fields would go here
+ }
+}
+----
+
+The statement `ext:context-instance "node-context";` marks any element of the
+`list node` as a possible valid *context instance* in `node-context` based
+routing.
+
+[NOTE]
+====
+The existence of a *context instance* node in operational or config data tree
+is not strongly tied to existence of RPC implementation.
+
+For most routed RPC models, there is relationship between the data present in
+operational data tree and RPC implementation availability, but this is
+not enforced by MD-SAL. This provides some flexibility for YANG model writers
+to better specify their routing model and requirements for implementations.
+Details when RPC implementations are available should be documented in YANG model.
+
+If user invokes RPC with a *context instance* that has no registered
+implementation, the RPC invocation will fail with the exception
+`DOMRpcImplementationNotAvailableException`.
+====
+
+===== Declaring a routed RPC
+
+To declare RPC to be routed based on `node-context` we need to add leaf
+of `instance-identifier` type (or type derived from `instance-identifier`)
+to the RPC and mark it as *context reference*.
+
+This is achieved using YANG extension `context-reference` from `yang-ext` model
+on leaf, which will be used for RPC routing.
+
+[source,yang]
+----
+rpc example-routed-rpc {
+ input {
+ leaf node {
+ ext:context-reference "node-context";
+ type "instance-identifier";
+ }
+ // other input to the RPC would go here
+ }
+}
+----
+
+The statement `ext:context-reference "node-context"` marks `leaf node` as
+*context reference* of type `node-context`. The value of this leaf, will be used
+by the MD-SAL to select the particular RPC implementation that registered itself
+as the implementation of the RPC for particular *context instance*.
+
+==== Using routed RPCs
+
+From a user perspective (e.g. invoking RPCs) there is no difference between
+routed and non-routed RPCs. Routing information is just an additional leaf in
+RPC which must be populated.
+
+// TODO: Add simple snippet of invoking such RPC even if it does not differ
+// from normal one.
+
+==== Implementing a routed RPC
+
+// TODO: Update this section to show some other example model
+// along with binding and DOM implementations
+
+Implementation
+
+===== Registering implementations
+
+// FIXME: Clean up bit wording in following section, use different example
+
+Implementations of a routed RPC (e.g., southbound plugins) will specify an
+instance-identifier for the *context reference* (in this case a node) for which
+they want to provide an implementation during registration. Consumers, e.g.,
+those calling the RPC are required to specify that instance-identifier (in this
+case the identifier of a node) when invoking RPC.
+
+Simple code which showcases that for add-flow via Binding-Aware APIs
+(https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=blob;f=opendaylight/md-sal/sal-binding-it/src/test/java/org/opendaylight/controller/test/sal/binding/it/RoutedServiceTest.java;h=d49d6f0e25e271e43c8550feb5eef63d96301184;hb=HEAD[RoutedServiceTest.java]
+):
+
+[source, java]
+----
+ 61 @Override
+ 62 public void onSessionInitiated(ProviderContext session) {
+ 63 assertNotNull(session);
+ 64 firstReg = session.addRoutedRpcImplementation(SalFlowService.class, salFlowService1);
+ 65 }
+----
+Line 64: We are registering salFlowService1 as implementation of
+SalFlowService RPC
+
+[source, java]
+----
+107 NodeRef nodeOne = createNodeRef("foo:node:1");
+109 /**
+110 * Provider 1 registers path of node 1
+111 */
+112 firstReg.registerPath(NodeContext.class, nodeOne);
+----
+
+Line 107: We are creating NodeRef (encapsulation of InstanceIdentifier)
+for "foo:node:1".
+
+Line 112: We register salFlowService1 as implementation for nodeOne.
+
+The salFlowService1 will be executed only for RPCs which contains
+Instance Identifier for foo:node:1.
Code Review / docs.git / commitdiff