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