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