Skip to content

Commit

Permalink
Update documentation on version property handling.
Browse files Browse the repository at this point in the history 
Original pull request: #4553
Closes #4536
  • Loading branch information
@christophstrobl @mp911de
christophstrobl authored and mp911de committed Nov 13, 2023
1 parent 88d639d commit 415e4d5
Show file tree
Hide file tree
Showing 2 changed files with 172 additions and 18 deletions.
77 changes: 70 additions & 7 deletions spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -941,6 +941,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 record and also an optional
* fields specification. Must not be {@literal null}.
Expand All @@ -957,6 +960,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 record and also an optional
* fields specification. Must not be {@literal null}.
Expand All @@ -975,6 +981,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 record and also an optional
* fields specification.
Expand All @@ -995,6 +1004,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 record and also an optional
* fields specification. Must not be {@literal null}.
Expand Down Expand Up @@ -1387,8 +1399,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}.
Expand All @@ -1404,7 +1419,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}.
Expand All @@ -1416,6 +1433,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}.
Expand All @@ -1427,6 +1449,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}.
Expand All @@ -1437,6 +1464,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.
Expand All @@ -1454,14 +1486,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);

Expand All @@ -1474,19 +1512,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.
*
Expand Down Expand Up @@ -1528,6 +1576,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 record to be upserted. Must not be
* {@literal null}.
Expand All @@ -1545,6 +1596,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 record to be updated. Must not be
* {@literal null}.
Expand Down Expand Up @@ -1583,7 +1637,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 record to be updated. Must not be
* {@literal null}.
Expand All @@ -1601,6 +1658,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 record to be updated. Must not be
* {@literal null}.
Expand Down Expand Up @@ -1638,6 +1698,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 record to be updated. Must not be
* {@literal null}.
Expand Down
Loading

0 comments on commit 415e4d5

Please sign in to comment.