From 39259ec29db488d24052ee135e063d2d21a77d0d Mon Sep 17 00:00:00 2001 From: James Daugherty Date: Wed, 12 Feb 2025 11:30:27 -0500 Subject: [PATCH] Doc fixes from data-mapping merge attempt --- docs/build.gradle | 38 +++++--- docs/src/docs/asciidoc/databaseSwitching.adoc | 3 +- .../gettingStarted/advancedConfig.adoc | 2 +- .../asciidoc/gettingStarted/basicSetup.adoc | 88 +++++++++++++++++++ .../asciidoc/gettingStarted/mongoOnly.adoc | 1 + .../gettingStarted/outsideGrails.adoc | 1 + .../asciidoc/gettingStarted/springBoot.adoc | 1 + .../gettingStarted/withHibernate.adoc | 1 + docs/src/docs/asciidoc/index.adoc | 62 +------------ .../src/docs/asciidoc/integrationTesting.adoc | 1 + .../asciidoc/introduction/compatibility.adoc | 1 + .../asciidoc/introduction/releaseNotes.adoc | 1 + .../asciidoc/introduction/upgradeNotes.adoc | 1 + docs/src/docs/asciidoc/lowLevelApi.adoc | 1 + .../asciidoc/multiTenancy/configuration.adoc | 1 + .../dynamicConnectionSources.adoc | 1 + .../src/docs/asciidoc/multiTenancy/index.adoc | 9 +- .../multiTenancy/multiTenancyModes.adoc | 1 + .../multiTenancy/tenantTransforms.adoc | 1 + .../asciidoc/multipleDataSources/index.adoc | 1 + docs/src/docs/asciidoc/objectMapping.adoc | 10 +-- .../asciidoc/objectMapping/customTypes.adoc | 1 + .../asciidoc/objectMapping/dirtyChecking.adoc | 1 + .../objectMapping/dynamicAttributes.adoc | 1 + .../asciidoc/objectMapping/idGeneration.adoc | 1 + .../asciidoc/objectMapping/writeConcern.adoc | 1 + .../docs/asciidoc/querying/geoSpatial.adoc | 1 + .../asciidoc/querying/geoSpatial/2dindex.adoc | 1 + .../querying/geoSpatial/2dsphere.adoc | 2 +- .../asciidoc/querying/geoSpatial/geoJson.adoc | 1 + .../docs/asciidoc/querying/queryIndexes.adoc | 2 +- .../asciidoc/querying/queryingBasics.adoc | 1 + .../docs/asciidoc/querying/textSearch.adoc | 1 + docs/src/docs/asciidoc/stateless.adoc | 10 +-- docs/src/docs/asciidoc/testing.adoc | 1 + docs/src/docs/asciidoc/transactions.adoc | 1 + 36 files changed, 156 insertions(+), 96 deletions(-) create mode 100644 docs/src/docs/asciidoc/gettingStarted/basicSetup.adoc diff --git a/docs/build.gradle b/docs/build.gradle index 452c7efa..882a6aed 100644 --- 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 index 2eb1f596..7ed1a179 100644 --- 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 index f1a77a67..f76a4d25 100644 --- 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 new file mode 100644 index 00000000..25905f7e --- /dev/null +++ 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.(BsonTypeCodecMap.java:44) + at org.bson.codecs.BsonDocumentCodec.(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 <> journal dir=/data/db/journal +2015-11-18T19:38:50.073+0100 I JOURNAL <> recover : no journal files present, no recovery needed +2015-11-18T19:38:50.090+0100 I JOURNAL <> Durability thread started +2015-11-18T19:38:50.090+0100 I JOURNAL <> Journal writer thread started +2015-11-18T19:38:50.090+0100 I CONTROL <> MongoDB starting : pid=52540 port=27017 dbpath=/data/db 64-bit host=Graemes-iMac.local +2015-11-18T19:38:50.090+0100 I CONTROL <> ** WARNING: You are running this process as the root user, which is not recommended. +2015-11-18T19:38:50.090+0100 I CONTROL <> +2015-11-18T19:38:50.090+0100 I CONTROL <> +2015-11-18T19:38:50.090+0100 I CONTROL <> ** WARNING: soft rlimits too low. Number of files is 256, should be at least 1000 +2015-11-18T19:38:50.090+0100 I CONTROL <> db version v3.0.4 +2015-11-18T19:38:50.090+0100 I CONTROL <> git version: 0481c958daeb2969800511e7475dc66986fa9ed5 +2015-11-18T19:38:50.090+0100 I CONTROL <> 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 <> allocator: system +2015-11-18T19:38:50.090+0100 I CONTROL <> options: {} +2015-11-18T19:38:50.176+0100 I NETWORK <> 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 index 79e508b7..4c30ec62 100644 --- 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 index a4c76940..b749796e 100644 --- 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 index 1c9cc9aa..28616e91 100644 --- 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 index 9efdabee..d95370d4 100644 --- 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 index 025759f1..e69a5f0d 100644 --- 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 index 50cb2315..21c8d44f 100644 --- 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. \ No newline at end of file diff --git a/docs/src/docs/asciidoc/introduction/compatibility.adoc b/docs/src/docs/asciidoc/introduction/compatibility.adoc index 7b1d340e..4c718f6a 100644 --- 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 index b32e05e1..e7a8e130 100644 --- 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 index b9fd5bb0..91f47ee4 100644 --- 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 index 5ba58970..97b68572 100644 --- 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 index f624c703..2b12d526 100644 --- 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 index 50be0dae..da9053b3 100644 --- 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 index 9bb0bed8..3c1f3939 100644 --- 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 index 21851c6f..3a7c942b 100644 --- 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 index 949b072b..ea235927 100644 --- 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 diff --git a/docs/src/docs/asciidoc/multipleDataSources/index.adoc b/docs/src/docs/asciidoc/multipleDataSources/index.adoc index 87cf04f7..2626524d 100644 --- a/docs/src/docs/asciidoc/multipleDataSources/index.adoc +++ b/docs/src/docs/asciidoc/multipleDataSources/index.adoc @@ -1,3 +1,4 @@ +== Multiple Data Sources GORM for MongoDB supports the notion of multiple data sources where multiple individual `MongoClient` instances can be configured and switched between. === Configuring Multiple Mongo Clients diff --git a/docs/src/docs/asciidoc/objectMapping.adoc b/docs/src/docs/asciidoc/objectMapping.adoc index b874768d..a02c400f 100644 --- a/docs/src/docs/asciidoc/objectMapping.adoc +++ b/docs/src/docs/asciidoc/objectMapping.adoc @@ -1,5 +1,5 @@ - -==== Basic Mapping +== Mapping Domain Classes +=== Basic Mapping The way GORM for MongoDB works is to map each domain class to a Mongo collection. For example given a domain class such as: @@ -16,7 +16,7 @@ class Person { This will map onto a MongoDB https://api.mongodb.org/java/current/com/mongodb/client/MongoCollection.html[Collection] called "person". -==== Embedded Documents +=== Embedded Documents It is quite common in MongoDB to embed documents within documents (nested documents). This can be done with GORM embedded types: @@ -58,7 +58,7 @@ class Person { -==== Basic Collection Types +=== Basic Collection Types You can also map lists and maps of basic types (such as strings) simply by defining the appropriate collection type: @@ -78,7 +78,7 @@ new Person(friends:['Fred', 'Bob'], pets:[chuck:"Dog", eddie:'Parrot']).save(flu Basic collection types are stored as native ArrayList and BSON documents within the Mongo documents. -==== Customized Collection and Database Mapping +=== Customized Collection and Database Mapping You may wish to customize how a domain class maps onto a `MongoCollection`. This is possible using the `mapping` block as follows: diff --git a/docs/src/docs/asciidoc/objectMapping/customTypes.adoc b/docs/src/docs/asciidoc/objectMapping/customTypes.adoc index a96c05ca..01ee8be2 100644 --- a/docs/src/docs/asciidoc/objectMapping/customTypes.adoc +++ b/docs/src/docs/asciidoc/objectMapping/customTypes.adoc @@ -1,3 +1,4 @@ +=== Custom User Types GORM for MongoDB will persist all common known Java types like String, Integer, URL etc., however if you want to persist one of your own classes that is not a domain class you can implement a custom user type. ==== Custom Codecs diff --git a/docs/src/docs/asciidoc/objectMapping/dirtyChecking.adoc b/docs/src/docs/asciidoc/objectMapping/dirtyChecking.adoc index 1176d50c..6613d577 100644 --- a/docs/src/docs/asciidoc/objectMapping/dirtyChecking.adoc +++ b/docs/src/docs/asciidoc/objectMapping/dirtyChecking.adoc @@ -1,3 +1,4 @@ +=== Understanding Dirty Checking In order to be as efficient as possible when it comes to generating updates GORM for MongoDb will track changes you make to persistent instances. When an object is updated only the properties or associations that have changed will be updated. diff --git a/docs/src/docs/asciidoc/objectMapping/dynamicAttributes.adoc b/docs/src/docs/asciidoc/objectMapping/dynamicAttributes.adoc index 6c996d83..135bdbb7 100644 --- a/docs/src/docs/asciidoc/objectMapping/dynamicAttributes.adoc +++ b/docs/src/docs/asciidoc/objectMapping/dynamicAttributes.adoc @@ -1,3 +1,4 @@ +=== Dynamic Attributes Unlike a relational database, MongoDB allows for "schemaless" persistence where there are no limits to the number of attributes a particular document can have. A GORM domain class on the other hand has a schema in that there are a fixed number of properties. For example consider the following domain class: [source,groovy] diff --git a/docs/src/docs/asciidoc/objectMapping/idGeneration.adoc b/docs/src/docs/asciidoc/objectMapping/idGeneration.adoc index 05709eb1..644aadf3 100644 --- a/docs/src/docs/asciidoc/objectMapping/idGeneration.adoc +++ b/docs/src/docs/asciidoc/objectMapping/idGeneration.adoc @@ -1,3 +1,4 @@ +=== Identity Generation By default in GORM entities are supplied with an integer-based identifier. So for example the following entity: [source,groovy] diff --git a/docs/src/docs/asciidoc/objectMapping/writeConcern.adoc b/docs/src/docs/asciidoc/objectMapping/writeConcern.adoc index 8c82fe5d..43a76f25 100644 --- a/docs/src/docs/asciidoc/objectMapping/writeConcern.adoc +++ b/docs/src/docs/asciidoc/objectMapping/writeConcern.adoc @@ -1,3 +1,4 @@ +=== Customizing the WriteConcern A feature of MongoDB is its ability to customize how important a database write is to the user. The Java client models this as a https://api.mongodb.org/java/current/com/mongodb/WriteConcern.html[WriteConcern] and there are various options that indicate whether the client cares about server or network errors, or whether the data has been successfully written or not. If you wish to customize the `WriteConcern` for a domain class you can do so in the mapping block: diff --git a/docs/src/docs/asciidoc/querying/geoSpatial.adoc b/docs/src/docs/asciidoc/querying/geoSpatial.adoc index 400d5637..b04bd65a 100644 --- a/docs/src/docs/asciidoc/querying/geoSpatial.adoc +++ b/docs/src/docs/asciidoc/querying/geoSpatial.adoc @@ -1,3 +1,4 @@ +=== Geospacial Querying MongoDB supports storing https://docs.mongodb.org/manual/applications/geospatial-indexes/[Geospacial data] in both flat and spherical surface types. To store data in a flat surface you use a "2d" index, whilst a "2dsphere" index used for spherical data. GORM for MongoDB supports both and the following sections describe how to define and query Geospacial data. diff --git a/docs/src/docs/asciidoc/querying/geoSpatial/2dindex.adoc b/docs/src/docs/asciidoc/querying/geoSpatial/2dindex.adoc index c2af642d..26001422 100644 --- a/docs/src/docs/asciidoc/querying/geoSpatial/2dindex.adoc +++ b/docs/src/docs/asciidoc/querying/geoSpatial/2dindex.adoc @@ -1,3 +1,4 @@ +==== Geospacial 2D Index Support MongoDB supports https://docs.mongodb.org/manual/core/2d/[2d indexes] that store points on a two-dimensional plane. although they are considered legacy and you should use `2dsphere` indexes instead. It is possible to use a MongoDB 2d index by mapping a list or map property using the `geoIndex` mapping: diff --git a/docs/src/docs/asciidoc/querying/geoSpatial/2dsphere.adoc b/docs/src/docs/asciidoc/querying/geoSpatial/2dsphere.adoc index c456a8fe..62338ca2 100644 --- a/docs/src/docs/asciidoc/querying/geoSpatial/2dsphere.adoc +++ b/docs/src/docs/asciidoc/querying/geoSpatial/2dsphere.adoc @@ -1,4 +1,4 @@ - +==== Geospacial 2D Sphere Support ==== Using a 2dsphere Index diff --git a/docs/src/docs/asciidoc/querying/geoSpatial/geoJson.adoc b/docs/src/docs/asciidoc/querying/geoSpatial/geoJson.adoc index 7b679fe9..1aba055f 100644 --- a/docs/src/docs/asciidoc/querying/geoSpatial/geoJson.adoc +++ b/docs/src/docs/asciidoc/querying/geoSpatial/geoJson.adoc @@ -1,3 +1,4 @@ +==== GeoJSON Data Models You can also store any GeoJSON shape using the `grails.mongodb.geo.Shape` super class: [source,groovy] diff --git a/docs/src/docs/asciidoc/querying/queryIndexes.adoc b/docs/src/docs/asciidoc/querying/queryIndexes.adoc index 07067fd4..dde8bc80 100644 --- a/docs/src/docs/asciidoc/querying/queryIndexes.adoc +++ b/docs/src/docs/asciidoc/querying/queryIndexes.adoc @@ -1,4 +1,4 @@ - +=== Querying Indexing ==== Basics diff --git a/docs/src/docs/asciidoc/querying/queryingBasics.adoc b/docs/src/docs/asciidoc/querying/queryingBasics.adoc index 3e587c20..7015723f 100644 --- a/docs/src/docs/asciidoc/querying/queryingBasics.adoc +++ b/docs/src/docs/asciidoc/querying/queryingBasics.adoc @@ -1,3 +1,4 @@ +=== Basic Querying GORM for MongoDB supports all of the https://gorm.grails.org/latest/hibernate/manual/index.html#querying[regular methods] for executing GORM queries apart from HQL, which is a Hibernate specific query language more appropriate for SQL databases. If you wish to execute a native MongoDB query you can use the `find` method that takes a https://api.mongodb.com/java/current/org/bson/conversions/Bson.html[Bson] argument. For example: diff --git a/docs/src/docs/asciidoc/querying/textSearch.adoc b/docs/src/docs/asciidoc/querying/textSearch.adoc index ae34cc21..8d21b5bb 100644 --- a/docs/src/docs/asciidoc/querying/textSearch.adoc +++ b/docs/src/docs/asciidoc/querying/textSearch.adoc @@ -1,3 +1,4 @@ +=== Full Text Search Using MongoDB 2.6 and above you can create https://docs.mongodb.org/manual/reference/operator/query/text/#op._S_text[full text search] indices. To create a "text" index using the `index` method inside the `mapping` block: diff --git a/docs/src/docs/asciidoc/stateless.adoc b/docs/src/docs/asciidoc/stateless.adoc index c3ef32d3..8808ec02 100644 --- a/docs/src/docs/asciidoc/stateless.adoc +++ b/docs/src/docs/asciidoc/stateless.adoc @@ -1,12 +1,12 @@ +== Stateless Mode GORM for MongoDB supports both stateless and stateful modes for mapping domain classes to MongoDB. In general stateful mapping is superior for write heavy applications and stateless mode better for read heavy applications (particularily when large amounts of data is involved). -==== Stateful mode - +=== Stateful mode Domain classes are by default stateful, which means when they are read from a MongoDB document their state is stored in the user session (which is typically bound to the request in Grails). This has several advantages for write heavy applications: -* GORM can automatically detect whether a call to save() is a an update or an insert and act appropriately +* GORM can automatically detect whether a call to save() is an update or an insert and act appropriately * GORM stores the state of the read MongoDB document and therefore updates to schemaless properties don't require an extra query * GORM can store the current version and therefore implement optimistic locking * Repeated reads of the same entity can be retrieved from the cache, thus optimizing reads as well @@ -26,7 +26,7 @@ With a stateful entity the updates to the three properties can be batched up and -==== Stateless Domain classes +=== Stateless Domain classes However, stateful domain classes can cause problems for read-heavy applications. Take for example the following code: @@ -64,7 +64,7 @@ class Book { ---- -==== Disadvantages of Stateless Mode +=== Disadvantages of Stateless Mode There are several disadvantages to using stateless domain classes as the default. One disadvantage is that if you are using assigned identifiers GORM cannot detect whether you want to do an insert or an update so you have to be explicit about which one you want: diff --git a/docs/src/docs/asciidoc/testing.adoc b/docs/src/docs/asciidoc/testing.adoc index 7e3ae996..0f1d9f94 100644 --- a/docs/src/docs/asciidoc/testing.adoc +++ b/docs/src/docs/asciidoc/testing.adoc @@ -1,3 +1,4 @@ +== Unit Testing To write unit tests with MongoDB and Spock you can simply extend from `grails.test.mongodb.MongoSpec`. `MongoSpec` is an abstract class that will initialise GORM in the setup phase of the specification being executed. It diff --git a/docs/src/docs/asciidoc/transactions.adoc b/docs/src/docs/asciidoc/transactions.adoc index d7851d33..c32878d6 100644 --- a/docs/src/docs/asciidoc/transactions.adoc +++ b/docs/src/docs/asciidoc/transactions.adoc @@ -1,3 +1,4 @@ +== Transactions MongoDB doesn't support transactions directly, however GORM for MongoDB does batch up inserts and updates until the session is flushed. This makes it possible to support some rollback options. You can use either transactional services or the static `withTransaction` method. To mark a service as using the MongoDB transaction manager, use the static `transactional` property with the value `'mongo'`: