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      * @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         RpcRegistration addRpcImplementation(QName rpcType, RpcImplementation implementation)
 212                 throws IllegalArgumentException;
 213
 214         RoutedRpcRegistration addRoutedRpcImplementation(QName rpcType, RpcImplementation implementation);
 215
 216         RoutedRpcRegistration addMountedRpcImplementation(QName rpcType, RpcImplementation implementation);
 217
 218         /**
 219          * Closes a session between provider and SAL.
 220          *
 221          * <p>
 222          * The close operation unregisters a provider and remove all registered
 223          * functionality of the provider from the system.
 224          */
 225         @Override
 226         void close();
 227
 228         @Override
 229         boolean isClosed();
 230
 231         Set<QName> getSupportedRpcs();
 232
 233         ListenerRegistration<RpcRegistrationListener> addRpcRegistrationListener(RpcRegistrationListener listener);
 234     }
 235
 236     public interface RpcRegistration extends ObjectRegistration<RpcImplementation> {
 237         QName getType();
 238
 239         @Override
 240         void close();
 241     }
 242
 243     public interface RoutedRpcRegistration extends RpcRegistration, RoutedRegistration<QName, InstanceIdentifier, RpcImplementation> {
 244     }
 245 }