2 Robert Varga <rovarga@cisco.com>
3 :rfc6020: https://tools.ietf.org/html/rfc6020
4 :mdsal-apidoc: https://nexus.opendaylight.org/content/sites/site/org.opendaylight.mdsal/boron/apidocs/org/opendaylight/mdsal/dom/api/
13 An instantiated logical tree that represents configuration or operational state data of a modeled problem domain (for example, a controller or a
17 A component acting on data, after this data are introduced into one or more
18 particular subtrees of a Data Tree.
20 Data Tree Identifier::
21 A unique identifier for a particular subtree of a Data Tree. It is composed of
22 the logical data store type and the instance identifier of the subtree's root node. It is represented by a `DOMDataTreeIdentifier`.
25 A component responsible for providing data for one or more particular subtrees of a Data Tree.
28 A component responsible for providing storage or access to a particular subtree of a Data Tree.
31 A longest-prefix mapping between Data Tree Identifiers and Data Tree Shards
32 responsible for providing access to a data subtree.
37 === Data Tree is a Namespace
38 The concept of a data tree comes from {rfc6020}[RFC6020]. It is is vaguely
39 split into two instances, configuration and operational. The implicit
40 assumption is that *config implies oper*, i.e. any configuration data is
41 also a valid operational data. Further interactions between the two are left
42 undefined and the YANG language is not strictly extensible in the number and
43 semantics of these instances, leaving a lot to implementation details. An
44 outline of data tree use, which is consistent with the current MD-SAL design,
45 is described in https://tools.ietf.org/html/draft-kwatsen-netmod-opstate[draft-kwatsen-netmod-opstate].
47 The OpenDaylight MD-SAL design makes no inherent assumptions about the
48 relationship between the configuration and operational data tree instances.
49 They are treated as separate entities and they are both fully addressable via
50 the `DOMDataTreeIdentifier` objects. It is up to MD-SAL plugins (e.g. protocol
51 plugins or applications) to maintain this relationship. This reflects the
52 asynchronous nature of applying configuration and also the fact that the
53 intended configuration data may be subject to translation (such as template
54 configuration instantiation).
56 Both the configuration and operational namespaces (data trees) are instances
57 of the Conceptual Data Tree. Any data item in the conceptual data tree is
58 addressed via a `YangInstanceIdentifier` object, which is a unique,
59 hierarchical, content-based identifier. All applications use the identifier
60 objects to identify data to MD-SAL services, which in turn are expected to
61 perform proper namespace management such that logical operation connectivity is
64 // Can you reword '...are expected to perform proper namespace management such that logical operation connectivity is maintained...' - not clear what you mean
66 === Identifiers versus Locators
68 It is important to note that when we talk about Identifiers and Locators,
70 https://en.wikipedia.org/wiki/Uniform_Resource_Identifier[URIs and URLs],
71 but rather URNs and URLs as strictly separate entities. MD-SAL plugins do not
72 have access to locators and it is the job of MD-SAL services to provide
73 location independence.
75 The details of how a particular MD-SAL service achieves location independence
76 is currently left up to the service's implementation, which leads to the
77 problem of having MD-SAL services cooperate, such as storing data in different
78 backends (in-memory, SQL, NoSQL, etc.) and providing unified access to all
79 available data. Note that data availability is subject to capabilities of a
80 particular storage engine and its operational state, which leads to the design
81 decision that a `YangInstanceIdentifier` lookup needs to be performed in two
84 . A longest-prefix match is performed to locate the storage backend instance for
86 . Masked path elements are resolved by the storage engine
90 A process similar to the first step above is performed today by the Distributed
91 Data Store implementation to split data into Shards. The concept of a Shard as
92 currently implemented is limited to specifying namespaces, and it does not
93 allow for pluggable storage engines.
95 In context of the Conceptual Data Tree, the concept of a Shard is generalized
96 as the shorthand equivalent of a storage backend instance. A Shard can be
97 attached at any (even wildcard) `YangInstanceIdentifier`. This contract is
98 exposed via the `DOMShardedDataTree`, which is an MD-SAL SPI class that
99 implements an `YangInstanceIdentifier` -> `Shard` registry service. This is
100 an omnipresent MD-SAL service, Shard Registry, whose visibility scope is a
101 single OpenDaylight instance (i.e. a cluster member). *Shard Layout* refers
102 to the mapping information contained in this service.
104 === Federation, Replication and High Availability
106 Support for various multi-node scenarios is a concern outside of core MD-SAL.
107 If a particular scenario requires the shard layout to be replicated (either
108 fully or partially), it is up to Shard providers to maintain an omnipresent
109 service on each node, which in turn is responsible for dynamically registering
110 `DOMDataTreeShard` instances with the Shard Registry service.
112 Since the Shard Layout is strictly local to a particular OpenDaylight instance,
113 an OpenDaylight cluster is geared towards being asymmetric with each node
114 serving its own view of the data. This allows each node to project its local
115 operational details, as well as the partitioning of the data set being worked
116 on based on workload and node availability. Partial symmetry of the conceptual
117 data tree can still be maintained to the extent that a particular deployment
120 // Can you reword: "...OpenDaylight cluster is geared towards being asymmetric with each node serving its own view of the data." It should be two sentences. But i can't figure out how to split it.
125 ==== Data Tree Listener
127 A Data Tree Listener is a data consumer, for example a process that wants
128 to act on data after it has been introduced to the Conceptual Data Tree.
130 A Data Tree Listener implements the {mdsal-apidoc}DOMDataTreeListener.html[DOMDataTreeListener]
131 interface and registers itself using {mdsal-apidoc}DOMDataTreeService.html[DOMDataTreeService].
133 A Data Tree Listener may register for multiple subtrees. Each time it is
134 invoked it will be provided with the current state of all subtrees that it
138 // FIXME: Consider linking / inlining interface
140 .DOMDataTreeListener interface signature
143 public interface DOMDataTreeListener extends EventListener {
145 void onDataTreeChanged(Collection<DataTreeCandidate> changes, // (1)
146 Map<DOMDataTreeIdentifier, NormalizedNode<?, ?>> subtrees);
148 void onDataTreeFailed(Collection<DOMDataTreeListeningException> causes); // (2)
151 <1> Invoked when the data tree to which the Data Tree Listener is subscribed
152 to changed. `changes` contains the collection of changes, `subtrees`
153 contains the current state of all subtrees to which the listener is
155 <2> Invoked when a subtree listening failure occurs. For example, a failure
156 can be triggered when a connection to an external subtree source is
160 ==== Data Tree Producer
162 A Data Tree Producer represents source of data in system. Data TreeProducer
163 implementations are not required to implement a specific interface, but
164 use a {mdsal-apidoc}DOMDataTreeProducer.html[DOMDataTreeProducer] instance
165 to publish data (i.e. to modify the Conceptual Data Tree).
167 A Data Tree Producer is exclusively bound to one or more subtrees of the
168 Conceptual Data Tree, i.e. binding a Data Tree Producer to a subtree prevents
169 other Data Tree Producers from modifying the subtree.
171 * A failed Data Tree Producer still holds a calim to the namespace to which
172 it is bound (i.e. the exclusive lock of the subtree) untill it is closed.
174 {mdsal-apidoc}DOMDataTreeProducer.html[DOMDataTreeProducer] represents a
175 Data Tree Producer context
177 * allows transactions to be submitted to subtrees specified at creation
179 * at any given time there may be a single transaction open.
180 * once a transaction is submitted, it will proceed to be committed
185 // FIXME: Consider linking / inlining interface
187 .DOMDataTreeProducer interface signature
190 public interface DOMDataTreeProducer extends DOMDataTreeProducerFactory, AutoCloseable {
191 DOMDataWriteTransaction createTransaction(boolean isolated); // (1)
192 DOMDataTreeProducer createProducer(Collection<DOMDataTreeIdentifier> subtrees); // (2)
195 <1> Allocates a new transaction. All previously allocated transactions must
196 have been either submitted or canceled. Setting `isolated` to `true`
197 disables state compression for this transaction.
198 <2> Creates a sub-producer for the provided `subtrees`. The parent producer
199 loses the ability to access the specified paths until the resulting child
200 producer is shut down.
202 // Would it be better to say 'closed' rather than 'shut down'?
207 - *A Data Tree Shard* is always bound to either the `OPERATIONAL`, or the
208 `CONFIG` space, never to both at the same time.
210 - *Data Tree Shards* may be nested, the parent shard must be aware of sub-shards
211 and execute every request in context of a self-consistent view of sub-shards
212 liveness. Data requests passing through it must be multiplexed with sub-shard
215 // Can you reword or explain this" "... must execute every request in context of a self-consistent view of sub-shards liveness..."
217 - *Shard Layout* is local to an OpenDaylight instance.
219 - *Shard Layout* is modified by agents (registering / unregistering Data Tree
220 Shards) in order to make the Data Tree Shard and the underlaying data
221 available to local instance.
223 // '..available to local instance' of what?
225 ==== Registering a Shard
227 // '..Registering a Shard' with what?
229 NOTE: Namespace in this context means a Data Tree Identifier prefix.
231 . *Claim a namespace* - An agent that is registering a shard must prove that it
232 has sufficient rights to modify the subtree where the shard is going to be
233 attached. A namespace for the shard is claimed by binding a Data Tree Producer
234 instance to same subtree where the shard will be bound. The Data Tree Producer
235 must not have any open child producers, and it should not have any outstanding
238 . *Create a shard instance* - Once a namespace is claimed, the agent creates a
241 . *Attach shard* - The agent registers the created shard instance and provides
242 in the reigstration the Data Tree Producer instance to verify the namespace
243 claim. The newly created Shard is checked for its ability to cooperate with
244 its parent shard. If the check is successful, the newly created Shard is
245 attached to its parent shard and recorded in the Shard layout.
247 . *Remove namespace claim* (optional) - If the Shard is providing storage for
248 applications, the agent should close the Data Tree Producer instance to make
249 the subtree available to applications.
251 IMPORTANT: Steps 1, 2 and 3 may fail, and the recovery strategy depends
252 on which step failed and on the failure reason.
254 // FIXME: Describe possible failures and recovery scenarios