2 * Copyright (c) 2013 Cisco Systems, Inc. and others. All rights reserved.
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
8 package org.opendaylight.controller.sal.core.api;
11 import java.util.concurrent.Future;
13 import org.opendaylight.controller.md.sal.common.api.routing.RoutedRegistration;
14 import org.opendaylight.controller.sal.core.api.data.DataBrokerService;
15 import org.opendaylight.controller.sal.core.api.data.DataProviderService;
16 import org.opendaylight.controller.sal.core.api.notify.NotificationPublishService;
17 import org.opendaylight.controller.sal.core.api.notify.NotificationService;
18 import org.opendaylight.yangtools.concepts.ListenerRegistration;
19 import org.opendaylight.yangtools.concepts.ObjectRegistration;
20 import org.opendaylight.yangtools.yang.common.QName;
21 import org.opendaylight.yangtools.yang.common.RpcResult;
22 import org.opendaylight.yangtools.yang.data.api.CompositeNode;
23 import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier;
24 import org.osgi.framework.BundleContext;
27 * Core component of the SAL layer responsible for wiring the SAL consumers.
29 * The responsibility of the broker is to maintain registration of SAL
30 * functionality {@link Consumer}s and {@link Provider}s, store provider and
31 * consumer specific context and functionality registration via
32 * {@link ConsumerSession} and provide access to infrastructure services, which
33 * removes direct dependencies between providers and consumers.
36 * <h3>Infrastructure services</h3> Some examples of infrastructure services:
39 * <li>RPC Invocation - see {@link ConsumerSession#rpc(QName, CompositeNode)},
40 * {@link ProviderSession#addRpcImplementation(QName, RpcImplementation)} and
41 * {@link RpcImplementation}
42 * <li>Notification Service - see {@link NotificationService} and
43 * {@link NotificationPublishService}
44 * <li>Functionality and Data model
45 * <li>Data Store access and modification - see {@link DataBrokerService} and
46 * {@link DataProviderService}
49 * The services are exposed via session.
51 * <h3>Session-based access</h3>
53 * The providers and consumers needs to register in order to use the
54 * binding-independent SAL layer and to expose functionality via SAL layer.
56 * For more information about session-based access see {@link ConsumerSession}
57 * and {@link ProviderSession}
62 public interface Broker {
65 * Registers the {@link Consumer}, which will use the SAL layer.
68 * During the registration, the broker obtains the initial functionality
69 * from consumer, using the {@link Consumer#getConsumerFunctionality()}, and
70 * register that functionality into system and concrete infrastructure
74 * Note that consumer could register additional functionality at later point
75 * by using service and functionality specific APIs.
78 * The consumer is required to use returned session for all communication
79 * with broker or one of the broker services. The session is announced to
80 * the consumer by invoking
81 * {@link Consumer#onSessionInitiated(ConsumerSession)}.
84 * Consumer to be registered.
86 * @return a session specific to consumer registration
87 * @throws IllegalArgumentException
88 * If the consumer is <code>null</code>.
89 * @throws IllegalStateException
90 * If the consumer is already registered.
92 ConsumerSession registerConsumer(Consumer cons, BundleContext context);
95 * Registers the {@link Provider}, which will use the SAL layer.
98 * During the registration, the broker obtains the initial functionality
99 * from consumer, using the {@link Provider#getProviderFunctionality()}, and
100 * register that functionality into system and concrete infrastructure
104 * Note that consumer could register additional functionality at later point
105 * by using service and functionality specific APIs (e.g.
106 * {@link ProviderSession#addRpcImplementation(QName, RpcImplementation)}
109 * The consumer is <b>required to use</b> returned session for all
110 * communication with broker or one of the broker services. The session is
111 * announced to the consumer by invoking
112 * {@link Provider#onSessionInitiated(ProviderSession)}.
116 * 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.
124 ProviderSession registerProvider(Provider prov, BundleContext context);
127 * {@link Consumer} specific access to the SAL functionality.
130 * ConsumerSession is {@link Consumer}-specific access to the SAL
131 * functionality and infrastructure services.
134 * The session serves to store SAL context (e.g. registration of
135 * functionality) for the consumer and provides access to the SAL
136 * infrastructure services and other functionality provided by
142 public interface ConsumerSession {
145 * Sends an RPC to other components registered to the broker.
147 * @see RpcImplementation
151 * Input data to the RPC
152 * @return Result of the RPC call
154 Future<RpcResult<CompositeNode>> rpc(QName rpc, CompositeNode input);
159 * Returns a session specific instance (implementation) of requested
164 * @return Session specific implementation of service
166 <T extends BrokerService> T getService(Class<T> service);
169 * Closes a session between consumer and broker.
172 * The close operation unregisters a consumer and remove all registered
173 * functionality of the consumer from the system.
180 * {@link Provider} specific access to the SAL functionality.
183 * ProviderSession is {@link Provider}-specific access to the SAL
184 * functionality and infrastructure services, which also allows for exposing
185 * the provider's functionality to the other {@link Consumer}s.
188 * The session serves to store SAL context (e.g. registration of
189 * functionality) for the providers and exposes access to the SAL
190 * infrastructure services, dynamic functionality registration and any other
191 * functionality provided by other {@link Provider}s.
194 public interface ProviderSession extends ConsumerSession {
196 * Registers an implementation of the rpc.
199 * The registered rpc functionality will be available to all other
200 * consumers and providers registered to the broker, which are aware of
201 * the {@link QName} assigned to the rpc.
204 * There is no assumption that rpc type is in the set returned by
205 * invoking {@link RpcImplementation#getSupportedRpcs()}. This allows
206 * for dynamic rpc implementations.
210 * @param implementation
211 * Provider's Implementation of the RPC functionality
212 * @throws IllegalArgumentException
213 * If the name of RPC is invalid
215 RpcRegistration addRpcImplementation(QName rpcType, RpcImplementation implementation)
216 throws IllegalArgumentException;
218 RoutedRpcRegistration addRoutedRpcImplementation(QName rpcType, RpcImplementation implementation);
220 RoutedRpcRegistration addMountedRpcImplementation(QName rpcType, RpcImplementation implementation);
223 * Closes a session between provider and SAL.
226 * The close operation unregisters a provider and remove all registered
227 * functionality of the provider from the system.
235 Set<QName> getSupportedRpcs();
237 ListenerRegistration<RpcRegistrationListener> addRpcRegistrationListener(RpcRegistrationListener listener);
240 public interface RpcRegistration extends ObjectRegistration<RpcImplementation> {
247 public interface RoutedRpcRegistration extends RpcRegistration,
248 RoutedRegistration<QName, InstanceIdentifier, RpcImplementation> {