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