Added doc for Json View _metadata and optimistic locking

data-jdbc/src/test/groovy/io/micronaut/data/jdbc/oraclexe/jsonview/OracleJdbcJsonViewSpec.groovy

@@ -3,6 +3,7 @@ package io.micronaut.data.jdbc.oraclexe.jsonview
 import io.micronaut.data.exceptions.OptimisticLockException
 import io.micronaut.data.model.Pageable
 import io.micronaut.data.model.Sort
+import io.micronaut.data.tck.entities.Metadata
 import io.micronaut.test.extensions.spock.annotation.MicronautTest
 import jakarta.inject.Inject
 import spock.lang.Specification
@@ -228,7 +229,7 @@ class OracleJdbcJsonViewSpec extends Specification {
 
         when:"Try to trigger optimistic lock exception with invalid ETAG"
         def newJoshStudentView = studentViewRepository.findByName(newStudentName).get()
-        newJoshStudentView.getMetadata().setEtag(UUID.randomUUID().toString())
+        newJoshStudentView.setMetadata(new Metadata(UUID.randomUUID().toString(), newJoshStudentView.getMetadata().asof()))
         studentViewRepository.update(newJoshStudentView)
         then:
         thrown(OptimisticLockException)

data-model/src/main/java/io/micronaut/data/model/query/builder/sql/AbstractSqlLikeQueryBuilder2.java

@@ -700,11 +700,16 @@ private void buildUpdateStatement(AnnotationMetadata annotationMetadata, QuerySt
 
         PersistentEntity entity = queryState.getEntity();
         boolean jsonEntity = isJsonEntity(annotationMetadata, queryState.getEntity());
-        if (jsonEntity && propertiesToUpdate.size() == 1) {
+        if (jsonEntity) {
             checkDialectSupportsJsonEntity(entity);
+            // JsonView updates only DATA column
+            String jsonEntityColumn = getJsonEntityColumn(annotationMetadata);
+            if (propertiesToUpdate.size() > 1 && propertiesToUpdate.keySet().contains(jsonEntityColumn)) {
+                List<String> nonSupportedColumns = propertiesToUpdate.keySet().stream().filter(s -> !jsonEntityColumn.equals(s)).collect(Collectors.toList());
+                throw new IllegalStateException("Json View supports only `" + jsonEntityColumn + "` column to be updated. Cannot update: " + nonSupportedColumns);
+            }
             // Update JsonView DATA column
             String name = propertiesToUpdate.keySet().iterator().next();
-            String jsonEntityColumn = getJsonEntityColumn(annotationMetadata);
             if (name.equals(jsonEntityColumn)) {
                 Object value = propertiesToUpdate.get(name);
                 queryString.append(queryState.getRootAlias()).append(DOT).append(jsonEntityColumn).append("=");
@@ -1740,7 +1745,7 @@ private QueryPropertyPath findProperty(String propertyPath) {
                     rootAlias
                 );
             }
-            throw new IllegalArgumentException("Cannot order on non-existent property path: " + pp);
+            throw new IllegalArgumentException("Cannot select or update non-existent property path: " + propertyPath);
         }
 
         @NonNull

data-r2dbc/src/test/groovy/io/micronaut/data/r2dbc/oraclexe/jsonview/OracleR2DbcJsonViewSpec.groovy

@@ -75,7 +75,7 @@ class OracleR2DbcJsonViewSpec extends Specification {
 
         when:"Test optimistic locking"
         contactView = contactViewRepository.findById(contactView.id).get()
-        contactView.metadata.etag = UUID.randomUUID().toString()
+        contactView.metadata = new io.micronaut.data.tck.entities.Metadata(UUID.randomUUID().toString(), contactView.metadata.asof())
         contactViewRepository.update(contactView)
         then:
         def e = thrown(OptimisticLockException)

data-tck/src/main/java/io/micronaut/data/tck/entities/Metadata.java

@@ -2,33 +2,18 @@
 
 import io.micronaut.core.annotation.Introspected;
 
+/**
+ * The Json Duality View metadata.
+ *
+ * @param etag A unique identifier for a specific version of the document, as a string of hexadecimal characters.
+ * @param asof The latest system change number (SCN) for the JSON document, as a JSON number.
+ *             This records the last logical point in time at which the document was generated.
+ */
 @Introspected
-public class Metadata {
+public record Metadata(
 
-    private String etag;
+    String etag,
 
-    private String asof;
-
-    public String getEtag() {
-        return etag;
-    }
-
-    public void setEtag(String etag) {
-        this.etag = etag;
-    }
-
-    public String getAsof() {
-        return asof;
-    }
-
-    public void setAsof(String asof) {
-        this.asof = asof;
-    }
-
-    public static Metadata of(String etag, String asof) {
-        Metadata metadata = new Metadata();
-        metadata.setEtag(etag);
-        metadata.setAsof(asof);
-        return metadata;
-    }
+    String asof
+) {
 }

data-tx/src/main/java/io/micronaut/transaction/annotation/Transactional.java

@@ -97,9 +97,9 @@
     boolean readOnly() default false;
 
     /**
-     * Defines the exceptions that will not result in a rollback.
+     * Defines the exceptions that will result in a rollback.
      *
-     * @return The exception types that will not result in a rollback.
+     * @return The exception types that will result in a rollback.
      * @since 3.5.0
      */
     Class<? extends Throwable>[] rollbackFor() default {};

src/main/docs/guide/dbc/sqlMapping/sqlJsonView.adoc

@@ -12,6 +12,44 @@ More about Oracle JSON VIEW can be read here https://docs.oracle.com/en/database
 Essentially, json view will be treated like mapped entity and will return JSON structure from the database and be mapped to java entity. All CRUD operations can be
 performed against json view mapped entities.
 
-Limitations
+==== Optimistic Locking
+
+You can use optimistic/lock-free concurrency control with duality views, writing JSON documents or committing their updates only when other sessions haven't modified them concurrently.
+
+Optimistic concurrency control at the document level uses embedded ETAG values in field etag, which is in the object that is the value of field `_metadata`.
+
+Example of class used to map `_metadata` field:
+
+[source,java]
+----
+/**
+ * The Json Duality View metadata.
+ *
+ * @param etag A unique identifier for a specific version of the document, as a string of hexadecimal characters.
+ * @param asof The latest system change number (SCN) for the JSON document, as a JSON number.
+*              This records the last logical point in time at which the document was generated.
+ */
+@Introspected
+public record Metadata(
+    String etag,
+    String asof
+) {
+}
+----
+
+Then this metadata class can be declared as property of class mapped to Json Duality View like this:
+
+[source,java]
+----
+@JsonProperty("_metadata")
+Metadata metadata;
+----
+
+If Json Duality View mapped entity is updated with invalid or unexpected `etag` value of the `metadata` field
+then `OptimisticLockingException` will be thrown.
+
+NOTE: Using `@Version` is not supported in Json Duality View mapped classes.
+
+==== Limitations
 
 * During schema creation, json view mapped entities are skipped, and it is expected for users to create them manually or via migration scripts.