opendaylight/sal/yang-prototype/sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareBroker.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.binding.api;\r
   9 \r
  10 import org.opendaylight.controller.yang.binding.RpcService;\r
  11 \r
  12 /**\r
  13  * Binding-aware core of the SAL layer responsible for wiring the SAL consumers.\r
  14  * \r
  15  * The responsibility of the broker is to maintain registration of SAL\r
  16  * functionality {@link Consumer}s and {@link Provider}s, store provider and\r
  17  * consumer specific context and functionality registration via\r
  18  * {@link ConsumerSession} and provide access to infrastructure services, which\r
  19  * removes direct dependencies between providers and consumers.\r
  20  * \r
  21  * The Binding-aware broker is also responsible for translation from Java\r
  22  * classes modeling the functionality and data to binding-indpenedent form which\r
  23  * is used in SAL Core.\r
  24  * \r
  25  * \r
  26  * <h3>Infrastructure services</h3> Some examples of infrastructure services:\r
  27  * \r
  28  * <ul>\r
  29  * <li>YANG Module service - see {@link ConsumerSession#getRpcService(Class)},\r
  30  * {@link ProviderSession}\r
  31  * <li>Notification Service - see {@link NotificationService} and\r
  32  * {@link NotificationProviderService}\r
  33  * <li>Functionality and Data model\r
  34  * <li>Data Store access and modification - see {@link DataBrokerService} and\r
  35  * {@link DataProviderService}\r
  36  * </ul>\r
  37  * \r
  38  * The services are exposed via session.\r
  39  * \r
  40  * <h3>Session-based access</h3>\r
  41  * \r
  42  * The providers and consumers needs to register in order to use the\r
  43  * binding-independent SAL layer and to expose functionality via SAL layer.\r
  44  * \r
  45  * For more information about session-based access see {@link ConsumerSession}\r
  46  * and {@link ProviderSession}\r
  47  * \r
  48  * \r
  49 \r
  50  * \r
  51  */\r
  52 public interface BindingAwareBroker {\r
  53     /**\r
  54      * Registers the {@link BindingAwareConsumer}, which will use the SAL layer.\r
  55      * \r
  56      * <p>\r
  57      * Note that consumer could register additional functionality at later point\r
  58      * by using service and functionality specific APIs.\r
  59      * \r
  60      * <p>\r
  61      * The consumer is required to use returned session for all communication\r
  62      * with broker or one of the broker services. The session is announced to\r
  63      * the consumer by invoking\r
  64      * {@link Consumer#onSessionInitiated(ConsumerSession)}.\r
  65      * \r
  66      * @param cons\r
  67      *            Consumer to be registered.\r
  68      * @return a session specific to consumer registration\r
  69      * @throws IllegalArgumentException\r
  70      *             If the consumer is <code>null</code>.\r
  71      * @throws IllegalStateException\r
  72      *             If the consumer is already registered.\r
  73      */\r
  74     ConsumerSession registerConsumer(BindingAwareConsumer consumer);\r
  75 \r
  76     /**\r
  77      * Registers the {@link BindingAwareProvider}, which will use the SAL layer.\r
  78      * \r
  79      * <p>\r
  80      * During the registration, the broker obtains the initial functionality\r
  81      * from consumer, using the\r
  82      * {@link BindingAwareProvider#getImplementations()}, and register that\r
  83      * functionality into system and concrete infrastructure services.\r
  84      * \r
  85      * <p>\r
  86      * Note that provider could register additional functionality at later point\r
  87      * by using service and functionality specific APIs.\r
  88      * \r
  89      * <p>\r
  90      * The consumer is <b>required to use</b> returned session for all\r
  91      * communication with broker or one of the broker services. The session is\r
  92      * announced to the consumer by invoking\r
  93      * {@link BindingAwareProvider#onSessionInitiated(ProviderSession)}.\r
  94      * \r
  95      * \r
  96      * @param prov\r
  97      *            Provider to be registered.\r
  98      * @return a session unique to the provider registration.\r
  99      * @throws IllegalArgumentException\r
 100      *             If the provider is <code>null</code>.\r
 101      * @throws IllegalStateException\r
 102      *             If the consumer is already registered.\r
 103      */\r
 104     ProviderSession registerProvider(BindingAwareProvider provider);\r
 105 \r
 106     /**\r
 107      * {@link BindingAwareConsumer} specific access to the SAL functionality.\r
 108      * \r
 109      * <p>\r
 110      * ConsumerSession is {@link BindingAwareConsumer}-specific access to the\r
 111      * SAL functionality and infrastructure services.\r
 112      * \r
 113      * <p>\r
 114      * The session serves to store SAL context (e.g. registration of\r
 115      * functionality) for the consumer and provides access to the SAL\r
 116      * infrastructure services and other functionality provided by\r
 117      * {@link Provider}s.\r
 118      * \r
 119 \r
 120      * \r
 121      */\r
 122     public interface ConsumerSession {\r
 123 \r
 124         /**\r
 125          * Returns a session specific instance (implementation) of requested\r
 126          * binding-aware infrastructural service\r
 127          * \r
 128          * @param service\r
 129          *            Broker service\r
 130          * @return Session specific implementation of service\r
 131          */\r
 132         <T extends BindingAwareService> T getSALService(Class<T> service);\r
 133 \r
 134         /**\r
 135          * Returns a session specific instance (implementation) of requested\r
 136          * YANG module implentation / service provided by consumer.\r
 137          * \r
 138          * @param service\r
 139          *            Broker service\r
 140          * @return Session specific implementation of service\r
 141          */\r
 142         <T extends RpcService> T getRpcService(Class<T> module);\r
 143     }\r
 144 \r
 145     /**\r
 146      * {@link BindingAwareProvider} specific access to the SAL functionality.\r
 147      * \r
 148      * <p>\r
 149      * ProviderSession is {@link BindingAwareProvider}-specific access to the\r
 150      * SAL functionality and infrastructure services, which also allows for\r
 151      * exposing the provider's functionality to the other\r
 152      * {@link BindingAwareConsumer}s.\r
 153      * \r
 154      * <p>\r
 155      * The session serves to store SAL context (e.g. registration of\r
 156      * functionality) for the providers and exposes access to the SAL\r
 157      * infrastructure services, dynamic functionality registration and any other\r
 158      * functionality provided by other {@link BindingAwareConsumer}s.\r
 159      * \r
 160      */\r
 161     public interface ProviderSession extends ConsumerSession {\r
 162 \r
 163         void addRpcImplementation(RpcService implementation);\r
 164 \r
 165         void removeRpcImplementation(RpcService implementation);\r
 166     }\r
 167 }\r
 168