src/site/asciidoc/overview.adoc

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