+++ /dev/null
-/* Javadoc style sheet */
-/*
-Overall document style
-*/
-body {
- background-color:#ffffff;
- color:#353833;
- font-family:Arial, Helvetica, sans-serif;
- font-size:76%;
- margin:0;
-}
-a:link, a:visited {
- text-decoration:none;
- color:#4c6b87;
-}
-a:hover, a:focus {
- text-decoration:none;
- color:#bb7a2a;
-}
-a:active {
- text-decoration:none;
- color:#4c6b87;
-}
-a[name] {
- color:#353833;
-}
-a[name]:hover {
- text-decoration:none;
- color:#353833;
-}
-pre {
- font-size:1.3em;
-}
-h1 {
- font-size:1.8em;
-}
-h2 {
- font-size:1.5em;
-}
-h3 {
- font-size:1.4em;
-}
-h4 {
- font-size:1.3em;
-}
-h5 {
- font-size:1.2em;
-}
-h6 {
- font-size:1.1em;
-}
-ul {
- list-style-type:disc;
-}
-code, tt {
- font-size:1.2em;
-}
-dt code {
- font-size:1.2em;
-}
-table tr td dt code {
- font-size:1.2em;
- vertical-align:top;
-}
-sup {
- font-size:.6em;
-}
-/*
-Document title and Copyright styles
-*/
-.clear {
- clear:both;
- height:0px;
- overflow:hidden;
-}
-.aboutLanguage {
- float:right;
- padding:0px 21px;
- font-size:.8em;
- z-index:200;
- margin-top:-7px;
-}
-.legalCopy {
- margin-left:.5em;
-}
-.bar a, .bar a:link, .bar a:visited, .bar a:active {
- color:#FFFFFF;
- text-decoration:none;
-}
-.bar a:hover, .bar a:focus {
- color:#bb7a2a;
-}
-.tab {
- background-color:#0066FF;
- background-image:url(resources/titlebar.gif);
- background-position:left top;
- background-repeat:no-repeat;
- color:#ffffff;
- padding:8px;
- width:5em;
- font-weight:bold;
-}
-/*
-Navigation bar styles
-*/
-.bar {
- background-image:url(resources/background.gif);
- background-repeat:repeat-x;
- color:#FFFFFF;
- padding:.8em .5em .4em .8em;
- height:auto;/*height:1.8em;*/
- font-size:1em;
- margin:0;
-}
-.topNav {
- background-image:url(resources/background.gif);
- background-repeat:repeat-x;
- color:#FFFFFF;
- float:left;
- padding:0;
- width:100%;
- clear:right;
- height:2.8em;
- padding-top:10px;
- overflow:hidden;
-}
-.bottomNav {
- margin-top:10px;
- background-image:url(resources/background.gif);
- background-repeat:repeat-x;
- color:#FFFFFF;
- float:left;
- padding:0;
- width:100%;
- clear:right;
- height:2.8em;
- padding-top:10px;
- overflow:hidden;
-}
-.subNav {
- background-color:#dee3e9;
- border-bottom:1px solid #9eadc0;
- float:left;
- width:100%;
- overflow:hidden;
-}
-.subNav div {
- clear:left;
- float:left;
- padding:0 0 5px 6px;
-}
-ul.navList, ul.subNavList {
- float:left;
- margin:0 25px 0 0;
- padding:0;
-}
-ul.navList li{
- list-style:none;
- float:left;
- padding:3px 6px;
-}
-ul.subNavList li{
- list-style:none;
- float:left;
- font-size:90%;
-}
-.topNav a:link, .topNav a:active, .topNav a:visited, .bottomNav a:link, .bottomNav a:active, .bottomNav a:visited {
- color:#FFFFFF;
- text-decoration:none;
-}
-.topNav a:hover, .bottomNav a:hover {
- text-decoration:none;
- color:#bb7a2a;
-}
-.navBarCell1Rev {
- background-image:url(resources/tab.gif);
- background-color:#a88834;
- color:#FFFFFF;
- margin: auto 5px;
- border:1px solid #c9aa44;
-}
-/*
-Page header and footer styles
-*/
-.header, .footer {
- clear:both;
- margin:0 20px;
- padding:5px 0 0 0;
-}
-.indexHeader {
- margin:10px;
- position:relative;
-}
-.indexHeader h1 {
- font-size:1.3em;
-}
-.title {
- color:#2c4557;
- margin:10px 0;
-}
-.subTitle {
- margin:5px 0 0 0;
-}
-.header ul {
- margin:0 0 25px 0;
- padding:0;
-}
-.footer ul {
- margin:20px 0 5px 0;
-}
-.header ul li, .footer ul li {
- list-style:none;
- font-size:1.2em;
-}
-/*
-Heading styles
-*/
-div.details ul.blockList ul.blockList ul.blockList li.blockList h4, div.details ul.blockList ul.blockList ul.blockListLast li.blockList h4 {
- background-color:#dee3e9;
- border-top:1px solid #9eadc0;
- border-bottom:1px solid #9eadc0;
- margin:0 0 6px -8px;
- padding:2px 5px;
-}
-ul.blockList ul.blockList ul.blockList li.blockList h3 {
- background-color:#dee3e9;
- border-top:1px solid #9eadc0;
- border-bottom:1px solid #9eadc0;
- margin:0 0 6px -8px;
- padding:2px 5px;
-}
-ul.blockList ul.blockList li.blockList h3 {
- padding:0;
- margin:15px 0;
-}
-ul.blockList li.blockList h2 {
- padding:0px 0 20px 0;
-}
-/*
-Page layout container styles
-*/
-.contentContainer, .sourceContainer, .classUseContainer, .serializedFormContainer, .constantValuesContainer {
- clear:both;
- padding:10px 20px;
- position:relative;
-}
-.indexContainer {
- margin:10px;
- position:relative;
- font-size:1.0em;
-}
-.indexContainer h2 {
- font-size:1.1em;
- padding:0 0 3px 0;
-}
-.indexContainer ul {
- margin:0;
- padding:0;
-}
-.indexContainer ul li {
- list-style:none;
-}
-.contentContainer .description dl dt, .contentContainer .details dl dt, .serializedFormContainer dl dt {
- font-size:1.1em;
- font-weight:bold;
- margin:10px 0 0 0;
- color:#4E4E4E;
-}
-.contentContainer .description dl dd, .contentContainer .details dl dd, .serializedFormContainer dl dd {
- margin:10px 0 10px 20px;
-}
-.serializedFormContainer dl.nameValue dt {
- margin-left:1px;
- font-size:1.1em;
- display:inline;
- font-weight:bold;
-}
-.serializedFormContainer dl.nameValue dd {
- margin:0 0 0 1px;
- font-size:1.1em;
- display:inline;
-}
-/*
-List styles
-*/
-ul.horizontal li {
- display:inline;
- font-size:0.9em;
-}
-ul.inheritance {
- margin:0;
- padding:0;
-}
-ul.inheritance li {
- display:inline;
- list-style:none;
-}
-ul.inheritance li ul.inheritance {
- margin-left:15px;
- padding-left:15px;
- padding-top:1px;
-}
-ul.blockList, ul.blockListLast {
- margin:10px 0 10px 0;
- padding:0;
-}
-ul.blockList li.blockList, ul.blockListLast li.blockList {
- list-style:none;
- margin-bottom:25px;
-}
-ul.blockList ul.blockList li.blockList, ul.blockList ul.blockListLast li.blockList {
- padding:0px 20px 5px 10px;
- border:1px solid #9eadc0;
- background-color:#f9f9f9;
-}
-ul.blockList ul.blockList ul.blockList li.blockList, ul.blockList ul.blockList ul.blockListLast li.blockList {
- padding:0 0 5px 8px;
- background-color:#ffffff;
- border:1px solid #9eadc0;
- border-top:none;
-}
-ul.blockList ul.blockList ul.blockList ul.blockList li.blockList {
- margin-left:0;
- padding-left:0;
- padding-bottom:15px;
- border:none;
- border-bottom:1px solid #9eadc0;
-}
-ul.blockList ul.blockList ul.blockList ul.blockList li.blockListLast {
- list-style:none;
- border-bottom:none;
- padding-bottom:0;
-}
-table tr td dl, table tr td dl dt, table tr td dl dd {
- margin-top:0;
- margin-bottom:1px;
-}
-/*
-Table styles
-*/
-.contentContainer table, .classUseContainer table, .constantValuesContainer table {
- border-bottom:1px solid #9eadc0;
- width:100%;
-}
-.contentContainer ul li table, .classUseContainer ul li table, .constantValuesContainer ul li table {
- width:100%;
-}
-.contentContainer .description table, .contentContainer .details table {
- border-bottom:none;
-}
-.contentContainer ul li table th.colOne, .contentContainer ul li table th.colFirst, .contentContainer ul li table th.colLast, .classUseContainer ul li table th, .constantValuesContainer ul li table th, .contentContainer ul li table td.colOne, .contentContainer ul li table td.colFirst, .contentContainer ul li table td.colLast, .classUseContainer ul li table td, .constantValuesContainer ul li table td{
- vertical-align:top;
- padding-right:20px;
-}
-.contentContainer ul li table th.colLast, .classUseContainer ul li table th.colLast,.constantValuesContainer ul li table th.colLast,
-.contentContainer ul li table td.colLast, .classUseContainer ul li table td.colLast,.constantValuesContainer ul li table td.colLast,
-.contentContainer ul li table th.colOne, .classUseContainer ul li table th.colOne,
-.contentContainer ul li table td.colOne, .classUseContainer ul li table td.colOne {
- padding-right:3px;
-}
-.overviewSummary caption, .packageSummary caption, .contentContainer ul.blockList li.blockList caption, .summary caption, .classUseContainer caption, .constantValuesContainer caption {
- position:relative;
- text-align:left;
- background-repeat:no-repeat;
- color:#FFFFFF;
- font-weight:bold;
- clear:none;
- overflow:hidden;
- padding:0px;
- margin:0px;
-}
-caption a:link, caption a:hover, caption a:active, caption a:visited {
- color:#FFFFFF;
-}
-.overviewSummary caption span, .packageSummary caption span, .contentContainer ul.blockList li.blockList caption span, .summary caption span, .classUseContainer caption span, .constantValuesContainer caption span {
- white-space:nowrap;
- padding-top:8px;
- padding-left:8px;
- display:block;
- float:left;
- background-image:url(resources/titlebar.gif);
- height:18px;
-}
-.overviewSummary .tabEnd, .packageSummary .tabEnd, .contentContainer ul.blockList li.blockList .tabEnd, .summary .tabEnd, .classUseContainer .tabEnd, .constantValuesContainer .tabEnd {
- width:10px;
- background-image:url(resources/titlebar_end.gif);
- background-repeat:no-repeat;
- background-position:top right;
- position:relative;
- float:left;
-}
-ul.blockList ul.blockList li.blockList table {
- margin:0 0 12px 0px;
- width:100%;
-}
-.tableSubHeadingColor {
- background-color: #EEEEFF;
-}
-.altColor {
- background-color:#eeeeef;
-}
-.rowColor {
- background-color:#ffffff;
-}
-.overviewSummary td, .packageSummary td, .contentContainer ul.blockList li.blockList td, .summary td, .classUseContainer td, .constantValuesContainer td {
- text-align:left;
- padding:3px 3px 3px 7px;
-}
-th.colFirst, th.colLast, th.colOne, .constantValuesContainer th {
- background:#dee3e9;
- border-top:1px solid #9eadc0;
- border-bottom:1px solid #9eadc0;
- text-align:left;
- padding:3px 3px 3px 7px;
-}
-td.colOne a:link, td.colOne a:active, td.colOne a:visited, td.colOne a:hover, td.colFirst a:link, td.colFirst a:active, td.colFirst a:visited, td.colFirst a:hover, td.colLast a:link, td.colLast a:active, td.colLast a:visited, td.colLast a:hover, .constantValuesContainer td a:link, .constantValuesContainer td a:active, .constantValuesContainer td a:visited, .constantValuesContainer td a:hover {
- font-weight:bold;
-}
-td.colFirst, th.colFirst {
- border-left:1px solid #9eadc0;
- white-space:nowrap;
-}
-td.colLast, th.colLast {
- border-right:1px solid #9eadc0;
-}
-td.colOne, th.colOne {
- border-right:1px solid #9eadc0;
- border-left:1px solid #9eadc0;
-}
-table.overviewSummary {
- padding:0px;
- margin-left:0px;
-}
-table.overviewSummary td.colFirst, table.overviewSummary th.colFirst,
-table.overviewSummary td.colOne, table.overviewSummary th.colOne {
- width:25%;
- vertical-align:middle;
-}
-table.packageSummary td.colFirst, table.overviewSummary th.colFirst {
- width:25%;
- vertical-align:middle;
-}
-/*
-Content styles
-*/
-.description pre {
- margin-top:0;
-}
-.deprecatedContent {
- margin:0;
- padding:10px 0;
-}
-.docSummary {
- padding:0;
-}
-/*
-Formatting effect styles
-*/
-.sourceLineNo {
- color:green;
- padding:0 30px 0 0;
-}
-h1.hidden {
- visibility:hidden;
- overflow:hidden;
- font-size:.9em;
-}
-.block {
- display:block;
- margin:3px 0 0 0;
-}
-.strong {
- font-weight:bold;
-}
-
+++ /dev/null
-= Architecture
-
-
-[plantuml]
-....
- package "MD-SAL Project" {
-
- () "MD-SAL Binding API" as mdsal.binding.api
- () "MD-SAL DOM API" as mdsal.dom.api
- [Binding Adapter] as mdsal.binding.adapter
- [Binding Data Codec] as mdsal.binding.codec
- [MD-SAL DOM Router] as mdsal.dom.router
- () "MD-SAL Shard SPI" as mdsal.shard.spi
-
- mdsal.binding.adapter --> mdsal.binding.codec : uses
- mdsal.binding.api -- mdsal.binding.adapter
- mdsal.binding.adapter .> mdsal.dom.api : uses
- mdsal.dom.api -- mdsal.dom.router
- mdsal.dom.router -- mdsal.shard.spi
- }
-....
+++ /dev/null
-= Conceptual Data Tree
-Robert Varga <rovarga@cisco.com>
-:rfc6020: https://tools.ietf.org/html/rfc6020
-:mdsal-apidoc: https://nexus.opendaylight.org/content/sites/site/org.opendaylight.mdsal/boron/apidocs/org/opendaylight/mdsal/dom/api/
-
-:toclevel: 3
-:toc:
-
-
-== Terminology
-
-Data Tree::
- An instantiated logical tree that represents configuration or operational state data of a modeled problem domain (for example, a controller or a
- network)
-
-Data Tree Consumer::
- A component acting on data, after this data are introduced into one or more
- particular subtrees of a Data Tree.
-
-Data Tree Identifier::
- A unique identifier for a particular subtree of a Data Tree. It is composed of
- the logical data store type and the instance identifier of the subtree's root node. It is represented by a `DOMDataTreeIdentifier`.
-
-Data Tree Producer::
- A component responsible for providing data for one or more particular subtrees of a Data Tree.
-
-Data Tree Shard::
- A component responsible for providing storage or access to a particular subtree of a Data Tree.
-
-Shard Layout::
- A longest-prefix mapping between Data Tree Identifiers and Data Tree Shards
- responsible for providing access to a data subtree.
-
-
-== Basic Concepts
-
-=== Data Tree is a Namespace
-The concept of a data tree comes from {rfc6020}[RFC6020]. It is is vaguely
-split into two instances, configuration and operational. The implicit
-assumption is that *config implies oper*, i.e. any configuration data is
-also a valid operational data. Further interactions between the two are left
-undefined and the YANG language is not strictly extensible in the number and
-semantics of these instances, leaving a lot to implementation details. An
-outline of data tree use, which is consistent with the current MD-SAL design,
-is described in https://tools.ietf.org/html/draft-kwatsen-netmod-opstate[draft-kwatsen-netmod-opstate].
-
-The OpenDaylight MD-SAL design makes no inherent assumptions about the
-relationship between the configuration and operational data tree instances.
-They are treated as separate entities and they are both fully addressable via
-the `DOMDataTreeIdentifier` objects. It is up to MD-SAL plugins (e.g. protocol
-plugins or applications) to maintain this relationship. This reflects the
-asynchronous nature of applying configuration and also the fact that the
-intended configuration data may be subject to translation (such as template
-configuration instantiation).
-
-Both the configuration and operational namespaces (data trees) are instances
-of the Conceptual Data Tree. Any data item in the conceptual data tree is
-addressed via a `YangInstanceIdentifier` object, which is a unique,
-hierarchical, content-based identifier. All applications use the identifier
-objects to identify data to MD-SAL services, which in turn are expected to
-perform proper namespace management such that logical operation connectivity is
-maintained.
-
-// Can you reword '...are expected to perform proper namespace management such that logical operation connectivity is maintained...' - not clear what you mean
-
-=== Identifiers versus Locators
-
-It is important to note that when we talk about Identifiers and Locators,
-we *do not* mean
-https://en.wikipedia.org/wiki/Uniform_Resource_Identifier[URIs and URLs],
-but rather URNs and URLs as strictly separate entities. MD-SAL plugins do not
-have access to locators and it is the job of MD-SAL services to provide
-location independence.
-
-The details of how a particular MD-SAL service achieves location independence
-is currently left up to the service's implementation, which leads to the
-problem of having MD-SAL services cooperate, such as storing data in different
-backends (in-memory, SQL, NoSQL, etc.) and providing unified access to all
-available data. Note that data availability is subject to capabilities of a
-particular storage engine and its operational state, which leads to the design
-decision that a `YangInstanceIdentifier` lookup needs to be performed in two
-steps:
-
-. A longest-prefix match is performed to locate the storage backend instance for
- that identifier
-. Masked path elements are resolved by the storage engine
-
-=== Data Tree Shard
-
-A process similar to the first step above is performed today by the Distributed
-Data Store implementation to split data into Shards. The concept of a Shard as
-currently implemented is limited to specifying namespaces, and it does not
-allow for pluggable storage engines.
-
-In context of the Conceptual Data Tree, the concept of a Shard is generalized
-as the shorthand equivalent of a storage backend instance. A Shard can be
-attached at any (even wildcard) `YangInstanceIdentifier`. This contract is
-exposed via the `DOMShardedDataTree`, which is an MD-SAL SPI class that
-implements an `YangInstanceIdentifier` -> `Shard` registry service. This is
-an omnipresent MD-SAL service, Shard Registry, whose visibility scope is a
-single OpenDaylight instance (i.e. a cluster member). *Shard Layout* refers
-to the mapping information contained in this service.
-
-=== Federation, Replication and High Availability
-
-Support for various multi-node scenarios is a concern outside of core MD-SAL.
-If a particular scenario requires the shard layout to be replicated (either
-fully or partially), it is up to Shard providers to maintain an omnipresent
-service on each node, which in turn is responsible for dynamically registering
-`DOMDataTreeShard` instances with the Shard Registry service.
-
-Since the Shard Layout is strictly local to a particular OpenDaylight instance,
-an OpenDaylight cluster is not strictly consistent in its mapping of
-`YangInstanceIdentifier` to data. When a query for the entire data tree is executed,
-the returned result will vary between member instances based on the differences
-of their Shard Layouts. This allows each node to project its local operational
-details, as well as the partitioning of the data set being worked on based
-on workload and node availability.
-
-Partial symmetry of the conceptual data tree can still be maintained to
-the extent that a particular deployment requires. For example the Shard
-containing the OpenFlow topology can be configured to be registered on all
-cluster members, leading to queries into that topology returning consistent
-results.
-
-== Design
-
-[[design-listener]]
-==== Data Tree Listener
-
-A Data Tree Listener is a data consumer, for example a process that wants
-to act on data after it has been introduced to the Conceptual Data Tree.
-
-A Data Tree Listener implements the {mdsal-apidoc}DOMDataTreeListener.html[DOMDataTreeListener]
-interface and registers itself using {mdsal-apidoc}DOMDataTreeService.html[DOMDataTreeService].
-
-A Data Tree Listener may register for multiple subtrees. Each time it is
-invoked it will be provided with the current state of all subtrees that it
-is registered for.
-
-
-// FIXME: Consider linking / inlining interface
-
-.DOMDataTreeListener interface signature
-[source, java]
-----
-public interface DOMDataTreeListener extends EventListener {
-
- void onDataTreeChanged(Collection<DataTreeCandidate> changes, // (1)
- Map<DOMDataTreeIdentifier, NormalizedNode<?, ?>> subtrees);
-
- void onDataTreeFailed(Collection<DOMDataTreeListeningException> causes); // (2)
-}
-----
-<1> Invoked when the data tree to which the Data Tree Listener is subscribed
- to changed. `changes` contains the collection of changes, `subtrees`
- contains the current state of all subtrees to which the listener is
- registered.
-<2> Invoked when a subtree listening failure occurs. For example, a failure
- can be triggered when a connection to an external subtree source is
- broken.
-
-[[design-producer]]
-==== Data Tree Producer
-
-A Data Tree Producer represents source of data in system. Data TreeProducer
-implementations are not required to implement a specific interface, but
-use a {mdsal-apidoc}DOMDataTreeProducer.html[DOMDataTreeProducer] instance
-to publish data (i.e. to modify the Conceptual Data Tree).
-
-A Data Tree Producer is exclusively bound to one or more subtrees of the
-Conceptual Data Tree, i.e. binding a Data Tree Producer to a subtree prevents
-other Data Tree Producers from modifying the subtree.
-
-* A failed Data Tree Producer still holds a claim to the namespace to which
- it is bound (i.e. the exclusive lock of the subtree) untill it is closed.
-
-{mdsal-apidoc}DOMDataTreeProducer.html[DOMDataTreeProducer] represents a
-Data Tree Producer context
-
-* allows transactions to be submitted to subtrees specified at creation
- time
-* at any given time there may be a single transaction open.
-* once a transaction is submitted, it will proceed to be committed
- asynchronously.
-
-
-
-// FIXME: Consider linking / inlining interface
-
-.DOMDataTreeProducer interface signature
-[source, java]
-----
-public interface DOMDataTreeProducer extends DOMDataTreeProducerFactory, AutoCloseable {
- DOMDataWriteTransaction createTransaction(boolean isolated); // (1)
- DOMDataTreeProducer createProducer(Collection<DOMDataTreeIdentifier> subtrees); // (2)
-}
-----
-<1> Allocates a new transaction. All previously allocated transactions must
- have been either submitted or canceled. Setting `isolated` to `true`
- disables state compression for this transaction.
-<2> Creates a sub-producer for the provided `subtrees`. The parent producer
- loses the ability to access the specified paths until the resulting child
- producer is closed.
-
-[[design-shard]]
-=== Data Tree Shard
-
-- *A Data Tree Shard* is always bound to either the `OPERATIONAL`, or the
- `CONFIG` space, never to both at the same time.
-
-- *Data Tree Shards* may be nested, the parent shard must be aware of sub-shards
- and execute every request in context of a self-consistent view of sub-shards
- liveness. Data requests passing through it must be multiplexed with sub-shard
- creations/deletions. In other words, if an application creates a transaction
- rooted at the parent Shard and attempts to access data residing in a sub-shard,
- the parent Shard implementation must coordinate with the sub-shard
- implementation to provide the illusion that the data resides in the parent shard.
- In the case of a transaction running concurrently with sub-shard creation or
- deletion, these operations need to execute atomically with respect to each other,
- which is to say that the transactions must completely execute as if the sub-shard
- creation/deletion occurred before the transaction started or as if the transaction
- completed before the sub-shard creation/deletion request was executed. This
- requirement can also be satisfied by the Shard implementation preventing
- transactions from completing. A Shard implementation may choose to abort any
- open transactions prior to executing a sub-shard operation.
-
-- *Shard Layout* is local to an OpenDaylight instance.
-
-- *Shard Layout* is modified by agents (registering / unregistering Data Tree
- Shards) in order to make the Data Tree Shard and the underlaying data
- available to plugins and applications executing on that particular OpenDaylight
- instance.
-
-==== Registering a Shard with the Conceptual Data Tree
-
-NOTE: Namespace in this context means a Data Tree Identifier prefix.
-
-. *Claim a namespace* - An agent that is registering a shard must prove that it
- has sufficient rights to modify the subtree where the shard is going to be
- attached. A namespace for the shard is claimed by binding a Data Tree Producer
- instance to same subtree where the shard will be bound. The Data Tree Producer
- must not have any open child producers, and it should not have any outstanding
- transactions.
-
-. *Create a shard instance* - Once a namespace is claimed, the agent creates a
- shard instance.
-
-. *Attach shard* - The agent registers the created shard instance and provides
- in the reigstration the Data Tree Producer instance to verify the namespace
- claim. The newly created Shard is checked for its ability to cooperate with
- its parent shard. If the check is successful, the newly created Shard is
- attached to its parent shard and recorded in the Shard layout.
-
-. *Remove namespace claim* (optional) - If the Shard is providing storage for
- applications, the agent should close the Data Tree Producer instance to make
- the subtree available to applications.
-
-IMPORTANT: Steps 1, 2 and 3 may fail, and the recovery strategy depends
-on which step failed and on the failure reason.
-
-// FIXME: Describe possible failures and recovery scenarios
+++ /dev/null
-= MD-SAL Overview
-
-The Model-Driven Service Adaptation Layer (MD-SAL) is message-bus inspired
-extensible middleware component that provides messaging and data storage
-functionality based on data and interface models defined by application developers
-(i.e. user-defined models).
-
-The MD-SAL:
-
- * Defines a *common-layer, concepts, data model building blocks and messaging
- patterns* and provides infrastructure / framework for applications and
- inter-application communication.
-
-// FIXME: Common integration point / reword this better
- * Provide common support for user-defined transport and payload formats, including
- payload serialization and adaptation (e.g. binary, XML or JSON).
-
-The MD-SAL uses *YANG* as the modeling language for both interface and data
-definitions, and provides a messaging and data-centric runtime for such services
-based on YANG modeling.
-
-The MD-SAL provides two different API types (flavours): +
-
-* *MD-SAL Binding:* MD-SAL APIs which extensively uses APIs and classes generated
- from YANG models, which provides compile-time safety.
-* *MD-SAL DOM:* (Document Object Model) APIs which uses DOM-like
- representation of data, which makes them more powerful, but provides less
- compile-time safety.
-
-NOTE: Model-driven nature of the MD-SAL and *DOM*-based APIs allows for
-behind-the-scene API and payload type mediation and transformation
-to facilitate seamless communication between applications - this enables
-for other components and applications to provide connectors / expose different
-set of APIs and derive most of its functionality purely from models, which
-all existing code can benefit from without modification.
-For example *RESTCONF Connector* is an application built on top of MD-SAL
-and exposes YANG-modeled application APIs transparently via HTTP and adds support
-for XML and JSON payload type.
-
-==== Basic concepts
-
-Basic concepts are building blocks which are used by applications, and from
-which MD-SAL uses to define messaging patterns and to provide services and
-behavior based on developer-supplied YANG models.
-
-Data Tree::
-All state-related data are modeled and represented as data tree,
-with possibility to address any element / subtree
-+
- * *Operational Data Tree* - Reported state of the system, published by the
- providers using MD-SAL. Represents a feedback loop for applications
- to observe state of the network / system.
- * *Configuration Data Tree* - Intended state of the system or network,
- populated by consumers, which expresses their intention.
-
-Instance Identifier::
-Unique identifier of node / subtree in data tree, which provides unambiguous
-information, how to reference and retrieve node / subtree from conceptual
-data trees.
-
-Notification::
-Asynchronous transient event which may be consumed by subscribers and they may
-act upon it
-
-RPC::
-asynchronous request-reply message pair, when request is triggered
-by consumer, send to the provider, which in future replies with reply message.
-+
-NOTE: In MD-SAL terminology, the term 'RPC' is used to define the input and
-output for a procedure (function) that is to be provided by a provider,
-and mediated by the MD-SAL, that means it may not result in remote call.
-
-==== Messaging Patterns
-
-MD-SAL provides several messaging patterns using broker derived from
-basic concepts, which are intended to transfer YANG modeled data between
-applications to provide data-centric integration between applications instead
-of API-centric integration.
-
-* *Unicast communication*
-** *Remote Procedure Calls* - unicast between consumer and provider, where
-consumer sends *request* message to provider, which asynchronously responds
-with *reply* message
-
-* *Publish / Subscribe*
-** *Notifications* - multicast transient message which is published by provider
- and is delivered to subscribers
-** *Data Change Events* - multicast asynchronous event, which is sent by data
-broker if there is change in conceptual data tree, and is delivered to subscribers
-
-* *Transactional access to Data Tree*
-** Transactional *reads* from conceptual *data tree* - read-only transactions with
- isolation from other running transactions.
-** Transactional *modification* to conceptual *data tree* - write transactions with
- isolation from other running transactions.
-** *Transaction chaining*
+++ /dev/null
-= Release Notes
-
-== Boron Release (in progress)
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<project name="mdsal">
- <body>
- <menu name="Overview">
- <item name="Javadocs" href="apidocs/index.html" />
- </menu>
- <menu name="Architecture & Design">
- <item name="Conceptual Data Tree" href="conceptual-data-tree.html" />
- </menu>
- </body>
-</project>
-
Code Review / mdsal.git / commitdiff