grails · jdaugherty · Feb 12, 2025 · Feb 12, 2025
diff --git a/docs/build.gradle b/docs/build.gradle
@@ -1,3 +1,5 @@
+import org.asciidoctor.gradle.jvm.AsciidoctorTask
+
 plugins {
     id 'groovy'
     id 'org.asciidoctor.jvm.convert' version "$asciidoctorGradleVersion"
@@ -58,21 +60,29 @@ dependencies {
     implementation 'org.mongodb:mongodb-driver-sync'
 }
 
-asciidoctor {
-    baseDirFollowsSourceDir()
-    attributes('experimental': 'true',
-               'compat-mode': 'true',
-               'toc': 'left',
-               'icons': 'font',
-               'reproducible': '',
-               'version': projectVersion,
-               'pluginVersion': projectVersion,
-               'mongoDriverVersion': resolveMongodbVersion.resolved,
-               'sourcedir': "$project.rootDir")
-
-    jvm {
-        jvmArgs('--add-opens', 'java.base/sun.nio.ch=ALL-UNNAMED', '--add-opens', 'java.base/java.io=ALL-UNNAMED')
+tasks.named('asciidoctor', AsciidoctorTask) { AsciidoctorTask it ->
+    dependsOn('resolveMongodbVersion')
+
+    inputs.dir project.layout.projectDirectory.dir('src/docs')
+    outputs.dir layout.buildDirectory.dir('docs')
+
+    it.jvm {
+        jvmArgs("--add-opens", "java.base/sun.nio.ch=ALL-UNNAMED", "--add-opens", "java.base/java.io=ALL-UNNAMED")
     }
+    it.baseDirFollowsSourceFile()
+    it.sourceDir layout.projectDirectory.dir('src/docs')
+    it.outputDir = layout.buildDirectory.dir('docs')
+    it.attributes = [
+            'experimental'  : 'true',
+            'compat-mode'   : 'true',
+            'toc'           : 'left',
+            'icons'         : 'font',
+            'reproducible'  : '',
+            'version'       : projectVersion,
+            'pluginVersion' : projectVersion,
+            'mongoDriverVersion': resolveMongodbVersion.resolved,
+            'sourcedir'     : "$project.rootDir"
+    ]
 }
 
 tasks.register('fetchSource') {

diff --git a/docs/src/docs/asciidoc/databaseSwitching.adoc b/docs/src/docs/asciidoc/databaseSwitching.adoc
@@ -1,4 +1,5 @@
-In addition to storing dynamic attributes, as of version 1.3.0 of the plugin you can also switch which database and/or collection to persist to at runtime. 
+== Switching Database or Collection at Runtime
+In addition to storing dynamic attributes, as of version 1.3.0 of the plugin you can also switch which database and/or collection to persist to at runtime.
 
 For example:
 

diff --git a/docs/src/docs/asciidoc/gettingStarted/advancedConfig.adoc b/docs/src/docs/asciidoc/gettingStarted/advancedConfig.adoc
@@ -1,4 +1,4 @@
-
+=== Advanced Configuration
 ==== Mongo Database Connection Configuration
 
 

diff --git a/docs/src/docs/asciidoc/gettingStarted/basicSetup.adoc b/docs/src/docs/asciidoc/gettingStarted/basicSetup.adoc
@@ -0,0 +1,88 @@
+== Getting Started
+=== Basic Setup
+
+To get started with GORM for MongoDB within Grails you need configure it as a dependency in `build.gradle`:
+
+[source,groovy,subs="attributes"]
+----
+dependencies {
+    compile 'org.grails.plugins:mongodb:{pluginVersion}'
+}
+----
+
+=== Common Errors
+
+If you receive an error that indicates a failure to resolve the `grails-datastore-simple` dependency you may need to add the following to `build.gradle` directly above the `dependencies` block:
+
+[source,groovy]
+.build.gradle
+----
+configurations.all {
+    exclude module:'grails-datastore-simple'
+}
+----
+
+If you receive an error at runtime such as:
+
+[source,groovy]
+----
+Caused by: org.bson.codecs.configuration.CodecConfigurationException: Can't find a codec for class org.bson.BsonDecimal128.
+        at org.bson.codecs.configuration.CodecCache.getOrThrow(CodecCache.java:46)
+        at org.bson.codecs.configuration.ProvidersCodecRegistry.get(ProvidersCodecRegistry.java:63)
+        at org.bson.codecs.configuration.ChildCodecRegistry.get(ChildCodecRegistry.java:51)
+        at org.bson.codecs.BsonTypeCodecMap.<init>(BsonTypeCodecMap.java:44)
+        at org.bson.codecs.BsonDocumentCodec.<init>(BsonDocumentCodec.java:65)
+----
+
+It means you have an older version of the MongoDB Java driver on your classpath and you should add the following declaration to `build.gradle` to ensure the dependency is correct:
+
+[source,groovy,subs="attributes"]
+.build.gradle
+----
+compile "org.mongodb:mongodb-driver:{mongoDriverVersion}"
+----
+
+=== Configuring MongoDB
+
+With that done you need to set up a running MongoDB server. Refer to the https://docs.mongodb.com/getting-started/shell/[MongoDB Documentation] for an explanation on how to startup a MongoDB instance. Once installed, starting MongoDB is typically a matter of executing the following command:
+
+[source,groovy]
+----
+MONGO_HOME/bin/mongod
+----
+
+With the above command executed in a terminal window you should see output like the following appear:
+
+[source,groovy]
+----
+2015-11-18T19:38:50.073+0100 I JOURNAL  <<initandlisten>> journal dir=/data/db/journal
+2015-11-18T19:38:50.073+0100 I JOURNAL  <<initandlisten>> recover : no journal files present, no recovery needed
+2015-11-18T19:38:50.090+0100 I JOURNAL  <<durability>> Durability thread started
+2015-11-18T19:38:50.090+0100 I JOURNAL  <<journal writer>> Journal writer thread started
+2015-11-18T19:38:50.090+0100 I CONTROL  <<initandlisten>> MongoDB starting : pid=52540 port=27017 dbpath=/data/db 64-bit host=Graemes-iMac.local
+2015-11-18T19:38:50.090+0100 I CONTROL  <<initandlisten>> ** WARNING: You are running this process as the root user, which is not recommended.
+2015-11-18T19:38:50.090+0100 I CONTROL  <<initandlisten>>
+2015-11-18T19:38:50.090+0100 I CONTROL  <<initandlisten>>
+2015-11-18T19:38:50.090+0100 I CONTROL  <<initandlisten>> ** WARNING: soft rlimits too low. Number of files is 256, should be at least 1000
+2015-11-18T19:38:50.090+0100 I CONTROL  <<initandlisten>> db version v3.0.4
+2015-11-18T19:38:50.090+0100 I CONTROL  <<initandlisten>> git version: 0481c958daeb2969800511e7475dc66986fa9ed5
+2015-11-18T19:38:50.090+0100 I CONTROL  <<initandlisten>> build info: Darwin mci-osx108-11.build.10gen.cc 12.5.0 Darwin Kernel Version 12.5.0: Sun Sep 29 13:33:47 PDT 2013; root:xnu-2050.48.12~1/RELEASE_X86_64 x86_64 BOOST_LIB_VERSION=1_49
+2015-11-18T19:38:50.090+0100 I CONTROL  <<initandlisten>> allocator: system
+2015-11-18T19:38:50.090+0100 I CONTROL  <<initandlisten>> options: {}
+2015-11-18T19:38:50.176+0100 I NETWORK  <<initandlisten>> waiting for connections on port 27017
+----
+
+As you can see the server is running on port 27017, but don't worry the MongoDB plugin for Grails will automatically configure itself to look for MongoDB on that port by default.
+
+If you want to configure how Grails connects to MongoDB then you can do so using the following settings in `grails-app/conf/application.yml`:
+
+[source,groovy]
+----
+grails:
+    mongodb:
+        host: "localhost"
+        port: 27017
+        username: "blah"
+        password: "blah"
+        databaseName: "foo"
+----
diff --git a/docs/src/docs/asciidoc/gettingStarted/mongoOnly.adoc b/docs/src/docs/asciidoc/gettingStarted/mongoOnly.adoc
@@ -1,3 +1,4 @@
+=== Using MongoDB Standalone
 If you plan to use MongoDB as your primary datastore then you need to remove the Hibernate plugin from the `build.gradle` file by commenting out the hibernate line in the plugins block
 
 [source,groovy]

diff --git a/docs/src/docs/asciidoc/gettingStarted/outsideGrails.adoc b/docs/src/docs/asciidoc/gettingStarted/outsideGrails.adoc
@@ -1,3 +1,4 @@
+=== GORM for MongoDB without Grails
 If you wish to use GORM for MongoDB outside of a Grails application you should declare the necessary dependencies, for example in Gradle:
 
 [source,groovy,subs="attributes"]

diff --git a/docs/src/docs/asciidoc/gettingStarted/springBoot.adoc b/docs/src/docs/asciidoc/gettingStarted/springBoot.adoc
@@ -1,3 +1,4 @@
+=== Using GORM in Spring Boot
 To use GORM for MongoDB in Spring Boot add the necessary dependencies to your Boot application:
 
 [source,groovy,subs="attributes"]

diff --git a/docs/src/docs/asciidoc/gettingStarted/withHibernate.adoc b/docs/src/docs/asciidoc/gettingStarted/withHibernate.adoc
@@ -1,3 +1,4 @@
+=== Combining MongoDB and Hibernate
 If you have both the Hibernate and Mongo plugins installed then by default all classes in the `grails-app/domain` directory will be persisted by Hibernate and not Mongo. If you want to persist a particular domain class with Mongo then you must use the `mapWith` property in the domain class:
 
 [source,groovy]

diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc
@@ -10,152 +10,94 @@ Graeme Rocher, Burt Beckwith, Puneet Behl
 include::introduction.adoc[]
 
 [[compatibility]]
-=== Compatibility with GORM for Hibernate
-
 include::introduction/compatibility.adoc[]
 
 [[releaseNotes]]
-=== Release Notes
-
 include::introduction/releaseNotes.adoc[]
 
 [[upgradeNotes]]
-=== Upgrade Notes
-
 include::introduction/upgradeNotes.adoc[]
 
 [[gettingStarted]]
-== Getting Started
-
-include::gettingStarted.adoc[]
+include::gettingStarted/basicSetup.adoc[]
 
 [[mongoOnly]]
-=== Using MongoDB Standalone
-
 include::gettingStarted/mongoOnly.adoc[]
 
 [[withHibernate]]
-=== Combining MongoDB and Hibernate
-
 include::gettingStarted/withHibernate.adoc[]
 
 [[advancedConfig]]
-=== Advanced Configuration
-
 include::gettingStarted/advancedConfig.adoc[]
 
 [[springBoot]]
-=== Using GORM in Spring Boot
-
 include::gettingStarted/springBoot.adoc[]
 
 [[outsideGrails]]
-=== GORM for MongoDB without Grails
-
 include::gettingStarted/outsideGrails.adoc[]
 
 [[objectMapping]]
-== Mapping Domain Classes
-
 include::objectMapping.adoc[]
 
 [[idGeneration]]
-=== Identity Generation
-
 include::objectMapping/idGeneration.adoc[]
 
 [[dirtyChecking]]
-=== Understanding Dirty Checking
-
 include::objectMapping/dirtyChecking.adoc[]
 
 [[queryIndexes]]
-=== Querying Indexing
-
 include::querying/queryIndexes.adoc[]
 
 [[writeConcern]]
-=== Customizing the WriteConcern
-
 include::objectMapping/writeConcern.adoc[]
 
 [[dynamicAttributes]]
-=== Dynamic Attributes
-
 include::objectMapping/dynamicAttributes.adoc[]
 
 [[customTypes]]
-=== Custom User Types
-
 include::objectMapping/customTypes.adoc[]
 
 [[querying]]
 == Querying
 
-[[queryingBasicsl]]
-=== Basic Querying
+[[queryingBasics]]
 include::querying/queryingBasics.adoc[]
 
 [[geoSpatial]]
-=== Geospacial Querying
-
 include::querying/geoSpatial.adoc[]
 
 [[twodsphere]]
-==== Geospacial 2D Sphere Support
-
 include::querying/geoSpatial/2dsphere.adoc[]
 
 [[twodindex]]
-==== Geospacial 2D Index Support
-
 include::querying/geoSpatial/2dindex.adoc[]
 
 [[geoJson]]
-==== GeoJSON Data Models
-
 include::querying/geoSpatial/geoJson.adoc[]
 
 [[textSearch]]
-=== Full Text Search
-
 include::querying/textSearch.adoc[]
 
 [[multipleDataSources]]
-== Multiple Data Sources
 include::multipleDataSources/index.adoc[]
 
 [[databaseSwitching]]
-== Switching Database or Collection at Runtime
-
 include::databaseSwitching.adoc[]
 
 [[multiTenancy]]
-== Multi-Tenancy
 include::multiTenancy/index.adoc[]
 
 [[stateless]]
-== Stateless Mode
-
 include::stateless.adoc[]
 
 [[lowLevelApi]]
-== Using the MongoDB Driver Directly
-
 include::lowLevelApi.adoc[]
 
 [[transactions]]
-== Transactions
-
 include::transactions.adoc[]
 
 [[testing]]
-== Unit Testing
-
 include::testing.adoc[]
-
-== Integration Testing
-
 include::integrationTesting.adoc[]
 
 [[reference]]

diff --git a/docs/src/docs/asciidoc/integrationTesting.adoc b/docs/src/docs/asciidoc/integrationTesting.adoc
@@ -1,3 +1,4 @@
+== Integration Testing
 There is a plugin available that will execute an in memory Mongo database during your integration tests. Data will be cleared between test cases so they can work similarly to H2 with `@Rollback`.
 
 Visit the github page of the link:https://github.com/grails-plugins/grails-embedded-mongodb[Embedded MongoDB Grails Plugin] to learn more.
diff --git a/docs/src/docs/asciidoc/introduction/compatibility.adoc b/docs/src/docs/asciidoc/introduction/compatibility.adoc
@@ -1,3 +1,4 @@
+=== Compatibility with GORM for Hibernate
 This implementation tries to be as compatible as possible with GORM for Hibernate. In general you can refer to the https://grails.org/doc/latest/guide/5.%20Object%20Relational%20Mapping%20(GORM).html[GORM documentation] and the "Domain Classes" section of the https://grails.org/doc/latest/[reference guide] (see the right nav) for usage information.
 
 The following key features are supported by GORM for Mongo:

diff --git a/docs/src/docs/asciidoc/introduction/releaseNotes.adoc b/docs/src/docs/asciidoc/introduction/releaseNotes.adoc
@@ -1,3 +1,4 @@
+=== Release Notes
 Below are the details of the changes across releases:
 
 ==== 7.1

diff --git a/docs/src/docs/asciidoc/introduction/upgradeNotes.adoc b/docs/src/docs/asciidoc/introduction/upgradeNotes.adoc
@@ -1,3 +1,4 @@
+=== Upgrade Notes
 ==== Dependency Upgrades
 
 GORM 7.1 supports Apache Groovy 3, Java 14, MongoDB Driver 4.3 and Spring 5.3.x.

diff --git a/docs/src/docs/asciidoc/lowLevelApi.adoc b/docs/src/docs/asciidoc/lowLevelApi.adoc
@@ -1,3 +1,4 @@
+== Using the MongoDB Driver Directly
 A lower level API is provided by the plugin via the MongoDB driver
 
 NOTE: There is an excellent tutorial on how to use the MongoDB Java driver's API directly in the https://mongodb.github.io/mongo-java-driver/3.1/driver/getting-started/quick-tour/[MongoDB documentation]

diff --git a/docs/src/docs/asciidoc/multiTenancy/configuration.adoc b/docs/src/docs/asciidoc/multiTenancy/configuration.adoc
@@ -1,3 +1,4 @@
+=== Configuring Multi Tenancy
 You can configure Multi-Tenancy the same way described in the link:../../hibernate/manual/index.html#multiTenancy[GORM for Hibernate documenation], simply specify a multi tenancy mode and resolver:
 
 [source,yaml]

diff --git a/docs/src/docs/asciidoc/multiTenancy/dynamicConnectionSources.adoc b/docs/src/docs/asciidoc/multiTenancy/dynamicConnectionSources.adoc
@@ -1,3 +1,4 @@
+=== Dynamic ConnectionSources
 If you are using a multi-tenancy mode of `DATABASE` then by default the expectation is that all tenants are configured in your `application.yml` file.
 
 However, it is possible read your Mongo client connection sources dynamically using link:../api/org/grails/datastore/mapping/mongo/connections/MongoConnectionSources.html[MongoConnectionSources].

diff --git a/docs/src/docs/asciidoc/multiTenancy/index.adoc b/docs/src/docs/asciidoc/multiTenancy/index.adoc
@@ -1,21 +1,14 @@
+== Multi-Tenancy
 GORM for MongoDb supports the following multi-tenancy modes:
 
 * `DATABASE` - A separate database with a separate connection pool is used to store each tenants data.
 * `SCHEMA` - The same database, but different schemas are used to store each tenants data.
 * `DISCRIMINATOR` - The same database is used with a discriminator used to partition and isolate data.
 
-=== Configuring Multi Tenancy
-
 include::configuration.adoc[]
 
-=== Multi-Tenancy Transformations
-
 include::tenantTransforms.adoc[]
 
-=== Multi Tenancy Modes
-
 include::multiTenancyModes.adoc[]
 
-=== Dynamic ConnectionSources
-
 include::dynamicConnectionSources.adoc[]
diff --git a/docs/src/docs/asciidoc/multiTenancy/multiTenancyModes.adoc b/docs/src/docs/asciidoc/multiTenancy/multiTenancyModes.adoc
@@ -1,3 +1,4 @@
+=== Multi Tenancy Modes
 As mentioned previously, GORM for MongoDB supports all three multi tenancy modes however there are some considerations to keep in mind.
 
 ==== Database Per Tenant

diff --git a/docs/src/docs/asciidoc/multiTenancy/tenantTransforms.adoc b/docs/src/docs/asciidoc/multiTenancy/tenantTransforms.adoc
@@ -1,3 +1,4 @@
+=== Multi-Tenancy Transformations
 The following transformations can be applied to any class to simplify greatly the development of Multi-Tenant applications. These include:
 
 - `@CurrentTenant` - Resolve the current tenant for the context of a class or method
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,4 @@

		=== Advanced Configuration
		==== Mongo Database Connection Configuration


Expand Down