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 }