GitHub-Spring
/
spring-data-mongodb
mirror of https://github.com/spring-projects/spring-data-mongodb.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Update documentation on version property handling. 

Original pull request: #4553
Closes #4536
pull/4514/merge
Christoph Strobl 2 years ago committed by Mark Paluch
parent
5e76c0493e
commit
fcf3143b79
No known key found for this signature in database
GPG Key ID: 4406B84C1661DCD1
3 changed files with 198 additions and 18 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 77
      spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java
  2. 113
      spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoOperations.java
  3. 26
      src/main/antora/modules/ROOT/pages/mongodb/template-crud-operations.adoc

77
spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java
Unescape View File

@ -945,6 +945,9 @@ public interface MongoOperations extends FluentMongoOperations {
/** /**
* Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a> * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a>
* to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}. * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an * @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an
* optional fields specification. Must not be {@literal null}. * optional fields specification. Must not be {@literal null}.
@ -961,6 +964,9 @@ public interface MongoOperations extends FluentMongoOperations {
/** /**
* Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a> * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a>
* to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}. * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an * @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an
* optional fields specification. Must not be {@literal null}. * optional fields specification. Must not be {@literal null}.
@ -979,6 +985,9 @@ public interface MongoOperations extends FluentMongoOperations {
* Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a> * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a>
* to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking
* {@link FindAndModifyOptions} into account. * {@link FindAndModifyOptions} into account.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an * @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an
* optional fields specification. * optional fields specification.
@ -999,6 +1008,9 @@ public interface MongoOperations extends FluentMongoOperations {
* Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a> * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify </a>
* to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking
* {@link FindAndModifyOptions} into account. * {@link FindAndModifyOptions} into account.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an * @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an
* optional fields specification. Must not be {@literal null}. * optional fields specification. Must not be {@literal null}.
@ -1391,8 +1403,11 @@ public interface MongoOperations extends FluentMongoOperations {
* leverages Type Conversion API. See * leverages Type Conversion API. See
* <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation" > Spring's * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation" > Spring's
* Type Conversion"</a> for more details. <br /> * Type Conversion"</a> for more details. <br />
* Insert is used to initially store the object into the database. To update an existing object use the save method. * Insert is used to initially store the object into the database. To update an existing object use the
* <br /> * {@link #save(Object)} method.
* <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* <p>
* The {@code objectToSave} must not be collection-like. * The {@code objectToSave} must not be collection-like.
* *
* @param objectToSave the object to store in the collection. Must not be {@literal null}. * @param objectToSave the object to store in the collection. Must not be {@literal null}.
@ -1408,7 +1423,9 @@ public interface MongoOperations extends FluentMongoOperations {
* The object is converted to the MongoDB native representation using an instance of {@see MongoConverter}. Unless * The object is converted to the MongoDB native representation using an instance of {@see MongoConverter}. Unless
* configured otherwise, an instance of {@link MappingMongoConverter} will be used. <br /> * configured otherwise, an instance of {@link MappingMongoConverter} will be used. <br />
* Insert is used to initially store the object into the database. To update an existing object use the save method. * Insert is used to initially store the object into the database. To update an existing object use the save method.
* <br /> * <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* <p>
* The {@code objectToSave} must not be collection-like. * The {@code objectToSave} must not be collection-like.
* *
* @param objectToSave the object to store in the collection. Must not be {@literal null}. * @param objectToSave the object to store in the collection. Must not be {@literal null}.
@ -1420,6 +1437,11 @@ public interface MongoOperations extends FluentMongoOperations {
/** /**
* Insert a Collection of objects into a collection in a single batch write to the database. * Insert a Collection of objects into a collection in a single batch write to the database.
* <p>
* If an object within the batch has an {@literal Id} property which holds a {@literal null} value, it will be set
* with the generated Id from MongoDB.
* <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* *
* @param batchToSave the batch of objects to save. Must not be {@literal null}. * @param batchToSave the batch of objects to save. Must not be {@literal null}.
* @param entityClass class that determines the collection to use. Must not be {@literal null}. * @param entityClass class that determines the collection to use. Must not be {@literal null}.
@ -1431,6 +1453,11 @@ public interface MongoOperations extends FluentMongoOperations {
/** /**
* Insert a batch of objects into the specified collection in a single batch write to the database. * Insert a batch of objects into the specified collection in a single batch write to the database.
* <p>
* If an object within the batch has an {@literal Id} property which holds a {@literal null} value, it will be set
* with the generated Id from MongoDB.
* <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* *
* @param batchToSave the list of objects to save. Must not be {@literal null}. * @param batchToSave the list of objects to save. Must not be {@literal null}.
* @param collectionName name of the collection to store the object in. Must not be {@literal null}. * @param collectionName name of the collection to store the object in. Must not be {@literal null}.
@ -1441,6 +1468,11 @@ public interface MongoOperations extends FluentMongoOperations {
/** /**
* Insert a mixed Collection of objects into a database collection determining the collection name to use based on the * Insert a mixed Collection of objects into a database collection determining the collection name to use based on the
* class. * class.
* <p>
* If an object within the batch has an {@literal Id} property which holds a {@literal null} value, it will be set
* with the generated Id from MongoDB.
* <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* *
* @param objectsToSave the list of objects to save. Must not be {@literal null}. * @param objectsToSave the list of objects to save. Must not be {@literal null}.
* @return the inserted objects. * @return the inserted objects.
@ -1458,7 +1490,11 @@ public interface MongoOperations extends FluentMongoOperations {
* String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from ObjectId to your * String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from ObjectId to your
* property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See * property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See
* <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation" > Spring's * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation" > Spring's
* Type Conversion"</a> for more details. <br /> * Type Conversion"</a> for more details.
* <p>
* A potential {@link org.springframework.data.annotation.Version} the property will be auto incremented. The
* operation raises an error in case the document has been modified in between.
* <p>
* The {@code objectToSave} must not be collection-like. * The {@code objectToSave} must not be collection-like.
* *
* @param objectToSave the object to store in the collection. Must not be {@literal null}. * @param objectToSave the object to store in the collection. Must not be {@literal null}.
@ -1466,6 +1502,8 @@ public interface MongoOperations extends FluentMongoOperations {
* @throws IllegalArgumentException in case the {@code objectToSave} is collection-like. * @throws IllegalArgumentException in case the {@code objectToSave} is collection-like.
* @throws org.springframework.data.mapping.MappingException if the target collection name cannot be * @throws org.springframework.data.mapping.MappingException if the target collection name cannot be
* {@link #getCollectionName(Class) derived} from the given object type. * {@link #getCollectionName(Class) derived} from the given object type.
* @throws org.springframework.dao.OptimisticLockingFailureException in case of version mismatch in case a
* {@link org.springframework.data.annotation.Version} is defined.
*/ */
<T> T save(T objectToSave); <T> T save(T objectToSave);
@ -1478,19 +1516,29 @@ public interface MongoOperations extends FluentMongoOperations {
* String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from ObjectId to your * String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from ObjectId to your
* property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See * property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See
* <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation">Spring's Type * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation">Spring's Type
* Conversion</a> for more details. <br /> * Conversion</a> for more details.
* <p>
* A potential {@link org.springframework.data.annotation.Version} the property will be auto incremented. The
* operation raises an error in case the document has been modified in between.
* <p>
* The {@code objectToSave} must not be collection-like. * The {@code objectToSave} must not be collection-like.
* *
* @param objectToSave the object to store in the collection. Must not be {@literal null}. * @param objectToSave the object to store in the collection. Must not be {@literal null}.
* @param collectionName name of the collection to store the object in. Must not be {@literal null}. * @param collectionName name of the collection to store the object in. Must not be {@literal null}.
* @return the saved object. * @return the saved object.
* @throws IllegalArgumentException in case the {@code objectToSave} is collection-like. * @throws IllegalArgumentException in case the {@code objectToSave} is collection-like.
* @throws org.springframework.dao.OptimisticLockingFailureException in case of version mismatch in case a
* {@link org.springframework.data.annotation.Version} is defined.
*/ */
<T> T save(T objectToSave, String collectionName); <T> T save(T objectToSave, String collectionName);
/** /**
* Performs an upsert. If no document is found that matches the query, a new document is created and inserted by * Performs an upsert. If no document is found that matches the query, a new document is created and inserted by
* combining the query document and the update document. <br /> * combining the query document and the update document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* <p>
* <strong>NOTE:</strong> {@link Query#getSortObject() sorting} is not supported by {@code db.collection.updateOne}. * <strong>NOTE:</strong> {@link Query#getSortObject() sorting} is not supported by {@code db.collection.updateOne}.
* Use {@link #findAndModify(Query, UpdateDefinition, FindAndModifyOptions, Class, String)} instead. * Use {@link #findAndModify(Query, UpdateDefinition, FindAndModifyOptions, Class, String)} instead.
* *
@ -1532,6 +1580,9 @@ public interface MongoOperations extends FluentMongoOperations {
/** /**
* Performs an upsert. If no document is found that matches the query, a new document is created and inserted by * Performs an upsert. If no document is found that matches the query, a new document is created and inserted by
* combining the query document and the update document. * combining the query document and the update document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the query document that specifies the criteria used to select a document to be upserted. Must not be * @param query the query document that specifies the criteria used to select a document to be upserted. Must not be
* {@literal null}. * {@literal null}.
@ -1549,6 +1600,9 @@ public interface MongoOperations extends FluentMongoOperations {
/** /**
* Updates the first object that is found in the collection of the entity class that matches the query document with * Updates the first object that is found in the collection of the entity class that matches the query document with
* the provided update document. * the provided update document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the query document that specifies the criteria used to select a document to be updated. Must not be * @param query the query document that specifies the criteria used to select a document to be updated. Must not be
* {@literal null}. * {@literal null}.
@ -1587,7 +1641,10 @@ public interface MongoOperations extends FluentMongoOperations {
/** /**
* Updates the first object that is found in the specified collection that matches the query document criteria with * Updates the first object that is found in the specified collection that matches the query document criteria with
* the provided updated document. <br /> * the provided updated document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the query document that specifies the criteria used to select a document to be updated. Must not be * @param query the query document that specifies the criteria used to select a document to be updated. Must not be
* {@literal null}. * {@literal null}.
@ -1605,6 +1662,9 @@ public interface MongoOperations extends FluentMongoOperations {
/** /**
* Updates all objects that are found in the collection for the entity class that matches the query document criteria * Updates all objects that are found in the collection for the entity class that matches the query document criteria
* with the provided updated document. * with the provided updated document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the query document that specifies the criteria used to select a document to be updated. Must not be * @param query the query document that specifies the criteria used to select a document to be updated. Must not be
* {@literal null}. * {@literal null}.
@ -1642,6 +1702,9 @@ public interface MongoOperations extends FluentMongoOperations {
/** /**
* Updates all objects that are found in the collection for the entity class that matches the query document criteria * Updates all objects that are found in the collection for the entity class that matches the query document criteria
* with the provided updated document. * with the provided updated document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the query document that specifies the criteria used to select a document to be updated. Must not be * @param query the query document that specifies the criteria used to select a document to be updated. Must not be
* {@literal null}. * {@literal null}.

113
spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoOperations.java
Unescape View File

@ -758,6 +758,9 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify</a> * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify</a>
* to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}. * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}.
* <p>
*A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
*incremented if not explicitly specified in the update.
* *
* @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an optional * @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an optional
* fields specification. Must not be {@literal null}. * fields specification. Must not be {@literal null}.
@ -773,6 +776,9 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify</a> * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify</a>
* to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}. * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query}.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an optional * @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an optional
* fields specification. Must not be {@literal null}. * fields specification. Must not be {@literal null}.
@ -790,6 +796,9 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
* Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify</a> * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify</a>
* to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking
* {@link FindAndModifyOptions} into account. * {@link FindAndModifyOptions} into account.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an optional * @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an optional
* fields specification. * fields specification.
@ -808,6 +817,9 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
* Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify</a> * Triggers <a href="https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/">findAndModify</a>
* to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking * to apply provided {@link Update} on documents matching {@link Criteria} of given {@link Query} taking
* {@link FindAndModifyOptions} into account. * {@link FindAndModifyOptions} into account.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an optional * @param query the {@link Query} class that specifies the {@link Criteria} used to find a document and also an optional
* fields specification. Must not be {@literal null}. * fields specification. Must not be {@literal null}.
@ -1190,7 +1202,9 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
* <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation" > Spring's * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation" > Spring's
* Type Conversion"</a> for more details. <br /> * Type Conversion"</a> for more details. <br />
* Insert is used to initially store the object into the database. To update an existing object use the save method. * Insert is used to initially store the object into the database. To update an existing object use the save method.
* <br /> * <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* <p>
* The {@code objectToSave} must not be collection-like. * The {@code objectToSave} must not be collection-like.
* *
* @param objectToSave the object to store in the collection. Must not be {@literal null}. * @param objectToSave the object to store in the collection. Must not be {@literal null}.
@ -1206,7 +1220,9 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
* The object is converted to the MongoDB native representation using an instance of {@see MongoConverter}. Unless * The object is converted to the MongoDB native representation using an instance of {@see MongoConverter}. Unless
* configured otherwise, an instance of {@link MappingMongoConverter} will be used. <br /> * configured otherwise, an instance of {@link MappingMongoConverter} will be used. <br />
* Insert is used to initially store the object into the database. To update an existing object use the save method. * Insert is used to initially store the object into the database. To update an existing object use the save method.
* <br /> * <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* <p>
* The {@code objectToSave} must not be collection-like. * The {@code objectToSave} must not be collection-like.
* *
* @param objectToSave the object to store in the collection. Must not be {@literal null}. * @param objectToSave the object to store in the collection. Must not be {@literal null}.
@ -1218,6 +1234,11 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Insert a Collection of objects into a collection in a single batch write to the database. * Insert a Collection of objects into a collection in a single batch write to the database.
* <p>
* If an object within the batch has an {@literal Id} property which holds a {@literal null} value, it will be set
* with the generated Id from MongoDB.
* <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* *
* @param batchToSave the batch of objects to save. Must not be {@literal null}. * @param batchToSave the batch of objects to save. Must not be {@literal null}.
* @param entityClass class that determines the collection to use. Must not be {@literal null}. * @param entityClass class that determines the collection to use. Must not be {@literal null}.
@ -1229,6 +1250,11 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Insert a batch of objects into the specified collection in a single batch write to the database. * Insert a batch of objects into the specified collection in a single batch write to the database.
* <p>
* If an object within the batch has an {@literal Id} property which holds a {@literal null} value, it will be set
* with the generated Id from MongoDB.
* <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* *
* @param batchToSave the list of objects to save. Must not be {@literal null}. * @param batchToSave the list of objects to save. Must not be {@literal null}.
* @param collectionName name of the collection to store the object in. Must not be {@literal null}. * @param collectionName name of the collection to store the object in. Must not be {@literal null}.
@ -1239,6 +1265,11 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Insert a mixed Collection of objects into a database collection determining the collection name to use based on the * Insert a mixed Collection of objects into a database collection determining the collection name to use based on the
* class. * class.
* <p>
* If an object within the batch has an {@literal Id} property which holds a {@literal null} value, it will be set
* with the generated Id from MongoDB.
* <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* *
* @param objectsToSave the list of objects to save. Must not be {@literal null}. * @param objectsToSave the list of objects to save. Must not be {@literal null}.
* @return the saved objects. * @return the saved objects.
@ -1256,7 +1287,9 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
* <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation" > Spring's * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation" > Spring's
* Type Conversion"</a> for more details. <br /> * Type Conversion"</a> for more details. <br />
* Insert is used to initially store the object into the database. To update an existing object use the save method. * Insert is used to initially store the object into the database. To update an existing object use the save method.
* * <p>
* A potential {@link org.springframework.data.annotation.Version} the property will be auto incremented. The
* operation raises an error in case the document has been modified in between.
* @param objectToSave the object to store in the collection. Must not be {@literal null}. * @param objectToSave the object to store in the collection. Must not be {@literal null}.
* @return the inserted objects. * @return the inserted objects.
*/ */
@ -1264,6 +1297,11 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Insert a Collection of objects into a collection in a single batch write to the database. * Insert a Collection of objects into a collection in a single batch write to the database.
* <p>
* If an object within the batch has an {@literal Id} property which holds a {@literal null} value, it will be set
* with the generated Id from MongoDB.
* <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* *
* @param batchToSave the publisher which provides objects to save. Must not be {@literal null}. * @param batchToSave the publisher which provides objects to save. Must not be {@literal null}.
* @param entityClass class that determines the collection to use. Must not be {@literal null}. * @param entityClass class that determines the collection to use. Must not be {@literal null}.
@ -1275,6 +1313,11 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Insert objects into the specified collection in a single batch write to the database. * Insert objects into the specified collection in a single batch write to the database.
* <p>
* If an object within the batch has an {@literal Id} property which holds a {@literal null} value, it will be set
* with the generated Id from MongoDB.
* <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* *
* @param batchToSave the publisher which provides objects to save. Must not be {@literal null}. * @param batchToSave the publisher which provides objects to save. Must not be {@literal null}.
* @param collectionName name of the collection to store the object in. Must not be {@literal null}. * @param collectionName name of the collection to store the object in. Must not be {@literal null}.
@ -1285,6 +1328,11 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Insert a mixed Collection of objects into a database collection determining the collection name to use based on the * Insert a mixed Collection of objects into a database collection determining the collection name to use based on the
* class. * class.
* <p>
* If an object within the batch has an {@literal Id} property which holds a {@literal null} value, it will be set
* with the generated Id from MongoDB.
* <p>
* Inserting new objects will trigger {@link org.springframework.data.annotation.Version} property initialization.
* *
* @param objectsToSave the publisher which provides objects to save. Must not be {@literal null}. * @param objectsToSave the publisher which provides objects to save. Must not be {@literal null}.
* @return the inserted objects. * @return the inserted objects.
@ -1300,7 +1348,11 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
* String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from ObjectId to your * String then MongoDB ObjectId will be used to populate that string. Otherwise, the conversion from ObjectId to your
* property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See * property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See
* <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation" > Spring's * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation" > Spring's
* Type Conversion"</a> for more details. <br /> * Type Conversion"</a> for more details.
* <p>
* A potential {@link org.springframework.data.annotation.Version} the property will be auto incremented. The
* operation raises an error in case the document has been modified in between.
* <p>
* The {@code objectToSave} must not be collection-like. * The {@code objectToSave} must not be collection-like.
* *
* @param objectToSave the object to store in the collection. Must not be {@literal null}. * @param objectToSave the object to store in the collection. Must not be {@literal null}.
@ -1308,6 +1360,8 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
* @throws IllegalArgumentException in case the {@code objectToSave} is collection-like. * @throws IllegalArgumentException in case the {@code objectToSave} is collection-like.
* @throws org.springframework.data.mapping.MappingException if the target collection name cannot be * @throws org.springframework.data.mapping.MappingException if the target collection name cannot be
* {@link #getCollectionName(Class) derived} from the given object type. * {@link #getCollectionName(Class) derived} from the given object type.
* @throws org.springframework.dao.OptimisticLockingFailureException in case of version mismatch in case a
* {@link org.springframework.data.annotation.Version} is defined.
*/ */
<T> Mono<T> save(T objectToSave); <T> Mono<T> save(T objectToSave);
@ -1321,11 +1375,16 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
* property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See * property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See
* <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation">Spring's Type * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation">Spring's Type
* Conversion</a> for more details. * Conversion</a> for more details.
* <p>
* A potential {@link org.springframework.data.annotation.Version} the property will be auto incremented. The
* operation raises an error in case the document has been modified in between.
* *
* @param objectToSave the object to store in the collection. Must not be {@literal null}. * @param objectToSave the object to store in the collection. Must not be {@literal null}.
* @param collectionName name of the collection to store the object in. Must not be {@literal null}. * @param collectionName name of the collection to store the object in. Must not be {@literal null}.
* @return the saved object. * @return the saved object.
* @throws IllegalArgumentException in case the {@code objectToSave} is collection-like. * @throws IllegalArgumentException in case the {@code objectToSave} is collection-like.
* @throws org.springframework.dao.OptimisticLockingFailureException in case of version mismatch in case a
* {@link org.springframework.data.annotation.Version} is defined.
*/ */
<T> Mono<T> save(T objectToSave, String collectionName); <T> Mono<T> save(T objectToSave, String collectionName);
@ -1339,11 +1398,16 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
* property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See * property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See
* <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation"> Spring's Type * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation"> Spring's Type
* Conversion</a> for more details. * Conversion</a> for more details.
* <p>
* A potential {@link org.springframework.data.annotation.Version} the property will be auto incremented. The
* operation raises an error in case the document has been modified in between.
* *
* @param objectToSave the object to store in the collection. Must not be {@literal null}. * @param objectToSave the object to store in the collection. Must not be {@literal null}.
* @return the saved object. * @return the saved object.
* @throws org.springframework.data.mapping.MappingException if the target collection name cannot be * @throws org.springframework.data.mapping.MappingException if the target collection name cannot be
* {@link #getCollectionName(Class) derived} from the given object type. * {@link #getCollectionName(Class) derived} from the given object type.
* @throws org.springframework.dao.OptimisticLockingFailureException in case of version mismatch in case a
* {@link org.springframework.data.annotation.Version} is defined.
*/ */
<T> Mono<T> save(Mono<? extends T> objectToSave); <T> Mono<T> save(Mono<? extends T> objectToSave);
@ -1357,16 +1421,25 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
* property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See * property type will be handled by Spring's BeanWrapper class that leverages Type Conversion API. See
* <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation">Spring's Type * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation">Spring's Type
* Conversion</a> for more details. * Conversion</a> for more details.
* <p>
* A potential {@link org.springframework.data.annotation.Version} the property will be auto incremented. The
* operation raises an error in case the document has been modified in between.
* *
* @param objectToSave the object to store in the collReactiveMongoOperationsection. Must not be {@literal null}. * @param objectToSave the object to store in the collReactiveMongoOperationsection. Must not be {@literal null}.
* @param collectionName name of the collection to store the object in. Must not be {@literal null}. * @param collectionName name of the collection to store the object in. Must not be {@literal null}.
* @return the saved object. * @return the saved object.
* @throws org.springframework.dao.OptimisticLockingFailureException in case of version mismatch in case a
* {@link org.springframework.data.annotation.Version} is defined.
*/ */
<T> Mono<T> save(Mono<? extends T> objectToSave, String collectionName); <T> Mono<T> save(Mono<? extends T> objectToSave, String collectionName);
/** /**
* Performs an upsert. If no document is found that matches the query, a new document is created and inserted by * Performs an upsert. If no document is found that matches the query, a new document is created and inserted by
* combining the query document and the update document. <br /> * combining the query document and the update document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* <p>
* <strong>NOTE:</strong> {@link Query#getSortObject() sorting} is not supported by {@code db.collection.updateOne}. * <strong>NOTE:</strong> {@link Query#getSortObject() sorting} is not supported by {@code db.collection.updateOne}.
* Use {@link #findAndModify(Query, UpdateDefinition, Class)} instead. * Use {@link #findAndModify(Query, UpdateDefinition, Class)} instead.
* *
@ -1406,6 +1479,9 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Performs an upsert. If no document is found that matches the query, a new document is created and inserted by * Performs an upsert. If no document is found that matches the query, a new document is created and inserted by
* combining the query document and the update document. * combining the query document and the update document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the query document that specifies the criteria used to select a document to be upserted. Must not be * @param query the query document that specifies the criteria used to select a document to be upserted. Must not be
* {@literal null}. * {@literal null}.
@ -1422,7 +1498,11 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Updates the first object that is found in the collection of the entity class that matches the query document with * Updates the first object that is found in the collection of the entity class that matches the query document with
* the provided update document. <br /> * the provided update document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
*
* <strong>NOTE:</strong> {@link Query#getSortObject() sorting} is not supported by {@code db.collection.updateOne}. * <strong>NOTE:</strong> {@link Query#getSortObject() sorting} is not supported by {@code db.collection.updateOne}.
* Use {@link #findAndModify(Query, UpdateDefinition, Class)} instead. * Use {@link #findAndModify(Query, UpdateDefinition, Class)} instead.
* *
@ -1463,7 +1543,10 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Updates the first object that is found in the specified collection that matches the query document criteria with * Updates the first object that is found in the specified collection that matches the query document criteria with
* the provided updated document. <br /> * the provided updated document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the query document that specifies the criteria used to select a document to be updated. Must not be * @param query the query document that specifies the criteria used to select a document to be updated. Must not be
* {@literal null}. * {@literal null}.
@ -1481,6 +1564,9 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Updates all objects that are found in the collection for the entity class that matches the query document criteria * Updates all objects that are found in the collection for the entity class that matches the query document criteria
* with the provided updated document. * with the provided updated document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the query document that specifies the criteria used to select a document to be updated. Must not be * @param query the query document that specifies the criteria used to select a document to be updated. Must not be
* {@literal null}. * {@literal null}.
@ -1518,6 +1604,9 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
/** /**
* Updates all objects that are found in the collection for the entity class that matches the query document criteria * Updates all objects that are found in the collection for the entity class that matches the query document criteria
* with the provided updated document. * with the provided updated document.
* <p>
* A potential {@link org.springframework.data.annotation.Version} property of the {@literal entityClass} will be auto
* incremented if not explicitly specified in the update.
* *
* @param query the query document that specifies the criteria used to select a document to be updated. Must not be * @param query the query document that specifies the criteria used to select a document to be updated. Must not be
* {@literal null}. * {@literal null}.
@ -1533,7 +1622,8 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
Mono<UpdateResult> updateMulti(Query query, UpdateDefinition update, Class<?> entityClass, String collectionName); Mono<UpdateResult> updateMulti(Query query, UpdateDefinition update, Class<?> entityClass, String collectionName);
/** /**
* Remove the given object from the collection by id. * Remove the given object from the collection by {@literal id} and (if applicable) its
* {@link org.springframework.data.annotation.Version}.
* *
* @param object must not be {@literal null}. * @param object must not be {@literal null}.
* @return the {@link DeleteResult} which lets you access the results of the previous delete. * @return the {@link DeleteResult} which lets you access the results of the previous delete.
@ -1552,7 +1642,8 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
Mono<DeleteResult> remove(Object object, String collectionName); Mono<DeleteResult> remove(Object object, String collectionName);
/** /**
* Remove the given object from the collection by id. * Remove the given object from the collection by {@literal id} and (if applicable) its
* {@link org.springframework.data.annotation.Version}.
* *
* @param objectToRemove must not be {@literal null}. * @param objectToRemove must not be {@literal null}.
* @return the {@link DeleteResult} which lets you access the results of the previous delete. * @return the {@link DeleteResult} which lets you access the results of the previous delete.
@ -1562,7 +1653,8 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
Mono<DeleteResult> remove(Mono<? extends Object> objectToRemove); Mono<DeleteResult> remove(Mono<? extends Object> objectToRemove);
/** /**
* Removes the given object from the given collection. * Removes the given object from the given collection by {@literal id} and (if applicable) its
* {@link org.springframework.data.annotation.Version}.
* *
* @param objectToRemove must not be {@literal null}. * @param objectToRemove must not be {@literal null}.
* @param collectionName name of the collection where the documents will be removed from, must not be {@literal null} or empty. * @param collectionName name of the collection where the documents will be removed from, must not be {@literal null} or empty.
@ -1852,7 +1944,6 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations {
<T> Flux<T> mapReduce(Query filterQuery, Class<?> domainType, String inputCollectionName, Class<T> resultType, <T> Flux<T> mapReduce(Query filterQuery, Class<?> domainType, String inputCollectionName, Class<T> resultType,
String mapFunction, String reduceFunction, MapReduceOptions options); String mapFunction, String reduceFunction, MapReduceOptions options);
/** /**
* Returns the underlying {@link MongoConverter}. * Returns the underlying {@link MongoConverter}.
* *

26
src/main/antora/modules/ROOT/pages/mongodb/template-crud-operations.adoc
Unescape View File

@ -294,6 +294,12 @@ Server performance of batch and bulk is identical.
However bulk operations do not publish xref:mongodb/lifecycle-events.adoc[lifecycle events]. However bulk operations do not publish xref:mongodb/lifecycle-events.adoc[lifecycle events].
==== ====
[IMPORTANT]
====
Any `@Version` property that has not been set prior to calling insert will be auto initialized with `1` (in case of a simple type like `int`) or `0` for wrapper types (eg. `Integer`). +
Read more in the see xref:mongodb/template-crud-operations.adoc#mongo-template.optimistic-locking[Optimistic Locking] section.
====
[[mongodb-template-update]] [[mongodb-template-update]]
== Update == Update
@ -338,6 +344,12 @@ In addition to the `Query` discussed earlier, we provide the update definition b
The `Update` class has methods that match the update modifiers available for MongoDB. The `Update` class has methods that match the update modifiers available for MongoDB.
Most methods return the `Update` object to provide a fluent style for the API. Most methods return the `Update` object to provide a fluent style for the API.
[IMPORTANT]
====
`@Version` properties if not included in the `Update` will be automatically incremented.
Read more in the see xref:mongodb/template-crud-operations.adoc#mongo-template.optimistic-locking[Optimistic Locking] section.
====
[[mongodb-template-update.methods]] [[mongodb-template-update.methods]]
=== Methods for Running Updates for Documents === Methods for Running Updates for Documents
@ -478,6 +490,12 @@ Mono<UpdateResult> result = template.update(Person.class)
WARNING: `upsert` does not support ordering. Please use xref:mongodb/template-crud-operations.adoc#mongo-template.find-and-upsert[findAndModify] to apply `Sort`. WARNING: `upsert` does not support ordering. Please use xref:mongodb/template-crud-operations.adoc#mongo-template.find-and-upsert[findAndModify] to apply `Sort`.
[IMPORTANT]
====
`@Version` properties if not included in the `Update` will be automatically initialized.
Read more in the see xref:mongodb/template-crud-operations.adoc#mongo-template.optimistic-locking[Optimistic Locking] section.
====
[[mongo-template.replace]] [[mongo-template.replace]]
=== Replacing Documents in a Collection === Replacing Documents in a Collection
@ -575,6 +593,12 @@ Person upserted = template.update(Person.class)
.findAndModifyValue() .findAndModifyValue()
---- ----
[IMPORTANT]
====
`@Version` properties if not included in the `Update` will be automatically incremented.
Read more in the see xref:mongodb/template-crud-operations.adoc#mongo-template.optimistic-locking[Optimistic Locking] section.
====
[[mongo-template.find-and-replace]] [[mongo-template.find-and-replace]]
== Find and Replace == Find and Replace
@ -664,6 +688,8 @@ template.save(tmp); // throws OptimisticLockingFailureException
<4> Try to update the previously loaded document that still has `version = 0`. The operation fails with an `OptimisticLockingFailureException`, as the current `version` is `1`. <4> Try to update the previously loaded document that still has `version = 0`. The operation fails with an `OptimisticLockingFailureException`, as the current `version` is `1`.
==== ====
Only certain CRUD operations on `MongoTemplate` do consider and alter version properties. Please consult `MongoOperations` java doc for detailed information.
IMPORTANT: Optimistic Locking requires to set the `WriteConcern` to `ACKNOWLEDGED`. Otherwise `OptimisticLockingFailureException` can be silently swallowed. IMPORTANT: Optimistic Locking requires to set the `WriteConcern` to `ACKNOWLEDGED`. Otherwise `OptimisticLockingFailureException` can be silently swallowed.
NOTE: As of Version 2.2 `MongoOperations` also includes the `@Version` property when removing an entity from the database. NOTE: As of Version 2.2 `MongoOperations` also includes the `@Version` property when removing an entity from the database.

Write Preview
Loading…
Cancel
Save