From 3013ae227e4fa919d69b0531dbf95707e85c31c1 Mon Sep 17 00:00:00 2001 From: Jukka Zitting Date: Mon, 4 Nov 2013 14:08:15 -0500 Subject: [PATCH 2/2] OAK-1126: Same node and property name support Adjust the NodeState contract to allow property and child node names to overlap --- .../apache/jackrabbit/oak/spi/state/NodeState.java | 4 ++-- oak-doc/src/site/markdown/nodestate.md | 25 +++++++++++----------- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/state/NodeState.java b/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/state/NodeState.java index 9c12c70..25315c9 100644 --- a/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/state/NodeState.java +++ b/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/state/NodeState.java @@ -28,8 +28,8 @@ import com.google.common.base.Predicate; * A node in a content tree consists of child nodes and properties, each * of which evolves through different states during its lifecycle. This * interface represents a specific, immutable state of a node. The state - * consists of an unordered set of name -> item mappings, where - * each item is either a property or a child node. + * consists of an unordered set of named properties and another of named + * child nodes. *

* Depending on context, a NodeState instance can be interpreted as * representing the state of just that node, of the subtree starting at diff --git a/oak-doc/src/site/markdown/nodestate.md b/oak-doc/src/site/markdown/nodestate.md index 2187ea5..e38f8f9 100644 --- a/oak-doc/src/site/markdown/nodestate.md +++ b/oak-doc/src/site/markdown/nodestate.md @@ -40,11 +40,11 @@ lays the foundation for the higher-level Oak API that's visible to clients. ## The state of a node -A _node_ in Oak is an unordered collection of named properties and child -nodes. As the content tree evolves through a sequence of revisions, a node -in it will go through a series of different states. A _node state_ then is -an _immutable_ snapshot of a specific state of a node and the subtree beneath -it. +A _node_ in Oak consists of an unordered collection of named properties and +another of named child nodes. As the content tree evolves through a sequence +of revisions, a node in it will go through a series of different states. +A _node state_ then is 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 @@ -60,10 +60,11 @@ 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 -information about it's location within a larger content tree. Instead each -property and child node state is uniquely named within a parent node state. -An algorithm that needs to know the path of a node can construct it from -the encountered names as it descends the tree structure. +information about it's location within a larger content tree. An algorithm +that needs to know the path of a node can construct it from the encountered +names as it descends the tree structure. Since child nodes are uniquely named +within a parent, the path of a node uniquely identifies it within the +content tree. Since node states are immutable, they are also easy to keep _thread-safe_. Implementations that use mutable data structures like caches or otherwise @@ -83,10 +84,8 @@ interface consists of three sets of methods: * The `compareAgainstBaseState` method for comparing states You can request a property or a child node by name, get the number of -properties or child nodes, or iterate through all of them. Even though -properties and child nodes are accessed through separate methods, they -share the same namespace so a given name can either refer to a property -or a child node, but not to both at the same time. +properties or child nodes, or iterate through all of them. It is possible +for a property and a child node to have the same name. Iteration order of properties and child nodes is _unspecified but stable_, so that re-iterating through the items of a _specific NodeState instance_ -- 1.8.3.msysgit.0