/**
* Provides a registry for Remote Procedure Call (RPC) service implementations. The RPCs are
* defined in YANG models.
+ *
* <p>
* There are 2 types of RPCs:
* <ul>
* </ul>
*
* <h2>Global RPC</h2>
+ *
* <p>
* 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.
+ *
* <p>
* Global RPCs are registered using the
* {@link #addRpcImplementation(Class, RpcService)} method.
*
* <h2>Routed RPC</h2>
+ *
* <p>
* 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.
+ *
* <p>
* RPC routing is based on:
* <ul>
* </ul>
*
* <h3>Context type</h3>
+ *
* <p>
* A context type is modeled in YANG using a combination of a YANG <code>identity</code>
* and Opendaylight specific extensions from <code>yang-ext</code> module. These extensions are:
* <code>instance-identifier</code> or a type derived from <code>instance-identifier</code>.</li>
* </ul>
*
- *
- * <h3>Routed RPC example</h3>
- * <p>
+ * <p><br>
* <h4>1. Defining a Context Type</h4>
+ *
* <p>
* The following snippet declares a simple YANG <code>identity</code> named <code>example-context</code>:
*
* ...
* }
* }
+ *
* <p>
* We then use the declared identity to define a context type by using it in combination
* with the <code>context-instance</code> 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 <code>example-context</code> context type.
+ *
* <p>
* The following YANG snippet imports the <code>yang-ext</code> module and defines the list
* element named <code>item</code> inside a container named <code>foo</code>:
* ...
* }
* }
+ *
* <p>
* The statement <code>ext:context-instance "example-context";</code> inside the list element
* declares that any instance identifier referencing <code>item</code> in the data
* InstanceIdentifier.create(Example.class)
* </pre>
* is not valid.
+ *
* <p>
* So using an <code>identity</code> in combination with <code>context-instance</code> we
* have effectively defined a context type that can be referenced in a YANG RPC input.
*
+ * <p>
* <h5>2. Defining an RPC to use the Context Type</h5>
+ *
* <p>
* 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.
+ *
* <p>
* The following snippet defines an RPC named <code>show-item</code> with 2 leaf elements
* as input: <code>item</code> of type <code>instance-identifier</code> and <code>description</code>:
* }
* }
* </pre>
+ *
* <p>
* We mark the <code>item</code> leaf with a <code>context-reference</code> statement that
* references the <code>example-context</code> context type. RPC calls will then be routed
* based on the instance identifier value contained in <code>item</code>. Only instance
* identifiers that point to a <code>foo/item</code> node are valid as input.
+ *
* <p>
* The generated RPC Service interface for the module is:
*
* Future<RpcResult<Void>> showItem(ShowItemInput input);
* }
* </pre>
+ *
* <p>
* For constructing the RPC input, there are generated classes ShowItemInput and ShowItemInputBuilder.
*
* <h5>3. Registering a routed RPC implementation</h5>
+ *
* <p>
* To register a routed implementation for the <code>show-item</code> 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.
+ *
* <p>
* The following snippet registers <code>myImpl</code> as the RPC implementation for an
* <code>item</code> with key <code>"foo"</code>:
* // YANG-generated class for the example-context identity.
* reg.registerPath(ExampleContext.class, path);
* </pre>
+ *
* <p>
* It is also possible to register the same implementation for multiple paths:
*
* arguments in ShowItemInput, extract the InstanceIdentifier value of the <code>item</code> leaf and select
* the implementation whose registered path matches the InstanceIdentifier value of the <code>item</code> leaf.
*
+ * <p><br>
* <h2>Notes for RPC Implementations</h2>
*
+ * <p>
* <h3>RpcResult</h3>
+ *
* <p>
* 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.
*
+ * <p>
* 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}
* 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.
+ *
* <p>
* 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
*/
-public interface RpcProviderRegistry extends //
- RpcConsumerRegistry, //
+@Deprecated
+public interface RpcProviderRegistry extends RpcConsumerRegistry,
RouteChangePublisher<RpcContextIdentifier, InstanceIdentifier<?>> {
/**
* Registers a global implementation of the provided RPC service interface.
/**
* Registers an implementation of the given routed RPC service interface.
+ *
* <p>
- * See the {@link RpcProviderRegistry class} documentation for information and example on
- * how to use routed RPCs.
+ * See the {@link RpcProviderRegistry class} documentation for information and example on how to use routed RPCs.
*
* @param serviceInterface the YANG-generated interface of the RPC Service for which to register.
* @param implementation the implementation instance to register.
* implementation via invoking RoutedRpcRegistration#registerPath(Class, InstanceIdentifer).
* {@link RoutedRpcRegistration#close()} should be called to unregister the implementation
* and all previously registered paths when no longer needed.
- *
- * @throws IllegalStateException
- * if the supplied RPC interface is not a routed RPC type.
+ * @throws IllegalStateException if the supplied RPC interface is not a routed RPC type.
*/
<T extends RpcService> RoutedRpcRegistration<T> addRoutedRpcImplementation(Class<T> serviceInterface,
- T implementation)
- throws IllegalStateException;
+ T implementation) throws IllegalStateException;
}
Code Review / controller.git / blobdiff