[DE-539] Spring Data: documented object mapping behavior (#476)

* Spring Data: documented object mapping behavior

* Review

* renamed computed values annotations

* Apply to 3.13

* fixed links

---------

Co-authored-by: Simran Spiller <simran@arangodb.com>

site/content/3.10/develop/integrations/spring-data-arangodb/_index.md

@@ -205,7 +205,6 @@ Spring Boot support is offered by [Spring Boot Starter ArangoDB](https://github.
 {{< tabs "spring-data" >}}
 
 {{< tab "Version 4" >}}
-- Java Record classes and Kotlin Data classes are not supported (DE-539)
 - GraalVM Native Image (available with Spring Boot 3) is not supported (DE-677)
 - Spring Data REST is not supported (DE-43)
 - Spring Data Reactive is not supported (DE-678)

site/content/3.10/develop/integrations/spring-data-arangodb/reference-version-4/mapping/_index.md

@@ -185,3 +185,64 @@ ArangoConverter arangoConverter;
   // ...
   MyEntity entity = converter.read(MyEntity.class, jn);
 ```
+
+## Object Mapping
+
+Spring Data ArangoDB delegates object mapping, object creation, field and property access to
+[Spring Data Commons](https://docs.spring.io/spring-data/commons/reference/object-mapping.html).
+
+Methods in `ArangoOperations` try modifying the domain objects accepted as parameters,
+updating the properties potentially modified by the server side, if the related fields
+are mutable. This applies to the fields annotated with:
+- `@ArangoId`
+- `@Id` 
+- `@Rev`
+
+In addition, the following methods also try to update the fields annotated with
+`@ArangoComputedValue`:
+- `ArangoOperations#repsert(Object)`
+- `ArangoOperations#repsertAll(Iterable<Object>, Class<?>)`
+
+## Object Identity
+
+The most of the methods in `ArangoOperations` and `ArangoRepository` return new
+entity instances, except the following:
+- `ArangoRepository#save(Object)`
+- `ArangoRepository#saveAll(Iterable<Object>)`
+
+These methods return by default the same instance(s) of the domain object(s)
+accepted as parameter(s) and update the properties potentially modified by the
+server side, if the related fields are mutable.
+This applies to the fields annotated with:
+- `@ArangoId`
+- `@Id`
+- `@Rev`
+- `@ArangoComputedValue`
+
+This behavior can be changed by overriding `ArangoConfiguration#returnOriginalEntities()`,
+which by default returns `true`. For example:
+
+```java
+@Configuration
+@EnableArangoRepositories
+public class MyConfiguration implements ArangoConfiguration {
+
+  // ...
+
+  @Override
+  public boolean returnOriginalEntities() {
+    return false; 
+  }
+
+}
+```
+
+Note that also in this case, input parameters properties are still updated, if mutable.
+
+## Working with immutable objects
+
+Spring Data ArangoDB can work with immutable entity classes, like Java Records,
+Kotlin data classes and final classes with immutable properties. In this case,
+to use `ArangoRepository#save(Object)` and `ArangoRepository#saveAll(Iterable<Object>)`
+is required overriding `ArangoConfiguration#returnOriginalEntities()` to make it
+return `false`, see [Object Identity](#object-identity).

site/content/3.11/develop/integrations/spring-data-arangodb/_index.md

@@ -205,7 +205,6 @@ Spring Boot support is offered by [Spring Boot Starter ArangoDB](https://github.
 {{< tabs "spring-data" >}}
 
 {{< tab "Version 4" >}}
-- Java Record classes and Kotlin Data classes are not supported (DE-539)
 - GraalVM Native Image (available with Spring Boot 3) is not supported (DE-677)
 - Spring Data REST is not supported (DE-43)
 - Spring Data Reactive is not supported (DE-678)

site/content/3.11/develop/integrations/spring-data-arangodb/reference-version-4/mapping/_index.md

@@ -185,3 +185,64 @@ ArangoConverter arangoConverter;
   // ...
   MyEntity entity = converter.read(MyEntity.class, jn);
 ```
+
+## Object Mapping
+
+Spring Data ArangoDB delegates object mapping, object creation, field and property access to
+[Spring Data Commons](https://docs.spring.io/spring-data/commons/reference/object-mapping.html).
+
+Methods in `ArangoOperations` try modifying the domain objects accepted as parameters,
+updating the properties potentially modified by the server side, if the related fields
+are mutable. This applies to the fields annotated with:
+- `@ArangoId`
+- `@Id` 
+- `@Rev`
+
+In addition, the following methods also try to update the fields annotated with
+`@ArangoComputedValue`:
+- `ArangoOperations#repsert(Object)`
+- `ArangoOperations#repsertAll(Iterable<Object>, Class<?>)`
+
+## Object Identity
+
+The most of the methods in `ArangoOperations` and `ArangoRepository` return new
+entity instances, except the following:
+- `ArangoRepository#save(Object)`
+- `ArangoRepository#saveAll(Iterable<Object>)`
+
+These methods return by default the same instance(s) of the domain object(s)
+accepted as parameter(s) and update the properties potentially modified by the
+server side, if the related fields are mutable.
+This applies to the fields annotated with:
+- `@ArangoId`
+- `@Id`
+- `@Rev`
+- `@ArangoComputedValue`
+
+This behavior can be changed by overriding `ArangoConfiguration#returnOriginalEntities()`,
+which by default returns `true`. For example:
+
+```java
+@Configuration
+@EnableArangoRepositories
+public class MyConfiguration implements ArangoConfiguration {
+
+  // ...
+
+  @Override
+  public boolean returnOriginalEntities() {
+    return false; 
+  }
+
+}
+```
+
+Note that also in this case, input parameters properties are still updated, if mutable.
+
+## Working with immutable objects
+
+Spring Data ArangoDB can work with immutable entity classes, like Java Records,
+Kotlin data classes and final classes with immutable properties. In this case,
+to use `ArangoRepository#save(Object)` and `ArangoRepository#saveAll(Iterable<Object>)`
+is required overriding `ArangoConfiguration#returnOriginalEntities()` to make it
+return `false`, see [Object Identity](#object-identity).

site/content/3.12/develop/integrations/spring-data-arangodb/_index.md

@@ -205,7 +205,6 @@ Spring Boot support is offered by [Spring Boot Starter ArangoDB](https://github.
 {{< tabs "spring-data" >}}
 
 {{< tab "Version 4" >}}
-- Java Record classes and Kotlin Data classes are not supported (DE-539)
 - GraalVM Native Image (available with Spring Boot 3) is not supported (DE-677)
 - Spring Data REST is not supported (DE-43)
 - Spring Data Reactive is not supported (DE-678)

site/content/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/_index.md

@@ -185,3 +185,64 @@ ArangoConverter arangoConverter;
   // ...
   MyEntity entity = converter.read(MyEntity.class, jn);
 ```
+
+## Object Mapping
+
+Spring Data ArangoDB delegates object mapping, object creation, field and property access to
+[Spring Data Commons](https://docs.spring.io/spring-data/commons/reference/object-mapping.html).
+
+Methods in `ArangoOperations` try modifying the domain objects accepted as parameters,
+updating the properties potentially modified by the server side, if the related fields
+are mutable. This applies to the fields annotated with:
+- `@ArangoId`
+- `@Id` 
+- `@Rev`
+
+In addition, the following methods also try to update the fields annotated with
+`@ArangoComputedValue`:
+- `ArangoOperations#repsert(Object)`
+- `ArangoOperations#repsertAll(Iterable<Object>, Class<?>)`
+
+## Object Identity
+
+The most of the methods in `ArangoOperations` and `ArangoRepository` return new
+entity instances, except the following:
+- `ArangoRepository#save(Object)`
+- `ArangoRepository#saveAll(Iterable<Object>)`
+
+These methods return by default the same instance(s) of the domain object(s)
+accepted as parameter(s) and update the properties potentially modified by the
+server side, if the related fields are mutable.
+This applies to the fields annotated with:
+- `@ArangoId`
+- `@Id`
+- `@Rev`
+- `@ArangoComputedValue`
+
+This behavior can be changed by overriding `ArangoConfiguration#returnOriginalEntities()`,
+which by default returns `true`. For example:
+
+```java
+@Configuration
+@EnableArangoRepositories
+public class MyConfiguration implements ArangoConfiguration {
+
+  // ...
+
+  @Override
+  public boolean returnOriginalEntities() {
+    return false; 
+  }
+
+}
+```
+
+Note that also in this case, input parameters properties are still updated, if mutable.
+
+## Working with immutable objects
+
+Spring Data ArangoDB can work with immutable entity classes, like Java Records,
+Kotlin data classes and final classes with immutable properties. In this case,
+to use `ArangoRepository#save(Object)` and `ArangoRepository#saveAll(Iterable<Object>)`
+is required overriding `ArangoConfiguration#returnOriginalEntities()` to make it
+return `false`, see [Object Identity](#object-identity).

site/content/3.13/develop/integrations/spring-data-arangodb/_index.md

@@ -205,7 +205,6 @@ Spring Boot support is offered by [Spring Boot Starter ArangoDB](https://github.
 {{< tabs "spring-data" >}}
 
 {{< tab "Version 4" >}}
-- Java Record classes and Kotlin Data classes are not supported (DE-539)
 - GraalVM Native Image (available with Spring Boot 3) is not supported (DE-677)
 - Spring Data REST is not supported (DE-43)
 - Spring Data Reactive is not supported (DE-678)

site/content/3.13/develop/integrations/spring-data-arangodb/reference-version-4/mapping/_index.md

@@ -185,3 +185,64 @@ ArangoConverter arangoConverter;
   // ...
   MyEntity entity = converter.read(MyEntity.class, jn);
 ```
+
+## Object Mapping
+
+Spring Data ArangoDB delegates object mapping, object creation, field and property access to
+[Spring Data Commons](https://docs.spring.io/spring-data/commons/reference/object-mapping.html).
+
+Methods in `ArangoOperations` try modifying the domain objects accepted as parameters,
+updating the properties potentially modified by the server side, if the related fields
+are mutable. This applies to the fields annotated with:
+- `@ArangoId`
+- `@Id` 
+- `@Rev`
+
+In addition, the following methods also try to update the fields annotated with
+`@ArangoComputedValue`:
+- `ArangoOperations#repsert(Object)`
+- `ArangoOperations#repsertAll(Iterable<Object>, Class<?>)`
+
+## Object Identity
+
+The most of the methods in `ArangoOperations` and `ArangoRepository` return new
+entity instances, except the following:
+- `ArangoRepository#save(Object)`
+- `ArangoRepository#saveAll(Iterable<Object>)`
+
+These methods return by default the same instance(s) of the domain object(s)
+accepted as parameter(s) and update the properties potentially modified by the
+server side, if the related fields are mutable.
+This applies to the fields annotated with:
+- `@ArangoId`
+- `@Id`
+- `@Rev`
+- `@ArangoComputedValue`
+
+This behavior can be changed by overriding `ArangoConfiguration#returnOriginalEntities()`,
+which by default returns `true`. For example:
+
+```java
+@Configuration
+@EnableArangoRepositories
+public class MyConfiguration implements ArangoConfiguration {
+
+  // ...
+
+  @Override
+  public boolean returnOriginalEntities() {
+    return false; 
+  }
+
+}
+```
+
+Note that also in this case, input parameters properties are still updated, if mutable.
+
+## Working with immutable objects
+
+Spring Data ArangoDB can work with immutable entity classes, like Java Records,
+Kotlin data classes and final classes with immutable properties. In this case,
+to use `ArangoRepository#save(Object)` and `ArangoRepository#saveAll(Iterable<Object>)`
+is required overriding `ArangoConfiguration#returnOriginalEntities()` to make it
+return `false`, see [Object Identity](#object-identity).