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.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.Registration;
  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;
  25
  26 /**
  27  * Core component of the SAL layer responsible for wiring the SAL consumers.
  28  *
  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.
  34  *
  35  *
  36  * <h3>Infrastructure services</h3> Some examples of infrastructure services:
  37  *
  38  * <ul>
  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}
  47  * </ul>
  48  *
  49  * The services are exposed via session.
  50  *
  51  * <h3>Session-based access</h3>
  52  *
  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.
  55  *
  56  * For more information about session-based access see {@link ConsumerSession}
  57  * and {@link ProviderSession}
  58  *
  59  *
  60  *
  61  */
  62 public interface Broker {
  63
  64     /**
  65      * Registers the {@link Consumer}, which will use the SAL layer.
  66      *
  67      * <p>
  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
  71      * services.
  72      *
  73      * <p>
  74      * Note that consumer could register additional functionality at later point
  75      * by using service and functionality specific APIs.
  76      *
  77      * <p>
  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)}.
  82      *
  83      * @param cons
  84      *            Consumer to be registered.
  85      * @param context
  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.
  91      */
  92     ConsumerSession registerConsumer(Consumer cons, BundleContext context);
  93
  94     /**
  95      * Registers the {@link Provider}, which will use the SAL layer.
  96      *
  97      * <p>
  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
 101      * services.
 102      *
 103      * <p>
 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)}
 107      *
 108      * <p>
 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)}.
 113      *
 114      *
 115      * @param prov
 116      *            Provider to be registered.
 117      * @param context
 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, BundleContext context);
 125
 126     /**
 127      * {@link Consumer} specific access to the SAL functionality.
 128      *
 129      * <p>
 130      * ConsumerSession is {@link Consumer}-specific access to the SAL
 131      * functionality and infrastructure services.
 132      *
 133      * <p>
 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
 137      * {@link Provider}s.
 138      *
 139      *
 140      *
 141      */
 142     public interface ConsumerSession {
 143
 144         /**
 145          * Sends an RPC to other components registered to the broker.
 146          *
 147          * @see RpcImplementation
 148          * @param rpc
 149          *            Name of RPC
 150          * @param input
 151          *            Input data to the RPC
 152          * @return Result of the RPC call
 153          */
 154         Future<RpcResult<CompositeNode>> rpc(QName rpc, CompositeNode input);
 155
 156         boolean isClosed();
 157
 158         /**
 159          * Returns a session specific instance (implementation) of requested
 160          * service
 161          *
 162          * @param service
 163          *            Broker service
 164          * @return Session specific implementation of service
 165          */
 166         <T extends BrokerService> T getService(Class<T> service);
 167
 168         /**
 169          * Closes a session between consumer and broker.
 170          *
 171          * <p>
 172          * The close operation unregisters a consumer and remove all registered
 173          * functionality of the consumer from the system.
 174          *
 175          */
 176         void close();
 177     }
 178
 179     /**
 180      * {@link Provider} specific access to the SAL functionality.
 181      *
 182      * <p>
 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.
 186      *
 187      * <p>
 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.
 192      *
 193      */
 194     public interface ProviderSession extends ConsumerSession {
 195         /**
 196          * Registers an implementation of the rpc.
 197          *
 198          * <p>
 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.
 202          *
 203          * <p>
 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.
 207          *
 208          * @param rpcType
 209          *            Name of Rpc
 210          * @param implementation
 211          *            Provider's Implementation of the RPC functionality
 212          * @throws IllegalArgumentException
 213          *             If the name of RPC is invalid
 214          */
 215         RpcRegistration addRpcImplementation(QName rpcType, RpcImplementation implementation)
 216                 throws IllegalArgumentException;
 217
 218         RoutedRpcRegistration addRoutedRpcImplementation(QName rpcType, RpcImplementation implementation);
 219
 220         RoutedRpcRegistration addMountedRpcImplementation(QName rpcType, RpcImplementation implementation);
 221
 222         /**
 223          * Closes a session between provider and SAL.
 224          *
 225          * <p>
 226          * The close operation unregisters a provider and remove all registered
 227          * functionality of the provider from the system.
 228          */
 229         @Override
 230         public void close();
 231
 232         @Override
 233         boolean isClosed();
 234
 235         Set<QName> getSupportedRpcs();
 236
 237         ListenerRegistration<RpcRegistrationListener> addRpcRegistrationListener(RpcRegistrationListener listener);
 238     }
 239
 240     public interface RpcRegistration extends Registration<RpcImplementation> {
 241         QName getType();
 242
 243         @Override
 244         void close();
 245     }
 246
 247     public interface RoutedRpcRegistration extends RpcRegistration,
 248             RoutedRegistration<QName, InstanceIdentifier, RpcImplementation> {
 249     }
 250 }