opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/BindingAwareConsumer.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.sal.binding.api.BindingAwareBroker.ConsumerContext;
  11
  12 /**
  13 *
  14 * A developer implemented component that gets registered with the Broker.
  15 *
  16 * Semantically, a consumer may:
  17 *
  18 * <ol>
  19 *   <li>Subscribe for Notifications </li>
  20 *   <li>Invoke RPCs</li>
  21 *   <li>Read from either the operational or config data tree</li>
  22 *   <li>Write to the config data tree</li>
  23 * </ol>
  24 * If you need to:
  25 * <ol>
  26 *   <li> Emit Notifications</li>
  27 *   <li> Provide the implementation of RPCs </li>
  28 *   <li> Write to the operational data tree </li>
  29 * </ol>
  30 *
  31 * Consider using a BindingAwareProvider
  32 *
  33 * Examples:
  34 *
  35 * To get a NotificationService:
  36 *
  37 * {code
  38 * public void onSessionInitiated(ProviderContext session) {
  39 *      NotificationProviderService notificationService = session.getSALService(NotificationProviderService.class);
  40 *      notificationService.publish(notification)
  41 * }
  42 * where notification is an instance of a modeled Notification.
  43 * For more information on sending notifications via the NotificationProviderService
  44 * @see org.opendaylight.controller.sal.binding.api.NotificationProviderService
  45 *
  46 *
  47 * A consumer can *invoke* and RPC ( ie, call foo(fooArgs)) but it cannot register an RPC
  48 * implementation with the MD-SAL that others can invoke(call).
  49 * To get an invokable RPC:
  50 *
  51 * {code
  52 * public void onSessionInitiated(ProviderContext session) {
  53 *    MyService rpcFlowSalService = session.getRpcService(MyService.class);
  54 * }
  55 *
  56 * Where MyService.class is a Service interface generated from a yang model with RPCs modeled in it.  The returned
  57 * rpcFlowSalService can be used like any other object by invoking its methods.  Note, nothing special needs to be done
  58 * for RoutedRPCs.  They just work.
  59 *
  60 * To get a DataBroker to allow access to the data tree:
  61 *
  62 * {code
  63 * public void onSessionInitiated(final ProviderContext session) {
  64 *      DataBroker databroker = session.getSALService(BindingDataBroker.class);
  65 * }
  66 * }
  67 * @see org.opendaylight.controller.md.sal.common.api.data.BindingDataBroker
  68 * for more info on using the DataBroker.
  69 *
  70 */
  71 public interface BindingAwareConsumer {
  72
  73     /**
  74      * Callback signaling initialization of the consumer session to the SAL.
  75      *
  76      * The consumer MUST use the session for all communication with SAL or
  77      * retrieving SAL infrastructure services.
  78      *
  79      * This method is invoked by
  80      * {@link BindingAwareBroker#registerConsumer(BindingAwareConsumer)}
  81      *
  82      * @param session
  83      *            Unique session between consumer and SAL.
  84      */
  85     void onSessionInitialized(ConsumerContext session);
  86
  87 }