dom/mdsal-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      * Note that consumer could register additional functionality at later point
  42      * by using service and functionality specific APIs.
  43      *
  44      * <p>
  45      * The consumer is required to use returned session for all communication
  46      * with broker or one of the broker services. The session is announced to
  47      * the consumer by invoking
  48      * {@link Consumer#onSessionInitiated(ConsumerSession)}.
  49      *
  50      * @param cons
  51      *            Consumer to be registered.
  52      * @return a session specific to consumer registration
  53      * @throws IllegalArgumentException
  54      *             If the consumer is <code>null</code>.
  55      * @throws IllegalStateException
  56      *             If the consumer is already registered.
  57      */
  58     ConsumerSession registerConsumer(Consumer cons);
  59
  60     /*
  61      * @deprecated Use registerConsumer(Consumer cons) instead (BundleContext is no longer used)
  62      */
  63     @Deprecated
  64     ConsumerSession registerConsumer(Consumer cons, BundleContext context);
  65
  66     /**
  67      * Registers the {@link Provider}, which will use the SAL layer.
  68      *
  69      * <p>
  70      * The consumer is <b>required to use</b> returned session for all
  71      * communication with broker or one of the broker services. The session is
  72      * announced to the consumer by invoking
  73      * {@link Provider#onSessionInitiated(ProviderSession)}.
  74      *
  75      *
  76      * @param prov
  77      *            Provider to be registered.
  78      * @return a session unique to the provider registration.
  79      * @throws IllegalArgumentException
  80      *             If the provider is <code>null</code>.
  81      * @throws IllegalStateException
  82      *             If the consumer is already registered.
  83      */
  84     ProviderSession registerProvider(Provider prov);
  85
  86     /*
  87      * @deprecated Use registerProvider(Provider cons) instead (BundleContext is no longer used)
  88      */
  89     @Deprecated
  90     ProviderSession registerProvider(Provider prov, BundleContext context);
  91
  92     /**
  93      * {@link Consumer} specific access to the SAL functionality.
  94      *
  95      * <p>
  96      * ConsumerSession is {@link Consumer}-specific access to the SAL
  97      * functionality and infrastructure services.
  98      *
  99      * <p>
 100      * The session serves to store SAL context (e.g. registration of
 101      * functionality) for the consumer and provides access to the SAL
 102      * infrastructure services and other functionality provided by
 103      * {@link Provider}s.
 104      *
 105      *
 106      *
 107      */
 108     public interface ConsumerSession {
 109
 110         boolean isClosed();
 111
 112         /**
 113          * Returns a session specific instance (implementation) of requested
 114          * service
 115          *
 116          * @param service
 117          *            Broker service
 118          * @return Session specific implementation of service
 119          */
 120         <T extends BrokerService> T getService(Class<T> service);
 121
 122         /**
 123          * Closes a session between consumer and broker.
 124          *
 125          * <p>
 126          * The close operation unregisters a consumer and remove all registered
 127          * functionality of the consumer from the system.
 128          *
 129          */
 130         void close();
 131     }
 132
 133     /**
 134      * {@link Provider} specific access to the SAL functionality.
 135      *
 136      * <p>
 137      * ProviderSession is {@link Provider}-specific access to the SAL
 138      * functionality and infrastructure services, which also allows for exposing
 139      * the provider's functionality to the other {@link Consumer}s.
 140      *
 141      * <p>
 142      * The session serves to store SAL context (e.g. registration of
 143      * functionality) for the providers and exposes access to the SAL
 144      * infrastructure services, dynamic functionality registration and any other
 145      * functionality provided by other {@link Provider}s.
 146      *
 147      */
 148     public interface ProviderSession extends ConsumerSession {
 149         /**
 150          * Closes a session between provider and SAL.
 151          *
 152          * <p>
 153          * The close operation unregisters a provider and remove all registered
 154          * functionality of the provider from the system.
 155          */
 156         @Override
 157         void close();
 158
 159         @Override
 160         boolean isClosed();
 161     }
 162 }