diff --git a/src/main/antora/modules/ROOT/examples/MongoApplication.java b/src/main/antora/modules/ROOT/examples/MongoApplication.java new file mode 100644 index 000000000..b7cb8d3ff --- /dev/null +++ b/src/main/antora/modules/ROOT/examples/MongoApplication.java @@ -0,0 +1,40 @@ +/* + * Copyright 2023 the original author or authors. + * + * Licensed 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 + * + * https://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. + */ +// tag::file[] +package org.springframework.data.mongodb.example; + +import static org.springframework.data.mongodb.core.query.Criteria.where; +import static org.springframework.data.mongodb.core.query.Query.query; + +import org.springframework.data.mongodb.core.MongoOperations; +import org.springframework.data.mongodb.core.MongoTemplate; +import org.springframework.data.mongodb.core.query.Query; + +import com.mongodb.client.MongoClients; + +public class MongoApplication { + + public static void main(String[] args) throws Exception { + + MongoOperations mongoOps = new MongoTemplate(MongoClients.create(), "database"); + mongoOps.insert(new Person("Joe", 34)); + + System.out.println(mongoOps.query(Person.class).matching(where("name").is("Joe")).firstValue()); + + mongoOps.dropCollection("person"); + } +} +//end::file[] diff --git a/src/main/antora/modules/ROOT/examples/Person.java b/src/main/antora/modules/ROOT/examples/Person.java new file mode 100644 index 000000000..561f24b06 --- /dev/null +++ b/src/main/antora/modules/ROOT/examples/Person.java @@ -0,0 +1,47 @@ +/* + * Copyright 2023 the original author or authors. + * + * Licensed 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 + * + * https://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. + */ +// tag::file[] +package org.springframework.data.mongodb.example; + +public class Person { + + private String id; + private String name; + private int age; + + public Person(String name, int age) { + this.name = name; + this.age = age; + } + + public String getId() { + return id; + } + + public String getName() { + return name; + } + + public int getAge() { + return age; + } + + @Override + public String toString() { + return "Person [id=" + id + ", name=" + name + ", age=" + age + "]"; + } +} +// end::file[] diff --git a/src/main/antora/modules/ROOT/examples/ReactiveMongoApplication.java b/src/main/antora/modules/ROOT/examples/ReactiveMongoApplication.java new file mode 100644 index 000000000..7ade8622d --- /dev/null +++ b/src/main/antora/modules/ROOT/examples/ReactiveMongoApplication.java @@ -0,0 +1,41 @@ +/* + * Copyright 2023 the original author or authors. + * + * Licensed 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 + * + * https://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. + */ +// tag::file[] +package org.springframework.data.mongodb.example; + +import static org.springframework.data.mongodb.core.query.Criteria.*; +import static org.springframework.data.mongodb.core.query.Query.*; + +import org.springframework.data.mongodb.core.ReactiveMongoOperations; +import org.springframework.data.mongodb.core.ReactiveMongoTemplate; + +import com.mongodb.reactivestreams.client.MongoClients; + +public class ReactiveMongoApplication { + + public static void main(String[] args) throws Exception { + + ReactiveMongoOperations mongoOps = new ReactiveMongoTemplate(MongoClients.create(), "database"); + + Mono joe = mongoOps.insert(new Person("Joe", 34)) + .then(mongoOps.query(Person.class).matching(where("name").is("Joe")).first()) + .doOnNext(System.out::println) + .block(); + + mongoOps.dropCollection("person").block(); + } +} +// end::file[] diff --git a/src/main/antora/modules/ROOT/nav.adoc b/src/main/antora/modules/ROOT/nav.adoc index b7d04618c..a83e3599e 100644 --- a/src/main/antora/modules/ROOT/nav.adoc +++ b/src/main/antora/modules/ROOT/nav.adoc @@ -1,11 +1,12 @@ * xref:index.adoc[Overview] -* xref:preface.adoc[] -* xref:upgrading.adoc[] -** xref:mongodb/introduction.adoc[] -** xref:mongodb/mongodb.adoc[] -*** xref:mongodb/getting-started.adoc[] -*** xref:mongodb/mongo-examples-repo.adoc[] -*** xref:mongodb/connectors.adoc[] +** xref:commons/upgrade.adoc[] +** xref:migration-guides.adoc[] +*** xref:migration-guide/migration-guide-2.x-to-3.x.adoc[] +*** xref:migration-guide/migration-guide-3.x-to-4.x.adoc[] + +* xref:mongodb.adoc[] +** xref:mongodb/getting-started.adoc[] +** xref:mongodb/configuration.adoc[] *** xref:mongodb/mongo-template.adoc[] *** xref:mongodb/mongo-template-save-update-remove.adoc[] *** xref:mongodb/mongo-query.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-2.x-to-3.x.adoc b/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-2.x-to-3.x.adoc new file mode 100644 index 000000000..5771eff54 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-2.x-to-3.x.adoc @@ -0,0 +1,58 @@ +[[mongodb.migration.2.x-3.x]] +== Migration Guide from 2.x to 3.x + +Spring Data MongoDB 3.x requires the MongoDB Java Driver 4.x + +To learn more about driver versions please visit the https://www.mongodb.com/docs/drivers/java/sync/current/upgrade/[MongoDB Documentation]. + +[[dependency-changes]] +=== Dependency Changes + +* `org.mongodb:mongo-java-driver` (uber jar) got replaced with: +** bson-jar +** core-jar +** sync-jar + +The change in dependencies allows usage of the reactive support without having to pull the synchronous driver. +NOTE: The new sync driver does no longer support `com.mongodb.DBObject`. Please use `org.bson.Document` instead. + +[[signature-changes]] +=== Signature Changes + +* `MongoTemplate` no longer supports `com.mongodb.MongoClient` and `com.mongodb.MongoClientOptions`. +Please use `com.mongodb.client.MongoClient` and `com.mongodb.MongoClientSettings` instead. + +In case you're using `AbstractMongoConfiguration` please switch to `AbstractMongoClientConfiguration`. + +[[namespace-changes]] +=== Namespace Changes + +The switch to `com.mongodb.client.MongoClient` requires an update of your configuration XML if you have one. +The best way to provide required connection information is by using a connection string. +Please see the https://docs.mongodb.com/manual/reference/connection-string/[MongoDB Documentation] for details. + +[source,xml] +==== +---- + +---- + +---- + + + + + +---- + +---- + + + +---- +==== diff --git a/src/main/antora/modules/ROOT/pages/upgrading.adoc b/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-3.x-to-4.x.adoc similarity index 53% rename from src/main/antora/modules/ROOT/pages/upgrading.adoc rename to src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-3.x-to-4.x.adoc index a32be6aa2..de8745621 100644 --- a/src/main/antora/modules/ROOT/pages/upgrading.adoc +++ b/src/main/antora/modules/ROOT/pages/migration-guide/migration-guide-3.x-to-4.x.adoc @@ -1,11 +1,5 @@ -[[upgrading.data-mongo]] -= Upgrading -:page-section-summary-toc: 1 - -include::{spring-data-commons-docs}/upgrade.adoc[leveloffset=+1] - -[[upgrading.3-4]] -== Upgrading MongoDB Drivers +[[mongodb.migration.3.x-4.x]] +== Migration Guide from 3.x to 4.x Spring Data MongoDB 4.x requires the MongoDB Java Driver 4.8.x + To learn more about driver versions please visit the https://www.mongodb.com/docs/drivers/java/sync/current/upgrade/[MongoDB Documentation]. diff --git a/src/main/antora/modules/ROOT/pages/migration-guides.adoc b/src/main/antora/modules/ROOT/pages/migration-guides.adoc new file mode 100644 index 000000000..3f8e783a1 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/migration-guides.adoc @@ -0,0 +1,8 @@ +[[mongodb.migration]] += Migration Guides +:page-section-summary-toc: 1 + +This section contains version-specific migration guides explaining how to upgrade between two versions. + + + diff --git a/src/main/antora/modules/ROOT/pages/mongodb.adoc b/src/main/antora/modules/ROOT/pages/mongodb.adoc index d54417859..eebf9a914 100644 --- a/src/main/antora/modules/ROOT/pages/mongodb.adoc +++ b/src/main/antora/modules/ROOT/pages/mongodb.adoc @@ -2,16 +2,21 @@ = MongoDB Support :page-section-summary-toc: 1 -Spring Data support for Apache Cassandra contains a wide range of features: +Spring Data support for MongoDB contains a wide range of features: -* Spring configuration support with xref:cassandra/configuration.adoc[Java-based `@Configuration` classes or the XML namespace]. -* The xref:cassandra/cql-template.adoc[`CqlTemplate`, `AsyncCqlTemplate`, and `ReactiveCqlTemplate`] helper classes that increases productivity by properly handling common Cassandra data access operations. -* The xref:cassandra/template.adoc[`CassandraTemplate`, `AsyncCassandraTemplate`, and `ReactiveCassandraTemplate`] helper classes that provide object mapping between CQL Tables and POJOs. -* xref:cassandra/cql-template.adoc#exception-translation[Exception translation] into Spring's portable {springDocsUrl}data-access.html#dao-exceptions[Data Access Exception Hierarchy]. -* Feature rich xref:object-mapping.adoc[object mapping] integrated with _Spring's_ {springDocsUrl}core.html#core-convert[Conversion Service]. -* xref:object-mapping.adoc#mapping.usage-annotations[Annotation-based mapping] metadata that is extensible to support other metadata formats. -* Java-based xref:cassandra/template.adoc#cassandra.template.query[query, criteria, and update DSLs]. -* Automatic implementation of xref:repositories.adoc[imperative and reactive `Repository` interfaces] including support for xref:repositories/custom-implementations.adoc[custom query methods]. +* Spring configuration support with Java-based `@Configuration` classes or an XML namespace for a Mongo driver instance and replica sets. +* `MongoTemplate` helper class that increases productivity when performing common Mongo operations. Includes integrated object mapping between documents and POJOs. +* Exception translation into Spring's portable Data Access Exception hierarchy. +* Feature-rich Object Mapping integrated with Spring's Conversion Service. +* Annotation-based mapping metadata that is extensible to support other metadata formats. +* Persistence and mapping lifecycle events. +* Java-based Query, Criteria, and Update DSLs. +* Automatic implementation of Repository interfaces, including support for custom finder methods. +* QueryDSL integration to support type-safe queries. +* Multi Document Transactions. +* GeoSpatial integration. -For most data-oriented tasks, you can use the `[Reactive|Async]CassandraTemplate` or the `Repository` support, both of which use the rich object-mapping functionality. `[Reactive|Async]CqlTemplate` is commonly used to increment counters or perform ad-hoc CRUD operations. `[Reactive|Async]CqlTemplate` also provides callback methods that make it easy to get low-level API objects, such as `com.datastax.oss.driver.api.core.CqlSession`, which lets you communicate directly with Cassandra. -Spring Data for Apache Cassandra uses consistent naming conventions on objects in various APIs to those found in the DataStax Java Driver so that they are familiar and so that you can map your existing knowledge onto the Spring APIs. +For most tasks, you should use `MongoTemplate` or the Repository support, which both leverage the rich mapping functionality. +`MongoTemplate` is the place to look for accessing functionality such as incrementing counters or ad-hoc CRUD operations. +`MongoTemplate` also provides callback methods so that it is easy for you to get the low-level API artifacts, such as `com.mongodb.client.MongoDatabase`, to communicate directly with MongoDB. +The goal with naming conventions on various API artifacts is to copy those in the base MongoDB Java driver so you can easily map your existing knowledge onto the Spring APIs. diff --git a/src/main/antora/modules/ROOT/pages/mongodb/connectors.adoc b/src/main/antora/modules/ROOT/pages/mongodb/configuration.adoc similarity index 100% rename from src/main/antora/modules/ROOT/pages/mongodb/connectors.adoc rename to src/main/antora/modules/ROOT/pages/mongodb/configuration.adoc diff --git a/src/main/antora/modules/ROOT/pages/mongodb/getting-started.adoc b/src/main/antora/modules/ROOT/pages/mongodb/getting-started.adoc index b8ab3efd6..19aaff74a 100644 --- a/src/main/antora/modules/ROOT/pages/mongodb/getting-started.adoc +++ b/src/main/antora/modules/ROOT/pages/mongodb/getting-started.adoc @@ -1,139 +1,61 @@ [[mongodb-getting-started]] = Getting Started -An easy way to bootstrap setting up a working environment is to create a Spring-based project in https://spring.io/tools/[STS]. +An easy way to bootstrap setting up a working environment is to create a Spring-based project via https://start.spring.io/#!type=maven-project&dependencies=data-mongodb[start.spring.io] or create a Spring project in https://spring.io/tools[Spring Tools]. -First, you need to set up a running MongoDB server. Refer to the https://docs.mongodb.org/manual/core/introduction/[MongoDB Quick Start guide] for an explanation on how to startup a MongoDB instance. Once installed, starting MongoDB is typically a matter of running the following command: `${MONGO_HOME}/bin/mongod` +[[mongo.examples-repo]] +== Examples Repository -To create a Spring project in STS: +The GitHub https://github.com/spring-projects/spring-data-examples[spring-data-examples repository] hosts several examples that you can download and play around with to get a feel for how the library works. -. Go to File -> New -> Spring Template Project -> Simple Spring Utility Project, and press Yes when prompted. Then enter a project and a package name, such as `org.spring.mongodb.example`. -. Add the following to the pom.xml files `dependencies` element: -+ -[source,xml,subs="+attributes"] ----- - - - - - - org.springframework.data - spring-data-mongodb - {version} - - - ----- -. Change the version of Spring in the pom.xml to be -+ -[source,xml,subs="+attributes"] ----- -{springVersion} ----- -. Add the following location of the Spring Milestone repository for Maven to your `pom.xml` such that it is at the same level of your `` element: -+ -[source,xml] ----- - - - spring-milestone - Spring Maven MILESTONE Repository - https://repo.spring.io/milestone - - ----- +[[mongodb.hello-world]] +== Hello World -The repository is also https://repo.spring.io/milestone/org/springframework/data/[browseable here]. - -You may also want to set the logging level to `DEBUG` to see some additional information. To do so, edit the `log4j.properties` file to have the following content: - -[source] ----- -log4j.category.org.springframework.data.mongodb=DEBUG -log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %40.40c:%4L - %m%n ----- +First, you need to set up a running MongoDB server. Refer to the https://docs.mongodb.org/manual/core/introduction/[MongoDB Quick Start guide] for an explanation on how to startup a MongoDB instance. +Once installed, starting MongoDB is typically a matter of running the following command: `${MONGO_HOME}/bin/mongod` Then you can create a `Person` class to persist: +==== [source,java] ---- -package org.spring.mongodb.example; - -public class Person { - - private String id; - private String name; - private int age; - - public Person(String name, int age) { - this.name = name; - this.age = age; - } - - public String getId() { - return id; - } - public String getName() { - return name; - } - public int getAge() { - return age; - } - - @Override - public String toString() { - return "Person [id=" + id + ", name=" + name + ", age=" + age + "]"; - } -} +include::example$Person.java[tags=file] ---- +==== You also need a main application to run: -[source,java] +[tabs] +====== +Imperative:: ++ +[source,java,indent=0,subs="verbatim,quotes",role="primary"] +---- +include::example$MongoApplication.java[tags=file] ---- -package org.spring.mongodb.example; - -import static org.springframework.data.mongodb.core.query.Criteria.where; - -import org.apache.commons.logging.Log; -import org.apache.commons.logging.LogFactory; -import org.springframework.data.mongodb.core.MongoOperations; -import org.springframework.data.mongodb.core.MongoTemplate; -import org.springframework.data.mongodb.core.query.Query; - -import com.mongodb.client.MongoClients; - -public class MongoApp { - - private static final Log log = LogFactory.getLog(MongoApp.class); - - public static void main(String[] args) throws Exception { - - MongoOperations mongoOps = new MongoTemplate(MongoClients.create(), "database"); - mongoOps.insert(new Person("Joe", 34)); - - log.info(mongoOps.findOne(new Query(where("name").is("Joe")), Person.class)); - mongoOps.dropCollection("person"); - } -} +Reactive:: ++ +[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] +---- +include::example$ReactiveMongoApplication.java[tags=file] ---- +====== When you run the main program, the preceding examples produce the following output: [source] ---- -10:01:32,062 DEBUG apping.MongoPersistentEntityIndexCreator: 80 - Analyzing class class org.spring.example.Person for index information. -10:01:32,265 DEBUG ramework.data.mongodb.core.MongoTemplate: 631 - insert Document containing fields: [_class, age, name] in collection: Person -10:01:32,765 DEBUG ramework.data.mongodb.core.MongoTemplate:1243 - findOne using query: { "name" : "Joe"} in db.collection: database.Person -10:01:32,953 INFO org.spring.mongodb.example.MongoApp: 25 - Person [id=4ddbba3c0be56b7e1b210166, name=Joe, age=34] -10:01:32,984 DEBUG ramework.data.mongodb.core.MongoTemplate: 375 - Dropped collection [database.person] +10:01:32,265 DEBUG o.s.data.mongodb.core.MongoTemplate - insert Document containing fields: [_class, age, name] in collection: Person +10:01:32,765 DEBUG o.s.data.mongodb.core.MongoTemplate - findOne using query: { "name" : "Joe"} in db.collection: database.Person +Person [id=4ddbba3c0be56b7e1b210166, name=Joe, age=34] +10:01:32,984 DEBUG o.s.data.mongodb.core.MongoTemplate - Dropped collection [database.person] ---- Even in this simple example, there are few things to notice: -* You can instantiate the central helper class of Spring Mongo, xref:reference/mongodb/mongo-template.adoc[`MongoTemplate`], by using the standard `com.mongodb.client.MongoClient` object and the name of the database to use. -* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See xref:reference/mapping.adoc[here].). +* You can instantiate the central helper class of Spring Mongo, xref:mongodb/mongo-template.adoc[`MongoTemplate`], by using the standard or reactive `MongoClient` object and the name of the database to use. +* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See xref:mongodb/mapping.adoc[here].). * Conventions are used for handling the `id` field, converting it to be an `ObjectId` when stored in the database. * Mapping conventions can use field access. Notice that the `Person` class has only getters. * If the constructor argument names match the field names of the stored document, they are used to instantiate the object diff --git a/src/main/antora/modules/ROOT/pages/mongodb/introduction.adoc b/src/main/antora/modules/ROOT/pages/mongodb/introduction.adoc deleted file mode 100644 index a107bd0e5..000000000 --- a/src/main/antora/modules/ROOT/pages/mongodb/introduction.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[[introduction]] -= Introduction -:page-section-summary-toc: 1 - -[[document-structure]] -== Document Structure - -This part of the reference documentation explains the core functionality offered by Spring Data MongoDB. - -"`xref:reference/mongodb.adoc[MongoDB support]`" introduces the MongoDB module feature set. - -"`xref:reference/mongo-repositories.adoc[MongoDB Repositories]`" introduces the repository support for MongoDB. diff --git a/src/main/antora/modules/ROOT/pages/mongodb/mongo-examples-repo.adoc b/src/main/antora/modules/ROOT/pages/mongodb/mongo-examples-repo.adoc deleted file mode 100644 index c6e6e8471..000000000 --- a/src/main/antora/modules/ROOT/pages/mongodb/mongo-examples-repo.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[[mongo.examples-repo]] -= Examples Repository -:page-section-summary-toc: 1 - -There is a https://github.com/spring-projects/spring-data-examples[GitHub repository with several examples] that you can download and play around with to get a feel for how the library works. - diff --git a/src/main/antora/modules/ROOT/pages/mongodb/mongodb.adoc b/src/main/antora/modules/ROOT/pages/mongodb/mongodb.adoc deleted file mode 100644 index 755680f62..000000000 --- a/src/main/antora/modules/ROOT/pages/mongodb/mongodb.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[[mongo.core]] -= MongoDB support -:page-section-summary-toc: 1 - -The MongoDB support contains a wide range of features: - -* Spring configuration support with Java-based `@Configuration` classes or an XML namespace for a Mongo driver instance and replica sets. -* `MongoTemplate` helper class that increases productivity when performing common Mongo operations.Includes integrated object mapping between documents and POJOs. -* Exception translation into Spring's portable Data Access Exception hierarchy. -* Feature-rich Object Mapping integrated with Spring's Conversion Service. -* Annotation-based mapping metadata that is extensible to support other metadata formats. -* Persistence and mapping lifecycle events. -* Java-based Query, Criteria, and Update DSLs. -* Automatic implementation of Repository interfaces, including support for custom finder methods. -* QueryDSL integration to support type-safe queries. -* Cross-store persistence support for JPA Entities with fields transparently persisted and retrieved with MongoDB (deprecated - to be removed without replacement). -* GeoSpatial integration. - -For most tasks, you should use `MongoTemplate` or the Repository support, which both leverage the rich mapping functionality. `MongoTemplate` is the place to look for accessing functionality such as incrementing counters or ad-hoc CRUD operations. `MongoTemplate` also provides callback methods so that it is easy for you to get the low-level API artifacts, such as `com.mongodb.client.MongoDatabase`, to communicate directly with MongoDB. The goal with naming conventions on various API artifacts is to copy those in the base MongoDB Java driver so you can easily map your existing knowledge onto the Spring APIs. -