opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareBroker.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.binding.api;
   9
  10 import org.opendaylight.controller.sal.binding.api.BindingAwareProvider.ProviderFunctionality;
  11 import org.opendaylight.controller.sal.binding.api.data.DataBrokerService;
  12 import org.opendaylight.controller.sal.binding.api.data.DataProviderService;
  13 import org.opendaylight.yangtools.yang.binding.BaseIdentity;
  14 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  15 import org.opendaylight.yangtools.yang.binding.RpcService;
  16 import org.osgi.framework.BundleContext;
  17
  18 /**
  19  * Binding-aware core of the SAL layer responsible for wiring the SAL consumers.
  20  *
  21  * The responsibility of the broker is to maintain registration of SAL
  22  * functionality {@link Consumer}s and {@link Provider}s, store provider and
  23  * consumer specific context and functionality registration via
  24  * {@link ConsumerContext} and provide access to infrastructure services, which
  25  * removes direct dependencies between providers and consumers.
  26  *
  27  * The Binding-aware broker is also responsible for translation from Java
  28  * classes modeling the functionality and data to binding-indpenedent form which
  29  * is used in SAL Core.
  30  *
  31  *
  32  * <h3>Infrastructure services</h3> Some examples of infrastructure services:
  33  *
  34  * <ul>
  35  * <li>YANG Module service - see {@link ConsumerContext#getRpcService(Class)},
  36  * {@link ProviderContext}
  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 ConsumerContext}
  52  * and {@link ProviderContext}
  53  *
  54  *
  55  *
  56  */
  57 public interface BindingAwareBroker {
  58     /**
  59      * Registers the {@link BindingAwareConsumer}, which will use the SAL layer.
  60      *
  61      * <p>
  62      * Note that consumer could register additional functionality at later point
  63      * by using service and functionality specific APIs.
  64      *
  65      * <p>
  66      * The consumer is required to use returned session for all communication
  67      * with broker or one of the broker services. The session is announced to
  68      * the consumer by invoking
  69      * {@link Consumer#onSessionInitiated(ConsumerContext)}.
  70      *
  71      * @param cons
  72      *            Consumer to be registered.
  73      * @return a session specific to consumer registration
  74      * @throws IllegalArgumentException
  75      *             If the consumer is <code>null</code>.
  76      * @throws IllegalStateException
  77      *             If the consumer is already registered.
  78      */
  79     ConsumerContext registerConsumer(BindingAwareConsumer consumer, BundleContext ctx);
  80
  81     /**
  82      * Registers the {@link BindingAwareProvider}, which will use the SAL layer.
  83      *
  84      * <p>
  85      * During the registration, the broker obtains the initial functionality
  86      * from consumer, using the
  87      * {@link BindingAwareProvider#getImplementations()}, and register that
  88      * functionality into system and concrete infrastructure services.
  89      *
  90      * <p>
  91      * Note that provider could register additional functionality at later point
  92      * by using service and functionality specific APIs.
  93      *
  94      * <p>
  95      * The consumer is <b>required to use</b> returned session for all
  96      * communication with broker or one of the broker services. The session is
  97      * announced to the consumer by invoking
  98      * {@link BindingAwareProvider#onSessionInitiated(ProviderContext)}.
  99      *
 100      *
 101      * @param prov
 102      *            Provider to be registered.
 103      * @return a session unique to the provider registration.
 104      * @throws IllegalArgumentException
 105      *             If the provider is <code>null</code>.
 106      * @throws IllegalStateException
 107      *             If the consumer is already registered.
 108      */
 109     ProviderContext registerProvider(BindingAwareProvider provider, BundleContext ctx);
 110
 111     /**
 112      * {@link BindingAwareConsumer} specific access to the SAL functionality.
 113      *
 114      * <p>
 115      * ConsumerSession is {@link BindingAwareConsumer}-specific access to the
 116      * SAL functionality and infrastructure services.
 117      *
 118      * <p>
 119      * The session serves to store SAL context (e.g. registration of
 120      * functionality) for the consumer and provides access to the SAL
 121      * infrastructure services and other functionality provided by
 122      * {@link Provider}s.
 123      *
 124      *
 125      *
 126      */
 127     public interface ConsumerContext {
 128
 129         /**
 130          * Returns a session specific instance (implementation) of requested
 131          * binding-aware infrastructural service
 132          *
 133          * @param service
 134          *            Broker service
 135          * @return Session specific implementation of service
 136          */
 137         <T extends BindingAwareService> T getSALService(Class<T> service);
 138
 139         /**
 140          * Returns a session specific instance (implementation) of requested
 141          * YANG module implentation / service provided by consumer.
 142          *
 143          * @param service
 144          *            Broker service
 145          * @return Session specific implementation of service
 146          */
 147         <T extends RpcService> T getRpcService(Class<T> module);
 148     }
 149
 150     /**
 151      * {@link BindingAwareProvider} specific access to the SAL functionality.
 152      *
 153      * <p>
 154      * ProviderSession is {@link BindingAwareProvider}-specific access to the
 155      * SAL functionality and infrastructure services, which also allows for
 156      * exposing the provider's functionality to the other
 157      * {@link BindingAwareConsumer}s.
 158      *
 159      * <p>
 160      * The session serves to store SAL context (e.g. registration of
 161      * functionality) for the providers and exposes access to the SAL
 162      * infrastructure services, dynamic functionality registration and any other
 163      * functionality provided by other {@link BindingAwareConsumer}s.
 164      *
 165      */
 166     public interface ProviderContext extends ConsumerContext {
 167         /**
 168          * Registers an global RpcService implementation.
 169          *
 170          * @param type
 171          * @param implementation
 172          * @return
 173          */
 174         <T extends RpcService> RpcRegistration<T> addRpcImplementation(Class<T> type, T implementation)
 175                 throws IllegalStateException;
 176
 177         <T extends RpcService> RpcRegistration<T> addMountRpcImplementation(Class<T> type,
 178                 InstanceIdentifier mount, T implementation) throws IllegalStateException;
 179
 180         <T extends RpcService> RoutedRpcRegistration<T> addRoutedRpcImplementation(Class<T> type, T implementation)
 181                 throws IllegalStateException;
 182
 183         void registerFunctionality(ProviderFunctionality functionality);
 184         void unregisterFunctionality(ProviderFunctionality functionality);
 185     }
 186
 187     public interface RpcRegistration<T extends RpcService> {
 188
 189         /**
 190          *
 191          * @return instance for which registration does exists.
 192          */
 193         T getService();
 194
 195         /**
 196          * Unregister an RpcService from broker.
 197          *
 198          */
 199         void unregister();
 200     }
 201
 202     public interface RoutedRpcRegistration<T extends RpcService> extends RpcRegistration<T> {
 203
 204         /**
 205          * Register particular instance identifier to be processed by this
 206          * RpcService
 207          *
 208          * @param context
 209          * @param instance
 210          */
 211         void registerInstance(Class<? extends BaseIdentity> context, InstanceIdentifier instance);
 212
 213         void unregisterInstance(Class<? extends BaseIdentity> context, InstanceIdentifier instance);
 214     }
 215 }