From e18365c2cce8c4a6d3a7ec403bba4979d3d9c3a0 Mon Sep 17 00:00:00 2001 From: Ed Warnicke Date: Tue, 24 Jun 2014 10:13:45 -0500 Subject: [PATCH] Improve documentation of BindingAware{Provider,Consumer} Change-Id: I39899f68f91a5c54099a404f00b944fa9cf3cec3 Signed-off-by: Ed Warnicke --- .../sal/binding/api/BindingAwareConsumer.java | 69 ++++++-- .../sal/binding/api/BindingAwareProvider.java | 150 ++++++++++++++++-- 2 files changed, 193 insertions(+), 26 deletions(-) diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareConsumer.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareConsumer.java index 4327451d21..bcbd6879d0 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareConsumer.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareConsumer.java @@ -10,17 +10,64 @@ package org.opendaylight.controller.sal.binding.api; import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ConsumerContext; /** - * - * Defines the component of controller and supplies additional metadata. A - * component of the controller or application supplies a concrete implementation - * of this interface. - * - * A user-implemented component (application) which facilitates the SAL and SAL - * services to access infrastructure services or providers' functionality. - * - * - * - */ +* +* A developer implemented component that gets registered with the Broker. +* +* Semantically, a consumer may: +* +*
    +*
  1. Subscribe for Notifications
    2. +*
  2. Invoke RPCs
    3. +*
  3. Read from either the operational or config data tree
    4. +*
  4. Write to the config data tree
    5. +*
+* If you need to: +*
    +*
  1. Emit Notifications
    2. +*
  2. Provide the implementation of RPCs
    3. +*
  3. Write to the operational data tree
    4. +*
