svn commit: r1868540 - /jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/compositens.md

[ro...@apache.org]

Author: rombert
Date: Thu Oct 17 08:44:14 2019
New Revision: 1868540

URL: http://svn.apache.org/viewvc?rev=1868540&view=rev
Log:
Improve the CompositeNodeStore documentation

Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/compositens.md

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/compositens.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/compositens.md?rev=1868540&r1=1868539&r2=1868540&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/compositens.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/compositens.md Thu Oct 17 08:44:14 2019
@@ -24,14 +24,50 @@ The `CompositeNodeStore` is a `NodeStore
 and exposes them through a single API. It is possible, for instance, to store all data in a 
 `DocumentNodeStore` instance and relocate `/libs` and `/apps` in a `SegmentNodeStore` instance.
 
-Each node stored wrapped by the composite node store instance is called a _mount_.
+Each node stored wrapped by the composite node store instance is called a _mount_. The
+`CompositeNodeStore` can be configured with one or more mounts, each owning a defined set
+of paths, and a _default mount_, owning the rest of the repository.
 
 ## Design limitations
 
+### Read-only mounts
+
 The implementation allows for a default mount, which is read-write, and for any number of 
 additional mounts, which are read-only. This limitation is by design and is not expected to
 be removed in future Oak version.
 
+There are two major aspects to this limitation
+
+1. Having a commit run accross two or more multiple node stores is complicated in terms of
+implementation. Atomic commits will be very hard to ensure in a performant manner across
+multiple stores. Additionally, it will impose implementation burders to each NodeStore
+in order to support this special-case scenario.
+1. There are multiple Oak subsystems that are not composite-aware and that would need to 
+changed for that to happen, and this would again complicate the implementation for a
+special-case scenario.
+
+### Referenceable nodes
+
+Referenceable nodes are not permitted in non-default mounts. The reason is cross-mount references
+can become invalid in scenarios where the set of mounts changes. Consider the following scenario:
+
+Mounts:
+
+* default mount `D`
+* non-default mount `N1`, currently mounted under /tmp
+* non-default mount `N2`, currently not mounted 
+
+In the repository, node `/content/bar` references referenceable node `/tmp/foo` (from N1). When
+the repository is shut down and reconfigureed to use N2 instead of N1, the  reference can be broken
+unless we ensure that the reference stores used by N1 and N2 are the same. This does not happen
+today.
+
+This constraint also means that:
+
+* versionable nodes are not permitted in non-default mounts, as they are referenceable
+* `nt:resource` nodes (usually found as children of `nt:file` nodes) are not permitted. It is recommended
+  to replace them with `oak:Resource` ( see also [OAK-4567](https://issues.apache.org/jira/browse/OAK-4567) ).
+
 ## Checking for read-only access
 
 The Composite NodeStore mounts various other node stores in read-only mode. Since the read-only mode