Update documentation on version property handling.

Original pull request: #4553
Closes #4536

Author: christophstrobl

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java

@@ -945,6 +945,9 @@ default <T> List<T> findDistinct(Query query, String field, String collection, C
 	/**
 	 * 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}.
+	 * <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 fields specification. Must not be {@literal null}.
@@ -961,6 +964,9 @@ default <T> List<T> findDistinct(Query query, String field, String collection, C
 	/**
 	 * 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}.
+	 * <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 fields specification. Must not be {@literal null}.
@@ -979,6 +985,9 @@ default <T> List<T> findDistinct(Query query, String field, String collection, C
 	 * 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
 	 * {@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 fields specification.
@@ -999,6 +1008,9 @@ default <T> List<T> findDistinct(Query query, String field, String collection, C
 	 * 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
 	 * {@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 fields specification. Must not be {@literal null}.
@@ -1391,8 +1403,11 @@ default long exactCount(Query query, String collectionName) {
 	 * leverages Type Conversion API. See
 	 * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#validation" > Spring's
 	 * 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.
-	 * <br />
+	 * Insert is used to initially store the object into the database. To update an existing object use the
+	 * {@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.
 	 *
 	 * @param objectToSave the object to store in the collection. Must not be {@literal null}.
@@ -1408,7 +1423,9 @@ default long exactCount(Query query, String collectionName) {
 	 * 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 />
 	 * 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.
 	 *
 	 * @param objectToSave the object to store in the collection. Must not be {@literal null}.
@@ -1420,6 +1437,11 @@ default long exactCount(Query query, String collectionName) {
 
 	/**
 	 * 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 entityClass class that determines the collection to use. Must not be {@literal null}.
@@ -1431,6 +1453,11 @@ default long exactCount(Query query, String collectionName) {
 
 	/**
 	 * 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 collectionName name of the collection to store the object in. Must not be {@literal null}.
@@ -1441,6 +1468,11 @@ default long exactCount(Query query, String collectionName) {
 	/**
 	 * Insert a mixed Collection of objects into a database collection determining the collection name to use based on the
 	 * 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}.
 	 * @return the inserted objects.
@@ -1458,14 +1490,20 @@ default long exactCount(Query query, String collectionName) {
 	 * 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
 	 * <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.
 	 *
 	 * @param objectToSave the object to store in the collection. Must not be {@literal null}.
 	 * @return the saved object.
 	 * @throws IllegalArgumentException in case the {@code objectToSave} is collection-like.
 	 * @throws org.springframework.data.mapping.MappingException if the target collection name cannot be
 	 *           {@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);
 
@@ -1478,19 +1516,29 @@ default long exactCount(Query query, String collectionName) {
 	 * 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
 	 * <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.
 	 *
 	 * @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}.
 	 * @return the saved object.
 	 * @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);
 
 	/**
 	 * 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}.
 	 * Use {@link #findAndModify(Query, UpdateDefinition, FindAndModifyOptions, Class, String)} instead.
 	 *
@@ -1532,6 +1580,9 @@ default long exactCount(Query query, String collectionName) {
 	/**
 	 * 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.
+	 * <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
 	 *          {@literal null}.
@@ -1549,6 +1600,9 @@ default long exactCount(Query query, String collectionName) {
 	/**
 	 * Updates the first object that is found in the collection of the entity class that matches the query document with
 	 * 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
 	 *          {@literal null}.
@@ -1587,7 +1641,10 @@ default long exactCount(Query query, String collectionName) {
 
 	/**
 	 * 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
 	 *          {@literal null}.
@@ -1605,6 +1662,9 @@ default long exactCount(Query query, String collectionName) {
 	/**
 	 * Updates all objects that are found in the collection for the entity class that matches the query document criteria
 	 * 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
 	 *          {@literal null}.
@@ -1642,6 +1702,9 @@ default long exactCount(Query query, String collectionName) {
 	/**
 	 * Updates all objects that are found in the collection for the entity class that matches the query document criteria
 	 * 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
 	 *          {@literal null}.