INT-3666: Add MongoDbMetadataStore

JIRA: https://jira.spring.io/browse/INT-3666

src/reference/asciidoc/meta-data-store.adoc

@@ -10,11 +10,13 @@ If a component is not directly provided with a reference to a `MetadataStore`, t
 If one is found then it will be used, otherwise it will create a new instance of `SimpleMetadataStore` which is an in-memory implementation that will only persist metadata within the lifecycle of the currently running Application Context.
 This means that upon restart you may end up with duplicate entries.
 
-If you need to persist metadata between Application Context restarts, two persistent `MetadataStores` are provided by the framework:
+If you need to persist metadata between Application Context restarts, these persistent `MetadataStores` are provided by
+the framework:
 
-* PropertiesPersistingMetadataStore
+* `PropertiesPersistingMetadataStore`
 * <<redis-metadata-store>>
 * <<gemfire-metadata-store>>
+* <<mongodb-metadata-store>>
 
 
 

src/reference/asciidoc/mongodb.adoc

@@ -140,6 +140,38 @@ To configure that scenario, simply extend one message store bean from the other:
 </int:channel>
 ----
 
+[[mongodb-metadata-store]]
+==== MongodDB Metadata Store
+
+As of _Spring Integration 4.2_, a new MongodDB-based `MetadataStore` (<<metadata-store>>) implementation is available.
+The `MongoDbMetadataStore` can be used to maintain metadata state across application restarts.
+This new `MetadataStore` implementation can be used with adapters such as:
+
+* <<twitter-inbound>>
+* <<feed-inbound-channel-adapter>>
+* <<file-reading>>
+* <<ftp-inbound>>
+* <<sftp-inbound>>
+
+In order to instruct these adapters to use the new `MongoDbMetadataStore`, simply declare a Spring bean using the
+bean name *metadataStore*. The _Twitter Inbound Channel Adapter_ and the _Feed Inbound Channel Adapter_ will both
+automatically pick up and use the declared `MongoDbMetadataStore`:
+
+[source,java]
+----
+@Bean
+public MetadataStore metadataStore(MongoDbFactory factory) {
+    return new MongoDbMetadataStore(factory, "integrationMetadataStore");
+}
+----
+
+The `MongoDbMetadataStore` also implements `ConcurrentMetadataStore`, allowing it to be reliably shared across multiple
+application instances where only one instance will be allowed to store or modify a key's value.
+All these operations are _atomic_ via MongoDB guarantees. For this purpose the `putIfAbsent` operation is implemented
+as a _stored_ JavaScript function. Fom more information see
+http://docs.spring.io/spring-data/data-mongo/docs/current/reference/html/#mongo.server-side-scripts[Script Operations]
+and `MongoDbMetadataStore` JavaDocs.
+
 [[mongodb-inbound-channel-adapter]]
 === MongoDB Inbound Channel Adapter
 

src/reference/asciidoc/whats-new.adoc

@@ -17,6 +17,11 @@ However, this has some important implications for (some) user environments.
 
 For complete details, see <<jmx-42-improvements>>.
 
+[[x4.2-mongodb-metadata-store]]
+==== MongodDB Metadata Store
+
+The `MongoDbMetadataStore` is now available. For more information, see <<mongodb-metadata-store>>.
+
 [[x4.2-general]]
 === General Changes