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