X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;ds=sidebyside;f=opendaylight%2Fmd-sal%2Fsal-binding-api%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fcontroller%2Fsal%2Fbinding%2Fapi%2FRpcProviderRegistry.java;h=367e55d927cfa9431b5dfde20c6c159f8dd827c6;hb=899ccfb2052bc5b2c52828d6ccb04c16f9787784;hp=22db985ba96b82cc4245a42f28ccd3e1f9959774;hpb=e55942fd1fcc4748197146b81f7497256de22a94;p=controller.git diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcProviderRegistry.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcProviderRegistry.java index 22db985ba9..367e55d927 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcProviderRegistry.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/RpcProviderRegistry.java @@ -17,6 +17,7 @@ import org.opendaylight.yangtools.yang.binding.RpcService; /** * Provides a registry for Remote Procedure Call (RPC) service implementations. The RPCs are * defined in YANG models. + * *
* There are 2 types of RPCs: *
* An RPC is global if there is intended to be only 1 registered implementation. A global RPC is not * explicitly declared as such, essentially any RPC that is not defined to be routed is considered global. + * *
* Global RPCs are registered using the * {@link #addRpcImplementation(Class, RpcService)} method. * *
* MD-SAL supports routing of RPC between multiple implementations where the appropriate * implementation is selected at run time based on the content of the RPC message as described in * YANG model. + * *
* RPC routing is based on: *
* A context type is modeled in YANG using a combination of a YANG identity
* and Opendaylight specific extensions from yang-ext
module. These extensions are:
@@ -65,14 +71,13 @@ import org.opendaylight.yangtools.yang.binding.RpcService;
* instance-identifier
or a type derived from instance-identifier
.
*
*
+ *
+ *
- *
* The following snippet declares a simple YANG identity
named example-context
:
*
- *
+ * {@code * module example { * ... * identity example-context { @@ -80,17 +85,19 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * } * ... * } - *+ * } + * *
* We then use the declared identity to define a context type by using it in combination
* with the context-instance
YANG extension. We'll associate the context type
* with a list element in the data tree. This defines the set of nodes whose instance
* identifiers are valid for the example-context
context type.
+ *
*
* The following YANG snippet imports the yang-ext
module and defines the list
* element named item
inside a container named foo
:
*
- *
+ * {@code * module foo { * ... * import yang-ext {prefix ext;} @@ -104,7 +111,8 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * } * ... * } - *+ * } + * *
* The statement ext:context-instance "example-context";
inside the list element
* declares that any instance identifier referencing item
in the data
@@ -118,15 +126,19 @@ import org.opendaylight.yangtools.yang.binding.RpcService;
* InstanceIdentifier.create(Example.class)
*
* is not valid.
+ *
*
* So using an identity
in combination with context-instance
we
* have effectively defined a context type that can be referenced in a YANG RPC input.
*
+ *
*
* To define an RPC to be routed based on the context type we need to add an input leaf element * that references the context type which will hold an instance identifier value to be * used to route the RPC. + * *
* The following snippet defines an RPC named show-item
with 2 leaf elements
* as input: item
of type instance-identifier
and description
:
@@ -149,11 +161,13 @@ import org.opendaylight.yangtools.yang.binding.RpcService;
* }
* }
*
+ *
*
* We mark the item
leaf with a context-reference
statement that
* references the example-context
context type. RPC calls will then be routed
* based on the instance identifier value contained in item
. Only instance
* identifiers that point to a foo/item
node are valid as input.
+ *
*
* The generated RPC Service interface for the module is: * @@ -162,15 +176,18 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * Future<RpcResult<Void>> showItem(ShowItemInput input); * } * + * *
* For constructing the RPC input, there are generated classes ShowItemInput and ShowItemInputBuilder. * *
* To register a routed implementation for the show-item
RPC, we must use the
* {@link #addRoutedRpcImplementation(Class, RpcService)} method. This
* will return a {@link RoutedRpcRegistration} instance which can then be used to register /
* unregister routed paths associated with the registered implementation.
+ *
*
* The following snippet registers myImpl
as the RPC implementation for an
* item
with key "foo"
:
@@ -185,6 +202,7 @@ import org.opendaylight.yangtools.yang.binding.RpcService;
* // YANG-generated class for the example-context identity.
* reg.registerPath(ExampleContext.class, path);
*
+ *
*
* It is also possible to register the same implementation for multiple paths:
*
@@ -203,13 +221,18 @@ import org.opendaylight.yangtools.yang.binding.RpcService;
* arguments in ShowItemInput, extract the InstanceIdentifier value of the item
leaf and select
* the implementation whose registered path matches the InstanceIdentifier value of the item
leaf.
*
+ *
*
*
* The generated interfaces require implementors to return - * {@link java.util.concurrent.Future Future}<{@link org.opendaylight.yangtools.yang.common.RpcResult RpcResult}<{RpcName}Output>> instances. + * {@link java.util.concurrent.Future Future}<{@link org.opendaylight.yangtools.yang.common.RpcResult RpcResult} + * <{RpcName}Output>> instances. * + *
* Implementations should do processing of RPC calls asynchronously and update the * returned {@link java.util.concurrent.Future Future} instance when processing is complete. * However using {@link com.google.common.util.concurrent.Futures#immediateFuture(Object) Futures.immediateFuture} @@ -223,13 +246,17 @@ import org.opendaylight.yangtools.yang.binding.RpcService; * or completely fail. This is intended to provide additional human readable information * for users of the API and to transfer warning / error information across the system * so it may be visible via other external APIs such as Restconf. + * *
* It is recommended to use the {@link org.opendaylight.yangtools.yang.common.RpcResult RpcResult}
* for conveying appropriate error information
* on failure rather than purposely throwing unchecked exceptions if at all possible.
* While unchecked exceptions will fail the returned {@link java.util.concurrent.Future Future},
* using the intended RpcResult to convey the error information is more user-friendly.
+ *
+ * @deprecated Use {@link org.opendaylight.mdsal.binding.api.RpcProviderService} instead
*/
+@Deprecated
public interface RpcProviderRegistry extends //
RpcConsumerRegistry, //
RouteChangePublisher