Merge "Remove unused class member SAVE"
[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.concurrent.Future;
11
12 import org.opendaylight.controller.sal.core.api.data.DataBrokerService;
13 import org.opendaylight.controller.sal.core.api.data.DataProviderService;
14 import org.opendaylight.controller.sal.core.api.notify.NotificationProviderService;
15 import org.opendaylight.controller.sal.core.api.notify.NotificationService;
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.osgi.framework.BundleContext;
20
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 NotificationService} and
39  * {@link NotificationProviderService}
40  * <li>Functionality and Data model
41  * <li>Data Store access and modification - see {@link DataBrokerService} and
42  * {@link 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      * @param context 
82      * @return a session specific to consumer registration
83      * @throws IllegalArgumentException
84      *             If the consumer is <code>null</code>.
85      * @throws IllegalStateException
86      *             If the consumer is already registered.
87      */
88     ConsumerSession registerConsumer(Consumer cons, BundleContext context);
89
90     /**
91      * Registers the {@link Provider}, which will use the SAL layer.
92      * 
93      * <p>
94      * During the registration, the broker obtains the initial functionality
95      * from consumer, using the {@link Provider#getProviderFunctionality()}, and
96      * register that functionality into system and concrete infrastructure
97      * services.
98      * 
99      * <p>
100      * Note that consumer could register additional functionality at later point
101      * by using service and functionality specific APIs (e.g.
102      * {@link ProviderSession#addRpcImplementation(QName, RpcImplementation)}
103      * 
104      * <p>
105      * The consumer is <b>required to use</b> returned session for all
106      * communication with broker or one of the broker services. The session is
107      * announced to the consumer by invoking
108      * {@link Provider#onSessionInitiated(ProviderSession)}.
109      * 
110      * 
111      * @param prov
112      *            Provider to be registered.
113      * @param context 
114      * @return a session unique to the provider registration.
115      * @throws IllegalArgumentException
116      *             If the provider is <code>null</code>.
117      * @throws IllegalStateException
118      *             If the consumer is already registered.
119      */
120     ProviderSession registerProvider(Provider prov, BundleContext context);
121
122     /**
123      * {@link Consumer} specific access to the SAL functionality.
124      * 
125      * <p>
126      * ConsumerSession is {@link Consumer}-specific access to the SAL
127      * functionality and infrastructure services.
128      * 
129      * <p>
130      * The session serves to store SAL context (e.g. registration of
131      * functionality) for the consumer and provides access to the SAL
132      * infrastructure services and other functionality provided by
133      * {@link Provider}s.
134      * 
135
136      * 
137      */
138     public interface ConsumerSession {
139
140         /**
141          * Sends an RPC to other components registered to the broker.
142          * 
143          * @see RpcImplementation
144          * @param rpc
145          *            Name of RPC
146          * @param input
147          *            Input data to the RPC
148          * @return Result of the RPC call
149          */
150         Future<RpcResult<CompositeNode>> rpc(QName rpc, CompositeNode input);
151
152         boolean isClosed();
153
154         /**
155          * Returns a session specific instance (implementation) of requested
156          * service
157          * 
158          * @param service
159          *            Broker service
160          * @return Session specific implementation of service
161          */
162         <T extends BrokerService> T getService(Class<T> service);
163
164         /**
165          * Closes a session between consumer and broker.
166          * 
167          * <p>
168          * The close operation unregisters a consumer and remove all registered
169          * functionality of the consumer from the system.
170          * 
171          */
172         void close();
173     }
174
175     /**
176      * {@link Provider} specific access to the SAL functionality.
177      * 
178      * <p>
179      * ProviderSession is {@link Provider}-specific access to the SAL
180      * functionality and infrastructure services, which also allows for exposing
181      * the provider's functionality to the other {@link Consumer}s.
182      * 
183      * <p>
184      * The session serves to store SAL context (e.g. registration of
185      * functionality) for the providers and exposes access to the SAL
186      * infrastructure services, dynamic functionality registration and any other
187      * functionality provided by other {@link Provider}s.
188      * 
189      */
190     public interface ProviderSession extends ConsumerSession {
191         /**
192          * Registers an implementation of the rpc.
193          * 
194          * <p>
195          * The registered rpc functionality will be available to all other
196          * consumers and providers registered to the broker, which are aware of
197          * the {@link QName} assigned to the rpc.
198          * 
199          * <p>
200          * There is no assumption that rpc type is in the set returned by
201          * invoking {@link RpcImplementation#getSupportedRpcs()}. This allows
202          * for dynamic rpc implementations.
203          * 
204          * @param rpcType
205          *            Name of Rpc
206          * @param implementation
207          *            Provider's Implementation of the RPC functionality
208          * @throws IllegalArgumentException
209          *             If the name of RPC is invalid
210          */
211         void addRpcImplementation(QName rpcType,
212                 RpcImplementation implementation)
213                 throws IllegalArgumentException;
214
215         /**
216          * Unregisters an Rpc implementation
217          * 
218          * @param rpcType
219          *            Name of Rpc
220          * @param implementation
221          *            Registered Implementation of the Rpc functionality
222          * @throws IllegalArgumentException
223          */
224         void removeRpcImplementation(QName rpcType,
225                 RpcImplementation implementation)
226                 throws IllegalArgumentException;
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         public void close();
237
238         @Override
239         boolean isClosed();
240     }
241 }