You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by th...@apache.org on 2014/10/06 15:35:12 UTC
svn commit: r1629650 [4/9] - in /jackrabbit/site/live/oak/docs: ./
architecture/ coldstandby/ nodestore/ oak_api/ plugins/ security/
security/accesscontrol/ security/authentication/ security/permission/
security/principal/ security/privilege/ security/...
Added: jackrabbit/site/live/oak/docs/differences_user.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/differences_user.html?rev=1629650&view=auto
==============================================================================
--- jackrabbit/site/live/oak/docs/differences_user.html (added)
+++ jackrabbit/site/live/oak/docs/differences_user.html Mon Oct 6 13:35:10 2014
@@ -0,0 +1,806 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2014-04-15
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="Date-Revision-yyyymmdd" content="20140415" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Jackrabbit Oak - User Management : Differences to Jackrabbit 2.x</title>
+ <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
+ <link rel="stylesheet" href="./css/site.css" />
+ <link rel="stylesheet" href="./css/print.css" media="print" />
+
+
+ <script type="text/javascript" src="./js/apache-maven-fluido-1.3.0.min.js"></script>
+
+
+ </head>
+ <body class="topBarEnabled">
+
+
+
+
+
+
+ <a href="http://github.com/apache/jackrabbit-oak">
+ <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"
+ src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"
+ alt="Fork me on GitHub">
+ </a>
+
+
+
+
+
+ <div id="topbar" class="navbar navbar-fixed-top ">
+ <div class="navbar-inner">
+ <div class="container-fluid">
+ <a data-target=".nav-collapse" data-toggle="collapse" class="btn btn-navbar">
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </a>
+
+ <ul class="nav">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Overview <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="index.html" title="Jackrabbit Oak">Jackrabbit Oak</a>
+</li>
+
+ <li> <a href="license.html" title="License">License</a>
+</li>
+
+ <li> <a href="downloads.html" title="Downloads">Downloads</a>
+</li>
+
+ <li> <a href="from_here.html" title="From here">From here</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts and architecture <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="overview.html" title="Overview">Overview</a>
+</li>
+
+ <li> <a href="nodestate.html" title="The node state model">The node state model</a>
+</li>
+
+ <li> <a href="microkernel.html" title="NodesStore and MicroKernel">NodesStore and MicroKernel</a>
+</li>
+
+ <li> <a href="query.html" title="Query">Query</a>
+</li>
+
+ <li> <a href="blobstore.html" title="BlobStore">BlobStore</a>
+</li>
+
+ <li> <a href="security/overview.html" title="Security">Security</a>
+</li>
+
+ <li> <a href="clustering.html" title="Clustering">Clustering</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Using Oak <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="use_getting_started.html" title="Getting Started">Getting Started</a>
+</li>
+
+ <li> <a href="differences.html" title="Differences to Jackrabbit 2">Differences to Jackrabbit 2</a>
+</li>
+
+ <li> <a href="osgi_config.html" title="Configuring Oak">Configuring Oak</a>
+</li>
+
+ <li> <a href="known_issues.html" title="Known Issues">Known Issues</a>
+</li>
+
+ <li> <a href="dos_and_donts.html" title="Dos and don'ts">Dos and don'ts</a>
+</li>
+
+ <li> <a href="when_things_go_wrong.html" title="When things go wrong">When things go wrong</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developing Oak <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="dev_getting_started.html" title="Getting Started">Getting Started</a>
+</li>
+
+ <li> <a href="participating.html" title="Participating">Participating</a>
+</li>
+
+ <li> <a href="apidocs/index.html" title="API docs">API docs</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Links <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="http://jackrabbit.apache.org/oak" title="Apache Jackrabbit Oak">Apache Jackrabbit Oak</a>
+</li>
+
+ <li> <a href="http://jackrabbit.apache.org/" title="Apache Jackrabbit">Apache Jackrabbit</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+
+
+
+
+ </div>
+
+ </div>
+ </div>
+ </div>
+
+ <div class="container-fluid">
+ <div id="banner">
+ <div class="pull-left">
+ <div id="bannerLeft">
+ <h2>Oak Documentation</h2>
+ </div>
+ </div>
+ <div class="pull-right"> </div>
+ <div class="clear"><hr/></div>
+ </div>
+
+ <div id="breadcrumbs">
+ <ul class="breadcrumb">
+
+
+ <li id="publishDate">Last Published: 2014-04-15</li>
+ <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
+
+
+
+
+ </ul>
+ </div>
+
+
+ <div class="row-fluid">
+ <div id="leftColumn" class="span3">
+ <div class="well sidebar-nav">
+
+
+ <ul class="nav nav-list">
+ <li class="nav-header">Overview</li>
+
+ <li>
+
+ <a href="index.html" title="Jackrabbit Oak">
+ <i class="none"></i>
+ Jackrabbit Oak</a>
+ </li>
+
+ <li>
+
+ <a href="license.html" title="License">
+ <i class="none"></i>
+ License</a>
+ </li>
+
+ <li>
+
+ <a href="downloads.html" title="Downloads">
+ <i class="none"></i>
+ Downloads</a>
+ </li>
+
+ <li>
+
+ <a href="from_here.html" title="From here">
+ <i class="none"></i>
+ From here</a>
+ </li>
+ <li class="nav-header">Concepts and architecture</li>
+
+ <li>
+
+ <a href="overview.html" title="Overview">
+ <i class="none"></i>
+ Overview</a>
+ </li>
+
+ <li>
+
+ <a href="nodestate.html" title="The node state model">
+ <i class="none"></i>
+ The node state model</a>
+ </li>
+
+ <li>
+
+ <a href="microkernel.html" title="NodesStore and MicroKernel">
+ <i class="none"></i>
+ NodesStore and MicroKernel</a>
+ </li>
+
+ <li>
+
+ <a href="query.html" title="Query">
+ <i class="none"></i>
+ Query</a>
+ </li>
+
+ <li>
+
+ <a href="blobstore.html" title="BlobStore">
+ <i class="none"></i>
+ BlobStore</a>
+ </li>
+
+ <li>
+
+ <a href="security/overview.html" title="Security">
+ <i class="none"></i>
+ Security</a>
+ </li>
+
+ <li>
+
+ <a href="clustering.html" title="Clustering">
+ <i class="none"></i>
+ Clustering</a>
+ </li>
+ <li class="nav-header">Using Oak</li>
+
+ <li>
+
+ <a href="use_getting_started.html" title="Getting Started">
+ <i class="none"></i>
+ Getting Started</a>
+ </li>
+
+ <li>
+
+ <a href="differences.html" title="Differences to Jackrabbit 2">
+ <i class="none"></i>
+ Differences to Jackrabbit 2</a>
+ </li>
+
+ <li>
+
+ <a href="osgi_config.html" title="Configuring Oak">
+ <i class="none"></i>
+ Configuring Oak</a>
+ </li>
+
+ <li>
+
+ <a href="known_issues.html" title="Known Issues">
+ <i class="none"></i>
+ Known Issues</a>
+ </li>
+
+ <li>
+
+ <a href="dos_and_donts.html" title="Dos and don'ts">
+ <i class="none"></i>
+ Dos and don'ts</a>
+ </li>
+
+ <li>
+
+ <a href="when_things_go_wrong.html" title="When things go wrong">
+ <i class="none"></i>
+ When things go wrong</a>
+ </li>
+ <li class="nav-header">Developing Oak</li>
+
+ <li>
+
+ <a href="dev_getting_started.html" title="Getting Started">
+ <i class="none"></i>
+ Getting Started</a>
+ </li>
+
+ <li>
+
+ <a href="participating.html" title="Participating">
+ <i class="none"></i>
+ Participating</a>
+ </li>
+
+ <li>
+
+ <a href="apidocs/index.html" title="API docs">
+ <i class="none"></i>
+ API docs</a>
+ </li>
+ <li class="nav-header">Links</li>
+
+ <li>
+
+ <a href="http://jackrabbit.apache.org/oak" class="externalLink" title="Apache Jackrabbit Oak">
+ <i class="none"></i>
+ Apache Jackrabbit Oak</a>
+ </li>
+
+ <li>
+
+ <a href="http://jackrabbit.apache.org/" class="externalLink" title="Apache Jackrabbit">
+ <i class="none"></i>
+ Apache Jackrabbit</a>
+ </li>
+ </ul>
+
+
+
+ <hr class="divider" />
+
+ <div id="poweredBy">
+
+ <script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>
+
+
+ <div class="g-plusone" data-href="http://jackrabbit.apache.org/oak-doc/" data-size="tall" ></div>
+
+ <div class="clear"></div>
+ <div class="clear"></div>
+ <div class="clear"></div>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
+ </a>
+ </div>
+ </div>
+ </div>
+
+
+ <div id="bodyColumn" class="span9" >
+
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. --><div class="section">
+<div class="section">
+<h3>User Management : Differences to Jackrabbit 2.x<a name="User_Management_:_Differences_to_Jackrabbit_2.x"></a></h3>
+<div class="section">
+<h4>1. Characteristics of the Default Implementation<a name="a1._Characteristics_of_the_Default_Implementation"></a></h4>
+<p>The default user management implementation present with OAK always stores user/group information in the workspace associated with the editing Session (see Jackrabbit 2.x <tt>UserPerWorkspaceUserManager</tt>). The implementation of a user management variant corresponding to Jackrabbit’s default <tt>UserManagerImpl</tt> is blocked by missing workspace handling (see <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-118">OAK-118</a>). The current user manager has the following characteristics that differ from the corresponding Jackrabbit implementation:</p>
+<div class="section">
+<h5>General<a name="General"></a></h5>
+
+<ul>
+
+<li>Changes made to the user management API are always transient and require <tt>Session#save()</tt> to be persisted.</li>
+
+<li>In case of a failure <tt>Session#refresh</tt> is no longer called in order to prevent reverting other changes unrelated to the user management operation. Consequently it’s the responsibility of the API consumer to specifically revert pending or invalid transient modifications.</li>
+
+<li>The implementation is no longer built on top of the JCR API but instead directly acts on <tt>Tree</tt> and <tt>PropertyState</tt> defined by the OAK API. This move allows to make use of the user management API within the OAK layer (aka SPI).</li>
+</ul></div>
+<div class="section">
+<h5>User/Group Creation<a name="UserGroup_Creation"></a></h5>
+
+<ul>
+
+<li>The <tt>rep:password</tt> property is no longer defined to be mandatory. Therefore a new user might be created without specifying a password. Note however, that <tt>User#changePassword</tt> does not allow to remove the password property.</li>
+
+<li><tt>UserManager#createGroup(Principal)</tt> will no longer generate a groupID in case the principal name collides with an existing user or group ID. This has been considered redundant as the Jackrabbit API in the mean time added <tt>UserManager#createGroup(String groupID)</tt>.</li>
+
+<li>Since OAK is designed to scale with flat hierarchies the former configuration options <tt>autoExpandTree</tt> and <tt>autoExpandSize</tt> are no longer supported.</li>
+</ul></div>
+<div class="section">
+<h5>Handling of the Authorizable ID<a name="Handling_of_the_Authorizable_ID"></a></h5>
+
+<ul>
+
+<li>As of OAK the node type definition of <tt>rep:Authorizable</tt> defines a new property <tt>rep:authorizableId</tt> which is intended to store the ID of a user or group.</li>
+
+<li>The default implementation comes with a dedicated property index for <tt>rep:authorizableId</tt> which asserts the uniqueness of that ID.</li>
+
+<li><tt>Authorizable#getID</tt> returns the string value contained in <tt>rep:authorizableID</tt> and for backwards compatibility falls back on the node name in case the ID property is missing.</li>
+
+<li>The name of the authorizable node is generated based on a configurable implementation of the <tt>AuthorizableNodeName</tt> interface (see configuration section below). By default it uses the ID as name hint and includes a conversion to a valid JCR node name.</li>
+</ul></div>
+<div class="section">
+<h5>equals() and hashCode() for Authorizables<a name="equals_and_hashCode_for_Authorizables"></a></h5>
+<p>The implementation of <tt>Object#equals()</tt> and <tt>Object#hashCode()</tt> for user and groups slightly differs from Jackrabbit 2.x. It no longer relies on the <i>sameness</i> of the underlaying JCR node but only compares IDs and the user manager instance.</p></div>
+<div class="section">
+<h5>The <i>everyone</i> Group<a name="The_everyone_Group"></a></h5>
+<p>As in Jackrabbit 2.x the OAK implementation contains special handling for the optional group corresponding to the <tt>EveryonePrincipal</tt> which always contains all Authorizable as member. As of OAK this fact is consistently reflected in all group membership related methods.</p></div>
+<div class="section">
+<h5>Query<a name="Query"></a></h5>
+<p>The user query is expected to work as in Jackrabbit 2.x with the following notable differences:</p>
+
+<ul>
+
+<li><tt>QueryBuilder#setScope(String groupID, boolean declaredOnly)</tt> now also works properly for the everyone group (see <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-949">OAK-949</a>)</li>
+
+<li><tt>QueryBuilder#impersonates(String principalName)</tt> works properly for the admin principal which are specially treated in the implementation of the <tt>Impersonation</tt> interface (see <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-1183">OAK-1183</a>).</li>
+</ul></div>
+<div class="section">
+<h5>Autosave Behavior<a name="Autosave_Behavior"></a></h5>
+<p>Due to the nature of the UserManager (see above) we decided to drop the auto-save behavior in the default implementation present with OAK. Consequently,</p>
+
+<ul>
+
+<li><tt>UserManager#autoSave(boolean)</tt> throws <tt>UnsupportedRepositoryOperationException</tt></li>
+
+<li><tt>UserManager#isAutoSave()</tt> always returns <tt>false</tt></li>
+</ul>
+<p>See also <tt>PARAM_SUPPORT_AUTOSAVE</tt> below; while this should not be needed if application code has been written against the Jackrabbit API (and thus testing if auto-save mode is enabled or not) this configuration option can be used as last resort.</p></div>
+<div class="section">
+<h5>XML Import<a name="XML_Import"></a></h5>
+<p>As of OAK 1.0 user and group nodes can be imported both with Session and Workspace import. The difference compare to Jackrabbit 2.x are listed below:</p>
+
+<ul>
+
+<li>Importing an authorizable to another tree than the configured user/group node will only failed upon save (-> see <tt>UserValidator</tt> during the <tt>Root#commit</tt>). With Jackrabbit 2.x core it used to fail immediately.</li>
+
+<li>NEW: The <tt>BestEffort</tt> behavior is now also implemented for the import of impersonators (was missing in Jackrabbit /2.x).</li>
+
+<li>NEW: Workspace Import</li>
+</ul></div>
+<div class="section">
+<h5>Group Membership<a name="Group_Membership"></a></h5>
+<div class="section">
+<h6>Behavior in Jackrabbit 2.x<a name="Behavior_in_Jackrabbit_2.x"></a></h6>
+<p>With the default configuration Jackrabbit 2.x stores the group members as <i>weak references</i> in a <tt>rep:members</tt> multi value property in the group node. If the <tt>groupMembershipSplitSize</tt> configuration parameter is set and valid, the group memberships are collected in a node structure below <tt>rep:members</tt> instead of the default multi valued property. Its value determines the maximum number of member properties until additional intermediate nodes are inserted. Valid parameter values are integers > 4. The node structure is a balanced b-tree where only the leave nodes carry the actual values in residual properties which name is the principal name of the member.</p></div>
+<div class="section">
+<h6>Behavior as of OAK 1.0<a name="Behavior_as_of_OAK_1.0"></a></h6>
+<p>As of Oak the user manager automatically chooses an appropriate storage structure depending on the number of group members. If the number of members is low they are stored as <i>weak references</i> in a <tt>rep:members</tt> multi value property. This is similar to Jackrabbit 2.x. If the number of members is high the user manager will limit the size of the multi value properties and create overflow <tt>rep:MemberReferences</tt> nodes below a <tt>rep:membersList</tt> node to hold the extra members.</p></div>
+<div class="section">
+<h6>Relevant new and modified node types<a name="Relevant_new_and_modified_node_types"></a></h6>
+
+<div class="source">
+<pre>[rep:Group] > rep:Authorizable, rep:MemberReferences
+ + rep:members (rep:Members) = rep:Members multiple protected VERSION /* @deprecated */
+ + rep:membersList (rep:MemberReferencesList) = rep:MemberReferencesList protected COPY
+
+[rep:MemberReferences]
+ - rep:members (WEAKREFERENCE) protected multiple < 'rep:Authorizable'
+
+[rep:MemberReferencesList]
+ + * (rep:MemberReferences) = rep:MemberReferences protected COPY
+</pre></div></div>
+<div class="section">
+<h6>Example Group with few members<a name="Example_Group_with_few_members"></a></h6>
+<p><i>(irrelevant properties excluded)</i></p>
+
+<div class="source">
+<pre>{
+ "jcr:primaryType": "rep:Group",
+ "rep:principalName": "contributor",
+ "rep:members": [
+ "429bbd5b-46a6-3c3d-808b-5fd4219d5c4d",
+ "ca58c408-fe06-357e-953c-2d23ffe1e096",
+ "3ebb1c04-76dd-317e-a9ee-5164182bc390",
+ "d3c827d3-4db2-30cc-9c41-0ed8117dbaff",
+ "f5777a0b-a933-3b4d-9405-613d8bc39cc7",
+ "fdd1547a-b19a-3154-90da-1eae8c2c3504",
+ "65c3084e-abfc-3719-8223-72c6cb9a3d6f"
+ ]
+}
+</pre></div></div>
+<div class="section">
+<h6>Example Group with many members<a name="Example_Group_with_many_members"></a></h6>
+<p><i>(irrelevant properties excluded)</i></p>
+
+<div class="source">
+<pre>{
+ "jcr:primaryType": "rep:Group",
+ "rep:principalName": "employees",
+ "rep:membersList": {
+ "jcr:primaryType": "rep:MemberReferencesList",
+ "0": {
+ "jcr:primaryType": "rep:MemberReferences",
+ "rep:members": [
+ "429bbd5b-46a6-3c3d-808b-5fd4219d5c4d",
+ "ca58c408-fe06-357e-953c-2d23ffe1e096",
+ ...
+ ]
+ },
+ ...
+ "341": {
+ "jcr:primaryType": "rep:MemberReferences",
+ "rep:members": [
+ "fdd1547a-b19a-3154-90da-1eae8c2c3504",
+ "65c3084e-abfc-3719-8223-72c6cb9a3d6f",
+ ...
+ ]
+ }
+ }
+}
+</pre></div>
+<p><i>Note</i>: The exact threshold value that determines the storage strategy is an implementation detail and might even vary depending on the underlying persistence layer.</p></div>
+<div class="section">
+<h6>Upgrading Groups from Jackrabbit 2.x to OAK content structure<a name="Upgrading_Groups_from_Jackrabbit_2.x_to_OAK_content_structure"></a></h6>
+<p>Upon upgrade from a Jackrabbit 2.x repository to OAK the group member lists that adjusted to reflect the new content structure as created by the OAK user management implementation; this means that the group member node structure will be changed by the migration process. Applications that rely on these implementation details of Jackrabbit 2.x user management instead of use the corresponding API calls will need to be modified accordingly.</p></div>
+<div class="section">
+<h6>Importing Group Members<a name="Importing_Group_Members"></a></h6>
+<p>Importing group members through the import methods in <tt>javax.jcr.Session</tt> or <tt>javax.jcr.Workspace</tt> is storage agnostic and supports both, property based and node based, strategies and is backward compatible to content exported from Jackrabbit 2.x. The group member lists that are modified during an import are internally processed using the normal user manager APIs. This implies that the node structure after the import might not be the same as the one represented in the input.</p></div></div></div>
+<div class="section">
+<h4>2. Builtin Users<a name="a2._Builtin_Users"></a></h4>
+<p>The setup of builtin user and group accounts is triggered by the configured <tt>WorkspaceInitializer</tt> associated with the user management configuration (see Configuration section below). </p>
+<p>The default user management implementation in OAK comes with an initializer that creates the following builtin user accounts (as in Jackrabbit 2.x):</p>
+<div class="section">
+<h5>Administrator User<a name="Administrator_User"></a></h5>
+<p>The admin user is always being created. The ID of this user is retrieved from the user configuration parameter <tt>PARAM_ADMIN_ID</tt>, which defaults to <tt>admin</tt>.</p>
+<p>As of OAK 1.0 however the administrator user might be created without initial password forcing the application to set the password upon start (see <tt>PARAM_OMIT_ADMIN_PW</tt> configuration parameter).</p></div>
+<div class="section">
+<h5>Anonymous User<a name="Anonymous_User"></a></h5>
+<p>In contrast to Jackrabbit 2.x the anonymous (or guest) user is optional. Creation will be skipped if the value of the <tt>PARAM_ANONYMOUS_ID</tt> configuration parameter is <tt>null</tt> or empty.</p>
+<p>Note, that the anonymous user will always be created without specifying a password in order to prevent login with SimpleCredentials. </p>
+<p>The proper way to obtain a guest session is (see also <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-793">OAK-793</a>):</p>
+
+<div class="source">
+<pre>Repository#login(new GuestCredentials(), wspName);
+</pre></div></div></div>
+<div class="section">
+<h4>3. Authorizable Actions<a name="a3._Authorizable_Actions"></a></h4>
+<p>The former internal interface <tt>AuthorizableAction</tt> has been slightly adjusted to match OAK requirements and is now part of the public OAK SPI interfaces. In contrast to Jackrabbit-core the AuthorizableAction(s) now operate directly on the OAK API which eases the handling of implementation specific tasks such as writing protected items.</p>
+<p>The example implementations of the <tt>AuthorizableAction</tt> interface present with OAK match the implementations available with Jackrabbit 2.x:</p>
+
+<ul>
+
+<li><tt>AccessControlAction</tt>: set up permission for new authorizables</li>
+
+<li><tt>PasswordAction</tt>: simplistic password verification upon user creation and password modification</li>
+
+<li><tt>PasswordChangeAction</tt>: verifies that the new password is different from the old one</li>
+
+<li><tt>ClearMembershipAction</tt>: clear group membership upon removal of an authorizable.</li>
+</ul>
+<p>As in jackrabbit core the actions are executed with the editing session and the target operation will fail if any of the configured actions fails (e.g. due to insufficient permissions by the editing OAK ContentSession).</p>
+<p>In order to match the OAK repository configuration setup and additional interface AuthorizableActionProvider has been introduced. See section Configuration below.</p></div>
+<div class="section">
+<h4>4. Node Type Definitions<a name="a4._Node_Type_Definitions"></a></h4>
+<p>The built-in node types related to user management tasks have been modified as follows:</p>
+
+<div class="source">
+<pre>[rep:Authorizable] > mix:referenceable, nt:hierarchyNode
+ abstract
+ + * (nt:base) = nt:unstructured VERSION
+ - rep:principalName (STRING) protected mandatory
+ - rep:authorizableId (STRING) protected /* @since oak 1.0 */
+ - * (UNDEFINED)
+ - * (UNDEFINED) multiple
+
+[rep:Group] > rep:Authorizable, rep:MemberReferences
+ + rep:members (rep:Members) = rep:Members multiple protected VERSION /* @deprecated */
+ + rep:membersList (rep:MemberReferencesList) = rep:MemberReferencesList protected COPY
+
+/** @since oak 1.0 */
+[rep:MemberReferences]
+ - rep:members (WEAKREFERENCE) protected multiple < 'rep:Authorizable'
+
+/** @since oak 1.0 */
+[rep:MemberReferencesList]
+ + * (rep:MemberReferences) = rep:MemberReferences protected COPY
+
+/** @deprecated since oak 1.0 */
+[rep:Members]
+ orderable
+ + * (rep:Members) = rep:Members protected multiple
+ - * (WEAKREFERENCE) protected < 'rep:Authorizable'
+</pre></div></div>
+<div class="section">
+<h4>5. API Extensions<a name="a5._API_Extensions"></a></h4>
+<p>The OAK project introduces the following user management related public interfaces and classes:</p>
+<p><tt>org.apache.jackrabbit.oak.spi.security.user.*</tt></p>
+
+<ul>
+
+<li><tt>AuthorizableNodeName</tt> : Defines the generation of the authorizable node names in case the user management implementation stores user information in the repository.</li>
+
+<li><tt>AuthorizableType</tt> : Ease handling with the different authorizable types.</li>
+
+<li><tt>UserConstants</tt> : Constants (NOTE: OAK names/paths)</li>
+</ul>
+<p><tt>org.apache.jackrabbit.oak.spi.security.user.action.*</tt></p>
+
+<ul>
+
+<li><tt>AuthorizableAction</tt> : (see above)</li>
+
+<li><tt>AuthorizableActionProvider</tt> : (see above)</li>
+</ul>
+<p><tt>org.apache.jackrabbit.oak.spi.security.user.util.*</tt></p>
+
+<ul>
+
+<li><tt>PasswordUtil</tt> : Utilities for password generation. This utility corresponds to the internal jackrabbit utility. As of OAK it also supports Password-Based Key Derivation Function 2 (PBKDF2) function for password generation.</li>
+
+<li><tt>UserUtil</tt> : Utilities related to general user management tasks.</li>
+</ul></div>
+<div class="section">
+<h4>6. Configuration<a name="a6._Configuration"></a></h4>
+<p>The following configuration options are present with the <tt>UserConfiguration</tt> as of OAK 1.0:</p>
+
+<ul>
+
+<li>getUserManager: Obtain a new user manager instance</li>
+
+<li>getAuthorizableActionProvider: Obtain a new instance of the AuthorizableActionProvider (see above)</li>
+</ul>
+<div class="section">
+<h5>Configuration Parameters supported by the default implementation<a name="Configuration_Parameters_supported_by_the_default_implementation"></a></h5>
+
+<table border="0" class="table table-striped">
+ <thead>
+
+<tr class="a">
+
+<th>Parameter </th>
+
+<th>Type </th>
+
+<th>Default </th>
+ </tr>
+ </thead>
+ <tbody>
+
+<tr class="b">
+
+<td><tt>PARAM_ADMIN_ID</tt> </td>
+
+<td>String </td>
+
+<td>“admin” </td>
+ </tr>
+
+<tr class="a">
+
+<td><tt>PARAM_OMIT_ADMIN_PW</tt> </td>
+
+<td>boolean </td>
+
+<td>false </td>
+ </tr>
+
+<tr class="b">
+
+<td><tt>PARAM_ANONYMOUS_ID</tt> </td>
+
+<td>String </td>
+
+<td>“anonymous” (nullable) </td>
+ </tr>
+
+<tr class="a">
+
+<td><tt>PARAM_USER_PATH</tt> </td>
+
+<td>String </td>
+
+<td>“/rep:security/rep:authorizables/rep:users” </td>
+ </tr>
+
+<tr class="b">
+
+<td><tt>PARAM_GROUP_PATH</tt> </td>
+
+<td>String </td>
+
+<td>“/rep:security/rep:authorizables/rep:groups” </td>
+ </tr>
+
+<tr class="a">
+
+<td><tt>PARAM_DEFAULT_DEPTH</tt> </td>
+
+<td>int </td>
+
+<td>2 </td>
+ </tr>
+
+<tr class="b">
+
+<td><tt>PARAM_GROUP_MEMBERSHIP_SPLIT_SIZE</tt> </td>
+
+<td>int </td>
+
+<td> </td>
+ </tr>
+
+<tr class="a">
+
+<td><tt>PARAM_PASSWORD_HASH_ALGORITHM</tt> </td>
+
+<td>String </td>
+
+<td>“SHA-256” </td>
+ </tr>
+
+<tr class="b">
+
+<td><tt>PARAM_PASSWORD_HASH_ITERATIONS</tt> </td>
+
+<td>int </td>
+
+<td>1000 </td>
+ </tr>
+
+<tr class="a">
+
+<td><tt>PARAM_PASSWORD_SALT_SIZE</tt> </td>
+
+<td>int </td>
+
+<td>8 </td>
+ </tr>
+
+<tr class="b">
+
+<td><tt>PARAM_AUTHORIZABLE_NODE_NAME</tt> </td>
+
+<td>AuthorizableNodeName </td>
+
+<td>AuthorizableNodeName#DEFAULT </td>
+ </tr>
+
+<tr class="a">
+
+<td><tt>PARAM_SUPPORT_AUTOSAVE</tt> </td>
+
+<td>boolean </td>
+
+<td>false </td>
+ </tr>
+ </tbody>
+</table>
+<p>The following configuration parameters present with the default implementation in Jackrabbit 2.x are no longer supported and will be ignored:</p>
+
+<ul>
+
+<li>“compatibleJR16”</li>
+
+<li>“autoExpandTree”</li>
+
+<li>“autoExpandSize”</li>
+
+<li>“groupMembershipSplitSize”</li>
+</ul>
+<!-- hidden references --></div></div></div></div>
+ </div>
+ </div>
+ </div>
+
+ <hr/>
+
+ <footer>
+ <div class="container-fluid">
+ <div class="row span12">Copyright © 2012-2014
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+
+
+
+
+
+
+ <div id="ohloh" class="pull-right">
+ <script type="text/javascript" src="http://www.ohloh.net/p/jackrabbit-oak/widgets/project_users_logo.js"></script>
+ </div>
+ </div>
+ </footer>
+ </body>
+</html>
\ No newline at end of file
Added: jackrabbit/site/live/oak/docs/documentmk.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/documentmk.html?rev=1629650&view=auto
==============================================================================
--- jackrabbit/site/live/oak/docs/documentmk.html (added)
+++ jackrabbit/site/live/oak/docs/documentmk.html Mon Oct 6 13:35:10 2014
@@ -0,0 +1,711 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2014-04-15
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="Date-Revision-yyyymmdd" content="20140415" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Jackrabbit Oak - Oak DocumentMK</title>
+ <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
+ <link rel="stylesheet" href="./css/site.css" />
+ <link rel="stylesheet" href="./css/print.css" media="print" />
+
+
+ <script type="text/javascript" src="./js/apache-maven-fluido-1.3.0.min.js"></script>
+
+
+ </head>
+ <body class="topBarEnabled">
+
+
+
+
+
+
+ <a href="http://github.com/apache/jackrabbit-oak">
+ <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"
+ src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"
+ alt="Fork me on GitHub">
+ </a>
+
+
+
+
+
+ <div id="topbar" class="navbar navbar-fixed-top ">
+ <div class="navbar-inner">
+ <div class="container-fluid">
+ <a data-target=".nav-collapse" data-toggle="collapse" class="btn btn-navbar">
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </a>
+
+ <ul class="nav">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Overview <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="index.html" title="Jackrabbit Oak">Jackrabbit Oak</a>
+</li>
+
+ <li> <a href="license.html" title="License">License</a>
+</li>
+
+ <li> <a href="downloads.html" title="Downloads">Downloads</a>
+</li>
+
+ <li> <a href="from_here.html" title="From here">From here</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts and architecture <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="overview.html" title="Overview">Overview</a>
+</li>
+
+ <li> <a href="nodestate.html" title="The node state model">The node state model</a>
+</li>
+
+ <li> <a href="microkernel.html" title="NodesStore and MicroKernel">NodesStore and MicroKernel</a>
+</li>
+
+ <li> <a href="query.html" title="Query">Query</a>
+</li>
+
+ <li> <a href="blobstore.html" title="BlobStore">BlobStore</a>
+</li>
+
+ <li> <a href="security/overview.html" title="Security">Security</a>
+</li>
+
+ <li> <a href="clustering.html" title="Clustering">Clustering</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Using Oak <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="use_getting_started.html" title="Getting Started">Getting Started</a>
+</li>
+
+ <li> <a href="differences.html" title="Differences to Jackrabbit 2">Differences to Jackrabbit 2</a>
+</li>
+
+ <li> <a href="osgi_config.html" title="Configuring Oak">Configuring Oak</a>
+</li>
+
+ <li> <a href="known_issues.html" title="Known Issues">Known Issues</a>
+</li>
+
+ <li> <a href="dos_and_donts.html" title="Dos and don'ts">Dos and don'ts</a>
+</li>
+
+ <li> <a href="when_things_go_wrong.html" title="When things go wrong">When things go wrong</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developing Oak <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="dev_getting_started.html" title="Getting Started">Getting Started</a>
+</li>
+
+ <li> <a href="participating.html" title="Participating">Participating</a>
+</li>
+
+ <li> <a href="apidocs/index.html" title="API docs">API docs</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Links <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="http://jackrabbit.apache.org/oak" title="Apache Jackrabbit Oak">Apache Jackrabbit Oak</a>
+</li>
+
+ <li> <a href="http://jackrabbit.apache.org/" title="Apache Jackrabbit">Apache Jackrabbit</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+
+
+
+
+ </div>
+
+ </div>
+ </div>
+ </div>
+
+ <div class="container-fluid">
+ <div id="banner">
+ <div class="pull-left">
+ <div id="bannerLeft">
+ <h2>Oak Documentation</h2>
+ </div>
+ </div>
+ <div class="pull-right"> </div>
+ <div class="clear"><hr/></div>
+ </div>
+
+ <div id="breadcrumbs">
+ <ul class="breadcrumb">
+
+
+ <li id="publishDate">Last Published: 2014-04-15</li>
+ <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
+
+
+
+
+ </ul>
+ </div>
+
+
+ <div class="row-fluid">
+ <div id="leftColumn" class="span3">
+ <div class="well sidebar-nav">
+
+
+ <ul class="nav nav-list">
+ <li class="nav-header">Overview</li>
+
+ <li>
+
+ <a href="index.html" title="Jackrabbit Oak">
+ <i class="none"></i>
+ Jackrabbit Oak</a>
+ </li>
+
+ <li>
+
+ <a href="license.html" title="License">
+ <i class="none"></i>
+ License</a>
+ </li>
+
+ <li>
+
+ <a href="downloads.html" title="Downloads">
+ <i class="none"></i>
+ Downloads</a>
+ </li>
+
+ <li>
+
+ <a href="from_here.html" title="From here">
+ <i class="none"></i>
+ From here</a>
+ </li>
+ <li class="nav-header">Concepts and architecture</li>
+
+ <li>
+
+ <a href="overview.html" title="Overview">
+ <i class="none"></i>
+ Overview</a>
+ </li>
+
+ <li>
+
+ <a href="nodestate.html" title="The node state model">
+ <i class="none"></i>
+ The node state model</a>
+ </li>
+
+ <li>
+
+ <a href="microkernel.html" title="NodesStore and MicroKernel">
+ <i class="none"></i>
+ NodesStore and MicroKernel</a>
+ </li>
+
+ <li>
+
+ <a href="query.html" title="Query">
+ <i class="none"></i>
+ Query</a>
+ </li>
+
+ <li>
+
+ <a href="blobstore.html" title="BlobStore">
+ <i class="none"></i>
+ BlobStore</a>
+ </li>
+
+ <li>
+
+ <a href="security/overview.html" title="Security">
+ <i class="none"></i>
+ Security</a>
+ </li>
+
+ <li>
+
+ <a href="clustering.html" title="Clustering">
+ <i class="none"></i>
+ Clustering</a>
+ </li>
+ <li class="nav-header">Using Oak</li>
+
+ <li>
+
+ <a href="use_getting_started.html" title="Getting Started">
+ <i class="none"></i>
+ Getting Started</a>
+ </li>
+
+ <li>
+
+ <a href="differences.html" title="Differences to Jackrabbit 2">
+ <i class="none"></i>
+ Differences to Jackrabbit 2</a>
+ </li>
+
+ <li>
+
+ <a href="osgi_config.html" title="Configuring Oak">
+ <i class="none"></i>
+ Configuring Oak</a>
+ </li>
+
+ <li>
+
+ <a href="known_issues.html" title="Known Issues">
+ <i class="none"></i>
+ Known Issues</a>
+ </li>
+
+ <li>
+
+ <a href="dos_and_donts.html" title="Dos and don'ts">
+ <i class="none"></i>
+ Dos and don'ts</a>
+ </li>
+
+ <li>
+
+ <a href="when_things_go_wrong.html" title="When things go wrong">
+ <i class="none"></i>
+ When things go wrong</a>
+ </li>
+ <li class="nav-header">Developing Oak</li>
+
+ <li>
+
+ <a href="dev_getting_started.html" title="Getting Started">
+ <i class="none"></i>
+ Getting Started</a>
+ </li>
+
+ <li>
+
+ <a href="participating.html" title="Participating">
+ <i class="none"></i>
+ Participating</a>
+ </li>
+
+ <li>
+
+ <a href="apidocs/index.html" title="API docs">
+ <i class="none"></i>
+ API docs</a>
+ </li>
+ <li class="nav-header">Links</li>
+
+ <li>
+
+ <a href="http://jackrabbit.apache.org/oak" class="externalLink" title="Apache Jackrabbit Oak">
+ <i class="none"></i>
+ Apache Jackrabbit Oak</a>
+ </li>
+
+ <li>
+
+ <a href="http://jackrabbit.apache.org/" class="externalLink" title="Apache Jackrabbit">
+ <i class="none"></i>
+ Apache Jackrabbit</a>
+ </li>
+ </ul>
+
+
+
+ <hr class="divider" />
+
+ <div id="poweredBy">
+
+ <script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>
+
+
+ <div class="g-plusone" data-href="http://jackrabbit.apache.org/oak-doc/" data-size="tall" ></div>
+
+ <div class="clear"></div>
+ <div class="clear"></div>
+ <div class="clear"></div>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
+ </a>
+ </div>
+ </div>
+ </div>
+
+
+ <div id="bodyColumn" class="span9" >
+
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. --><h1>Oak DocumentMK</h1>
+<p>One of the plugins in Oak stores data in a document oriented format. The plugin implements two low level APIs, the <tt>MicroKernel</tt> and <tt>NodeStore</tt> interface.</p>
+<div class="section">
+<h2>Backend implementations<a name="Backend_implementations"></a></h2>
+<p>DocumentMK supports a number of backends, with a storage abstraction called <tt>DocumentStore</tt>:</p>
+
+<ul>
+
+<li><tt>MongoDocumentStore</tt>: stores documents in a MongoDB.</li>
+
+<li><tt>MemoryDocumentStore</tt>: keeps documents in memory. This implementation should only be used for testing purposes.</li>
+
+<li><tt>RDBDocumentStore</tt>: stores documents in a relational data base.</li>
+</ul>
+<p>The remaining part of the document will focus on the <tt>MongoDocumentStore</tt> to explain and illustrate concepts of the DocumentMK.</p></div>
+<div class="section">
+<h2>Content Model<a name="Content_Model"></a></h2>
+<p>The repository data is stored in two collections: the <tt>nodes</tt> collection for node data, and the <tt>blobs</tt> collection for binaries. There is a third collection, <tt>clusterNodes</tt>, which contains metadata of all cluster nodes. The data can be viewed using the MongoDB shell:</p>
+
+<div class="source">
+<pre>> show collections
+blobs
+clusterNodes
+nodes
+</pre></div></div>
+<div class="section">
+<h2>Node Content Model<a name="Node_Content_Model"></a></h2>
+<p>The <tt>DocumentMK</tt> stores each node in a separate MongoDB document and updates to a node are stored by adding new revision/value pairs to the document. This way the previous state of a node is preserved and can still be retrieved by a session looking at a given snapshot (revision) of the repository.</p>
+<p>The basic MongoDB document of a node in Oak looks like this:</p>
+
+<div class="source">
+<pre>{
+ "_id" : "1:/node",
+ "_deleted" : {
+ "r13f3875b5d1-0-1" : "false"
+ },
+ "_lastRev" : {
+ "r0-0-1" : "r13f3875b5d1-0-1"
+ },
+ "_modified" : NumberLong(274208361),
+ "_modCount" : NumberLong(1),
+ "_children" : Boolean(true),
+ "_revisions" : {
+ "r13f3875b5d1-0-1" : "c"
+ }
+}
+</pre></div>
+<p>All fields in the above document are metadata and are not exposed through the Oak API. DocumentMK has two types of fields. Simple fields are key/value pairs like the <tt>_id</tt> or <tt>_modified</tt> field. Versioned fields are kept in sub-documents where the key is a revision paired with the value at this revision.</p>
+<p>The <tt>_id</tt> field is used as the primary key and consists of a combination of the depth of the path and the path itself. This is an optimization to align sibling keys in the index.</p>
+<p>The <tt>_deleted</tt> sub-document contains the revision this node was created in. In the above example the root node was created in revision <tt>r13f3875b5d1-0-1</tt>. If the node is later deleted, the <tt>_deleted</tt> sub-document will get a new field with the revision the node was deleted in.</p>
+<p>The sub-document <tt>_lastRev</tt> contains the last revision written to this node by each cluster node. In the above example the DocumentMK cluster node with id <tt>1</tt> modified the node the last time in revision <tt>r13f3875b5d1-0-1</tt>, when it created the node. The revision key in the <tt>_lastRev</tt> sub-document is synthetic and the only information actually used by DocumentMK is the clusterId. The <tt>_lastRev</tt> sub-document is only updated for non-branch commits or on merge, when changes become visible to all readers.</p>
+<p>The <tt>_modified</tt> field contains an indexed low-resolution timestamp when the node was last modified. The time resolution is five seconds. This field is also updated when a branch commit modifies a node.</p>
+<p>The <tt>_modCount</tt> field contains a modification counter, which is incremented with every change to the document. This field allows DocumentMK to perform conditional updates without requesting the whole document.</p>
+<p>The <tt>_children</tt> field is a boolean flag to indicate if this node has child nodes. By default a node would not have this field. If any node gets added as child of this node then it would be set to true. It is used to optimize access to child nodes and allows DocumentMK to omit calls to fetch child nodes for leaf nodes.</p>
+<p>Finally, the <tt>_revisions</tt> sub-document contains commit information about changes marked with a revision. E.g. the single entry in the above document tells us that everything marked with revision <tt>r13f3875b5d1-0-1</tt> is committed and therefore valid. In case the change is done in a branch then the value would be the base revision. It is only added for those nodes which happen to be the commit root for any given commit.</p>
+<p>Adding a property <tt>prop</tt> with value <tt>foo</tt> to the node in a next step will result in the following document:</p>
+
+<div class="source">
+<pre>{
+ "_deleted" : {
+ "r13f3875b5d1-0-1" : "false"
+ },
+ "_id" : "1:/node",
+ "_lastRev" : {
+ "r0-0-1" : "r13f38818ab6-0-1"
+ },
+ "_modified" : NumberLong(274208516),
+ "_modCount" : NumberLong(2),
+ "_revisions" : {
+ "r13f3875b5d1-0-1" : "c",
+ "r13f38818ab6-0-1" : "c"
+ },
+ "prop" : {
+ "r13f38818ab6-0-1" : "\"foo\""
+ }
+}
+</pre></div>
+<p>Now the document contains a new sub-document with the name of the new property. The value of the property is annotated with the revision the property was set. With each successful commit to this node, a new field is added to the <tt>_revisions</tt> sub-document. Similarly the <tt>_lastRev</tt> sub-document and <tt>_modified</tt> field are updated.</p>
+<p>After the node is deleted the document looks like this:</p>
+
+<div class="source">
+<pre>{
+ "_deleted" : {
+ "r13f3875b5d1-0-1" : "false",
+ "r13f38835063-2-1" : "true"
+ },
+ "_id" : "1:/node",
+ "_lastRev" : {
+ "r0-0-1" : "r13f38835063-2-1"
+ },
+ "_modified" : NumberLong(274208539),
+ "_modCount" : NumberLong(3),
+ "_revisions" : {
+ "r13f3875b5d1-0-1" : "c",
+ "r13f38818ab6-0-1" : "c",
+ "r13f38835063-2-1" : "c"
+ },
+ "prop" : {
+ "r13f38818ab6-0-1" : "\"foo\""
+ }
+}
+</pre></div>
+<p>The <tt>_deleted</tt> sub-document now contains a <tt>r13f38835063-2-1</tt> field marking the node as deleted in this revision.</p>
+<p>Reading the node in previous revisions is still possible, even if it is now marked as deleted as of revision <tt>r13f38835063-2-1</tt>.</p></div>
+<div class="section">
+<h2>Revisions<a name="Revisions"></a></h2>
+<p>As seen in the examples above, a revision is a String and may look like this: <tt>r13f38835063-2-1</tt>. It consists of three parts:</p>
+
+<ul>
+
+<li>A timestamp derived from the system time of the machine it was generated on: <tt>13f38835063</tt></li>
+
+<li>A counter to distinguish revisions created with the same timestamp: <tt>-2</tt></li>
+
+<li>The cluster node id where this revision was created: <tt>-1</tt></li>
+</ul></div>
+<div class="section">
+<h2>Branches<a name="Branches"></a></h2>
+<p>MicroKernel implementations support branches, which allows a client to stage multiple commits and make them visible with a single merge call. In DocumentMK a branch commit looks very similar to a regular commit, but instead of setting the value of an entry in <tt>_revisions</tt> to <tt>c</tt> (committed), it marks it with the base revision of the branch commit. In contrast to regular commits where the commit root is the common ancestor of all nodes modified in a commit, the commit root of a branch commit is always the root node. This is because a branch will likely have multiple commits and a commit root must already be known when the first commit happens on a branch. To make sure the following branch commits can use the same commit root, DocumentMK simply picks the root node, which always works in this case.</p>
+<p>A root node may look like this:</p>
+
+<div class="source">
+<pre>{
+ "_deleted" : {
+ "r13fcda88ac0-0-1" : "false",
+ },
+ "_id" : "0:/",
+ "_lastRev" : {
+ "r0-0-1" : "r13fcda91720-0-1"
+ },
+ "_modified" : NumberLong(274708995),
+ "_modCount" : NumberLong(2),
+ "_revisions" : {
+ "r13fcda88ac0-0-1" : "c",
+ "r13fcda91720-0-1" : "c"
+ },
+ "prop" : {
+ "r13fcda91720-0-1" : "\"foo\""
+ }
+}
+</pre></div>
+<p>The root node was created in revision <tt>r13fcda88ac0-0-1</tt> and later in revision <tt>r13fcda91720-0-1</tt> property <tt>prop</tt> was set to <tt>foo</tt>. To keep the example simple, we now assume a branch is created based on the revision the root node was last modified and a branch commit is done to modify the existing property. After the branch commit the root node looks like this:</p>
+
+<div class="source">
+<pre>{
+ "_deleted" : {
+ "r13fcda88ac0-0-1" : "false",
+ },
+ "_id" : "0:/",
+ "_lastRev" : {
+ "r0-0-1" : "r13fcda91720-0-1"
+ },
+ "_modified" : NumberLong(274708995),
+ "_modCount" : NumberLong(3),
+ "_revisions" : {
+ "r13fcda88ac0-0-1" : "c",
+ "r13fcda91720-0-1" : "c",
+ "r13fcda919eb-0-1" : "r13fcda91720-0-1"
+ },
+ "prop" : {
+ "r13fcda91720-0-1" : "\"foo\"",
+ "r13fcda919eb-0-1" : "\"bar\"",
+ }
+}
+</pre></div>
+<p>At this point the modified property is only visible to a reader when it reads with the branch revision <tt>r13fcda919eb-0-1</tt> because the revision is marked with the base version of this commit in the <tt>_revisions</tt> sub-document. Note, the <tt>_lastRev</tt> is not updated for branch commits but only when a branch is merged.</p>
+<p>When the branch is later merged, the root node will look like this:</p>
+
+<div class="source">
+<pre>{
+ "_deleted" : {
+ "r13fcda88ac0-0-1" : "false",
+ },
+ "_id" : "0:/",
+ "_lastRev" : {
+ "r0-0-1" : "r13fcda91b12-0-1"
+ },
+ "_modified" : NumberLong(274708995),
+ "_modCount" : NumberLong(4),
+ "_revisions" : {
+ "r13fcda88ac0-0-1" : "c",
+ "r13fcda91720-0-1" : "c",
+ "r13fcda919eb-0-1" : "c-r13fcda91b12-0-1"
+ },
+ "prop" : {
+ "r13fcda91720-0-1" : "\"foo\"",
+ "r13fcda919eb-0-1" : "\"bar\"",
+ }
+}
+</pre></div>
+<p>Now, the changed property is visible to readers with a revision equal or newer than <tt>r13fcda91b12-0-1</tt>.</p>
+<p>The same logic is used for changes to other nodes that belong to a branch commit. DocumentMK internally resolves the commit revision for a modification before it decides whether a reader is able to see a given change.</p></div>
+<div class="section">
+<h2>Previous Documents<a name="Previous_Documents"></a></h2>
+<p>Over time the size of a document grows because DocumentMK adds data to the document with every modification, but never deletes anything to keep the history. Old data is moved when there are 1000 commits to be moved or the document is bigger than 1 MB. A document with a reference to old data looks like this:</p>
+
+<div class="source">
+<pre>{
+ "_deleted" : {
+ "r13fcda88ac0-0-1" : "false",
+ },
+ "_id" : "0:/",
+ "_lastRev" : {
+ "r0-0-1" : "r13fcda91b12-0-1"
+ },
+ "_modified" : NumberLong(274708995),
+ "_modCount" : NumberLong(1004),
+ "_revisions" : {
+ "r13fcda88ac0-0-1" : "c",
+ "r13fcda91720-0-1" : "c",
+ "r13fcda919eb-0-1" : "c-r13fcda91b12-0-1"
+ },
+ "_prev" : {
+ "r13fcda88ae0-0-1" : "r13fcda91710-0-1"
+ },
+ "prop" : {
+ "r13fcda91720-0-1" : "\"foo\"",
+ "r13fcda919eb-0-1" : "\"bar\"",
+ }
+}
+</pre></div>
+<p>The optional sub-document <tt>_prev</tt> contains a list of revision pairs, each indicating the range of commit revisions a previous document contains. In the above example there is one document with previous commits from <tt>r13fcda88ae0-0-1</tt> to <tt>r13fcda91710-0-1</tt>. The id of the previous document is derived from the upper bound of the range and the id/path of the current document. The id of the previous document for <tt>r13fcda88ae0-0-1</tt> and <tt>0:/</tt> is <tt>1:p/r13fcda88ae0-0-1</tt> and may looks like this:</p>
+
+<div class="source">
+<pre>{
+ "_id" : "1:p/r13fcda88ae0-0-1",
+ "_modCount" : NumberLong(1),
+ "_revisions" : {
+ "r13fcda88ae0-0-1" : "c",
+ "r13fcda88af0-0-1" : "c",
+ ...
+ "r13fcda91710-0-1" : "c"
+ },
+ "prop" : {
+ "r13fcda88ae0-0-1" : "\"foo\"",
+ "r13fcda88af0-0-1" : "\"bar\"",
+ ...
+ "r13fcda91710-0-1" : "\"baz\""
+ }
+}
+</pre></div>
+<p>Previous documents only contain immutable data, which means it only contains committed and merged <tt>_revisions</tt>. This also means the previous ranges of committed data may overlap because branch commits are not moved to previous documents until the branch is merged.</p></div>
+<div class="section">
+<h2>Background Operations<a name="Background_Operations"></a></h2>
+<p>Each DocumentMK instance connecting to same database in Mongo server performs certain background task.</p>
+<div class="section">
+<h3>Renew Cluster Id Lease<a name="Renew_Cluster_Id_Lease"></a></h3>
+<p>Each cluster node uses a unique cluster node id, which is the last part of the revision id. Each cluster node has a lease on the cluster node id, as described in the section <a href="#Cluster_Node_Metadata">Cluster Node Metadata</a>.</p></div>
+<div class="section">
+<h3>Background Document Split<a name="Background_Document_Split"></a></h3>
+<p>DocumentMK periodically checks documents for their size and if necessary splits them up and moves old data to a previous document. This is done in the background by each DocumentMK instance for the data it created.</p></div>
+<div class="section">
+<h3>Background Writes<a name="Background_Writes"></a></h3>
+<p>While performing commits there are certain nodes which are modified but do not become part of commit. For example when a node under /a/b/c is updated then the <tt>_lastRev</tt> property of all ancestors also need to be updated to the commit revision. Such changes are accumulated and flushed periodically through a asynchronous job.</p></div>
+<div class="section">
+<h3>Background Reads<a name="Background_Reads"></a></h3>
+<p>DocumentMK periodically picks up changes from other DocumentMK instances by polling the root node for changes of <tt>_lastRev</tt>. This happens once every second.</p></div></div>
+<div class="section">
+<h2>Pending Topics<a name="Pending_Topics"></a></h2>
+<div class="section">
+<h3>Conflict Detection and Handling<a name="Conflict_Detection_and_Handling"></a></h3></div></div>
+<div class="section">
+<h2>Cluster Node Metadata<a name="Cluster_Node_Metadata"></a></h2>
+<p>Cluster node metadata is stored in the <tt>clusterNodes</tt> collection. There is one entry for each cluster node that is running, and there are entries for cluster nodes that were ran. Old entries are kept so that if a cluster node is started again, it gets the same cluster node id as before (which is not strictly needed for consistency, but nice for support, if one would want to find out which change originated from which cluster node).</p>
+<p>Each running cluster node updates the lease time of the cluster node id once every minute, to ensure each cluster node uses a different cluster node id.</p>
+
+<div class="source">
+<pre>> db.clusterNodes.find().pretty()
+
+{
+ "_id" : "1",
+ "_modCount" : NumberLong(2),
+ "leaseEnd" : NumberLong("1390465250135"),
+ "instance" : "/Users/test/jackrabbit/oak/trunk/oak-jcr",
+ "machine" : "mac:20c9d043f141",
+ "info" : "...pid: 11483, uuid: 6b6e8e4f-8322-4b19-a2b2-de0c573620b9 ..."
+}
+{
+ "_id" : "2",
+ "_modCount" : NumberLong(2),
+ "leaseEnd" : NumberLong("1390465252206"),
+ "instance" : "/Users/mueller/jackrabbit/oak/trunk/oak-jcr",
+ "machine" : "mac:20c9d043f141",
+ "info" : "...pid: 11483, uuid: 28ada13d-ec9c-4d48-aeb9-cef53aa4bb9e ..."
+}
+</pre></div>
+<p>The <tt>_id</tt> is the cluster node id of the node, which is the last part of the revision id. The <tt>leaseEnd</tt> is updated once per minute by running cluster nodes. It is the number of milliseconds since 1970. The <tt>instance</tt> is the current working directory. The <tt>machine</tt> is the lowest number of the network addresses, or a random uuid if this is not available. The <tt>info</tt> contains the same info as a string, plus additionally the process id and the uuid.</p>
+<div class="section">
+<h3>Changing the Read Preference and Write Concern at Runtime<a name="Changing_the_Read_Preference_and_Write_Concern_at_Runtime"></a></h3>
+<p>The read preference and write concern of all cluster nodes can be changed at runtime without having to restart the instances, by setting the property <tt>readWriteMode</tt> of this collection. All cluster nodes will pick up the change within one minute (when they renew the lease of the cluster node id). This is a string property with the format <tt>'read:<readPreference>, write:<writeConcern>'</tt> (please note the space after the comma, and no spaces before and after the colon). The following shell command will set the read preference to <tt>primary</tt> and the write concern to <tt>majority</tt> for all cluster nodes:</p>
+
+<div class="source">
+<pre>> db.clusterNodes.update({},
+ {$set: {readWriteMode:'read:primary, write:majority'}},
+ {multi: true})
+</pre></div></div></div>
+<div class="section">
+<h2>License<a name="License"></a></h2>
+<p>(see the top-level <a href="../LICENSE.txt">LICENSE.txt</a> for full license details)</p>
+<p>Collective work: Copyright 2013 The Apache Software Foundation.</p>
+<p>Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at</p>
+
+<div class="source">
+<pre> http://www.apache.org/licenses/LICENSE-2.0
+</pre></div>
+<p>Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.</p></div>
+ </div>
+ </div>
+ </div>
+
+ <hr/>
+
+ <footer>
+ <div class="container-fluid">
+ <div class="row span12">Copyright © 2012-2014
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+
+
+
+
+
+
+ <div id="ohloh" class="pull-right">
+ <script type="text/javascript" src="http://www.ohloh.net/p/jackrabbit-oak/widgets/project_users_logo.js"></script>
+ </div>
+ </div>
+ </footer>
+ </body>
+</html>
\ No newline at end of file
Modified: jackrabbit/site/live/oak/docs/dos_and_donts.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/dos_and_donts.html?rev=1629650&r1=1629649&r2=1629650&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/dos_and_donts.html (original)
+++ jackrabbit/site/live/oak/docs/dos_and_donts.html Mon Oct 6 13:35:10 2014
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2014-09-24
+ | Generated by Apache Maven Doxia at 2014-10-06
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20140924" />
+ <meta name="Date-Revision-yyyymmdd" content="20141006" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak - Session refresh behavior</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -67,7 +67,7 @@
<li> <a href="architecture/overview.html" title="Overview">Overview</a>
</li>
- <li> <a href="architecture/nodestate.html" title="The node state model">The node state model</a>
+ <li> <a href="architecture/nodestate.html" title="The Node State Model">The Node State Model</a>
</li>
</ul>
</li>
@@ -109,19 +109,22 @@
<li> <a href="use_getting_started.html" title="Getting Started">Getting Started</a>
</li>
- <li> <a href="construct.html" title="Repository construction">Repository construction</a>
+ <li> <a href="construct.html" title="Repository Construction">Repository Construction</a>
</li>
<li> <a href="osgi_config.html" title="Configuring Oak">Configuring Oak</a>
</li>
+ <li> <a href="command_line.html" title="Command Line Tools">Command Line Tools</a>
+</li>
+
<li> <a href="differences.html" title="Differences to Jackrabbit 2">Differences to Jackrabbit 2</a>
</li>
<li> <a href="known_issues.html" title="Known Issues">Known Issues</a>
</li>
- <li> <a href="dos_and_donts.html" title="Dos and don'ts">Dos and don'ts</a>
+ <li> <a href="dos_and_donts.html" title="Dos and Don'ts">Dos and Don'ts</a>
</li>
<li> <a href="coldstandby/coldstandby.html" title="Cold Standby">Cold Standby</a>
@@ -141,7 +144,7 @@
<li> <a href="participating.html" title="Participating">Participating</a>
</li>
- <li> <a href="apidocs/index.html" title="API docs">API docs</a>
+ <li> <a href="apidocs/index.html" title="API Docs">API Docs</a>
</li>
</ul>
</li>
@@ -182,7 +185,7 @@
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2014-09-24</li>
+ <li id="publishDate">Last Published: 2014-10-06</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.1-SNAPSHOT</li>
@@ -231,9 +234,9 @@
<li>
- <a href="architecture/nodestate.html" title="The node state model">
+ <a href="architecture/nodestate.html" title="The Node State Model">
<i class="none"></i>
- The node state model</a>
+ The Node State Model</a>
</li>
<li class="nav-header">Main APIs</li>
@@ -297,9 +300,9 @@
<li>
- <a href="construct.html" title="Repository construction">
+ <a href="construct.html" title="Repository Construction">
<i class="none"></i>
- Repository construction</a>
+ Repository Construction</a>
</li>
<li>
@@ -311,6 +314,13 @@
<li>
+ <a href="command_line.html" title="Command Line Tools">
+ <i class="none"></i>
+ Command Line Tools</a>
+ </li>
+
+ <li>
+
<a href="differences.html" title="Differences to Jackrabbit 2">
<i class="none"></i>
Differences to Jackrabbit 2</a>
@@ -325,7 +335,7 @@
<li class="active">
- <a href="#"><i class="none"></i>Dos and don'ts</a>
+ <a href="#"><i class="none"></i>Dos and Don'ts</a>
</li>
<li>
@@ -359,9 +369,9 @@
<li>
- <a href="apidocs/index.html" title="API docs">
+ <a href="apidocs/index.html" title="API Docs">
<i class="none"></i>
- API docs</a>
+ API Docs</a>
</li>
<li class="nav-header">Links</li>
Modified: jackrabbit/site/live/oak/docs/downloads.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/downloads.html?rev=1629650&r1=1629649&r2=1629650&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/downloads.html (original)
+++ jackrabbit/site/live/oak/docs/downloads.html Mon Oct 6 13:35:10 2014
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2014-09-24
+ | Generated by Apache Maven Doxia at 2014-10-06
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20140924" />
+ <meta name="Date-Revision-yyyymmdd" content="20141006" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak - Downloads</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -67,7 +67,7 @@
<li> <a href="architecture/overview.html" title="Overview">Overview</a>
</li>
- <li> <a href="architecture/nodestate.html" title="The node state model">The node state model</a>
+ <li> <a href="architecture/nodestate.html" title="The Node State Model">The Node State Model</a>
</li>
</ul>
</li>
@@ -109,19 +109,22 @@
<li> <a href="use_getting_started.html" title="Getting Started">Getting Started</a>
</li>
- <li> <a href="construct.html" title="Repository construction">Repository construction</a>
+ <li> <a href="construct.html" title="Repository Construction">Repository Construction</a>
</li>
<li> <a href="osgi_config.html" title="Configuring Oak">Configuring Oak</a>
</li>
+ <li> <a href="command_line.html" title="Command Line Tools">Command Line Tools</a>
+</li>
+
<li> <a href="differences.html" title="Differences to Jackrabbit 2">Differences to Jackrabbit 2</a>
</li>
<li> <a href="known_issues.html" title="Known Issues">Known Issues</a>
</li>
- <li> <a href="dos_and_donts.html" title="Dos and don'ts">Dos and don'ts</a>
+ <li> <a href="dos_and_donts.html" title="Dos and Don'ts">Dos and Don'ts</a>
</li>
<li> <a href="coldstandby/coldstandby.html" title="Cold Standby">Cold Standby</a>
@@ -141,7 +144,7 @@
<li> <a href="participating.html" title="Participating">Participating</a>
</li>
- <li> <a href="apidocs/index.html" title="API docs">API docs</a>
+ <li> <a href="apidocs/index.html" title="API Docs">API Docs</a>
</li>
</ul>
</li>
@@ -182,7 +185,7 @@
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2014-09-24</li>
+ <li id="publishDate">Last Published: 2014-10-06</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.1-SNAPSHOT</li>
@@ -229,9 +232,9 @@
<li>
- <a href="architecture/nodestate.html" title="The node state model">
+ <a href="architecture/nodestate.html" title="The Node State Model">
<i class="none"></i>
- The node state model</a>
+ The Node State Model</a>
</li>
<li class="nav-header">Main APIs</li>
@@ -295,9 +298,9 @@
<li>
- <a href="construct.html" title="Repository construction">
+ <a href="construct.html" title="Repository Construction">
<i class="none"></i>
- Repository construction</a>
+ Repository Construction</a>
</li>
<li>
@@ -309,6 +312,13 @@
<li>
+ <a href="command_line.html" title="Command Line Tools">
+ <i class="none"></i>
+ Command Line Tools</a>
+ </li>
+
+ <li>
+
<a href="differences.html" title="Differences to Jackrabbit 2">
<i class="none"></i>
Differences to Jackrabbit 2</a>
@@ -323,9 +333,9 @@
<li>
- <a href="dos_and_donts.html" title="Dos and don'ts">
+ <a href="dos_and_donts.html" title="Dos and Don'ts">
<i class="none"></i>
- Dos and don'ts</a>
+ Dos and Don'ts</a>
</li>
<li>
@@ -359,9 +369,9 @@
<li>
- <a href="apidocs/index.html" title="API docs">
+ <a href="apidocs/index.html" title="API Docs">
<i class="none"></i>
- API docs</a>
+ API Docs</a>
</li>
<li class="nav-header">Links</li>