docs/index.rst

   1 .. _mdsal:
   2
   3 ######
   4 MD-SAL
   5 ######
   6
   7 .. _overview:
   8
   9 Overview
  10 ========
  11
  12 The Model-Driven Service Adaptation Layer (MD-SAL) is message-bus inspired
  13 extensible middleware component that provides messaging and data storage
  14 functionality based on data and interface models defined by application
  15 developers (i.e. user-defined models).
  16
  17 The MD-SAL:
  18
  19 * Defines a **common-layer, concepts, data model building blocks and messaging
  20   patterns** and provides infrastructure / framework for applications and
  21   inter-application communication.
  22
  23 .. FIXME: Common integration point / reword this better
  24
  25 * Provide common support for user-defined transport and payload formats,
  26   including payload serialization and adaptation (e.g. binary, XML or JSON).
  27
  28 The MD-SAL uses **YANG** as the modeling language for both interface and data
  29 definitions, and provides a messaging and data-centric runtime for such
  30 services based on YANG modeling.
  31
  32 The MD-SAL provides two different API types (flavours):
  33
  34 * **MD-SAL Binding:** MD-SAL APIs which extensively uses APIs and classes
  35   generated from YANG models, which provides compile-time safety.
  36 * **MD-SAL DOM:** (Document Object Model) APIs which uses DOM-like
  37   representation of data, which makes them more powerful, but provides less
  38   compile-time safety.
  39
  40 .. note::
  41
  42    Model-driven nature of the MD-SAL and **DOM**-based APIs allows for
  43    behind-the-scene API and payload type mediation and transformation
  44    to facilitate seamless communication between applications - this enables
  45    for other components and applications to provide connectors / expose
  46    different set of APIs and derive most of its functionality purely from
  47    models, which all existing code can benefit from without modification.
  48    For example **RESTCONF Connector** is an application built on top of MD-SAL
  49    and exposes YANG-modeled application APIs transparently via HTTP and adds
  50    support for XML and JSON payload type.
  51
  52 .. _basic-concepts:
  53
  54 Basic concepts
  55 ==============
  56
  57 Basic concepts are building blocks which are used by applications, and from
  58 which MD-SAL uses to define messaging patterns and to provide services and
  59 behavior based on developer-supplied YANG models.
  60
  61 :Data Tree: All state-related data are modeled and represented as data tree,
  62     with possibility to address any element / subtree
  63
  64     * **Operational Data Tree** - Reported state of the system, published by
  65       the providers using MD-SAL. Represents a feedback loop for applications
  66       to observe state of the network / system.
  67     * **Configuration Data Tree** - Intended state of the system or network,
  68       populated by consumers, which expresses their intention.
  69
  70 :Instance Identifier: Unique identifier of node / subtree in data tree, which
  71     provides unambiguous information, how to reference and retrieve node /
  72     subtree from conceptual data trees.
  73
  74 :Notification: Asynchronous transient event which may be consumed by
  75     subscribers and they may act upon it.
  76
  77 :RPC: asynchronous request-reply message pair, when request is triggered by
  78     consumer, send to the provider, which in future replies with reply message.
  79
  80     .. note::
  81
  82        In MD-SAL terminology, the term 'RPC' is used to define the input and
  83        output for a procedure (function) that is to be provided by a provider,
  84        and mediated by the MD-SAL, that means it may not result in remote call.
  85
  86 .. _messaging-patterns:
  87
  88 Messaging Patterns
  89 ==================
  90
  91 MD-SAL provides several messaging patterns using broker derived from
  92 basic concepts, which are intended to transfer YANG modeled data between
  93 applications to provide data-centric integration between applications instead
  94 of API-centric integration.
  95
  96 * **Unicast communication**
  97
  98   * **Remote Procedure Calls** - unicast between consumer and provider, where
  99     consumer sends **request** message to provider, which asynchronously
 100     responds with **reply** message.
 101
 102 * **Publish / Subscribe**
 103
 104   * **Notifications** - multicast transient message which is published by
 105     provider and is delivered to subscribers.
 106
 107   * **Data Change Events** - multicast asynchronous event, which is sent by
 108     data broker if there is change in conceptual data tree, and is delivered to
 109     subscribers.
 110
 111 * **Transactional access to Data Tree**
 112
 113   * Transactional **reads** from conceptual **data tree** - read-only
 114     transactions with isolation from other running transactions.
 115   * Transactional **modification** to conceptual **data tree** - write
 116     transactions with isolation from other running transactions.
 117   * **Transaction chaining**
 118
 119 Table of Contents
 120 =================
 121
 122 .. toctree::
 123    :maxdepth: 1
 124
 125    architecture
 126    conceptual-data-tree
 127    incremental-backup