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;
10 import java.util.concurrent.Future;
12 import org.opendaylight.controller.md.sal.common.api.routing.RoutedRegistration;
13 import org.opendaylight.controller.sal.core.api.data.DataBrokerService;
14 import org.opendaylight.controller.sal.core.api.data.DataProviderService;
15 import org.opendaylight.controller.sal.core.api.notify.NotificationPublishService;
16 import org.opendaylight.controller.sal.core.api.notify.NotificationService;
17 import org.opendaylight.yangtools.concepts.Registration;
18 import org.opendaylight.yangtools.yang.common.QName;
19 import org.opendaylight.yangtools.yang.common.RpcResult;
20 import org.opendaylight.yangtools.yang.data.api.CompositeNode;
21 import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier;
22 import org.osgi.framework.BundleContext;
25 * Core component of the SAL layer responsible for wiring the SAL consumers.
27 * The responsibility of the broker is to maintain registration of SAL
28 * functionality {@link Consumer}s and {@link Provider}s, store provider and
29 * consumer specific context and functionality registration via
30 * {@link ConsumerSession} and provide access to infrastructure services, which
31 * removes direct dependencies between providers and consumers.
34 * <h3>Infrastructure services</h3> Some examples of infrastructure services:
37 * <li>RPC Invocation - see {@link ConsumerSession#rpc(QName, CompositeNode)},
38 * {@link ProviderSession#addRpcImplementation(QName, RpcImplementation)} and
39 * {@link RpcImplementation}
40 * <li>Notification Service - see {@link NotificationService} and
41 * {@link NotificationPublishService}
42 * <li>Functionality and Data model
43 * <li>Data Store access and modification - see {@link DataBrokerService} and
44 * {@link DataProviderService}
47 * The services are exposed via session.
49 * <h3>Session-based access</h3>
51 * The providers and consumers needs to register in order to use the
52 * binding-independent SAL layer and to expose functionality via SAL layer.
54 * For more information about session-based access see {@link ConsumerSession}
55 * and {@link ProviderSession}
60 public interface Broker {
63 * Registers the {@link Consumer}, which will use the SAL layer.
66 * During the registration, the broker obtains the initial functionality
67 * from consumer, using the {@link Consumer#getConsumerFunctionality()}, and
68 * register that functionality into system and concrete infrastructure
72 * Note that consumer could register additional functionality at later point
73 * by using service and functionality specific APIs.
76 * The consumer is required to use returned session for all communication
77 * with broker or one of the broker services. The session is announced to
78 * the consumer by invoking
79 * {@link Consumer#onSessionInitiated(ConsumerSession)}.
82 * Consumer to be registered.
84 * @return a session specific to consumer registration
85 * @throws IllegalArgumentException
86 * If the consumer is <code>null</code>.
87 * @throws IllegalStateException
88 * If the consumer is already registered.
90 ConsumerSession registerConsumer(Consumer cons, BundleContext context);
93 * Registers the {@link Provider}, which will use the SAL layer.
96 * During the registration, the broker obtains the initial functionality
97 * from consumer, using the {@link Provider#getProviderFunctionality()}, and
98 * register that functionality into system and concrete infrastructure
102 * Note that consumer could register additional functionality at later point
103 * by using service and functionality specific APIs (e.g.
104 * {@link ProviderSession#addRpcImplementation(QName, RpcImplementation)}
107 * The consumer is <b>required to use</b> returned session for all
108 * communication with broker or one of the broker services. The session is
109 * announced to the consumer by invoking
110 * {@link Provider#onSessionInitiated(ProviderSession)}.
114 * Provider to be registered.
116 * @return a session unique to the provider registration.
117 * @throws IllegalArgumentException
118 * If the provider is <code>null</code>.
119 * @throws IllegalStateException
120 * If the consumer is already registered.
122 ProviderSession registerProvider(Provider prov, BundleContext context);
125 * {@link Consumer} specific access to the SAL functionality.
128 * ConsumerSession is {@link Consumer}-specific access to the SAL
129 * functionality and infrastructure services.
132 * The session serves to store SAL context (e.g. registration of
133 * functionality) for the consumer and provides access to the SAL
134 * infrastructure services and other functionality provided by
140 public interface ConsumerSession {
143 * Sends an RPC to other components registered to the broker.
145 * @see RpcImplementation
149 * Input data to the RPC
150 * @return Result of the RPC call
152 Future<RpcResult<CompositeNode>> rpc(QName rpc, CompositeNode input);
157 * Returns a session specific instance (implementation) of requested
162 * @return Session specific implementation of service
164 <T extends BrokerService> T getService(Class<T> service);
167 * Closes a session between consumer and broker.
170 * The close operation unregisters a consumer and remove all registered
171 * functionality of the consumer from the system.
178 * {@link Provider} specific access to the SAL functionality.
181 * ProviderSession is {@link Provider}-specific access to the SAL
182 * functionality and infrastructure services, which also allows for exposing
183 * the provider's functionality to the other {@link Consumer}s.
186 * The session serves to store SAL context (e.g. registration of
187 * functionality) for the providers and exposes access to the SAL
188 * infrastructure services, dynamic functionality registration and any other
189 * functionality provided by other {@link Provider}s.
192 public interface ProviderSession extends ConsumerSession {
194 * Registers an implementation of the rpc.
197 * The registered rpc functionality will be available to all other
198 * consumers and providers registered to the broker, which are aware of
199 * the {@link QName} assigned to the rpc.
202 * There is no assumption that rpc type is in the set returned by
203 * invoking {@link RpcImplementation#getSupportedRpcs()}. This allows
204 * for dynamic rpc implementations.
208 * @param implementation
209 * Provider's Implementation of the RPC functionality
210 * @throws IllegalArgumentException
211 * If the name of RPC is invalid
213 RpcRegistration addRpcImplementation(QName rpcType, RpcImplementation implementation)
214 throws IllegalArgumentException;
216 RoutedRpcRegistration addRoutedRpcImplementation(QName rpcType, RpcImplementation implementation);
218 RoutedRpcRegistration addMountedRpcImplementation(QName rpcType, RpcImplementation implementation);
221 * Closes a session between provider and SAL.
224 * The close operation unregisters a provider and remove all registered
225 * functionality of the provider from the system.
234 public interface RpcRegistration extends Registration<RpcImplementation> {
238 public interface RoutedRpcRegistration extends RpcRegistration,
239 RoutedRegistration<QName, InstanceIdentifier, RpcImplementation> {