opendaylight/sal/yang-prototype/sal/sal-core-api/src/main/java/org/opendaylight/controller/sal/core/api/Broker.java

   1 /*\r
   2  * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.\r
   3  *\r
   4  * This program and the accompanying materials are made available under the\r
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,\r
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html\r
   7  */\r
   8 package org.opendaylight.controller.sal.core.api;\r
   9 \r
  10 import java.util.concurrent.Future;\r
  11 \r
  12 import org.opendaylight.controller.sal.core.api.data.DataBrokerService;\r
  13 import org.opendaylight.controller.sal.core.api.data.DataProviderService;\r
  14 import org.opendaylight.controller.sal.core.api.notify.NotificationProviderService;\r
  15 import org.opendaylight.controller.sal.core.api.notify.NotificationService;\r
  16 import org.opendaylight.controller.yang.common.QName;\r
  17 import org.opendaylight.controller.yang.common.RpcResult;\r
  18 import org.opendaylight.controller.yang.data.api.CompositeNode;\r
  19 \r
  20 \r
  21 /**\r
  22  * Core component of the SAL layer responsible for wiring the SAL consumers.\r
  23  * \r
  24  * The responsibility of the broker is to maintain registration of SAL\r
  25  * functionality {@link Consumer}s and {@link Provider}s, store provider and\r
  26  * consumer specific context and functionality registration via\r
  27  * {@link ConsumerSession} and provide access to infrastructure services, which\r
  28  * removes direct dependencies between providers and consumers.\r
  29  * \r
  30  * \r
  31  * <h3>Infrastructure services</h3> Some examples of infrastructure services:\r
  32  * \r
  33  * <ul>\r
  34  * <li>RPC Invocation - see {@link ConsumerSession#rpc(QName, CompositeNode)},\r
  35  * {@link ProviderSession#addRpcImplementation(QName, RpcImplementation)} and\r
  36  * {@link RpcImplementation}\r
  37  * <li>Notification Service - see {@link NotificationService} and\r
  38  * {@link NotificationProviderService}\r
  39  * <li>Functionality and Data model\r
  40  * <li>Data Store access and modification - see {@link DataBrokerService} and\r
  41  * {@link DataProviderService}\r
  42  * </ul>\r
  43  * \r
  44  * The services are exposed via session.\r
  45  * \r
  46  * <h3>Session-based access</h3>\r
  47  * \r
  48  * The providers and consumers needs to register in order to use the\r
  49  * binding-independent SAL layer and to expose functionality via SAL layer.\r
  50  * \r
  51  * For more information about session-based access see {@link ConsumerSession}\r
  52  * and {@link ProviderSession}\r
  53  * \r
  54  * \r
  55  * \r
  56  */\r
  57 public interface Broker {\r
  58 \r
  59     /**\r
  60      * Registers the {@link Consumer}, which will use the SAL layer.\r
  61      * \r
  62      * <p>\r
  63      * During the registration, the broker obtains the initial functionality\r
  64      * from consumer, using the {@link Consumer#getConsumerFunctionality()}, and\r
  65      * register that functionality into system and concrete infrastructure\r
  66      * services.\r
  67      * \r
  68      * <p>\r
  69      * Note that consumer could register additional functionality at later point\r
  70      * by using service and functionality specific APIs.\r
  71      * \r
  72      * <p>\r
  73      * The consumer is required to use returned session for all communication\r
  74      * with broker or one of the broker services. The session is announced to\r
  75      * the consumer by invoking\r
  76      * {@link Consumer#onSessionInitiated(ConsumerSession)}.\r
  77      * \r
  78      * @param cons\r
  79      *            Consumer to be registered.\r
  80      * @return a session specific to consumer registration\r
  81      * @throws IllegalArgumentException\r
  82      *             If the consumer is <code>null</code>.\r
  83      * @throws IllegalStateException\r
  84      *             If the consumer is already registered.\r
  85      */\r
  86     ConsumerSession registerConsumer(Consumer cons);\r
  87 \r
  88     /**\r
  89      * Registers the {@link Provider}, which will use the SAL layer.\r
  90      * \r
  91      * <p>\r
  92      * During the registration, the broker obtains the initial functionality\r
  93      * from consumer, using the {@link Provider#getProviderFunctionality()}, and\r
  94      * register that functionality into system and concrete infrastructure\r
  95      * services.\r
  96      * \r
  97      * <p>\r
  98      * Note that consumer could register additional functionality at later point\r
  99      * by using service and functionality specific APIs (e.g.\r
 100      * {@link ProviderSession#addRpcImplementation(QName, RpcImplementation)}\r
 101      * \r
 102      * <p>\r
 103      * The consumer is <b>required to use</b> returned session for all\r
 104      * communication with broker or one of the broker services. The session is\r
 105      * announced to the consumer by invoking\r
 106      * {@link Provider#onSessionInitiated(ProviderSession)}.\r
 107      * \r
 108      * \r
 109      * @param prov\r
 110      *            Provider to be registered.\r
 111      * @return a session unique to the provider registration.\r
 112      * @throws IllegalArgumentException\r
 113      *             If the provider is <code>null</code>.\r
 114      * @throws IllegalStateException\r
 115      *             If the consumer is already registered.\r
 116      */\r
 117     ProviderSession registerProvider(Provider prov);\r
 118 \r
 119     /**\r
 120      * {@link Consumer} specific access to the SAL functionality.\r
 121      * \r
 122      * <p>\r
 123      * ConsumerSession is {@link Consumer}-specific access to the SAL\r
 124      * functionality and infrastructure services.\r
 125      * \r
 126      * <p>\r
 127      * The session serves to store SAL context (e.g. registration of\r
 128      * functionality) for the consumer and provides access to the SAL\r
 129      * infrastructure services and other functionality provided by\r
 130      * {@link Provider}s.\r
 131      * \r
 132 \r
 133      * \r
 134      */\r
 135     public interface ConsumerSession {\r
 136 \r
 137         /**\r
 138          * Sends an RPC to other components registered to the broker.\r
 139          * \r
 140          * @see RpcImplementation\r
 141          * @param rpc\r
 142          *            Name of RPC\r
 143          * @param input\r
 144          *            Input data to the RPC\r
 145          * @return Result of the RPC call\r
 146          */\r
 147         Future<RpcResult<CompositeNode>> rpc(QName rpc, CompositeNode input);\r
 148 \r
 149         /**\r
 150          * Returns a session specific instance (implementation) of requested\r
 151          * service\r
 152          * \r
 153          * @param service\r
 154          *            Broker service\r
 155          * @return Session specific implementation of service\r
 156          */\r
 157         <T extends BrokerService> T getService(Class<T> service);\r
 158 \r
 159         /**\r
 160          * Closes a session between consumer and broker.\r
 161          * \r
 162          * <p>\r
 163          * The close operation unregisters a consumer and remove all registered\r
 164          * functionality of the consumer from the system.\r
 165          * \r
 166          */\r
 167         void close();\r
 168     }\r
 169 \r
 170     /**\r
 171      * {@link Provider} specific access to the SAL functionality.\r
 172      * \r
 173      * <p>\r
 174      * ProviderSession is {@link Provider}-specific access to the SAL\r
 175      * functionality and infrastructure services, which also allows for exposing\r
 176      * the provider's functionality to the other {@link Consumer}s.\r
 177      * \r
 178      * <p>\r
 179      * The session serves to store SAL context (e.g. registration of\r
 180      * functionality) for the providers and exposes access to the SAL\r
 181      * infrastructure services, dynamic functionality registration and any other\r
 182      * functionality provided by other {@link Provider}s.\r
 183      * \r
 184      */\r
 185     public interface ProviderSession extends ConsumerSession {\r
 186         /**\r
 187          * Registers an implementation of the rpc.\r
 188          * \r
 189          * <p>\r
 190          * The registered rpc functionality will be available to all other\r
 191          * consumers and providers registered to the broker, which are aware of\r
 192          * the {@link QName} assigned to the rpc.\r
 193          * \r
 194          * <p>\r
 195          * There is no assumption that rpc type is in the set returned by\r
 196          * invoking {@link RpcImplementation#getSupportedRpcs()}. This allows\r
 197          * for dynamic rpc implementations.\r
 198          * \r
 199          * @param rpcType\r
 200          *            Name of Rpc\r
 201          * @param implementation\r
 202          *            Provider's Implementation of the RPC functionality\r
 203          * @throws IllegalArgumentException\r
 204          *             If the name of RPC is invalid\r
 205          */\r
 206         void addRpcImplementation(QName rpcType,\r
 207                 RpcImplementation implementation)\r
 208                 throws IllegalArgumentException;\r
 209 \r
 210         /**\r
 211          * Unregisters an Rpc implementation\r
 212          * \r
 213          * @param rpcType\r
 214          *            Name of Rpc\r
 215          * @param implementation\r
 216          *            Registered Implementation of the Rpc functionality\r
 217          * @throws IllegalArgumentException\r
 218          */\r
 219         void removeRpcImplementation(QName rpcType,\r
 220                 RpcImplementation implementation)\r
 221                 throws IllegalArgumentException;\r
 222 \r
 223         /**\r
 224          * Closes a session between provider and SAL.\r
 225          * \r
 226          * <p>\r
 227          * The close operation unregisters a provider and remove all registered\r
 228          * functionality of the provider from the system.\r
 229          */\r
 230         @Override\r
 231         public void close();\r
 232     }\r
 233 }\r