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