You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by ju...@apache.org on 2013/04/22 15:12:00 UTC
svn commit: r1470487 - in /jackrabbit/oak/trunk/doc: nodestate-r1.png
nodestate-r1.uxf nodestate-r2.png nodestate-r2.uxf nodestate.md
Author: jukka
Date: Mon Apr 22 13:12:00 2013
New Revision: 1470487
URL: http://svn.apache.org/r1470487
Log:
OAK-781: Clarify / fix effects of MISSING_NODE as base state of NodeBuilder
Start improving documentation on NodeState/Builder especially about the exists() mechanism
Added:
jackrabbit/oak/trunk/doc/nodestate-r1.png (with props)
jackrabbit/oak/trunk/doc/nodestate-r1.uxf
jackrabbit/oak/trunk/doc/nodestate-r2.png (with props)
jackrabbit/oak/trunk/doc/nodestate-r2.uxf
Modified:
jackrabbit/oak/trunk/doc/nodestate.md
Added: jackrabbit/oak/trunk/doc/nodestate-r1.png
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/doc/nodestate-r1.png?rev=1470487&view=auto
==============================================================================
Binary file - no diff available.
Propchange: jackrabbit/oak/trunk/doc/nodestate-r1.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: jackrabbit/oak/trunk/doc/nodestate-r1.uxf
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/doc/nodestate-r1.uxf?rev=1470487&view=auto
==============================================================================
--- jackrabbit/oak/trunk/doc/nodestate-r1.uxf (added)
+++ jackrabbit/oak/trunk/doc/nodestate-r1.uxf Mon Apr 22 13:12:00 2013
@@ -0,0 +1,194 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<diagram program="umlet" version="12.0">
+ <zoom_level>10</zoom_level>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>250</x>
+ <y>180</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=yellow</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>210</x>
+ <y>110</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=yellow</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>160</x>
+ <y>40</y>
+ <w>80</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<-</panel_attributes>
+ <additional_attributes>60;70;30;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>130</x>
+ <y>110</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=green</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>170</x>
+ <y>40</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=yellow</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>50</x>
+ <y>110</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=green</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>90</x>
+ <y>40</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=green</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>0</x>
+ <y>110</y>
+ <w>80</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<-
+</panel_attributes>
+ <additional_attributes>30;70;60;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>200</x>
+ <y>110</y>
+ <w>80</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<-</panel_attributes>
+ <additional_attributes>60;70;30;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>10</x>
+ <y>180</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=green</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>40</x>
+ <y>110</y>
+ <w>80</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<-</panel_attributes>
+ <additional_attributes>60;70;30;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>50</x>
+ <y>40</y>
+ <w>150</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<-
+</panel_attributes>
+ <additional_attributes>30;70;130;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>40</x>
+ <y>40</y>
+ <w>80</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<-
+</panel_attributes>
+ <additional_attributes>30;70;60;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>80</x>
+ <y>40</y>
+ <w>80</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<-</panel_attributes>
+ <additional_attributes>60;70;30;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>90</x>
+ <y>180</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=green</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.custom.Text</type>
+ <coordinates>
+ <x>170</x>
+ <y>10</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>r2</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.custom.Text</type>
+ <coordinates>
+ <x>90</x>
+ <y>10</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>r1</panel_attributes>
+ <additional_attributes/>
+ </element>
+</diagram>
Added: jackrabbit/oak/trunk/doc/nodestate-r2.png
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/doc/nodestate-r2.png?rev=1470487&view=auto
==============================================================================
Binary file - no diff available.
Propchange: jackrabbit/oak/trunk/doc/nodestate-r2.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: jackrabbit/oak/trunk/doc/nodestate-r2.uxf
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/doc/nodestate-r2.uxf?rev=1470487&view=auto
==============================================================================
--- jackrabbit/oak/trunk/doc/nodestate-r2.uxf (added)
+++ jackrabbit/oak/trunk/doc/nodestate-r2.uxf Mon Apr 22 13:12:00 2013
@@ -0,0 +1,216 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<diagram program="umlet" version="12.0">
+ <zoom_level>10</zoom_level>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>60</x>
+ <y>190</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=green</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.custom.Text</type>
+ <coordinates>
+ <x>140</x>
+ <y>20</y>
+ <w>130</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>with access control</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>20</x>
+ <y>120</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=green</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>230</x>
+ <y>120</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=white
+bt=.
+</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>150</x>
+ <y>120</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=white
+bt=.</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.custom.Text</type>
+ <coordinates>
+ <x>230</x>
+ <y>80</y>
+ <w>40</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>baz</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>190</x>
+ <y>50</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=green</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.custom.Text</type>
+ <coordinates>
+ <x>30</x>
+ <y>20</y>
+ <w>90</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>raw content</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>140</x>
+ <y>120</y>
+ <w>80</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<-</panel_attributes>
+ <additional_attributes>60;70;30;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>140</x>
+ <y>50</y>
+ <w>80</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<.</panel_attributes>
+ <additional_attributes>30;70;60;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.custom.Text</type>
+ <coordinates>
+ <x>20</x>
+ <y>160</y>
+ <w>40</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bar</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>180</x>
+ <y>50</y>
+ <w>80</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<.</panel_attributes>
+ <additional_attributes>60;70;30;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>190</x>
+ <y>190</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=green</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>10</x>
+ <y>50</y>
+ <w>80</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<-</panel_attributes>
+ <additional_attributes>30;70;60;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.Class</type>
+ <coordinates>
+ <x>60</x>
+ <y>50</y>
+ <w>30</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bg=green</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.custom.Text</type>
+ <coordinates>
+ <x>150</x>
+ <y>80</y>
+ <w>40</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>foo</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.Relation</type>
+ <coordinates>
+ <x>10</x>
+ <y>120</y>
+ <w>80</w>
+ <h>90</h>
+ </coordinates>
+ <panel_attributes>lt=<-</panel_attributes>
+ <additional_attributes>60;70;30;30</additional_attributes>
+ </element>
+ <element>
+ <type>com.umlet.element.custom.Text</type>
+ <coordinates>
+ <x>20</x>
+ <y>80</y>
+ <w>40</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>foo</panel_attributes>
+ <additional_attributes/>
+ </element>
+ <element>
+ <type>com.umlet.element.custom.Text</type>
+ <coordinates>
+ <x>150</x>
+ <y>160</y>
+ <w>40</w>
+ <h>30</h>
+ </coordinates>
+ <panel_attributes>bar</panel_attributes>
+ <additional_attributes/>
+ </element>
+</diagram>
Modified: jackrabbit/oak/trunk/doc/nodestate.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/doc/nodestate.md?rev=1470487&r1=1470486&r2=1470487&view=diff
==============================================================================
--- jackrabbit/oak/trunk/doc/nodestate.md (original)
+++ jackrabbit/oak/trunk/doc/nodestate.md Mon Apr 22 13:12:00 2013
@@ -46,6 +46,17 @@ in it will go through a series of differ
an _immutable_ snapshot of a specific state of a node and the subtree beneath
it.
+As an example, the following diagram shows two revisions of a content tree,
+the first revision consists of five nodes, and in the second revision a
+sixth node is added in one of the subtrees. Note how unmodified subtrees
+can be shared across revisions, while only the modified nodes and their
+ancestors up to the root (shown in yellow) need to be updated to reflect
+the change. This way both revisions remain readable at all times without
+the implementation having to make a separate copy of the entire repository
+for each revision.
+
+
+
To avoid making a special case of the root node and therefore to make it
easy to write algorithms that can recursively process each subtree as a
standalone content tree, a node state is _unnamed_ and does not contain
@@ -67,6 +78,7 @@ interface consists of three sets of meth
* Methods for accessing properties
* Methods for accessing child nodes
+ * The `exists` method for checking whether the node exists or is accessible
* The `builder` method for building modified states
* The `compareAgainstBaseState` method for comparing states
@@ -82,10 +94,56 @@ will return the items in the same order
is not defined nor does it necessarily remain the same across different
instances.
-The last two methods, `builder` and `compareAgainstBaseState`, are
-covered in the next two sections. See also the `NodeState` javadocs for
+The last three methods, `exists`, `builder` and `compareAgainstBaseState`,
+are covered in the next sections. See also the `NodeState` javadocs for
more details about this interface and all its methods.
+## Existence and iterability of node states
+
+The `exists` method makes it possible to always traverse any path regardless
+of whether the named content exists or not. The `getChildNode` method returns
+a child `NodeState` instance for any given name, and the caller is expected
+to use the `exists` method to check whether the named node actually does exist.
+The purpose of this feature is to allow paths like `/foo/bar` to be traversed
+even if the current user only has read access to the `bar` node but not its
+parent `foo`. As a consequence it's even possible to access content like a
+fictional `/bar` subtree that doesn't exist at all. A piece of code for
+accessing such content could look like this:
+
+```java
+NodeState root = ...;
+
+NodeState foo = root.getChildNode("foo");
+assert !foo.exists();
+NodeState bar = foo.getChildNode("bar");
+assert bar.exists();
+
+NodeState baz = root.getChildNode("baz");
+assert !baz.exists();
+```
+
+The following diagram illustrates such a content tree, both as the raw
+content that simply exists and as an access controlled view of that tree:
+
+
+
+If a node is missing, i.e. its `exists` method returns `false` and thus it
+either does not exist at all or is read-protected, one can't list any of
+its properties or child nodes. And on the other hand, a non-readable node or
+property will only show up when listing the child nodes or properties of its
+parent. In other words, a node or a property is _iterable_ only if both it
+and its parent are readable. For example, attempts to list properties or
+child nodes of the node `foo` will show up empty:
+
+```java
+assert !foo.getProperties().iterator().hasNext();
+assert !foo.getChildNodeEntries().iterator().hasNext();
+```
+
+Note that without some external knowledge about the accessibility of a child
+node like `bar` there's no way for a piece of code to distinguish between
+the existing but non-readable node `foo` and the non-existing node `baz`.
+
## Building new node states
Since node states are immutable, a separate builder interface,