binding/mdsal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareProvider.java

   1 /*
   2  * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.controller.sal.binding.api;
   9
  10 import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ProviderContext;
  11
  12 /**
  13  *
  14  * A developer implemented component that gets registered with the Broker.
  15  *
  16  * Semantically, a provider may:
  17  *
  18  * <ol>
  19  * <li>Emit Notifications</li>
  20  * <li>Provide the implementation of RPCs</li>
  21  * <li>Write to the operational data tree</li>
  22  * </ol>
  23  *
  24  *
  25  * <p>
  26  *
  27  * In addition, a BindingAwareProvider can in pursuit of its goals:
  28  *
  29  * <ol>
  30  * <li>Subscribe for Notifications</li>
  31  * <li>Invoke RPCs</li>
  32  * <li>Read from either the operational or config data tree</li>
  33  * <li>Write to the config data tree</li>
  34  * </ol>
  35  * (All of the above are things a Consumer can also do).
  36  *
  37  * <p>
  38  *
  39  * Examples:
  40  *
  41  * <p>
  42  *
  43  * To get a NotificationService:
  44  *
  45  * <pre>
  46  * {code
  47  * public void onSessionInitiated(ProviderContext session) {
  48  *      NotificationProviderService notificationService = session.getSALService(NotificationProviderService.class);
  49  * }
  50  * }
  51  * </pre>
  52  *
  53  *
  54  *
  55  * To register an RPC implementation:
  56  *
  57  * <pre>
  58  * {code
  59  * public void onSessionInitiated(ProviderContext session) {
  60  *    RpcRegistration&lt;MyService&gt; registration = session.addRpcImplementation(MyService.class, myImplementationInstance);
  61  * }
  62  * }
  63  * </pre>
  64  *
  65  * <p>
  66  *
  67  * Where MyService.class is a Service interface generated from a yang model with RPCs modeled in it
  68  * and myImplementationInstance is an instance of a class that implements MyService.
  69  *
  70  * To register a Routed RPC Implementation:
  71  *
  72  * <pre>
  73  * {code
  74  * public void onSessionInitiated(ProviderContext session) {
  75  *   RoutedRpcRegistration&lt;SalFlowService&gt; flowRegistration = session.addRoutedRpcImplementation(SalFlowService.class, salFlowServiceImplementationInstance);
  76  *      flowRegistration.registerPath(NodeContext.class, nodeInstanceId);
  77  * }
  78  * }
  79  * </pre>
  80  *
  81  * Where SalFlowService.class is a Service interface generated from a yang model with RPCs modeled
  82  * in it and salFlowServiceImplementationInstance is an instance of a class that implements
  83  * SalFlowService.
  84  * <p>
  85  * The line:
  86  *
  87  * <pre>
  88  * {code
  89  * flowRegistration.registerPath(NodeContext.class, nodeInstanceId);
  90  * }
  91  * </pre>
  92  *
  93  * Is indicating that the RPC implementation is registered to handle RPC invocations that have their
  94  * NodeContext pointing to the node with instance id nodeInstanceId. This bears a bit of further
  95  * explanation. RoutedRPCs can be 'routed' to an implementation based upon 'context'. 'context' is a
  96  * pointer (instanceId) to some place in the data tree. In this example, the 'context' is a pointer
  97  * to a Node. In this way, a provider can register its ability to provide a service for a particular
  98  * Node, but not *all* Nodes. The Broker routes the RPC by 'context' to the correct implementation,
  99  * without the caller having to do extra work. Because of this when a RoutedRPC is registered, it
 100  * needs to also be able to indicate for which 'contexts' it is providing an implementation.
 101  *
 102  * An example of a Routed RPC would be an updateFlow(node, flow) that would be routed based on node
 103  * to the provider which had registered to provide it *for that node*.
 104  *
 105  * <p>
 106  *
 107  * To get a DataBroker to allow access to the data tree:
 108  *
 109  * <pre>
 110  * {code
 111  * public void onSessionInitiated(final ProviderContext session) {
 112  *      DataBroker databroker = session.getSALService(BindingDataBroker.class);
 113  * }
 114  * }
 115  * </pre>
 116  *
 117  *
 118  */
 119 public interface BindingAwareProvider {
 120
 121     /**
 122      * Callback signaling initialization of the consumer session to the SAL.
 123      *
 124      * The consumer MUST use the session for all communication with SAL or retrieving SAL
 125      * infrastructure services.
 126      *
 127      * This method is invoked by {@link BindingAwareBroker#registerProvider(BindingAwareProvider)}
 128      *
 129      * @param session Unique session between consumer and SAL.
 130      */
 131     void onSessionInitiated(ProviderContext session);
 132 }