+* +* Consider using a BindingAwareProvider +* +* Examples: +* +* To get a NotificationService: +* +* {code +* public void onSessionInitiated(ProviderContext session) { +* NotificationProviderService notificationService = session.getSALService(NotificationProviderService.class); +* notificationService.publish(notification) +* } +* where notification is an instance of a modeled Notification. +* For more information on sending notifications via the NotificationProviderService +* @see org.opendaylight.controller.sal.binding.api.NotificationProviderService +* +* +* A consumer can *invoke* and RPC ( ie, call foo(fooArgs)) but it cannot register an RPC +* implementation with the MD-SAL that others can invoke(call). +* To get an invokable RPC: +* +* {code +* public void onSessionInitiated(ProviderContext session) { +* MyService rpcFlowSalService = session.getRpcService(MyService.class); +* } +* +* Where MyService.class is a Service interface generated from a yang model with RPCs modeled in it. The returned +* rpcFlowSalService can be used like any other object by invoking its methods. Note, nothing special needs to be done +* for RoutedRPCs. They just work. +* +* To get a DataBroker to allow access to the data tree: +* +* {code +* public void onSessionInitiated(final ProviderContext session) { +* DataBroker databroker = session.getSALService(BindingDataBroker.class); +* } +* } +* @see org.opendaylight.controller.md.sal.common.api.data.BindingDataBroker +* for more info on using the DataBroker. +* +*/ public interface BindingAwareConsumer { /** diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareProvider.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareProvider.java index 0812e5f53c..cb26cad2f3 100644 --- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareProvider.java +++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareProvider.java @@ -15,37 +15,131 @@ import org.opendaylight.yangtools.yang.binding.RpcService; /** * - * Defines the component of controller and supplies additional metadata. A - * component of the controller or application supplies a concrete implementation - * of this interface. + * A developer implemented component that gets registered with the Broker. * + * Semantically, a provider may: + * + *
    + *
  1. Emit Notifications
    2. + *
  2. Provide the implementation of RPCs
    3. + *
  3. Write to the operational data tree
    4. + *
+ * + * If a class is not doing at least one of those three, consider using + * a BindingAwareConsumer instead: + * @see org.opendaylight.controller.sal.binding.api.BindingAwareConsumer + * + *

+ * + *In addition, a BindingAwareProvider can in pursuit of its goals: + * + *

    + *
  1. Subscribe for Notifications
    2. + *
  2. Invoke RPCs
    3. + *
  3. Read from either the operational or config data tree
    4. + *
  4. Write to the config data tree
    5. + *
+ * (All of the above are things a Consumer can also do). + * + *

+ * + * Examples: + * + *

+ * + * To get a NotificationService: + * + * {code + * public void onSessionInitiated(ProviderContext session) { + * NotificationProviderService notificationService = session.getSALService(NotificationProviderService.class); + * } + * For more information on sending notifications via the NotificationProviderService + * @see org.opendaylight.controller.sal.binding.api.NotificationProviderService + * + * To register an RPC implementation: + * + * {code + * public void onSessionInitiated(ProviderContext session) { + * RpcRegistration registration = session.addRpcImplementation(MyService.class, myImplementationInstance); + * } + * + *

+ * + * Where MyService.class is a Service interface generated from a yang model with RPCs modeled in it and myImplementationInstance + * is an instance of a class that implements MyService. + * + * To register a Routed RPC Implementation: + * {code + * public void onSessionInitiated(ProviderContext session) { + * RoutedRpcRegistration flowRegistration = session.addRoutedRpcImplementation(SalFlowService.class, salFlowServiceImplementationInstance); + flowRegistration.registerPath(NodeContext.class, nodeInstanceId); + * } + * } + * + * Where SalFlowService.class is a Service interface generated from a yang model with RPCs modeled in it and salFlowServiceImplementationInstance is an instance + * of a class that implements SalFlowService. *

- * A user-implemented component (application) which facilitates the SAL and SAL - * services to access infrastructure services and to provide functionality to - * {@link Consumer}s and other providers. + * The line: + * {code + * flowRegistration.registerPath(NodeContext.class, nodeInstanceId); + * } + * Is indicating that the RPC implementation is registered to handle RPC invocations that have their NodeContext pointing to the node with instance id nodeInstanceId. + * This bears a bit of further explanation. RoutedRPCs can be 'routed' to an implementation based upon 'context'. 'context' is a pointer (instanceId) to some place + * in the data tree. In this example, the 'context' is a pointer to a Node. In this way, a provider can register its ability to provide a service for a particular + * Node, but not *all* Nodes. The Broker routes the RPC by 'context' to the correct implementation, without the caller having to do extra work. Because of this when + * a RoutedRPC is registered, it needs to also be able to indicate for which 'contexts' it is providing an implementation. + * + * An example of a Routed RPC would be an updateFlow(node, flow) that would be routed based on node to the provider which had registered to provide + * it *for that node*. + * + *

* + * To get a DataBroker to allow access to the data tree: + * + * {code + * public void onSessionInitiated(final ProviderContext session) { + * DataBroker databroker = session.getSALService(BindingDataBroker.class); + * } + * } + * @see org.opendaylight.controller.md.sal.common.api.data.BindingDataBroker + * for more info on using the DataBroker. * */ public interface BindingAwareProvider { /** - * Returns a set of provided implementations of YANG modules and their rpcs. + * @deprecated * + * This interface was originally intended to solve problems of how to get Implementations + * of functionality from a provider, but that is no longer necessary because the Provider + * Registers RPCs in onSessionInitiated. * - * @return Set of provided implementation of YANG modules and their Rpcs + * Recommend: + * {code + * public Collection getImplementations() { + * return Collections.emptySet(); + * } + * } */ + @Deprecated Collection getImplementations(); /** - * Gets a set of implementations of provider functionality to be registered - * into system during the provider registration to the SAL. + * @deprecated * - *

- * This method is invoked by {@link Broker#registerProvider(Provider)} to - * learn the initial provided functionality + * This interface was originally intended to solve problems of how to get Functionality + * a provider could provide, but that is no longer necessary because the Provider + * Registers RPCs in onSessionInitiated. + * + * Recommend: + * {code + * public Collection getFunctionality() { + * return Collections.emptySet(); + * } + * } * - * @return Set of provider's functionality. */ + @Deprecated Collection getFunctionality(); /** @@ -58,12 +152,38 @@ public interface BindingAwareProvider { * * */ + @Deprecated public interface ProviderFunctionality { } - + /** + * Callback signaling initialization of the consumer session to the SAL. + * + * The consumer MUST use the session for all communication with SAL or + * retrieving SAL infrastructure services. + * + * This method is invoked by + * {@link BindingAwareBroker#registerProvider(BindingAwareProvider)} + * + * @param session Unique session between consumer and SAL. + */ void onSessionInitiated(ProviderContext session); + /* + * @deprecated + * + * A provider was at one point considered an extension of a consumer, thus this + * call. It is deprecated and the @see org.opendaylight.controller.sal.binding.api.BindingAwareConsumer#onSessionInitiated + * used, or you should simply use {@link #onSessionInitiated(ProviderContext)} + * + * Recommend: + * {code + * public final void onSessionInitialized(ConsumerContext session) { + * // NOOP - as method is deprecated + * } + * } + */ + @Deprecated void onSessionInitialized(ConsumerContext session); } -- 2.36.6