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.md.sal.common.api.routing.RoutedRegistration;
  11 import org.opendaylight.yangtools.concepts.ObjectRegistration;
  12 import org.opendaylight.yangtools.yang.binding.BaseIdentity;
  13 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  14 import org.opendaylight.yangtools.yang.binding.RpcService;
  15 import org.osgi.framework.BundleContext;
  16
  17 /**
  18  * Binding-aware core of the SAL layer responsible for wiring the SAL consumers.
  19  *
  20  * <p>
  21  * The responsibility of the broker is to maintain registration of SAL
  22  * functionality Consumers and Providers, 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  * <p>
  28  * The Binding-aware broker is also responsible for translation from Java
  29  * classes modeling the functionality and data to binding-independent form which
  30  * is used in SAL Core.
  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  * </ul>
  40  *
  41  * <p>
  42  * The services are exposed via session.
  43  *
  44  * <h3>Session-based access</h3>
  45  *
  46  * <p>
  47  * The providers and consumers needs to register in order to use the
  48  * binding-independent SAL layer and to expose functionality via SAL layer.
  49  *
  50  * <p>
  51  * For more information about session-based access see {@link ConsumerContext}
  52  * and {@link ProviderContext}
  53  */
  54 public interface BindingAwareBroker {
  55     /*
  56      * @deprecated Use registerConsumer(BindingAwareConsumer cons) instead (BundleContext is no longer used)
  57      */
  58     @Deprecated
  59     ConsumerContext registerConsumer(BindingAwareConsumer consumer, BundleContext ctx);
  60
  61     /**
  62      * Registers the {@link BindingAwareConsumer}, which will use the SAL layer.
  63      *
  64      * <p>
  65      * Note that consumer could register additional functionality at later point
  66      * by using service and functionality specific APIs.
  67      *
  68      * <p>
  69      * The consumer is required to use returned session for all communication
  70      * with broker or one of the broker services. The session is announced to
  71      * the consumer by invoking
  72      * {@link BindingAwareConsumer#onSessionInitialized(ConsumerContext)}.
  73      *
  74      * @param consumer
  75      *            Consumer to be registered.
  76      * @return a session specific to consumer registration
  77      * @throws IllegalArgumentException
  78      *             If the consumer is <code>null</code>.
  79      * @throws IllegalStateException
  80      *             If the consumer is already registered.
  81      */
  82     ConsumerContext registerConsumer(BindingAwareConsumer consumer);
  83
  84     /*
  85      * @deprecated Use registerProvider(BindingAwareProvider prov) instead (BundleContext is no longer used)
  86      */
  87     @Deprecated
  88     ProviderContext registerProvider(BindingAwareProvider provider, BundleContext ctx);
  89
  90     /**
  91      * Registers the {@link BindingAwareProvider}, which will use the SAL layer.
  92      *
  93      * <p>
  94      * During the registration, the broker obtains the initial functionality
  95      * from consumer, using the
  96      * BindingAwareProvider#getImplementations(), and register that
  97      * functionality into system and concrete infrastructure services.
  98      *
  99      * <p>
 100      * Note that provider could register additional functionality at later point
 101      * by using service and functionality specific APIs.
 102      *
 103      * <p>
 104      * The consumer is <b>required to use</b> returned session for all
 105      * communication with broker or one of the broker services. The session is
 106      * announced to the consumer by invoking
 107      * {@link BindingAwareProvider#onSessionInitiated(ProviderContext)}.
 108      *
 109      *
 110      * @param provider
 111      *            Provider to be registered.
 112      * @return a session unique to the provider registration.
 113      * @throws IllegalArgumentException
 114      *             If the provider is <code>null</code>.
 115      * @throws IllegalStateException
 116      *             If the consumer is already registered.
 117      */
 118     ProviderContext registerProvider(BindingAwareProvider provider);
 119
 120     /**
 121      * {@link BindingAwareConsumer} specific access to the SAL functionality.
 122      *
 123      * <p>
 124      * ConsumerSession is {@link BindingAwareConsumer}-specific access to the
 125      * SAL functionality and infrastructure services.
 126      *
 127      * <p>
 128      * The session serves to store SAL context (e.g. registration of
 129      * functionality) for the consumer and provides access to the SAL
 130      * infrastructure services and other functionality provided by
 131      * {@link BindingAwareProvider}s.
 132      */
 133     interface ConsumerContext extends RpcConsumerRegistry {
 134
 135         /**
 136          * Returns a session specific instance (implementation) of requested binding-aware infrastructure service.
 137          *
 138          * @param service
 139          *            Broker service
 140          * @return Session specific implementation of service
 141          */
 142         <T extends BindingAwareService> T getSALService(Class<T> service);
 143     }
 144
 145     /**
 146      * {@link BindingAwareProvider} specific access to the SAL functionality.
 147      *
 148      * <p>
 149      * ProviderSession is {@link BindingAwareProvider}-specific access to the
 150      * SAL functionality and infrastructure services, which also allows for
 151      * exposing the provider's functionality to the other
 152      * {@link BindingAwareConsumer}s.
 153      *
 154      * <p>
 155      * The session serves to store SAL context (e.g. registration of
 156      * functionality) for the providers and exposes access to the SAL
 157      * infrastructure services, dynamic functionality registration and any other
 158      * functionality provided by other {@link BindingAwareConsumer}s.
 159      *
 160      */
 161     interface ProviderContext extends ConsumerContext, RpcProviderRegistry {
 162
 163     }
 164
 165     /**
 166      * Represents an RPC implementation registration. Users should call the
 167      * {@link ObjectRegistration#close close} method when the registration is no longer needed.
 168      *
 169      * @param <T> the implemented RPC service interface
 170      */
 171     interface RpcRegistration<T extends RpcService> extends ObjectRegistration<T> {
 172
 173         /**
 174          * Returns the implemented RPC service interface.
 175          */
 176         Class<T> getServiceType();
 177
 178         @Override
 179         void close();
 180     }
 181
 182     /**
 183      * Represents a routed RPC implementation registration. Users should call the
 184      * {@link RoutedRegistration#close close} method when the registration is no longer needed.
 185      *
 186      * @param <T> the implemented RPC service interface
 187      */
 188     interface RoutedRpcRegistration<T extends RpcService> extends RpcRegistration<T>,
 189             RoutedRegistration<Class<? extends BaseIdentity>, InstanceIdentifier<?>, T> {
 190
 191         /**
 192          * Register particular instance identifier to be processed by this RpcService.
 193          *
 194          * @deprecated in favor of RoutedRegistration#registerPath(Object, Object).
 195          */
 196         @Deprecated
 197         void registerInstance(Class<? extends BaseIdentity> context, InstanceIdentifier<?> instance);
 198
 199         /**
 200          * Unregister particular instance identifier to be processed by this RpcService.
 201          *
 202          * @deprecated in favor of RoutedRegistration#unregisterPath(Class, InstanceIdentifier).
 203          */
 204         @Deprecated
 205         void unregisterInstance(Class<? extends BaseIdentity> context, InstanceIdentifier<?> instance);
 206     }
 207 }