@ -8,7 +8,7 @@ For further information, see the full https://docs.mongodb.org/manual/aggregatio
[[mongo.aggregation.basic-concepts]]
[[mongo.aggregation.basic-concepts]]
== Basic Concepts
== Basic Concepts
The Aggregation Framework support in Spring Data MongoDB is based on the following key abstractions: `Aggregation`, `AggregationDefinition`, and `AggregationResults`.
The Aggregation Framework support in Spring Data MongoDB is based on the following key abstractions: javadoc:org.springframework.data.mongodb.core.aggregation.Aggregation[] and javadoc:org.springframework.data.mongodb.core.aggregation.AggregationResults[].
Listening to a https://docs.mongodb.com/manual/tutorial/change-streams-example/[Change Stream by using a Sync Driver] creates a long running, blocking task that needs to be delegated to a separate component.
Listening to a https://docs.mongodb.com/manual/tutorial/change-streams-example/[Change Stream by using a Sync Driver] creates a long running, blocking task that needs to be delegated to a separate component.
In this case, we need to first create a `MessageListenerContainer`, which will be the main entry point for running the specific `SubscriptionRequest` tasks.
In this case, we need to first create a javadoc:org.springframework.data.mongodb.core.messaging.MessageListenerContainer[] which will be the main entry point for running the specific `SubscriptionRequest` tasks.
Spring Data MongoDB already ships with a default implementation that operates on `MongoTemplate` and is capable of creating and running `Task` instances for a `ChangeStreamRequest`.
Spring Data MongoDB already ships with a default implementation that operates on `MongoTemplate` and is capable of creating and running `Task` instances for a javadoc:org.springframework.data.mongodb.core.messaging.ChangeStreamRequest[].
The following example shows how to use Change Streams with `MessageListener` instances:
The following example shows how to use Change Streams with `MessageListener` instances:
@ -55,7 +55,7 @@ Person [id=4ddbba3c0be56b7e1b210166, name=Joe, age=34]
Even in this simple example, there are few things to notice:
Even in this simple example, there are few things to notice:
* You can instantiate the central helper class of Spring Mongo, xref:mongodb/template-api.adoc[`MongoTemplate`], by using the standard or reactive `MongoClient` object and the name of the database to use.
* You can instantiate the central helper class of Spring Mongo, xref:mongodb/template-api.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/mapping.adoc[here].).
* 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/mapping.adoc[here]).
* Conventions are used for handling the `id` field, converting it to be an `ObjectId` when stored in the database.
* 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.
* 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
* If the constructor argument names match the field names of the stored document, they are used to instantiate the object
@ -5,7 +5,7 @@ The MongoDB mapping framework includes several `org.springframework.context.Appl
Being based on Spring's `ApplicationContext` event infrastructure enables other products, such as Spring Integration, to easily receive these events, as they are a well known eventing mechanism in Spring-based applications.
Being based on Spring's `ApplicationContext` event infrastructure enables other products, such as Spring Integration, to easily receive these events, as they are a well known eventing mechanism in Spring-based applications.
Entity lifecycle events can be costly and you may notice a change in the performance profile when loading large result sets.
Entity lifecycle events can be costly and you may notice a change in the performance profile when loading large result sets.
You can disable lifecycle events on the link:https://docs.spring.io/spring-data/mongodb/docs/{version}/api/org/springframework/data/mongodb/core/MongoTemplate.html#setEntityLifecycleEventsEnabled(boolean)[Template API].
You can disable lifecycle events on the javadoc:org.springframework.data.mongodb.core.MongoTemplate#setEntityLifecycleEventsEnabled(boolean)[Template API].
To intercept an object before it goes through the conversion process (which turns your domain object into a `org.bson.Document`), you can register a subclass of `AbstractMongoEventListener` that overrides the `onBeforeConvert` method.
To intercept an object before it goes through the conversion process (which turns your domain object into a `org.bson.Document`), you can register a subclass of `AbstractMongoEventListener` that overrides the `onBeforeConvert` method.
When the event is dispatched, your listener is called and passed the domain object before it goes into the converter.
When the event is dispatched, your listener is called and passed the domain object before it goes into the converter.
@ -23,7 +23,7 @@ public class BeforeConvertListener extends AbstractMongoEventListener<Person> {
----
----
====
====
To intercept an object before it goes into the database, you can register a subclass of `org.springframework.data.mongodb.core.mapping.event.AbstractMongoEventListener` that overrides the `onBeforeSave` method. When the event is dispatched, your listener is called and passed the domain object and the converted `com.mongodb.Document`. The following example shows how to do so:
To intercept an object before it goes into the database, you can register a subclass of javadoc:org.springframework.data.mongodb.core.mapping.event.AbstractMongoEventListener[] that overrides the `onBeforeSave` method. When the event is dispatched, your listener is called and passed the domain object and the converted `com.mongodb.Document`. The following example shows how to do so:
The `MongoTemplate` and its reactive counterpart class, located in the `org.springframework.data.mongodb.core` package, is the central class of Spring's MongoDB support and provides a rich feature set for interacting with the database.
The javadoc:org.springframework.data.mongodb.core.MongoTemplate[] and its javadoc:org.springframework.data.mongodb.core.ReactiveMongoTemplate[reactive] counterpart class, located in the `org.springframework.data.mongodb.core` package, is the central class of Spring's MongoDB support and provides a rich feature set for interacting with the database.
The template offers convenience operations to create, update, delete, and query MongoDB documents and provides a mapping between your domain objects and MongoDB documents.
The template offers convenience operations to create, update, delete, and query MongoDB documents and provides a mapping between your domain objects and MongoDB documents.
NOTE: Once configured, `MongoTemplate` is thread-safe and can be reused across multiple instances.
NOTE: Once configured, `MongoTemplate` is thread-safe and can be reused across multiple instances.
@ -9,14 +9,14 @@ NOTE: Once configured, `MongoTemplate` is thread-safe and can be reused across m
[[mongo-template.convenience-methods]]
[[mongo-template.convenience-methods]]
== Convenience Methods
== Convenience Methods
The `MongoTemplate` class implements the interface `MongoOperations`.
The javadoc:org.springframework.data.mongodb.core.MongoTemplate[] class implements the interface javadoc:org.springframework.data.mongodb.core.MongoOperations[].
In as much as possible, the methods on `MongoOperations` are named after methods available on the MongoDB driver `Collection` object, to make the API familiar to existing MongoDB developers who are used to the driver API.
In as much as possible, the methods on `MongoOperations` are named after methods available on the MongoDB driver `Collection` object, to make the API familiar to existing MongoDB developers who are used to the driver API.
For example, you can find methods such as `find`, `findAndModify`, `findAndReplace`, `findOne`, `insert`, `remove`, `save`, `update`, and `updateMulti`.
For example, you can find methods such as `find`, `findAndModify`, `findAndReplace`, `findOne`, `insert`, `remove`, `save`, `update`, and `updateMulti`.
The design goal was to make it as easy as possible to transition between the use of the base MongoDB driver and `MongoOperations`.
The design goal was to make it as easy as possible to transition between the use of the base MongoDB driver and `MongoOperations`.
A major difference between the two APIs is that `MongoOperations` can be passed domain objects instead of `Document`.
A major difference between the two APIs is that `MongoOperations` can be passed domain objects instead of `Document`.
Also, `MongoOperations` has fluent APIs for `Query`, `Criteria`, and `Update` operations instead of populating a `Document` to specify the parameters for those operations.
Also, `MongoOperations` has fluent APIs for `Query`, `Criteria`, and `Update` operations instead of populating a `Document` to specify the parameters for those operations.
For more information please refer to the the xref:mongodb/template-crud-operations.adoc[CRUD] and xref:mongodb/template-query-operations.adoc[Query] sections of the documentation.
For more information please refer to the xref:mongodb/template-crud-operations.adoc[CRUD] and xref:mongodb/template-query-operations.adoc[Query] sections of the documentation.
NOTE: The preferred way to reference the operations on `MongoTemplate` instance is through its interface, `MongoOperations`.
NOTE: The preferred way to reference the operations on `MongoTemplate` instance is through its interface, `MongoOperations`.
@ -37,7 +37,7 @@ The `execute` callbacks gives you a reference to either a `MongoCollection` or a
* `<T> T` *executeInSession* `(DbCallback<T> action)`: Runs the given `DbCallback` within the same connection to the database so as to ensure consistency in a write-heavy environment where you may read the data that you wrote.
* `<T> T` *executeInSession* `(DbCallback<T> action)`: Runs the given `DbCallback` within the same connection to the database so as to ensure consistency in a write-heavy environment where you may read the data that you wrote.
The following example uses the `CollectionCallback` to return information about an index:
The following example uses the javadoc:org.springframework.data.mongodb.core.CollectionCallback[] to return information about an index:
[tabs]
[tabs]
======
======
@ -108,7 +108,7 @@ Flux<Jedi> all = template.query(SWCharacter.class)
======
======
NOTE: Using projections allows `MongoTemplate` to optimize result mapping by limiting the actual response to fields required
NOTE: Using projections allows `MongoTemplate` to optimize result mapping by limiting the actual response to fields required
by the projection target type. This applies as long as the `Query` itself does not contain any field restriction and the
by the projection target type. This applies as long as the javadoc:org.springframework.data.mongodb.core.query.Query[] itself does not contain any field restriction and the
target type is a closed interface or DTO projection.
target type is a closed interface or DTO projection.
WARNING: Projections must not be applied to xref:mongodb/mapping/document-references.adoc[DBRefs].
WARNING: Projections must not be applied to xref:mongodb/mapping/document-references.adoc[DBRefs].
@ -158,7 +158,7 @@ Look into the implementation for more details on the mapping.
[[mongo-template.type-mapping]]
[[mongo-template.type-mapping]]
== Domain Type Mapping
== Domain Type Mapping
The mapping between MongoDB documents and domain classes is done by delegating to an implementation of the `MongoConverter` interface.
The mapping between MongoDB documents and domain classes is done by delegating to an implementation of the javadoc:org.springframework.data.mongodb.core.convert.MongoConverter[] interface.
Spring provides `MappingMongoConverter`, but you can also write your own converter.
Spring provides javadoc:org.springframework.data.mongodb.core.convert.MappingMongoConverter[], but you can also write your own converter.
While the `MappingMongoConverter` can use additional metadata to specify the mapping of objects to documents, it can also convert objects that contain no additional metadata by using some conventions for the mapping of IDs and collection names.
While the `MappingMongoConverter` can use additional metadata to specify the mapping of objects to documents, it can also convert objects that contain no additional metadata by using some conventions for the mapping of IDs and collection names.
These conventions, as well as the use of mapping annotations, are explained in the xref:mongodb/mapping/mapping.adoc[Mapping] chapter.
These conventions, as well as the use of mapping annotations, are explained in the xref:mongodb/mapping/mapping.adoc[Mapping] chapter.
There are several overloaded constructors of `MongoTemplate` and `ReactiveMongoTemplate`:
There are several overloaded constructors of javadoc:org.springframework.data.mongodb.core.MongoTemplate[] and javadoc:org.springframework.data.mongodb.core.ReactiveMongoTemplate[]:
* `MongoTemplate(MongoClient mongo, String databaseName)`: Takes the `MongoClient` object and the default database name to operate against.
* `MongoTemplate(MongoClient mongo, String databaseName)`: Takes the `MongoClient` object and the default database name to operate against.
* `MongoTemplate(MongoDatabaseFactory mongoDbFactory)`: Takes a MongoDbFactory object that encapsulated the `MongoClient` object, database name, and username and password.
* `MongoTemplate(MongoDatabaseFactory mongoDbFactory)`: Takes a MongoDbFactory object that encapsulated the `MongoClient` object, database name, and username and password.
By setting `MongoTemplate#useEstimatedCount(...)` to `true` _MongoTemplate#count(...)_ operations, that use an empty filter query, will be delegated to `estimatedCount`, as long as there is no transaction active and the template is not bound to a xref:mongodb/client-session-transactions.adoc[session].
By setting `MongoTemplate#useEstimatedCount(...)` to `true` _MongoTemplate#count(...)_ operations, that use an empty filter query, will be delegated to `estimatedCount`, as long as there is no transaction active and the template is not bound to a xref:mongodb/client-session-transactions.adoc[session].
Please refer to to the xref:mongodb/template-document-count.adoc#mongo.query.count[Counting Documents] section for more information.
Please refer to the xref:mongodb/template-document-count.adoc#mongo.query.count[Counting Documents] section for more information.
MongoDB supports storing binary files inside its filesystem, GridFS.
MongoDB supports storing binary files inside its filesystem, GridFS.
Spring Data MongoDB provides a `GridFsOperations` and `ReactiveGridFsOperations` interface as well as the corresponding implementation, `GridFsTemplate` and `ReactiveGridFsTemplate`, to let you interact with the filesystem.
Spring Data MongoDB provides a javadoc:org.springframework.data.mongodb.gridfs.GridFsOperations[] and javadoc:org.springframework.data.mongodb.gridfs.ReactiveGridFsOperations[] interface as well as the corresponding implementation, `GridFsTemplate` and `ReactiveGridFsTemplate`, to let you interact with the filesystem.
You can set up a template instance by handing it a `MongoDatabaseFactory`/`ReactiveMongoDatabaseFactory` as well as a `MongoConverter`, as the following example shows:
You can set up a template instance by handing it a `MongoDatabaseFactory`/`ReactiveMongoDatabaseFactory` as well as a `MongoConverter`, as the following example shows:
@ -472,7 +472,7 @@ The `Metrics` enum used here actually implements an interface so that other metr
A `Metric` is backed by a multiplier to transform the distance value of the given metric into native distances.
A `Metric` is backed by a multiplier to transform the distance value of the given metric into native distances.
The sample shown here would consider the 10 to be miles. Using one of the built-in metrics (miles and kilometers) automatically triggers the spherical flag to be set on the query.
The sample shown here would consider the 10 to be miles. Using one of the built-in metrics (miles and kilometers) automatically triggers the spherical flag to be set on the query.
If you want to avoid that, pass plain `double` values into `maxDistance(…)`.
If you want to avoid that, pass plain `double` values into `maxDistance(…)`.
For more information, see the https://docs.spring.io/spring-data/mongodb/docs/{version}/api/index.html[JavaDoc] of `NearQuery` and `Distance`.
For more information, see the Javadoc of javadoc:org.springframework.data.mongodb.core.query.NearQuery[] and `Distance`.
The geo-near operations return a `GeoResults` wrapper object that encapsulates `GeoResult` instances.
The geo-near operations return a `GeoResults` wrapper object that encapsulates `GeoResult` instances.
Wrapping `GeoResults` allows accessing the average distance of all results.
Wrapping `GeoResults` allows accessing the average distance of all results.
@ -486,7 +486,7 @@ MongoDB supports https://geojson.org/[GeoJSON] and simple (legacy) coordinate pa
[[mongo.geo-json.domain.classes]]
[[mongo.geo-json.domain.classes]]
== GeoJSON Types in Domain Classes
== GeoJSON Types in Domain Classes
Usage of https://geojson.org/[GeoJSON] types in domain classes is straightforward. The `org.springframework.data.mongodb.core.geo` package contains types such as `GeoJsonPoint`, `GeoJsonPolygon`, and others. These types are extend the existing `org.springframework.data.geo` types. The following example uses a `GeoJsonPoint`:
Usage of https://geojson.org/[GeoJSON] types in domain classes is straightforward. The `org.springframework.data.mongodb.core.geo` package contains types such as `GeoJsonPoint`, `GeoJsonPolygon`, and others. These types are extend the existing `org.springframework.data.geo` types. The following example uses a javadoc:org.springframework.data.mongodb.core.geo.GeoJsonPoint[]:
Mark Paluch
1 year ago