Improve documentation of BindingAware{Provider,Consumer}
[controller.git] / opendaylight / md-sal / sal-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 java.util.Collection;
11
12 import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ConsumerContext;
13 import org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ProviderContext;
14 import org.opendaylight.yangtools.yang.binding.RpcService;
15
16 /**
17  *
18  * A developer implemented component that gets registered with the Broker.
19  *
20  * Semantically, a provider may:
21  *
22  * <ol>
23  *   <li> Emit Notifications</li>
24  *   <li> Provide the implementation of RPCs </li>
25  *   <li> Write to the operational data tree </li>
26  * </ol>
27  *
28  * If a class is not doing at least one of those three, consider using
29  * a BindingAwareConsumer instead:
30  * @see org.opendaylight.controller.sal.binding.api.BindingAwareConsumer
31  *
32  * <p>
33  *
34  *In addition, a BindingAwareProvider can in pursuit of its goals:
35  *
36  * <ol>
37  *   <li>Subscribe for Notifications </li>
38  *   <li>Invoke RPCs</li>
39  *   <li>Read from either the operational or config data tree</li>
40  *   <li>Write to the config data tree</li>
41  * </ol>
42  * (All of the above are things a Consumer can also do).
43  *
44  *<p>
45  *
46  * Examples:
47  *
48  *<p>
49  *
50  * To get a NotificationService:
51  *
52  * {code
53  * public void onSessionInitiated(ProviderContext session) {
54  *      NotificationProviderService notificationService = session.getSALService(NotificationProviderService.class);
55  * }
56  * For more information on sending notifications via the NotificationProviderService
57  * @see org.opendaylight.controller.sal.binding.api.NotificationProviderService
58  *
59  * To register an RPC implementation:
60  *
61  * {code
62  * public void onSessionInitiated(ProviderContext session) {
63  *    RpcRegistration<MyService> registration = session.addRpcImplementation(MyService.class, myImplementationInstance);
64  * }
65  *
66  * <p>
67  *
68  * Where MyService.class is a Service interface generated from a yang model with RPCs modeled in it and myImplementationInstance
69  * is an instance of a class that implements MyService.
70  *
71  * To register a Routed RPC Implementation:
72  * {code
73  * public void onSessionInitiated(ProviderContext session) {
74  *   RoutedRpcRegistration<SalFlowService> flowRegistration = session.addRoutedRpcImplementation(SalFlowService.class, salFlowServiceImplementationInstance);
75      flowRegistration.registerPath(NodeContext.class, nodeInstanceId);
76  * }
77  * }
78  *
79  * Where SalFlowService.class is a Service interface generated from a yang model with RPCs modeled in it and salFlowServiceImplementationInstance is an instance
80  * of a class that implements SalFlowService.
81  * <p>
82  * The line:
83  * {code
84  * flowRegistration.registerPath(NodeContext.class, nodeInstanceId);
85  * }
86  * Is indicating that the RPC implementation is registered to handle RPC invocations that have their NodeContext pointing to the node with instance id nodeInstanceId.
87  * 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
88  * 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
89  * 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
90  * a RoutedRPC is registered, it needs to also be able to indicate for which 'contexts' it is providing an implementation.
91  *
92  * 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
93  * it *for that node*.
94  *
95  *<p>
96  *
97  * To get a DataBroker to allow access to the data tree:
98  *
99  * {code
100  * public void onSessionInitiated(final ProviderContext session) {
101  *      DataBroker databroker = session.getSALService(BindingDataBroker.class);
102  * }
103  * }
104  * @see org.opendaylight.controller.md.sal.common.api.data.BindingDataBroker
105  * for more info on using the DataBroker.
106  *
107  */
108 public interface BindingAwareProvider {
109
110     /**
111      * @deprecated
112      *
113      * This interface was originally intended to solve problems of how to get Implementations
114      * of functionality from a provider, but that is no longer necessary because the Provider
115      * Registers RPCs in onSessionInitiated.
116      *
117      * Recommend:
118      * {code
119      * public Collection<? extends RpcService> getImplementations() {
120      *   return Collections.emptySet();
121      * }
122      * }
123      */
124     @Deprecated
125     Collection<? extends RpcService> getImplementations();
126
127     /**
128      * @deprecated
129      *
130      * This interface was originally intended to solve problems of how to get Functionality
131      *  a provider could provide, but that is no longer necessary because the Provider
132      * Registers RPCs in onSessionInitiated.
133      *
134      * Recommend:
135      * {code
136      * public Collection<? extends ProviderFunctionality> getFunctionality() {
137      *   return Collections.emptySet();
138      * }
139      * }
140      *
141      */
142     @Deprecated
143     Collection<? extends ProviderFunctionality> getFunctionality();
144
145     /**
146      * Functionality provided by the {@link BindingAwareProvider}
147      *
148      * <p>
149      * Marker interface used to mark the interfaces describing specific
150      * functionality which could be exposed by providers to other components.
151      *
152      *
153      *
154      */
155     @Deprecated
156     public interface ProviderFunctionality {
157
158     }
159     /**
160      * Callback signaling initialization of the consumer session to the SAL.
161      *
162      * The consumer MUST use the session for all communication with SAL or
163      * retrieving SAL infrastructure services.
164      *
165      * This method is invoked by
166      * {@link BindingAwareBroker#registerProvider(BindingAwareProvider)}
167      *
168      * @param session Unique session between consumer and SAL.
169      */
170     void onSessionInitiated(ProviderContext session);
171
172     /*
173      * @deprecated
174      *
175      * A provider was at one point considered an extension of a consumer, thus this
176      * call.  It is deprecated and the @see org.opendaylight.controller.sal.binding.api.BindingAwareConsumer#onSessionInitiated
177      * used, or you should simply use {@link #onSessionInitiated(ProviderContext)}
178      *
179      * Recommend:
180      * {code
181      * public final void onSessionInitialized(ConsumerContext session) {
182      *   // NOOP - as method is deprecated
183      * }
184      * }
185      */
186     @Deprecated
187     void onSessionInitialized(ConsumerContext session);
188
189 }

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.