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.controller.sal.binding.api.BindingAwareProvider.ProviderFunctionality;
  12 import org.opendaylight.yangtools.concepts.ObjectRegistration;
  13 import org.opendaylight.yangtools.yang.binding.BaseIdentity;
  14 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  15 import org.opendaylight.yangtools.yang.binding.RpcService;
  16 import org.osgi.framework.BundleContext;
  17
  18 /**
  19  * Binding-aware core of the SAL layer responsible for wiring the SAL consumers.
  20  *
  21  * The responsibility of the broker is to maintain registration of SAL
  22  * functionality {@link Consumer}s and {@link Provider}s, 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  * The Binding-aware broker is also responsible for translation from Java
  28  * classes modeling the functionality and data to binding-independent form which
  29  * is used in SAL Core.
  30  *
  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  * <li>Functionality and Data model
  40  * <li>Data Store access and modification - see {@link org.opendaylight.controller.sal.binding.api.data.DataBrokerService} and
  41  * {@link org.opendaylight.controller.sal.binding.api.data.DataProviderService}
  42  * </ul>
  43  *
  44  * The services are exposed via session.
  45  *
  46  * <h3>Session-based access</h3>
  47  *
  48  * The providers and consumers needs to register in order to use the
  49  * binding-independent SAL layer and to expose functionality via SAL layer.
  50  *
  51  * For more information about session-based access see {@link ConsumerContext}
  52  * and {@link ProviderContext}
  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     public interface ConsumerContext extends RpcConsumerRegistry {
 122
 123         /**
 124          * Returns a session specific instance (implementation) of requested
 125          * binding-aware infrastructural service
 126          *
 127          * @param service
 128          *            Broker service
 129          * @return Session specific implementation of service
 130          */
 131         <T extends BindingAwareService> T getSALService(Class<T> service);
 132     }
 133
 134     /**
 135      * {@link BindingAwareProvider} specific access to the SAL functionality.
 136      *
 137      * <p>
 138      * ProviderSession is {@link BindingAwareProvider}-specific access to the
 139      * SAL functionality and infrastructure services, which also allows for
 140      * exposing the provider's functionality to the other
 141      * {@link BindingAwareConsumer}s.
 142      *
 143      * <p>
 144      * The session serves to store SAL context (e.g. registration of
 145      * functionality) for the providers and exposes access to the SAL
 146      * infrastructure services, dynamic functionality registration and any other
 147      * functionality provided by other {@link BindingAwareConsumer}s.
 148      *
 149      */
 150     public interface ProviderContext extends ConsumerContext, RpcProviderRegistry {
 151
 152         @Deprecated
 153         void registerFunctionality(ProviderFunctionality functionality);
 154
 155         @Deprecated
 156         void unregisterFunctionality(ProviderFunctionality functionality);
 157     }
 158
 159     /**
 160      * Represents an RPC implementation registration. Users should call the
 161      * {@link ObjectRegistration#close close} method when the registration is no longer needed.
 162      *
 163      * @param <T> the implemented RPC service interface
 164      */
 165     public interface RpcRegistration<T extends RpcService> extends ObjectRegistration<T> {
 166
 167         /**
 168          * Returns the implemented RPC service interface.
 169          */
 170         Class<T> getServiceType();
 171
 172         @Override
 173         void close();
 174     }
 175
 176     /**
 177      * Represents a routed RPC implementation registration. Users should call the
 178      * {@link RoutedRegistration#close close} method when the registration is no longer needed.
 179      *
 180      * @param <T> the implemented RPC service interface
 181      */
 182     public interface RoutedRpcRegistration<T extends RpcService> extends RpcRegistration<T>,
 183             RoutedRegistration<Class<? extends BaseIdentity>, InstanceIdentifier<?>, T> {
 184
 185         /**
 186          * Register particular instance identifier to be processed by this
 187          * RpcService
 188          *
 189          * Deprecated in favor of {@link RoutedRegistration#registerPath(Object, Object)}.
 190          *
 191          * @param context
 192          * @param instance
 193          */
 194         @Deprecated
 195         void registerInstance(Class<? extends BaseIdentity> context, InstanceIdentifier<?> instance);
 196
 197         /**
 198          * Unregister particular instance identifier to be processed by this
 199          * RpcService
 200          *
 201          * Deprecated in favor of {@link RoutedRegistration#unregisterPath(Object, Object)}.
 202          *
 203          * @param context
 204          * @param instance
 205          */
 206         @Deprecated
 207         void unregisterInstance(Class<? extends BaseIdentity> context, InstanceIdentifier<?> instance);
 208     }
 209 }