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