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"
/>
