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-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,42 @@ 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.
+
+==== Limitations
 
 * During schema creation, json view mapped entities are skipped, and it is expected for users to create them manually or via migration scripts.