jackrabbit-oak-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ju...@apache.org
Subject svn commit: r1384292 - in /jackrabbit/oak/trunk/doc: ./ nodestate.md
Date Thu, 13 Sep 2012 12:08:59 GMT
Author: jukka
Date: Thu Sep 13 12:08:59 2012
New Revision: 1384292

URL: http://svn.apache.org/viewvc?rev=1384292&view=rev
OAK-301: Document Oak internals

Initial draft documentation about the NodeState model


Added: jackrabbit/oak/trunk/doc/nodestate.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/doc/nodestate.md?rev=1384292&view=auto
--- jackrabbit/oak/trunk/doc/nodestate.md (added)
+++ jackrabbit/oak/trunk/doc/nodestate.md Thu Sep 13 12:08:59 2012
@@ -0,0 +1,46 @@
+# Understanding the node state model
+This article describes the node state model that is the core design
+abstraction inside the oak-core component. Understanding the node state
+model is essential to working with Oak internals and to building custom
+Oak extensions.
+## Background
+Oak organizes all content in a large tree hierarcy that consists of nodes
+and properties. Each snapshot or revision of this content tree is immutable,
+and changes to the tree are expressed as a sequence of new revisions. The
+MicroKernel of an Oak repository is responsible for managing the content
+tree and its revisions.
+The JSON-based MicroKernel API works well as a part of a remote protocol
+but is cumbersome to use directly in oak-core. There are also many cases
+where transient or virtual content that doesn't (yet) exist in the
+MicroKernel needs to be managed by Oak. The node state model as expressed
+in the NodeState interface in oak-core is designed for these purposes. It
+provides a unified low-level abstraction for managing all tree content and
+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
+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.
+Since node states are immutable, they are also easy to keep _thread-safe_.
+Implementations that use mutable data structures like caches or otherwise
+aren't thread-safe by default, are expected to use other mechanisms like
+synchronization to ensure thread-safety.

View raw message