From dd0ac6c809a45558de10f7d3acfaf68cb080ea57 Mon Sep 17 00:00:00 2001 From: radovanradic Date: Mon, 27 Jan 2025 11:50:24 +0100 Subject: [PATCH] Added doc for Json View _metadata and optimistic locking --- .../jsonview/OracleJdbcJsonViewSpec.groovy | 3 +- .../jsonview/OracleR2DbcJsonViewSpec.groovy | 2 +- .../micronaut/data/tck/entities/Metadata.java | 37 ++++++------------ .../transaction/annotation/Transactional.java | 4 +- .../guide/dbc/sqlMapping/sqlJsonView.adoc | 38 ++++++++++++++++++- 5 files changed, 53 insertions(+), 31 deletions(-) diff --git a/data-jdbc/src/test/groovy/io/micronaut/data/jdbc/oraclexe/jsonview/OracleJdbcJsonViewSpec.groovy b/data-jdbc/src/test/groovy/io/micronaut/data/jdbc/oraclexe/jsonview/OracleJdbcJsonViewSpec.groovy index 8ed8d3633bb..cc122e43da8 100644 --- a/data-jdbc/src/test/groovy/io/micronaut/data/jdbc/oraclexe/jsonview/OracleJdbcJsonViewSpec.groovy +++ b/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) diff --git a/data-r2dbc/src/test/groovy/io/micronaut/data/r2dbc/oraclexe/jsonview/OracleR2DbcJsonViewSpec.groovy b/data-r2dbc/src/test/groovy/io/micronaut/data/r2dbc/oraclexe/jsonview/OracleR2DbcJsonViewSpec.groovy index fb54bfe4e6f..515b24ef446 100644 --- a/data-r2dbc/src/test/groovy/io/micronaut/data/r2dbc/oraclexe/jsonview/OracleR2DbcJsonViewSpec.groovy +++ b/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) diff --git a/data-tck/src/main/java/io/micronaut/data/tck/entities/Metadata.java b/data-tck/src/main/java/io/micronaut/data/tck/entities/Metadata.java index d65e89f47a6..e6736d99501 100644 --- a/data-tck/src/main/java/io/micronaut/data/tck/entities/Metadata.java +++ b/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 +) { } diff --git a/data-tx/src/main/java/io/micronaut/transaction/annotation/Transactional.java b/data-tx/src/main/java/io/micronaut/transaction/annotation/Transactional.java index b15fd63c2b6..3ebe9155082 100644 --- a/data-tx/src/main/java/io/micronaut/transaction/annotation/Transactional.java +++ b/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[] rollbackFor() default {}; diff --git a/src/main/docs/guide/dbc/sqlMapping/sqlJsonView.adoc b/src/main/docs/guide/dbc/sqlMapping/sqlJsonView.adoc index 151f41321c9..1cb5ca980f7 100644 --- a/src/main/docs/guide/dbc/sqlMapping/sqlJsonView.adoc +++ b/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.