Author: mreutegg
Date: Thu May 17 13:26:29 2018
New Revision: 1831781

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

Add MongoDocumentStore specific documentation

Added:
    
jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/mongo-document-store.md
Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/plugins/blobstore.md
    jackrabbit/oak/trunk/oak-doc/src/site/site.xml

Added: 
jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/mongo-document-store.md
URL: 
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/mongo-document-store.md?rev=1831781&view=auto
==============================================================================
--- 
jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/mongo-document-store.md
 (added)
+++ 
jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/mongo-document-store.md
 Thu May 17 13:26:29 2018
@@ -0,0 +1,96 @@
+<!--
+   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.
+  -->
+# MongoDB DocumentStore
+
+The `MongoDocumentStore` is one of the backend implementations for the
+[DocumentNodeStore](../documentmk.html). The MongoDocumentStore use MongoDB
+to persist nodes as documents.
+
+## <a name="recommendations"></a> Recommendations
+
+Before deploying a MongoDocumentStore on MongoDB, make sure recommendations
+described in [production 
notes](https://docs.mongodb.com/manual/administration/production-notes/)
+have been applied.
+
+The recommended MongoDB version depends on the Oak release. Below table lists
+the recommended MongoDB version for each Oak release. More recent MongoDB
+versions may also work, but are untested.
+
+Oak Release | MongoDB version
+------------|----------------
+1.0.x | 2.6.x
+1.2.x | 3.2.x
+1.4.x | 3.2.x
+1.6.x | 3.2.x
+1.8.x | 3.4.x
+
+For production deployments use a replica-set with at least three mongod
+instances and a majority write concern. Fewer than three instances (e.g. two
+instances and an arbiter) may lead to data loss when the primary fails.
+
+When using MongoDB 3.4 or newer, set the 
[maxStalenessSeconds](https://docs.mongodb.com/manual/core/read-preference/#maxstalenessseconds)
+option in the MongoDB URI to `90`. This is an additional safeguard and will
+prevent reads from a secondary that are too far behind.
+
+Initializing a DocumentNodeStore on MongoDB with default values will also use
+MongoDB to store blobs. While this is convenient for development and tests, the
+use of MongoDB as a blob store in production is not recommended. MongoDB
+replicates all changes through a single op-log. Large blobs can lead to a
+significantly reduced op-log window and cause delay in replicating other 
changes
+between the replica-set members. See available [blob 
stores](../../plugins/blobstore.html)
+alternatives for production use.
+
+## <a name="initialization"></a> Initialization
+
+The recommended method to initialize a `DocumentNodeStore` with a
+`MongoDocumentStore` is using an OSGi container and configure the
+`DocumentNodeStoreService`. See corresponding [Repository OSGi 
Configuration](../../osgi_config.html).
+
+Alternatively a MongoDB based DocumentNodeStore can be created with the help of
+a `MongoDocumentNodeStoreBuilder`.
+
+    DocumentNodeStore store = newMongoDocumentNodeStoreBuilder()
+        .setMongoDB("mongodb://localhost:27017", "oak", 0).build();
+    // do something with the store
+    NodeState root = store.getRoot();
+
+    // dispose it when done
+    store.dispose();
+
+Please note, even though the default is to store blobs in MongoDB, this is not
+a recommended setup. See also [recommendations](#recommendations).
+
+## <a name="configuration"></a> Configuration
+
+Independent of whether the DocumentNodeStore is initialized via the OSGi 
service
+or the builder, the implementation will automatically take care of some
+appropriate default MongoDB client parameters. This includes the write concern,
+which controls how many MongoDB replica-set members must acknowledge a write
+operation. Without an explicit write concern specified in the MongoDB URI, the
+implementation will set write concern based on the MongoDB topology. If MongoDB
+is setup as a replica-set, then Oak will use a `majority` write concern. When
+running on a single standalone MongoDB instance, the write concern is set to
+'acknowledged'.
+
+Similarly, a read concern is set automatically, unless explicitly specified in
+the MongoDB URI. A `majority` read concern is set when supported, enabled on
+the MongoDB server and a majority write concern is in use. Otherwise the read
+concern is set to `local`.
+
+Oak will log WARN messages if it deems the read and write concerns given via 
the
+MongoDB URI insufficient.
+

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md
URL: 
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md?rev=1831781&r1=1831780&r2=1831781&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md 
(original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md Thu 
May 17 13:26:29 2018
@@ -17,6 +17,7 @@
 # Oak Document Storage
 
 * [Oak Document Storage](#oak-document-storage)
+    * [New in 1.8](#new-1.8)
     * [New in 1.6](#new-1.6)
     * [Backend implementations](#backend-implementations)
     * [Content Model](#content-model)
@@ -47,7 +48,14 @@
 One of the plugins in Oak stores data in a document oriented format. 
 The plugin implements the low level `NodeStore` interface.
 
-The document storage optionally uses the [persistent 
cache](persistent-cache.html) to reduce read operations on the backend storage.
+The document storage optionally uses the [persistent 
cache](persistent-cache.html)
+to reduce read operations on the backend storage.
+
+## <a name="new-1.8"></a> New in 1.8
+
+* [Sweep Revision](#sweep-revision)
+* [Unlock upgrade](#unlockUpgrade)
+* [Continuous and oak-run triggered Revision GC](#revision-gc)
 
 ## <a name="new-1.6"></a> New in 1.6
 
@@ -60,22 +68,10 @@ The document storage optionally uses the
 The DocumentNodeStore supports a number of backends, with a storage abstraction
 called `DocumentStore`:
 
-* `MongoDocumentStore`: stores documents in a MongoDB.
+* [`MongoDocumentStore`](document/mongo-document-store.html): stores documents 
in a MongoDB.
 * `RDBDocumentStore`: stores documents in a relational data base.
 * `MemoryDocumentStore`: keeps documents in memory. This implementation should 
only be used for testing purposes.
 
-The recommended MongoDB version depends on the Oak release. Below table lists
-the recommended MongoDB version for each Oak release. More recent MongoDB
-versions may also work, but are untested.
-
-Oak Release | MongoDB version
-------------|----------------
-1.0.x | 2.6.x
-1.2.x | 3.2.x
-1.4.x | 3.2.x
-1.6.x | 3.2.x
-1.8.x | 3.4.x
-
 The remaining part of the document will focus on the `MongoDocumentStore` to
 explain and illustrate concepts of the DocumentNodeStore.
 

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/plugins/blobstore.md
URL: 
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/plugins/blobstore.md?rev=1831781&r1=1831780&r2=1831781&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/plugins/blobstore.md 
(original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/plugins/blobstore.md Thu May 
17 13:26:29 2018
@@ -103,14 +103,15 @@ can be used
 
 #### DocumentNodeStore
 
-By default DocumentNodeStore when running on Mongo uses `MongoBlobStore`. 
Depending on requirements 
-one of the following can be used  
+By default DocumentNodeStore when running on Mongo uses `MongoBlobStore`.
+Depending on requirements one of the following can be used
                   
-* MongoBlobStore - Used by default
+* MongoBlobStore - Used by default and recommended only for development and 
testing.
 * FileDataStore - This should be used if the binaries have to be stored on the 
file system. This 
   would also be used when a JR2 repository is migrated to Oak
 * S3DataStore - This should be used when binaries are stored in Amazon S3. 
Typically used when running
   in Amazon AWS
+* AzureDataStore - This should be used when binaries are stored in Microsoft 
Azure Blob storage
 
 #### Caching DataStore
 

Modified: jackrabbit/oak/trunk/oak-doc/src/site/site.xml
URL: 
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/site.xml?rev=1831781&r1=1831780&r2=1831781&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/site.xml (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/site.xml Thu May 17 13:26:29 2018
@@ -41,6 +41,7 @@ under the License.
     <menu name="Features and Plugins">
       <item href="nodestore/overview.html" name="Node Storage" 
collapse="false">
         <item href="nodestore/documentmk.html" name="Document NodeStore" 
collapse="false">
+          <item href="nodestore/document/mongo-document-store.html" 
name="MongoDB DocumentStore" />
           <item href="nodestore/document/node-bundling.html" name="Node 
Bundling" />
           <item href="nodestore/document/secondary-store.html" name="Secondary 
Store" />
           <item href="nodestore/persistent-cache.html" name="Persistent Cache" 
/>


Reply via email to