You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by ch...@apache.org on 2017/03/24 05:58:12 UTC
svn commit: r1788363 [5/17] - in /jackrabbit/site/live/oak/docs: ./
architecture/ coldstandby/ features/ nodestore/ nodestore/document/
nodestore/segment/ oak-mongo-js/ oak-mongo-js/scripts/
oak-mongo-js/scripts/prettify/ oak-mongo-js/styles/ oak_api/ ...
Added: jackrabbit/site/live/oak/docs/nodestore/document/secondary-store.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/nodestore/document/secondary-store.html?rev=1788363&view=auto
==============================================================================
--- jackrabbit/site/live/oak/docs/nodestore/document/secondary-store.html (added)
+++ jackrabbit/site/live/oak/docs/nodestore/document/secondary-store.html Fri Mar 24 05:58:10 2017
@@ -0,0 +1,765 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2017-03-24
+ | 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="20170324" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Jackrabbit Oak - <a name="secondary-node-store"></a> Secondary NodeStore</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>
+
+ <a class="brand" href="../../" title="Oak logo">
+
+
+ <img src="../../oak_logo.png" alt="Oak logo" />
+
+ </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="../../articles.html" title="Articles">Articles</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="../../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>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a>
+</li>
+
+ <li> <a href="../../oak_api/overview.html" title="Oak API">Oak API</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Features and Plugins <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li class="dropdown-submenu">
+ <a href="../../nodestore/overview.html" title="Node Storage">Node Storage</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../../nodestore/documentmk.html" title="Document NodeStore">Document NodeStore</a>
+</li>
+ <li> <a href="../../nodestore/segment/overview.html" title="Segment NodeStore">Segment NodeStore</a>
+</li>
+ </ul>
+ </li>
+
+ <li> <a href="../../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
+</li>
+
+ <li class="dropdown-submenu">
+ <a href="../../query/query.html" title="Query">Query</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../../query/query-engine.html" title="Query Engine">Query Engine</a>
+</li>
+ <li> <a href="../../query/indexing.html" title="Indexing">Indexing</a>
+</li>
+ <li> <a href="../../query/lucene.html" title="Lucene Index">Lucene Index</a>
+</li>
+ <li> <a href="../../query/property-index.html" title="Property Index">Property Index</a>
+</li>
+ <li> <a href="../../query/solr.html" title="Solr Index">Solr Index</a>
+</li>
+ </ul>
+ </li>
+
+ <li> <a href="../../security/overview.html" title="Security">Security</a>
+</li>
+
+ <li> <a href="../../features/atomic-counter.html" title="Atomic Counter">Atomic Counter</a>
+</li>
+
+ <li> <a href="../../features/observation.html" title="Observation">Observation</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="../../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="../../migration.html" title="Migration">Migration</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>
+
+ <li> <a href="../../coldstandby/coldstandby.html" title="Cold Standby">Cold Standby</a>
+</li>
+
+ <li> <a href="../../FAQ.html" title="FAQ">FAQ</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="../../developing-with-git.html" title="Developing with Git">Developing with Git</a>
+</li>
+
+ <li> <a href="../../diagnostic-builds.html" title="Cutting diagnostic builds">Cutting diagnostic builds</a>
+</li>
+
+ <li> <a href="../../attribution.html" title="Attribution">Attribution</a>
+</li>
+
+ <li> <a href="../../release-schedule.html" title="Release Schedule">Release Schedule</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: 2017-03-24</li>
+ <li class="divider">|</li> <li id="projectVersion">Version: 1.8-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="../../articles.html" title="Articles">
+ <i class="none"></i>
+ Articles</a>
+ </li>
+ <li class="nav-header">Concepts and Architecture</li>
+
+ <li>
+
+ <a href="../../architecture/overview.html" title="Overview">
+ <i class="none"></i>
+ Overview</a>
+ </li>
+
+ <li>
+
+ <a href="../../architecture/nodestate.html" title="The Node State Model">
+ <i class="none"></i>
+ The Node State Model</a>
+ </li>
+ <li class="nav-header">Main APIs</li>
+
+ <li>
+
+ <a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API">
+ <i class="none"></i>
+ JCR API</a>
+ </li>
+
+ <li>
+
+ <a href="../../oak_api/overview.html" title="Oak API">
+ <i class="none"></i>
+ Oak API</a>
+ </li>
+ <li class="nav-header">Features and Plugins</li>
+
+ <li>
+
+ <a href="../../nodestore/overview.html" title="Node Storage">
+ <i class="icon-chevron-down"></i>
+ Node Storage</a>
+ <ul class="nav nav-list">
+
+ <li>
+
+ <a href="../../nodestore/documentmk.html" title="Document NodeStore">
+ <i class="icon-chevron-down"></i>
+ Document NodeStore</a>
+ <ul class="nav nav-list">
+
+ <li>
+
+ <a href="../../nodestore/document/node-bundling.html" title="Node Bundling">
+ <i class="none"></i>
+ Node Bundling</a>
+ </li>
+
+ <li class="active">
+
+ <a href="#"><i class="none"></i>Secondary Store</a>
+ </li>
+
+ <li>
+
+ <a href="../../nodestore/persistent-cache.html" title="Persistent Cache">
+ <i class="none"></i>
+ Persistent Cache</a>
+ </li>
+
+ <li>
+
+ <a href="../../clustering.html" title="Clustering">
+ <i class="none"></i>
+ Clustering</a>
+ </li>
+ </ul>
+ </li>
+
+ <li>
+
+ <a href="../../nodestore/segment/overview.html" title="Segment NodeStore">
+ <i class="none"></i>
+ Segment NodeStore</a>
+ </li>
+ </ul>
+ </li>
+
+ <li>
+
+ <a href="../../plugins/blobstore.html" title="Blob Storage">
+ <i class="none"></i>
+ Blob Storage</a>
+ </li>
+
+ <li>
+
+ <a href="../../query/query.html" title="Query">
+ <i class="icon-chevron-down"></i>
+ Query</a>
+ <ul class="nav nav-list">
+
+ <li>
+
+ <a href="../../query/query-engine.html" title="Query Engine">
+ <i class="none"></i>
+ Query Engine</a>
+ </li>
+
+ <li>
+
+ <a href="../../query/indexing.html" title="Indexing">
+ <i class="none"></i>
+ Indexing</a>
+ </li>
+
+ <li>
+
+ <a href="../../query/lucene.html" title="Lucene Index">
+ <i class="none"></i>
+ Lucene Index</a>
+ </li>
+
+ <li>
+
+ <a href="../../query/property-index.html" title="Property Index">
+ <i class="none"></i>
+ Property Index</a>
+ </li>
+
+ <li>
+
+ <a href="../../query/solr.html" title="Solr Index">
+ <i class="none"></i>
+ Solr Index</a>
+ </li>
+ </ul>
+ </li>
+
+ <li>
+
+ <a href="../../security/overview.html" title="Security">
+ <i class="none"></i>
+ Security</a>
+ </li>
+
+ <li>
+
+ <a href="../../features/atomic-counter.html" title="Atomic Counter">
+ <i class="none"></i>
+ Atomic Counter</a>
+ </li>
+
+ <li>
+
+ <a href="../../features/observation.html" title="Observation">
+ <i class="none"></i>
+ Observation</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="../../construct.html" title="Repository Construction">
+ <i class="none"></i>
+ Repository Construction</a>
+ </li>
+
+ <li>
+
+ <a href="../../osgi_config.html" title="Configuring Oak">
+ <i class="none"></i>
+ Configuring Oak</a>
+ </li>
+
+ <li>
+
+ <a href="../../command_line.html" title="Command Line Tools">
+ <i class="none"></i>
+ Command Line Tools</a>
+ </li>
+
+ <li>
+
+ <a href="../../migration.html" title="Migration">
+ <i class="none"></i>
+ Migration</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="../../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="../../coldstandby/coldstandby.html" title="Cold Standby">
+ <i class="none"></i>
+ Cold Standby</a>
+ </li>
+
+ <li>
+
+ <a href="../../FAQ.html" title="FAQ">
+ <i class="none"></i>
+ FAQ</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="../../developing-with-git.html" title="Developing with Git">
+ <i class="none"></i>
+ Developing with Git</a>
+ </li>
+
+ <li>
+
+ <a href="../../diagnostic-builds.html" title="Cutting diagnostic builds">
+ <i class="none"></i>
+ Cutting diagnostic builds</a>
+ </li>
+
+ <li>
+
+ <a href="../../attribution.html" title="Attribution">
+ <i class="none"></i>
+ Attribution</a>
+ </li>
+
+ <li>
+
+ <a href="../../release-schedule.html" title="Release Schedule">
+ <i class="none"></i>
+ Release Schedule</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/docs/" 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><a name="secondary-node-store"></a> Secondary NodeStore</h1>
+
+<ul>
+
+<li><a href="#secondary-node-store">Secondary NodeStore</a></li>
+
+<li><a href="#read-flow">Read Flow</a></li>
+
+<li><a href="#write-flow">Write Flow</a>
+
+<ul>
+
+<li><a href="#write-flow-local-changes">Local Changes</a></li>
+
+<li><a href="#write-flow-external-changes">External Changes</a></li>
+
+<li><a href="#write-flow-startup-sync">Startup Sync</a></li>
+ </ul></li>
+
+<li><a href="#usage">Setup </a></li>
+
+<li><a href="#setup-considerations">Setup Considerations</a></li>
+
+<li><a href="#administration">Administration</a>
+
+<ul>
+
+<li><a href="#secondary-store-maintenance">Maintenance</a></li>
+
+<li><a href="#secondary-store-cluster">New Cluster Member</a></li>
+ </ul></li>
+</ul>
+<p><tt>@since Oak 1.6</tt> <tt>Experimental Feature</tt></p>
+<p>Compared to SegmentNodeStore DocumentNodeStore has higher latency for reads for the data not present in the cache. This happens due to multiple round trips required to serve a hierarchical read access over remote storage. For e.g. reading content of path <i>/content/assets/nature/sunrise.jpg</i> would require around 4 remote calls if the path content is not present in local cache. <a href="../persistent-cache.html">Persistent Cache</a> helped in improving this by enabling caching lot more content off heap compared to limited inmemory cache. </p>
+<p>With new <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-1312">Secondary NodeStore</a> support its now possible to configure a SegmentNodeStore as a secondary store to store content under certain set of paths locally. SegmentNodeStore act a local copy of remote repository (secondary store) more like a local git repo which gets updated from primary store (remote Mongo storage) via observation. Writes are still routed to primary store but reads can be served from local secondary store.</p>
+<p><img src="secondary-store.png" alt="Secondary Store Setup" /></p>
+<p>In above setup 2 Oak Cluser nodes connect to same Mongo server. In each Oak instance a SegmentNodeStore is configured as secondary store. This store gets updated by observer.</p>
+<p><b>Experimental Feature</b></p>
+<p>This feature is currently experimental. Following feature item is currently pending</p>
+
+<ul>
+
+<li><a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-5352">OAK-5352</a> - Support for maintenance task for secondary NodeStore</li>
+</ul>
+<div class="section">
+<h2><a name="read-flow"></a> Read Flow<a name="Read_Flow"></a></h2>
+<p>Reading /a/b at revision r1 would happen like below</p>
+<p><img src="secondary-store-read.png" alt="Secondary Store Read Flow" /> </p>
+<p>Key points here</p>
+
+<ul>
+
+<li>Secondary NodeStore can be configured to only stored content under certain paths</li>
+
+<li>Read would be first attempted from any configured secondary NodeStore.
+
+<ol style="list-style-type: decimal">
+
+<li>Secondary NodeStore would check if it stores content for that path. Note that it can be configured with path inclusions</li>
+
+<li>It then checks whether its root revision is later than revision at which read is being requested</li>
+
+<li>If NodeState at given path and revision is found then its returned</li>
+ </ol></li>
+
+<li>If read is not possible from secondary NodeStore then read is done from in memory which may in turn read from remote Mongo in case of cache miss</li>
+
+<li>If read is successful from Secondary NodeStore which is based on SegmentNodeStore then further child read from that path would be directly handled by SegmentNodeStore by passing DocumentNodeStore altogether. So if /a/b@r1 is found in secondary then read for /a/b/c@r1 would be directly handled by secondary store</li>
+</ul>
+<p>Note that even if root revision of secondary store is lagging behind current head its possible that read for /a/b can be handled by secondary store if /a has not been modified recently. So those parts of repo which have not been recently modified would most likely be served from Secondary NodeStore and avoid remote calls to Mongo.</p></div>
+<div class="section">
+<h2><a name="write-flow"></a> Write Flow<a name="Write_Flow"></a></h2>
+<p>Updates to secondary store happen in 3 ways</p>
+<p><img src="secondary-store-write.png" alt="Secondary Store Write Flow" /> </p>
+<p>Key points here</p>
+
+<ul>
+
+<li>Writes done by NodeStore caller i.e. JCR layer are always done on primary store i.e. Mongo</li>
+
+<li>Secondary NodeStore is updated via Oak Observation support and NodeState diff</li>
+
+<li>Secondary NodeStore can be configured with path filter and then it would only be interested in changes for configured paths</li>
+</ul>
+<div class="section">
+<h3><a name="write-flow-local-changes"></a> Local Changes<a name="Local_Changes"></a></h3>
+<p>For local changes done on that cluster nodes the writes are applied as part of Observation call where DocumentNodeStore send content change callback to all registered observers. Here Secondary NodeStore registers itself as an Observer and listed for such callback.</p>
+<p>So upon any local change it gets a callback with latest state of root paths. There it performs a diff between local head revision and new head revision and applies the changes onto local store</p></div>
+<div class="section">
+<h3><a name="write-flow-external-changes"></a> External Changes<a name="External_Changes"></a></h3>
+<p>DocumentNodeStore periodically performs <a href="../documentmk.html#bg-read">background reads</a> to pickup changes from other cluster node. Such a change is then pushed to registered observer as an external change. Secondary NodeStore uses same flow as for local changes to update its state.</p>
+<p>This diff based update mechanism would then only read content from remote for the changed paths and further only for paths in which secondary NodeStore is interested</p></div>
+<div class="section">
+<h3><a name="write-flow-startup-sync"></a> Startup Sync<a name="Startup_Sync"></a></h3>
+<p>If the cluster node is shutdown and later started then at time of start the secondary NodeStore would try to synchronize its state with remote storage again by performing diff between local head revision and remote head revision. This is done asynchronously and does not block the startup</p></div></div>
+<div class="section">
+<h2><a name="usage"></a> Setup<a name="Setup"></a></h2>
+<p>For enabling this feature following OSGi configurations have to be done</p>
+<p><b>1. Configure SegmentNodeStore in secondary role</b></p>
+<p>Create an OSGi config file <tt>org.apache.jackrabbit.oak.segment.SegmentNodeStoreFactory-secondary.config</tt> with following content</p>
+
+<div class="source">
+<pre>role="secondary"
+</pre></div>
+<p>This would create a SegmentNodeStore in secondary role and uses default <tt>segmentstore-secondary</tt> directory to store the segment files. Refer to <a href="../../osgi_config.html#config-SegmentNodeStoreService">config options</a> for more details. Note all the options for <tt>SegmentNodeStoreService</tt> are applicable for <tt>SegmentNodeStoreFactory</tt></p>
+<p><b>2. Configure SecondaryStoreCacheService (optional)</b></p>
+<p>By default secondary NodeStore would be activated based on previous config only. However it can be tweaked further by creating an OSGi config file <tt>org.apache.jackrabbit.oak.plugins.document.secondary.SecondaryStoreCacheService.config</tt></p>
+
+<div class="source">
+<pre>includedPaths=[ \
+ "/libs", \
+ "/apps", \
+ "/content"
+ ]
+</pre></div>
+<p>Above config would enable secondary NodeStore for paths ‘/libs, /apps and /content’</p></div>
+<div class="section">
+<h2><a name="setup-considerations"></a> Setup Considerations<a name="Setup_Considerations"></a></h2>
+<p>While enabling secondary NodeStore feature following aspects needs to be considered</p>
+
+<ul>
+
+<li>SegmentNodeStore used as secondary NodeStore would compete with system resource like memory along with in memory caches of DocumentNodeStore and Lucene index files. So system must have sufficient memory to for all these 3 components</li>
+
+<li>SegmentNodeStore can be copied from any existing cluster node to a new node.</li>
+
+<li>If this is being enabled for existing setup then initial sync would take some time. So take that into account while planning to enable this feature</li>
+
+<li>For best performance include those paths of the repository which are accessed by end user. Specially those content paths where read to write ratio is high.</li>
+</ul></div>
+<div class="section">
+<h2><a name="administration"></a> Administration<a name="Administration"></a></h2>
+<div class="section">
+<h3><a name="secondary-store-maintenance"></a> Maintenance<a name="Maintenance"></a></h3>
+<p>Certain maintenance like <a href="../segment/overview.html#garbage-collection">online RevisionGC</a> for secondary NodeStore i.e. SegmentNodeStore need to be enabled. (This feature is currently pending <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-5352">OAK-5352</a>).</p>
+<p>This would ensure that older revision gets garbage collected</p></div>
+<div class="section">
+<h3><a name="secondary-store-cluster"></a> New Cluster Member<a name="New_Cluster_Member"></a></h3>
+<p>If a new Oak server is joined to cluster then it should be done by cloning the secondary NodeStore from some existing cluster member otherwise the initial sync would take a long time to complete</p></div></div>
+ </div>
+ </div>
+ </div>
+
+ <hr/>
+
+ <footer>
+ <div class="container-fluid">
+ <div class="row span12">Copyright © 2012-2017
+ <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_thin_badge.js"></script>
+ </div>
+ </div>
+ </footer>
+ </body>
+</html>
\ No newline at end of file
Propchange: jackrabbit/site/live/oak/docs/nodestore/document/secondary-store.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/site/live/oak/docs/nodestore/document/secondary-store.png
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/nodestore/document/secondary-store.png?rev=1788363&view=auto
==============================================================================
Binary file - no diff available.
Propchange: jackrabbit/site/live/oak/docs/nodestore/document/secondary-store.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Modified: jackrabbit/site/live/oak/docs/nodestore/documentmk.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/nodestore/documentmk.html?rev=1788363&r1=1788362&r2=1788363&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/nodestore/documentmk.html (original)
+++ jackrabbit/site/live/oak/docs/nodestore/documentmk.html Fri Mar 24 05:58:10 2017
@@ -1,15 +1,15 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2017-03-21
+ | Generated by Apache Maven Doxia at 2017-03-24
| 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="20170321" />
+ <meta name="Date-Revision-yyyymmdd" content="20170324" />
<meta http-equiv="Content-Language" content="en" />
- <title>Jackrabbit Oak - Oak Document Storage</title>
+ <title>Jackrabbit Oak - <a name="oak-document-storage"></a> Oak Document Storage</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" />
@@ -65,6 +65,9 @@
<li> <a href="../downloads.html" title="Downloads">Downloads</a>
</li>
+
+ <li> <a href="../articles.html" title="Articles">Articles</a>
+</li>
</ul>
</li>
<li class="dropdown">
@@ -93,31 +96,42 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Features and Plugins <b class="caret"></b></a>
<ul class="dropdown-menu">
- <li> <a href="../features/atomic-counter.html" title="Atomic Counter">Atomic Counter</a>
+ <li class="dropdown-submenu">
+ <a href="../nodestore/overview.html" title="Node Storage">Node Storage</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../nodestore/documentmk.html" title="Document NodeStore">Document NodeStore</a>
</li>
+ <li> <a href="../nodestore/segment/overview.html" title="Segment NodeStore">Segment NodeStore</a>
+</li>
+ </ul>
+ </li>
<li> <a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
</li>
- <li> <a href="../clustering.html" title="Clustering">Clustering</a>
+ <li class="dropdown-submenu">
+ <a href="../query/query.html" title="Query">Query</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../query/query-engine.html" title="Query Engine">Query Engine</a>
</li>
-
- <li> <a href="../nodestore/documentmk.html" title="DocumentNodeStore">DocumentNodeStore</a>
+ <li> <a href="../query/indexing.html" title="Indexing">Indexing</a>
</li>
-
- <li> <a href="../nodestore/overview.html" title="Node Storage">Node Storage</a>
+ <li> <a href="../query/lucene.html" title="Lucene Index">Lucene Index</a>
</li>
-
- <li> <a href="../nodestore/persistent-cache.html" title="Persistent Cache">Persistent Cache</a>
+ <li> <a href="../query/property-index.html" title="Property Index">Property Index</a>
</li>
-
- <li> <a href="../query/query.html" title="Query">Query</a>
+ <li> <a href="../query/solr.html" title="Solr Index">Solr Index</a>
</li>
+ </ul>
+ </li>
<li> <a href="../security/overview.html" title="Security">Security</a>
</li>
- <li> <a href="../nodestore/segment/overview.html" title="Segment Node Store">Segment Node Store</a>
+ <li> <a href="../features/atomic-counter.html" title="Atomic Counter">Atomic Counter</a>
+</li>
+
+ <li> <a href="../features/observation.html" title="Observation">Observation</a>
</li>
</ul>
</li>
@@ -216,7 +230,7 @@
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2017-03-21</li>
+ <li id="publishDate">Last Published: 2017-03-24</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.8-SNAPSHOT</li>
@@ -254,6 +268,13 @@
<i class="none"></i>
Downloads</a>
</li>
+
+ <li>
+
+ <a href="../articles.html" title="Articles">
+ <i class="none"></i>
+ Articles</a>
+ </li>
<li class="nav-header">Concepts and Architecture</li>
<li>
@@ -285,53 +306,108 @@
Oak API</a>
</li>
<li class="nav-header">Features and Plugins</li>
-
+
<li>
- <a href="../features/atomic-counter.html" title="Atomic Counter">
+ <a href="../nodestore/overview.html" title="Node Storage">
+ <i class="icon-chevron-down"></i>
+ Node Storage</a>
+ <ul class="nav nav-list">
+
+ <li class="active">
+
+ <a href="#"><i class="icon-chevron-down"></i>Document NodeStore</a>
+ <ul class="nav nav-list">
+
+ <li>
+
+ <a href="../nodestore/document/node-bundling.html" title="Node Bundling">
<i class="none"></i>
- Atomic Counter</a>
+ Node Bundling</a>
</li>
-
+
<li>
- <a href="../plugins/blobstore.html" title="Blob Storage">
+ <a href="../nodestore/document/secondary-store.html" title="Secondary Store">
<i class="none"></i>
- Blob Storage</a>
+ Secondary Store</a>
</li>
-
+
+ <li>
+
+ <a href="../nodestore/persistent-cache.html" title="Persistent Cache">
+ <i class="none"></i>
+ Persistent Cache</a>
+ </li>
+
<li>
<a href="../clustering.html" title="Clustering">
<i class="none"></i>
Clustering</a>
</li>
-
- <li class="active">
-
- <a href="#"><i class="none"></i>DocumentNodeStore</a>
- </li>
-
+ </ul>
+ </li>
+
<li>
- <a href="../nodestore/overview.html" title="Node Storage">
+ <a href="../nodestore/segment/overview.html" title="Segment NodeStore">
<i class="none"></i>
- Node Storage</a>
+ Segment NodeStore</a>
</li>
+ </ul>
+ </li>
<li>
- <a href="../nodestore/persistent-cache.html" title="Persistent Cache">
+ <a href="../plugins/blobstore.html" title="Blob Storage">
<i class="none"></i>
- Persistent Cache</a>
+ Blob Storage</a>
</li>
-
+
<li>
<a href="../query/query.html" title="Query">
- <i class="none"></i>
+ <i class="icon-chevron-down"></i>
Query</a>
+ <ul class="nav nav-list">
+
+ <li>
+
+ <a href="../query/query-engine.html" title="Query Engine">
+ <i class="none"></i>
+ Query Engine</a>
+ </li>
+
+ <li>
+
+ <a href="../query/indexing.html" title="Indexing">
+ <i class="none"></i>
+ Indexing</a>
+ </li>
+
+ <li>
+
+ <a href="../query/lucene.html" title="Lucene Index">
+ <i class="none"></i>
+ Lucene Index</a>
+ </li>
+
+ <li>
+
+ <a href="../query/property-index.html" title="Property Index">
+ <i class="none"></i>
+ Property Index</a>
+ </li>
+
+ <li>
+
+ <a href="../query/solr.html" title="Solr Index">
+ <i class="none"></i>
+ Solr Index</a>
</li>
+ </ul>
+ </li>
<li>
@@ -342,9 +418,16 @@
<li>
- <a href="../nodestore/segment/overview.html" title="Segment Node Store">
+ <a href="../features/atomic-counter.html" title="Atomic Counter">
<i class="none"></i>
- Segment Node Store</a>
+ Atomic Counter</a>
+ </li>
+
+ <li>
+
+ <a href="../features/observation.html" title="Observation">
+ <i class="none"></i>
+ Observation</a>
</li>
<li class="nav-header">Using Oak</li>
@@ -514,11 +597,91 @@
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 Document Storage</h1>
+ limitations under the License. --><h1><a name="oak-document-storage"></a> Oak Document Storage</h1>
+
+<ul>
+
+<li><a href="#oak-document-storage">Oak Document Storage</a>
+
+<ul>
+
+<li><a href="#new-1.6">New in 1.6</a></li>
+
+<li><a href="#backend-implementations">Backend implementations</a></li>
+
+<li><a href="#content-model">Content Model</a></li>
+
+<li><a href="#node-content-model">Node Content Model</a></li>
+
+<li><a href="#revisions">Revisions</a></li>
+
+<li><a href="#clock-requirements">Clock requirements</a></li>
+
+<li><a href="#branches">Branches</a></li>
+
+<li><a href="#previous-documents">Previous Documents</a></li>
+
+<li><a href="#node-bundling">Node Bundling</a></li>
+
+<li><a href="#background-operations">Background Operations</a>
+
+<ul>
+
+<li><a href="#renew-cluster-id-lease">Renew Cluster Id Lease</a></li>
+
+<li><a href="#background-document-split">Background Document Split</a></li>
+
+<li><a href="#background-writes">Background Writes</a></li>
+
+<li><a href="#bg-read">Background Reads</a></li>
+ </ul></li>
+
+<li><a href="#pending-topics">Pending Topics</a>
+
+<ul>
+
+<li><a href="#conflict-detection-and-handling">Conflict Detection and Handling</a></li>
+ </ul></li>
+
+<li><a href="#cluster-node-metadata">Cluster Node Metadata</a>
+
+<ul>
+
+<li><a href="#rw-preference">Specifying the Read Preference and Write Concern</a>
+
+<ul>
+
+<li><a href="#via-configuration">Via Configuration</a></li>
+
+<li><a href="#changing-at-runtime">Changing at Runtime</a></li>
+ </ul></li>
+ </ul></li>
+
+<li><a href="#cache">Caching</a>
+
+<ul>
+
+<li><a href="#cache-invalidation">Cache Invalidation</a></li>
+
+<li><a href="#cache-configuration">Cache Configuration</a></li>
+ </ul></li>
+
+<li><a href="#unlockUpgrade">Unlock upgrade </a></li>
+ </ul></li>
+</ul>
<p>One of the plugins in Oak stores data in a document oriented format. The plugin implements the low level <tt>NodeStore</tt> interface.</p>
<p>The document storage optionally uses the <a href="persistent-cache.html">persistent cache</a> to reduce read operations on the backend storage.</p>
<div class="section">
-<h2>Backend implementations<a name="Backend_implementations"></a></h2>
+<h2><a name="new-1.6"></a> New in 1.6<a name="New_in_1.6"></a></h2>
+
+<ul>
+
+<li><a href="#node-bundling">Node Bundling</a></li>
+
+<li><a href="#secondary-store">Secondary Store</a></li>
+</ul></div>
+<div class="section">
+<h2><a name="backend-implementations"></a> 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>
@@ -531,7 +694,7 @@
</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>
+<h2><a name="content-model"></a> 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">
@@ -541,7 +704,7 @@ clusterNodes
nodes
</pre></div></div>
<div class="section">
-<h2>Node Content Model<a name="Node_Content_Model"></a></h2>
+<h2><a name="node-content-model"></a> 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>
@@ -620,7 +783,7 @@ nodes
<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>
+<h2><a name="revisions"></a> 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>
@@ -632,10 +795,10 @@ nodes
<li>The cluster node id where this revision was created: <tt>-1</tt></li>
</ul></div>
<div class="section">
-<h2>Clock requirements<a name="Clock_requirements"></a></h2>
+<h2><a name="clock-requirements"></a> Clock requirements<a name="Clock_requirements"></a></h2>
<p>Revisions are used by the DocumentMK to identify the sequence of changes done on items in the repository. This is also done across cluster nodes for revisions with different cluster node ids. This requires the system clocks on the machines running Oak and the backend system to approximately in sync. It is recommended to run an NTP daemon or some similar service to keep the clock synchronized. Oak allows clock differences up to 2 seconds between the machine where Oak is running and the machine where the backend store (MongoDB or RDBMS) is running. Oak may refuse to start if it detects a larger clock difference. Clock differences between the machines running in an Oak cluster will result in delayed propagation of changes between cluster nodes and warnings in the log files.</p></div>
<div class="section">
-<h2>Branches<a name="Branches"></a></h2>
+<h2><a name="branches"></a> Branches<a name="Branches"></a></h2>
<p>DocumentMK 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>
@@ -711,7 +874,7 @@ nodes
<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>
+<h2><a name="previous-documents"></a> 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">
@@ -761,27 +924,30 @@ nodes
</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>
+<h2><a name="node-bundling"></a> node-bundling</h2>
+<p><tt>@since Oak 1.6</tt></p>
+<p>Refer to <a href="document/node-bundling.html">Node Bundling</a></p></div>
+<div class="section">
+<h2><a name="background-operations"></a> 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>
+<h3><a name="renew-cluster-id-lease"></a> 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>
+<h3><a name="background-document-split"></a> 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>
-<p><a name="bg-read"></a></p></div>
+<h3><a name="background-writes"></a> 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>
+<h3><a name="bg-read"></a> 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>
+<h2><a name="pending-topics"></a> 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>
+<h3><a name="conflict-detection-and-handling"></a> 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>
+<h2><a name="cluster-node-metadata"></a> 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>
@@ -806,13 +972,12 @@ nodes
}
</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>
-<p><a name="rw-preference"></a></p>
<div class="section">
-<h3>Specifying the Read Preference and Write Concern<a name="Specifying_the_Read_Preference_and_Write_Concern"></a></h3>
+<h3><a name="rw-preference"></a> Specifying the Read Preference and Write Concern<a name="Specifying_the_Read_Preference_and_Write_Concern"></a></h3>
<p>With <tt>MongoDocumentStore</tt> you can specify the the <a class="externalLink" href="http://docs.mongodb.org/manual/core/read-preference/">read preference</a> and <a class="externalLink" href="http://docs.mongodb.org/manual/core/write-concern/">write concern</a>. This can be enabled in Oak via two modes. </p>
<p>Note that <tt>MongoDocumentStore</tt> might still use a pre defined read preference like primary where ever required. So if for some code path like reading latest <tt>_lastRev</tt> of root node its required that read is performed from primary (for consistency) then code would explicitly use the readPreference primary for that operation. For all other operation Mongo Java Driver would use default settings where read preference is set to <tt>Primary</tt> and write concern is set to <tt>Acknowledged</tt>. Via using one of the two modes below a user can tune the default settings as per its need</p>
<div class="section">
-<h4>Via Configuration<a name="Via_Configuration"></a></h4>
+<h4><a name="via-configuration"></a> Via Configuration<a name="Via_Configuration"></a></h4>
<p>In this mode the config is specified as part of the Mongo URI (See <a href="../osgi_config.html#document-node-store">configuration</a>). So if a user wants that reads from secondaries should prefer secondary with tag <i>dc:ny,rack:1</i> otherwise they go to other secondary then he can specify that via following mongouri</p>
<div class="source">
@@ -820,17 +985,16 @@ nodes
</pre></div>
<p>Refer to <a class="externalLink" href="http://docs.mongodb.org/manual/reference/connection-string/#read-preference-options">Read Preference Options</a> and <a class="externalLink" href="http://docs.mongodb.org/manual/reference/connection-string/#write-concern-options">Write Concern Options</a> for more details. </p></div>
<div class="section">
-<h4>Changing at Runtime<a name="Changing_at_Runtime"></a></h4>
+<h4><a name="changing-at-runtime"></a> Changing at Runtime<a name="Changing_at_Runtime"></a></h4>
<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>'readPreference=<preference>&w=<writeConcern>'</tt> similar to the way it is used in mongouri. Just that it does not include other option details. 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:'readPreference=primary&w=majority'}},
{multi: true})
-</pre></div>
-<p><a name="cache"></a></p></div></div></div>
+</pre></div></div></div></div>
<div class="section">
-<h2>Caching<a name="Caching"></a></h2>
+<h2><a name="cache"></a> Caching<a name="Caching"></a></h2>
<p><tt>DocumentNodeStore</tt> maintains multiple caches to provide an optimum performance. By default the cached instances are kept in heap memory but some of the caches can be backed by <a href="persistent-cache.html">persistent cache</a>.</p>
<ol style="list-style-type: decimal">
@@ -857,13 +1021,13 @@ nodes
</ol>
<p>All the above caches are managed on heap. For the last 3 <tt>nodeCache</tt>, <tt>childrenCache</tt> and <tt>diffCache</tt> Oak provides support for <a href="persistent-cache.html">persistent cache</a>. By enabling the persistent cache feature Oak can manage a much larger cache off heap and thus avoid freeing up heap memory for application usage.</p>
<div class="section">
-<h3>Cache Invalidation<a name="Cache_Invalidation"></a></h3>
+<h3><a name="cache-invalidation"></a> Cache Invalidation<a name="Cache_Invalidation"></a></h3>
<p><tt>documentCache</tt> and <tt>docChildrenCache</tt> are containing mutable state which requires consistency checks to be performed to keep them in sync with the backend persisted state. Oak uses a MVCC model under which it maintains a consistent view of a given Node at a given revision. This allows using local cache instead of using a global clustered cache where changes made by any other cluster node need not be instantly reflected on all other nodes. </p>
<p>Each cluster node periodically performs <a href="#bg-read">background reads</a> to pickup changes done by other cluster nodes. At that time it performs <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-1156">consistency check</a> to ensure that cached instance state reflect the state in the backend persisted state. Performing the check would take some time would be proportional number of entries present in the cache. </p>
<p>For repository to work properly its important to ensure that such background reads do not consume much time and <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-2646">work is underway</a> to improve current approach. <i>To ensure that such background operation (which include the cache invalidation checks) perform quickly one should not set a large size for these caches</i>.</p>
<p>All other caches consist of immutable state and hence no cache invalidation needs to be performed for them. For that reason those caches can be backed by persistent cache and even having large number of entries in such caches would not be a matter of concern. </p></div>
<div class="section">
-<h3>Cache Configuration<a name="Cache_Configuration"></a></h3>
+<h3><a name="cache-configuration"></a> Cache Configuration<a name="Cache_Configuration"></a></h3>
<p>In a default setup the <a href="../osgi_config.html#document-node-store">DocumentNodeStoreService</a> takes a single config for <tt>cache</tt> which is internally distributed among the various caches above in following way</p>
<ol style="list-style-type: decimal">
@@ -883,6 +1047,19 @@ nodes
<p>Lately <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-2546">options are provided</a> to have a fine grained control over the distribution. See <a href="../osgi_config.html#cache-allocation">Cache Allocation</a></p>
<p>While distributing ensure that cache left for <tt>documentCache</tt> is not very large i.e. prefer to keep that ~500 MB max or lower. As a large <tt>documentCache</tt> can lead to increase in the time taken to perform cache invalidation.</p>
<p>Further make use of the persistent cache. This reduces pressure on GC by keeping instances off heap with slight decrease in performance compared to keeping them on heap.</p></div></div>
+<div class="section">
+<h2><a name="unlockUpgrade"></a> Unlock upgrade<a name="Unlock_upgrade"></a></h2>
+<p>On startup the DocumentNodeStore checks if its version is compatible with the format version currently in use. A read-only DocumentNodeStore can read the current version as well as older versions. A read-write DocumentNodeStore on the other hand can only write to the DocumentStore when the format version matches its own version. The DocumentNodeStore maintains this format version in the <tt>settings</tt> collection accessible to all cluster nodes.</p>
+<p>Upgrading to a newer Oak version may therefore first require an update of the format version before a newer version of a DocumentNodeStore can be started on existing data. The oak-run tools contains an <tt>unlockUpgrade</tt> mode to perform this operation. Use the oak-run tool with the version matching the target upgrade version to unlock an upgrade with the following command. The below example unlocks an upgrade to 1.8 with a DocumentNodeStore on MongoDB:</p>
+
+<div class="source">
+<pre>> java -jar oak-run-1.8.0.jar unlockUpgrade mongodb://example.com:27017/oak
+</pre></div>
+<p>Please note that unlocking an upgrade is only possible when all cluster nodes are inactive, otherwise the command will refuse to change the format version.</p></div>
+<div class="section">
+<h2><a name="secondary-store"></a> Secondary Store<a name="Secondary_Store"></a></h2>
+<p><tt>@since Oak 1.6</tt></p>
+<p>Refer to <a href="document/secondary-store.html">Secondary Store</a></p></div>
</div>
</div>
</div>
Modified: jackrabbit/site/live/oak/docs/nodestore/overview.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/nodestore/overview.html?rev=1788363&r1=1788362&r2=1788363&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/nodestore/overview.html (original)
+++ jackrabbit/site/live/oak/docs/nodestore/overview.html Fri Mar 24 05:58:10 2017
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2017-03-21
+ | Generated by Apache Maven Doxia at 2017-03-24
| 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="20170321" />
+ <meta name="Date-Revision-yyyymmdd" content="20170324" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak - Node Storage</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
@@ -65,6 +65,9 @@
<li> <a href="../downloads.html" title="Downloads">Downloads</a>
</li>
+
+ <li> <a href="../articles.html" title="Articles">Articles</a>
+</li>
</ul>
</li>
<li class="dropdown">
@@ -93,31 +96,42 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Features and Plugins <b class="caret"></b></a>
<ul class="dropdown-menu">
- <li> <a href="../features/atomic-counter.html" title="Atomic Counter">Atomic Counter</a>
+ <li class="dropdown-submenu">
+ <a href="../nodestore/overview.html" title="Node Storage">Node Storage</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../nodestore/documentmk.html" title="Document NodeStore">Document NodeStore</a>
</li>
+ <li> <a href="../nodestore/segment/overview.html" title="Segment NodeStore">Segment NodeStore</a>
+</li>
+ </ul>
+ </li>
<li> <a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
</li>
- <li> <a href="../clustering.html" title="Clustering">Clustering</a>
+ <li class="dropdown-submenu">
+ <a href="../query/query.html" title="Query">Query</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../query/query-engine.html" title="Query Engine">Query Engine</a>
</li>
-
- <li> <a href="../nodestore/documentmk.html" title="DocumentNodeStore">DocumentNodeStore</a>
+ <li> <a href="../query/indexing.html" title="Indexing">Indexing</a>
</li>
-
- <li> <a href="../nodestore/overview.html" title="Node Storage">Node Storage</a>
+ <li> <a href="../query/lucene.html" title="Lucene Index">Lucene Index</a>
</li>
-
- <li> <a href="../nodestore/persistent-cache.html" title="Persistent Cache">Persistent Cache</a>
+ <li> <a href="../query/property-index.html" title="Property Index">Property Index</a>
</li>
-
- <li> <a href="../query/query.html" title="Query">Query</a>
+ <li> <a href="../query/solr.html" title="Solr Index">Solr Index</a>
</li>
+ </ul>
+ </li>
<li> <a href="../security/overview.html" title="Security">Security</a>
</li>
- <li> <a href="../nodestore/segment/overview.html" title="Segment Node Store">Segment Node Store</a>
+ <li> <a href="../features/atomic-counter.html" title="Atomic Counter">Atomic Counter</a>
+</li>
+
+ <li> <a href="../features/observation.html" title="Observation">Observation</a>
</li>
</ul>
</li>
@@ -216,7 +230,7 @@
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2017-03-21</li>
+ <li id="publishDate">Last Published: 2017-03-24</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.8-SNAPSHOT</li>
@@ -254,6 +268,13 @@
<i class="none"></i>
Downloads</a>
</li>
+
+ <li>
+
+ <a href="../articles.html" title="Articles">
+ <i class="none"></i>
+ Articles</a>
+ </li>
<li class="nav-header">Concepts and Architecture</li>
<li>
@@ -285,53 +306,108 @@
Oak API</a>
</li>
<li class="nav-header">Features and Plugins</li>
-
+
+ <li class="active">
+
+ <a href="#"><i class="icon-chevron-down"></i>Node Storage</a>
+ <ul class="nav nav-list">
+
<li>
- <a href="../features/atomic-counter.html" title="Atomic Counter">
+ <a href="../nodestore/documentmk.html" title="Document NodeStore">
+ <i class="icon-chevron-down"></i>
+ Document NodeStore</a>
+ <ul class="nav nav-list">
+
+ <li>
+
+ <a href="../nodestore/document/node-bundling.html" title="Node Bundling">
<i class="none"></i>
- Atomic Counter</a>
+ Node Bundling</a>
</li>
-
+
<li>
- <a href="../plugins/blobstore.html" title="Blob Storage">
+ <a href="../nodestore/document/secondary-store.html" title="Secondary Store">
<i class="none"></i>
- Blob Storage</a>
+ Secondary Store</a>
</li>
-
+
+ <li>
+
+ <a href="../nodestore/persistent-cache.html" title="Persistent Cache">
+ <i class="none"></i>
+ Persistent Cache</a>
+ </li>
+
<li>
<a href="../clustering.html" title="Clustering">
<i class="none"></i>
Clustering</a>
</li>
-
+ </ul>
+ </li>
+
<li>
- <a href="../nodestore/documentmk.html" title="DocumentNodeStore">
+ <a href="../nodestore/segment/overview.html" title="Segment NodeStore">
<i class="none"></i>
- DocumentNodeStore</a>
+ Segment NodeStore</a>
</li>
-
- <li class="active">
-
- <a href="#"><i class="none"></i>Node Storage</a>
- </li>
+ </ul>
+ </li>
<li>
- <a href="../nodestore/persistent-cache.html" title="Persistent Cache">
+ <a href="../plugins/blobstore.html" title="Blob Storage">
<i class="none"></i>
- Persistent Cache</a>
+ Blob Storage</a>
</li>
-
+
<li>
<a href="../query/query.html" title="Query">
- <i class="none"></i>
+ <i class="icon-chevron-down"></i>
Query</a>
+ <ul class="nav nav-list">
+
+ <li>
+
+ <a href="../query/query-engine.html" title="Query Engine">
+ <i class="none"></i>
+ Query Engine</a>
+ </li>
+
+ <li>
+
+ <a href="../query/indexing.html" title="Indexing">
+ <i class="none"></i>
+ Indexing</a>
+ </li>
+
+ <li>
+
+ <a href="../query/lucene.html" title="Lucene Index">
+ <i class="none"></i>
+ Lucene Index</a>
+ </li>
+
+ <li>
+
+ <a href="../query/property-index.html" title="Property Index">
+ <i class="none"></i>
+ Property Index</a>
+ </li>
+
+ <li>
+
+ <a href="../query/solr.html" title="Solr Index">
+ <i class="none"></i>
+ Solr Index</a>
</li>
+ </ul>
+ </li>
<li>
@@ -342,9 +418,16 @@
<li>
- <a href="../nodestore/segment/overview.html" title="Segment Node Store">
+ <a href="../features/atomic-counter.html" title="Atomic Counter">
+ <i class="none"></i>
+ Atomic Counter</a>
+ </li>
+
+ <li>
+
+ <a href="../features/observation.html" title="Observation">
<i class="none"></i>
- Segment Node Store</a>
+ Observation</a>
</li>
<li class="nav-header">Using Oak</li>
Modified: jackrabbit/site/live/oak/docs/nodestore/persistent-cache.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/nodestore/persistent-cache.html?rev=1788363&r1=1788362&r2=1788363&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/nodestore/persistent-cache.html (original)
+++ jackrabbit/site/live/oak/docs/nodestore/persistent-cache.html Fri Mar 24 05:58:10 2017
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2017-03-21
+ | Generated by Apache Maven Doxia at 2017-03-24
| 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="20170321" />
+ <meta name="Date-Revision-yyyymmdd" content="20170324" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak - Persistent Cache</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
@@ -65,6 +65,9 @@
<li> <a href="../downloads.html" title="Downloads">Downloads</a>
</li>
+
+ <li> <a href="../articles.html" title="Articles">Articles</a>
+</li>
</ul>
</li>
<li class="dropdown">
@@ -93,31 +96,42 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Features and Plugins <b class="caret"></b></a>
<ul class="dropdown-menu">
- <li> <a href="../features/atomic-counter.html" title="Atomic Counter">Atomic Counter</a>
+ <li class="dropdown-submenu">
+ <a href="../nodestore/overview.html" title="Node Storage">Node Storage</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../nodestore/documentmk.html" title="Document NodeStore">Document NodeStore</a>
</li>
+ <li> <a href="../nodestore/segment/overview.html" title="Segment NodeStore">Segment NodeStore</a>
+</li>
+ </ul>
+ </li>
<li> <a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
</li>
- <li> <a href="../clustering.html" title="Clustering">Clustering</a>
+ <li class="dropdown-submenu">
+ <a href="../query/query.html" title="Query">Query</a>
+ <ul class="dropdown-menu">
+ <li> <a href="../query/query-engine.html" title="Query Engine">Query Engine</a>
</li>
-
- <li> <a href="../nodestore/documentmk.html" title="DocumentNodeStore">DocumentNodeStore</a>
+ <li> <a href="../query/indexing.html" title="Indexing">Indexing</a>
</li>
-
- <li> <a href="../nodestore/overview.html" title="Node Storage">Node Storage</a>
+ <li> <a href="../query/lucene.html" title="Lucene Index">Lucene Index</a>
</li>
-
- <li> <a href="../nodestore/persistent-cache.html" title="Persistent Cache">Persistent Cache</a>
+ <li> <a href="../query/property-index.html" title="Property Index">Property Index</a>
</li>
-
- <li> <a href="../query/query.html" title="Query">Query</a>
+ <li> <a href="../query/solr.html" title="Solr Index">Solr Index</a>
</li>
+ </ul>
+ </li>
<li> <a href="../security/overview.html" title="Security">Security</a>
</li>
- <li> <a href="../nodestore/segment/overview.html" title="Segment Node Store">Segment Node Store</a>
+ <li> <a href="../features/atomic-counter.html" title="Atomic Counter">Atomic Counter</a>
+</li>
+
+ <li> <a href="../features/observation.html" title="Observation">Observation</a>
</li>
</ul>
</li>
@@ -216,7 +230,7 @@
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2017-03-21</li>
+ <li id="publishDate">Last Published: 2017-03-24</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.8-SNAPSHOT</li>
@@ -254,6 +268,13 @@
<i class="none"></i>
Downloads</a>
</li>
+
+ <li>
+
+ <a href="../articles.html" title="Articles">
+ <i class="none"></i>
+ Articles</a>
+ </li>
<li class="nav-header">Concepts and Architecture</li>
<li>
@@ -285,53 +306,108 @@
Oak API</a>
</li>
<li class="nav-header">Features and Plugins</li>
-
+
<li>
- <a href="../features/atomic-counter.html" title="Atomic Counter">
+ <a href="../nodestore/overview.html" title="Node Storage">
+ <i class="icon-chevron-down"></i>
+ Node Storage</a>
+ <ul class="nav nav-list">
+
+ <li>
+
+ <a href="../nodestore/documentmk.html" title="Document NodeStore">
+ <i class="icon-chevron-down"></i>
+ Document NodeStore</a>
+ <ul class="nav nav-list">
+
+ <li>
+
+ <a href="../nodestore/document/node-bundling.html" title="Node Bundling">
<i class="none"></i>
- Atomic Counter</a>
+ Node Bundling</a>
</li>
-
+
<li>
- <a href="../plugins/blobstore.html" title="Blob Storage">
+ <a href="../nodestore/document/secondary-store.html" title="Secondary Store">
<i class="none"></i>
- Blob Storage</a>
+ Secondary Store</a>
</li>
-
+
+ <li class="active">
+
+ <a href="#"><i class="none"></i>Persistent Cache</a>
+ </li>
+
<li>
<a href="../clustering.html" title="Clustering">
<i class="none"></i>
Clustering</a>
</li>
-
+ </ul>
+ </li>
+
<li>
- <a href="../nodestore/documentmk.html" title="DocumentNodeStore">
+ <a href="../nodestore/segment/overview.html" title="Segment NodeStore">
<i class="none"></i>
- DocumentNodeStore</a>
+ Segment NodeStore</a>
</li>
+ </ul>
+ </li>
<li>
- <a href="../nodestore/overview.html" title="Node Storage">
+ <a href="../plugins/blobstore.html" title="Blob Storage">
<i class="none"></i>
- Node Storage</a>
+ Blob Storage</a>
</li>
-
- <li class="active">
-
- <a href="#"><i class="none"></i>Persistent Cache</a>
- </li>
-
+
<li>
<a href="../query/query.html" title="Query">
- <i class="none"></i>
+ <i class="icon-chevron-down"></i>
Query</a>
+ <ul class="nav nav-list">
+
+ <li>
+
+ <a href="../query/query-engine.html" title="Query Engine">
+ <i class="none"></i>
+ Query Engine</a>
+ </li>
+
+ <li>
+
+ <a href="../query/indexing.html" title="Indexing">
+ <i class="none"></i>
+ Indexing</a>
</li>
+
+ <li>
+
+ <a href="../query/lucene.html" title="Lucene Index">
+ <i class="none"></i>
+ Lucene Index</a>
+ </li>
+
+ <li>
+
+ <a href="../query/property-index.html" title="Property Index">
+ <i class="none"></i>
+ Property Index</a>
+ </li>
+
+ <li>
+
+ <a href="../query/solr.html" title="Solr Index">
+ <i class="none"></i>
+ Solr Index</a>
+ </li>
+ </ul>
+ </li>
<li>
@@ -342,9 +418,16 @@
<li>
- <a href="../nodestore/segment/overview.html" title="Segment Node Store">
+ <a href="../features/atomic-counter.html" title="Atomic Counter">
+ <i class="none"></i>
+ Atomic Counter</a>
+ </li>
+
+ <li>
+
+ <a href="../features/observation.html" title="Observation">
<i class="none"></i>
- Segment Node Store</a>
+ Observation</a>
</li>
<li class="nav-header">Using Oak</li>