Deprecate old MD-SAL APIs for removal
[controller.git] / opendaylight / md-sal / sal-binding-api / src / main / java / org / opendaylight / controller / sal / binding / api / BindingAwareConsumer.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.ConsumerContext;
11
12 /**
13  * A developer implemented component that gets registered with the Broker.
14  *
15  * <p>
16  * Semantically, a consumer may:
17  *
18  * <ol>
19  *   <li>Subscribe for Notifications </li>
20  *   <li>Invoke RPCs</li>
21  *   <li>Read from either the operational or config data tree</li>
22  *   <li>Write to the config data tree</li>
23  * </ol>
24  * If you need to:
25  * <ol>
26  *   <li> Emit Notifications</li>
27  *   <li> Provide the implementation of RPCs </li>
28  *   <li> Write to the operational data tree </li>
29  * </ol>
30  *
31  * <p>
32  * Consider using a BindingAwareProvider
33  *
34  * <p>
35  * Examples:
36  *
37  * <p>
38  * To get a NotificationService:
39  *
40  * <p>
41  * {code
42  * public void onSessionInitiated(ProviderContext session) {
43  *      NotificationProviderService notificationService = session.getSALService(NotificationProviderService.class);
44  *      notificationService.publish(notification)
45  * }
46  * where notification is an instance of a modeled Notification.
47  * For more information on sending notifications via the NotificationProviderService
48  * see org.opendaylight.controller.sal.binding.api.NotificationProviderService
49  *
50  * <p>
51  * A consumer can *invoke* and RPC ( ie, call foo(fooArgs)) but it cannot register an RPC
52  * implementation with the MD-SAL that others can invoke(call).
53  * To get an invokable RPC:
54  *
55  * <p>
56  * {code
57  * public void onSessionInitiated(ProviderContext session) {
58  *    MyService rpcFlowSalService = session.getRpcService(MyService.class);
59  * }
60  *
61  * <p>
62  * Where MyService.class is a Service interface generated from a yang model with RPCs modeled in it.  The returned
63  * rpcFlowSalService can be used like any other object by invoking its methods.  Note, nothing special needs to be done
64  * for RoutedRPCs.  They just work.
65  *
66  * <p>
67  * To get a DataBroker to allow access to the data tree:
68  *
69  * <p>
70  * {code
71  * public void onSessionInitiated(final ProviderContext session) {
72  *      DataBroker databroker = session.getSALService(BindingDataBroker.class);
73  * }
74  * }
75 */
76 @Deprecated(forRemoval = true)
77 public interface BindingAwareConsumer {
78
79     /**
80      * Callback signaling initialization of the consumer session to the SAL.
81      *
82      * <p>
83      * The consumer MUST use the session for all communication with SAL or
84      * retrieving SAL infrastructure services.
85      *
86      * <p>
87      * This method is invoked by {@link BindingAwareBroker#registerConsumer(BindingAwareConsumer)}
88      *
89      * @param session
90      *            Unique session between consumer and SAL.
91      */
92     void onSessionInitialized(ConsumerContext session);
93 }

©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.