b48f6cb61a6fd6a1c4c8555292fd0ff4a821b652
[controller.git] / opendaylight / md-sal / sal-dom-api / src / main / java / org / opendaylight / controller / sal / core / api / Broker.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.core.api;
9
10 import java.util.Set;
11 import java.util.concurrent.Future;
12
13 import org.opendaylight.controller.md.sal.common.api.routing.RoutedRegistration;
14 import org.opendaylight.yangtools.concepts.ListenerRegistration;
15 import org.opendaylight.yangtools.concepts.ObjectRegistration;
16 import org.opendaylight.yangtools.yang.common.QName;
17 import org.opendaylight.yangtools.yang.common.RpcResult;
18 import org.opendaylight.yangtools.yang.data.api.CompositeNode;
19 import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier;
20 import org.osgi.framework.BundleContext;
21
22 /**
23  * Core component of the SAL layer responsible for wiring the SAL consumers.
24  *
25  * The responsibility of the broker is to maintain registration of SAL
26  * functionality {@link Consumer}s and {@link Provider}s, store provider and
27  * consumer specific context and functionality registration via
28  * {@link ConsumerSession} and provide access to infrastructure services, which
29  * removes direct dependencies between providers and consumers.
30  *
31  *
32  * <h3>Infrastructure services</h3> Some examples of infrastructure services:
33  *
34  * <ul>
35  * <li>RPC Invocation - see {@link ConsumerSession#rpc(QName, CompositeNode)},
36  * {@link ProviderSession#addRpcImplementation(QName, RpcImplementation)} and
37  * {@link RpcImplementation}
38  * <li>Notification Service - see {@link org.opendaylight.controller.sal.core.api.notify.NotificationService} and
39  * {@link org.opendaylight.controller.sal.core.api.notify.NotificationPublishService}
40  * <li>Functionality and Data model
41  * <li>Data Store access and modification - see {@link org.opendaylight.controller.sal.core.api.data.DataBrokerService} and
42  * {@link org.opendaylight.controller.sal.core.api.data.DataProviderService}
43  * </ul>
44  *
45  * The services are exposed via session.
46  *
47  * <h3>Session-based access</h3>
48  *
49  * The providers and consumers needs to register in order to use the
50  * binding-independent SAL layer and to expose functionality via SAL layer.
51  *
52  * For more information about session-based access see {@link ConsumerSession}
53  * and {@link ProviderSession}
54  *
55  *
56  *
57  */
58 public interface Broker {
59
60     /**
61      * Registers the {@link Consumer}, which will use the SAL layer.
62      *
63      * <p>
64      * During the registration, the broker obtains the initial functionality
65      * from consumer, using the {@link Consumer#getConsumerFunctionality()}, and
66      * register that functionality into system and concrete infrastructure
67      * services.
68      *
69      * <p>
70      * Note that consumer could register additional functionality at later point
71      * by using service and functionality specific APIs.
72      *
73      * <p>
74      * The consumer is required to use returned session for all communication
75      * with broker or one of the broker services. The session is announced to
76      * the consumer by invoking
77      * {@link Consumer#onSessionInitiated(ConsumerSession)}.
78      *
79      * @param cons
80      *            Consumer to be registered.
81      * @return a session specific to consumer registration
82      * @throws IllegalArgumentException
83      *             If the consumer is <code>null</code>.
84      * @throws IllegalStateException
85      *             If the consumer is already registered.
86      */
87     ConsumerSession registerConsumer(Consumer cons);
88
89     /*
90      * @deprecated Use registerConsumer(Consumer cons) instead (BundleContext is no longer used)
91      */
92     @Deprecated
93     ConsumerSession registerConsumer(Consumer cons, BundleContext context);
94
95     /**
96      * Registers the {@link Provider}, which will use the SAL layer.
97      *
98      * <p>
99      * During the registration, the broker obtains the initial functionality
100      * from consumer, using the {@link Provider#getProviderFunctionality()}, and
101      * register that functionality into system and concrete infrastructure
102      * services.
103      *
104      * <p>
105      * Note that consumer could register additional functionality at later point
106      * by using service and functionality specific APIs (e.g.
107      * {@link ProviderSession#addRpcImplementation(QName, RpcImplementation)}
108      *
109      * <p>
110      * The consumer is <b>required to use</b> returned session for all
111      * communication with broker or one of the broker services. The session is
112      * announced to the consumer by invoking
113      * {@link Provider#onSessionInitiated(ProviderSession)}.
114      *
115      *
116      * @param prov
117      *            Provider to be registered.
118      * @return a session unique to the provider registration.
119      * @throws IllegalArgumentException
120      *             If the provider is <code>null</code>.
121      * @throws IllegalStateException
122      *             If the consumer is already registered.
123      */
124     ProviderSession registerProvider(Provider prov);
125
126     /*
127      * @deprecated Use registerProvider(Provider cons) instead (BundleContext is no longer used)
128      */
129     @Deprecated
130     ProviderSession registerProvider(Provider prov, BundleContext context);
131
132     /**
133      * {@link Consumer} specific access to the SAL functionality.
134      *
135      * <p>
136      * ConsumerSession is {@link Consumer}-specific access to the SAL
137      * functionality and infrastructure services.
138      *
139      * <p>
140      * The session serves to store SAL context (e.g. registration of
141      * functionality) for the consumer and provides access to the SAL
142      * infrastructure services and other functionality provided by
143      * {@link Provider}s.
144      *
145      *
146      *
147      */
148     public interface ConsumerSession {
149
150         /**
151          * Sends an RPC to other components registered to the broker.
152          *
153          * @see RpcImplementation
154          * @param rpc
155          *            Name of RPC
156          * @param input
157          *            Input data to the RPC
158          * @return Result of the RPC call
159          */
160         Future<RpcResult<CompositeNode>> rpc(QName rpc, CompositeNode input);
161
162         boolean isClosed();
163
164         /**
165          * Returns a session specific instance (implementation) of requested
166          * service
167          *
168          * @param service
169          *            Broker service
170          * @return Session specific implementation of service
171          */
172         <T extends BrokerService> T getService(Class<T> service);
173
174         /**
175          * Closes a session between consumer and broker.
176          *
177          * <p>
178          * The close operation unregisters a consumer and remove all registered
179          * functionality of the consumer from the system.
180          *
181          */
182         void close();
183     }
184
185     /**
186      * {@link Provider} specific access to the SAL functionality.
187      *
188      * <p>
189      * ProviderSession is {@link Provider}-specific access to the SAL
190      * functionality and infrastructure services, which also allows for exposing
191      * the provider's functionality to the other {@link Consumer}s.
192      *
193      * <p>
194      * The session serves to store SAL context (e.g. registration of
195      * functionality) for the providers and exposes access to the SAL
196      * infrastructure services, dynamic functionality registration and any other
197      * functionality provided by other {@link Provider}s.
198      *
199      */
200     public interface ProviderSession extends ConsumerSession {
201         /**
202          * Registers an implementation of the rpc.
203          *
204          * <p>
205          * The registered rpc functionality will be available to all other
206          * consumers and providers registered to the broker, which are aware of
207          * the {@link QName} assigned to the rpc.
208          *
209          * <p>
210          * There is no assumption that rpc type is in the set returned by
211          * invoking {@link RpcImplementation#getSupportedRpcs()}. This allows
212          * for dynamic rpc implementations.
213          *
214          * @param rpcType
215          *            Name of Rpc
216          * @param implementation
217          *            Provider's Implementation of the RPC functionality
218          * @throws IllegalArgumentException
219          *             If the name of RPC is invalid
220          */
221         RpcRegistration addRpcImplementation(QName rpcType, RpcImplementation implementation)
222                 throws IllegalArgumentException;
223
224         RoutedRpcRegistration addRoutedRpcImplementation(QName rpcType, RpcImplementation implementation);
225
226         RoutedRpcRegistration addMountedRpcImplementation(QName rpcType, RpcImplementation implementation);
227
228         /**
229          * Closes a session between provider and SAL.
230          *
231          * <p>
232          * The close operation unregisters a provider and remove all registered
233          * functionality of the provider from the system.
234          */
235         @Override
236         void close();
237
238         @Override
239         boolean isClosed();
240
241         Set<QName> getSupportedRpcs();
242
243         ListenerRegistration<RpcRegistrationListener> addRpcRegistrationListener(RpcRegistrationListener listener);
244     }
245
246     public interface RpcRegistration extends ObjectRegistration<RpcImplementation> {
247         QName getType();
248
249         @Override
250         void close();
251     }
252
253     public interface RoutedRpcRegistration extends RpcRegistration, RoutedRegistration<QName, InstanceIdentifier, RpcImplementation> {
254     }
255 }

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