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
