jackrabbit-oak-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ju...@apache.org
Subject svn commit: r1470487 - in /jackrabbit/oak/trunk/doc: nodestate-r1.png nodestate-r1.uxf nodestate-r2.png nodestate-r2.uxf nodestate.md
Date Mon, 22 Apr 2013 13:12:00 GMT
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=&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=&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=&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=&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=&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=&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=&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=&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=&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=&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=&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=&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.
+
+![two revisions of a content tree](nodestate-r1.png?raw=true)
+
 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:
+
+![content tree with and without access control](nodestate-r2.png?raw=true)
+
+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,



Mime
View raw message