docs/developer-guide/yang-push-developer-guide.rst

   1 YANG-PUSH Developer Guide
   2 =========================
   3
   4 Overview
   5 --------
   6
   7 The YANG PUBSUB project allows subscriptions to be placed on targeted
   8 subtrees of YANG datastores residing on remote devices. Changes in YANG
   9 objects within the remote subtree can be pushed to an OpenDaylight
  10 controller as specified without a requiring the controller to make a
  11 continuous set of fetch requests.
  12
  13 YANG-PUSH capabilities available
  14 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15
  16 This module contains the base code which embodies the intent of
  17 YANG-PUSH requirements for subscription as defined in
  18 {i2rs-pub-sub-requirements}
  19 [https://datatracker.ietf.org/doc/draft-ietf-i2rs-pub-sub-requirements/].
  20 The mechanism for delivering on these YANG-PUSH requirements over
  21 Netconf transport is defined in {netconf-yang-push} [netconf-yang-push:
  22 https://tools.ietf.org/html/draft-ietf-netconf-yang-push-00].
  23
  24 Note that in the current release, not all capabilities of
  25 draft-ietf-netconf-yang-push are realized. Currently only implemented is
  26 **create-subscription** RPC support from
  27 ietf-datastore-push@2015-10-15.yang; and this will be for periodic
  28 subscriptions only. There of course is intent to provide much additional
  29 functionality in future OpenDaylight releases.
  30
  31 Future YANG-PUSH capabilities
  32 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  33
  34 Over time, the intent is to flesh out more robust capabilities which
  35 will allow OpenDaylight applications to subscribe to YANG-PUSH compliant
  36 devices. Capabilities for future releases will include:
  37
  38 Support for subscription change/delete: **modify-subscription** rpc
  39 support for all mountpoint devices or particular mountpoint device
  40 **delete-subscription** rpc support for all mountpoint devices or
  41 particular mountpoint device
  42
  43 Support for static subscriptions: This will enable the receipt of
  44 subscription updates pushed from publishing devices where no signaling
  45 from the controller has been used to establish the subscriptions.
  46
  47 Support for additional transports: NETCONF is not the only transport of
  48 interest to OpenDaylight or the subscribed devices. Over time this code
  49 will support Restconf and HTTP/2 transport requirements defined in
  50 {netconf-restconf-yang-push}
  51 [https://tools.ietf.org/html/draft-voit-netconf-restconf-yang-push-01]
  52
  53 YANG-PUSH Architecture
  54 ----------------------
  55
  56 The code architecture of Yang push consists of two main elements
  57
  58 YANGPUSH Provider YANGPUSH Listener
  59
  60 YANGPUSH Provider receives create-subscription requests from
  61 applications and then establishes/registers the corresponding listener
  62 which will receive information pushed by a publisher. In addition,
  63 YANGPUSH Provider also invokes an augmented OpenDaylight
  64 create-subscription RPC which enables applications to register for
  65 notification as per rfc5277. This augmentation adds periodic time period
  66 (duration) and subscription-id values to the existing RPC parameters.
  67 The Java package supporting this capability is
  68 “org.opendaylight.yangpush.impl”. Below class supports the YANGPUSH
  69 Provider capability:
  70
  71 (1) YangpushDomProvider The Binding Independent version. It uses a
  72 neutral data Document Object Model format for data and API calls, which
  73 is independent of any generated Java language bindings from the YANG
  74 model.
  75
  76 The YANGPUSH Listener accepts update notifications from a device after
  77 they have been de-encapsulated from the NETCONF transport. The YANGPUSH
  78 Listener then passes these updates to MD-SAL. This function is
  79 implemented via the YangpushDOMNotificationListener class within the
  80 “org.opendaylight.yangpush.listner” Java package.
  81
  82 Key APIs and Interfaces
  83 -----------------------
  84
  85 YangpushDomProvider
  86 ~~~~~~~~~~~~~~~~~~~
  87
  88 Central to this is onSessionInitiated which acquires the Document Object
  89 Model format based versions of MD-SAL services, including the MountPoint
  90 service and RPCs. Via these acquired services, invoke
  91 registerDataChangeListener over in YangpushDOMNotificationListener.
  92
  93 YangpushDOMNotificationListener
  94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  95
  96 This API handles instances of a received Push Updates which are inbound
  97 to the listener and places these in MD-SAL. Key classes in include:
  98
  99 onPushUpdate Converts and validates the encoding of the pushed
 100 subscription update. If the subscription exists and is active, calls
 101 updateDataStoreForPushUpdate so that the information can be put in
 102 MD-SAL. Finally logs the pushed subscription update as well as some
 103 additional context information.
 104
 105 updateDataStoreForPushUpdate Used to put the published information into
 106 MD-SAL. This pushed information will also include elements such as the
 107 subscription-id, the identity of the publisher, the time of the update,
 108 the incoming encoding type, and the pushed YANG subtree information.
 109
 110 YangpushDOMNotificationListener Starts the listener tracking a new
 111 Subscription ID from a particular publisher.
 112
 113 API Reference Documentation
 114 ---------------------------
 115
 116 Javadocs are generated while creating mvn:site and they are located in
 117 target/ directory in each module.