binding/mdsal-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
  11
  12 import org.opendaylight.mdsal.binding.api.RpcConsumerRegistry;
  13
  14 import org.opendaylight.yangtools.concepts.ObjectRegistration;
  15 import org.opendaylight.yangtools.yang.binding.BaseIdentity;
  16 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  17 import org.opendaylight.yangtools.yang.binding.RpcService;
  18
  19 /**
  20  * Binding-aware core of the SAL layer responsible for wiring the SAL consumers.
  21  *
  22  * The responsibility of the broker is to maintain registration of SAL functionality
  23  * {@link BindingAwareConsumer}s and {@link BindingAwareProvider}s, store provider and consumer
  24  * specific context and functionality registration via
  25  * {@link org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ConsumerContext} and
  26  * provide access to infrastructure services, which removes direct dependencies between providers
  27  * and consumers.
  28  *
  29  * The Binding-aware broker is also responsible for translation from Java classes modeling the
  30  * functionality and data to binding-independent form which is used in SAL Core.
  31  *
  32  *
  33  * <h3>Infrastructure services</h3> Some examples of infrastructure services: The services are
  34  * exposed via session.
  35  *
  36  * <h3>Session-based access</h3>
  37  *
  38  * The providers and consumers needs to register in order to use the binding-independent SAL layer
  39  * and to expose functionality via SAL layer.
  40  *
  41  * For more information about session-based access see
  42  * {@link org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ConsumerContext} and
  43  * {@link ProviderContext}
  44  */
  45 public interface BindingAwareBroker {
  46
  47     /**
  48      * Registers the {@link BindingAwareConsumer}, which will use the SAL layer.
  49      *
  50      * <p>
  51      * Note that consumer could register additional functionality at later point by using service
  52      * and functionality specific APIs.
  53      *
  54      * <p>
  55      * The consumer is required to use returned session for all communication with broker or one of
  56      * the broker services. The session is announced to the consumer by invoking
  57      * {@link BindingAwareConsumer#onSessionInitialized(org.opendaylight.controller.sal.binding.api.BindingAwareBroker.ConsumerContext)}.
  58      *
  59      * @param consumer Consumer to be registered.
  60      * @return a session specific to consumer registration
  61      * @throws IllegalArgumentException If the consumer is <code>null</code>.
  62      * @throws IllegalStateException If the consumer is already registered.
  63      */
  64     ConsumerContext registerConsumer(BindingAwareConsumer consumer);
  65
  66     /**
  67      * Registers the {@link BindingAwareProvider}, which will use the SAL layer.
  68      *
  69      * <p>
  70      * Note that provider could register additional functionality at later point by using service
  71      * and functionality specific APIs.
  72      *
  73      * <p>
  74      * The consumer is <b>required to use</b> returned session for all communication with broker or
  75      * one of the broker services. The session is announced to the consumer by invoking
  76      * {@link BindingAwareProvider#onSessionInitiated(ProviderContext)}.
  77      *
  78      *
  79      * @param provider Provider to be registered.
  80      * @return a session unique to the provider registration.
  81      * @throws IllegalArgumentException If the provider is <code>null</code>.
  82      * @throws IllegalStateException If the consumer is already registered.
  83      */
  84     ProviderContext registerProvider(BindingAwareProvider provider);
  85
  86     /**
  87      * {@link BindingAwareConsumer} specific access to the SAL functionality.
  88      *
  89      * <p>
  90      * ConsumerSession is {@link BindingAwareConsumer}-specific access to the SAL functionality and
  91      * infrastructure services.
  92      *
  93      * <p>
  94      * The session serves to store SAL context (e.g. registration of functionality) for the consumer
  95      * and provides access to the SAL infrastructure services and other functionality provided by
  96      * providers.
  97      */
  98     public interface ConsumerContext extends RpcConsumerRegistry {
  99
 100         /**
 101          * Returns a session specific instance (implementation) of requested
 102          * binding-aware infrastructural service
 103          *
 104          * @param service
 105          *            Broker service
 106          * @return Session specific implementation of service
 107          */
 108         <T extends BindingAwareService> T getSALService(Class<T> service);
 109     }
 110
 111     /**
 112      * {@link BindingAwareProvider} specific access to the SAL functionality.
 113      *
 114      * <p>
 115      * ProviderSession is {@link BindingAwareProvider}-specific access to the
 116      * SAL functionality and infrastructure services, which also allows for
 117      * exposing the provider's functionality to the other
 118      * {@link BindingAwareConsumer}s.
 119      *
 120      * <p>
 121      * The session serves to store SAL context (e.g. registration of
 122      * functionality) for the providers and exposes access to the SAL
 123      * infrastructure services, dynamic functionality registration and any other
 124      * functionality provided by other {@link BindingAwareConsumer}s.
 125      *
 126      */
 127     public interface ProviderContext extends ConsumerContext, RpcProviderRegistry {
 128
 129     }
 130
 131     /**
 132      * Represents an RPC implementation registration. Users should call the
 133      * {@link ObjectRegistration#close close} method when the registration is no longer needed.
 134      *
 135      * @param <T> the implemented RPC service interface
 136      */
 137     public interface RpcRegistration<T extends RpcService> extends ObjectRegistration<T> {
 138
 139         /**
 140          * Returns the implemented RPC service interface.
 141          */
 142         Class<T> getServiceType();
 143
 144         @Override
 145         void close();
 146     }
 147
 148     /**
 149      * Represents a routed RPC implementation registration. Users should call the
 150      * {@link RpcRegistration#close() close} method when the registration is no longer needed.
 151      *
 152      * @param <T> the implemented RPC service interface
 153      */
 154     public interface RoutedRpcRegistration<T extends RpcService> extends RpcRegistration<T> {
 155
 156         /**
 157          * Register particular instance identifier to be processed by this
 158          * RpcService
 159          *
 160          * @param context
 161          * @param instance
 162          */
 163         void registerPath(Class<? extends BaseIdentity> context, InstanceIdentifier<?> instance);
 164
 165         /**
 166          * Unregister particular instance identifier to be processed by this
 167          * RpcService
 168          *
 169          * @param context
 170          * @param instance
 171          */
 172         void unregisterPath(Class<? extends BaseIdentity> context, InstanceIdentifier<?> instance);
 173     }
 174 }