Merge pull request #1537 from SpineEventEngine/extension-props-for-tx…

…-entity

Extension properties for `TransactionalEntity`

buildSrc/src/main/kotlin/io/spine/internal/dependency/ProtoData.kt

@@ -33,7 +33,12 @@ package io.spine.internal.dependency
  */
 @Suppress("unused", "ConstPropertyName")
 object ProtoData {
-    const val version = "0.9.11"
+    const val version = "0.11.6"
+
+    /**
+     * The version of ProtoData used in McJava for building McJava.
+     */
+    const val dogfoodingVersion = "0.11.6"
     const val group = "io.spine.protodata"
     const val compiler = "$group:protodata-compiler:$version"
 

buildSrc/src/main/kotlin/io/spine/internal/dependency/Spine.kt

@@ -45,7 +45,7 @@ object Spine {
          *
          * @see <a href="https://github.com/SpineEventEngine/base">spine-base</a>
          */
-        const val base = "2.0.0-SNAPSHOT.188"
+        const val base = "2.0.0-SNAPSHOT.189"
 
         /**
          * The version of [Spine.reflect].
@@ -59,7 +59,7 @@ object Spine {
          *
          * @see <a href="https://github.com/SpineEventEngine/logging">spine-logging</a>
          */
-        const val logging = "2.0.0-SNAPSHOT.206"
+        const val logging = "2.0.0-SNAPSHOT.215"
 
         /**
          * The version of [Spine.testlib].
@@ -75,28 +75,28 @@ object Spine {
          * @see [Spine.CoreJava.server]
          * @see <a href="https://github.com/SpineEventEngine/core-java">core-java</a>
          */
-        const val core = "2.0.0-SNAPSHOT.155"
+        const val core = "2.0.0-SNAPSHOT.157"
 
         /**
          * The version of [Spine.modelCompiler].
          *
          * @see <a href="https://github.com/SpineEventEngine/model-compiler">spine-model-compiler</a>
          */
-        const val mc = "2.0.0-SNAPSHOT.132"
+        const val mc = "2.0.0-SNAPSHOT.133"
 
         /**
          * The version of [McJava].
          *
          * @see <a href="https://github.com/SpineEventEngine/mc-java">spine-mc-java</a>
          */
-        const val mcJava = "2.0.0-SNAPSHOT.168"
+        const val mcJava = "2.0.0-SNAPSHOT.170"
 
         /**
          * The version of [Spine.baseTypes].
          *
          * @see <a href="https://github.com/SpineEventEngine/base-types">spine-base-types</a>
          */
-        const val baseTypes = "2.0.0-SNAPSHOT.124"
+        const val baseTypes = "2.0.0-SNAPSHOT.125"
 
         /**
          * The version of [Spine.time].
@@ -124,7 +124,7 @@ object Spine {
          *
          * @see <a href="https://github.com/SpineEventEngine/tool-base">spine-tool-base</a>
          */
-        const val toolBase = "2.0.0-SNAPSHOT.180"
+        const val toolBase = "2.0.0-SNAPSHOT.183"
 
         /**
          * The version of [Spine.javadocTools].

buildSrc/src/main/kotlin/io/spine/internal/dependency/Validation.kt

@@ -33,7 +33,7 @@ package io.spine.internal.dependency
  */
 @Suppress("unused", "ConstPropertyName")
 object Validation {
-    const val version = "2.0.0-SNAPSHOT.99"
+    const val version = "2.0.0-SNAPSHOT.104"
     const val group = "io.spine.validation"
     const val runtime = "$group:spine-validation-java-runtime:$version"
     const val java = "$group:spine-validation-java:$version"

pom.xml

@@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject.
  -->
 <groupId>io.spine</groupId>
 <artifactId>spine-core-java</artifactId>
-<version>2.0.0-SNAPSHOT.157</version>
+<version>2.0.0-SNAPSHOT.158</version>
 
 <inceptionYear>2015</inceptionYear>
 
@@ -62,13 +62,13 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine</groupId>
     <artifactId>spine-base</artifactId>
-    <version>2.0.0-SNAPSHOT.188</version>
+    <version>2.0.0-SNAPSHOT.189</version>
     <scope>compile</scope>
   </dependency>
   <dependency>
     <groupId>io.spine</groupId>
     <artifactId>spine-base-types</artifactId>
-    <version>2.0.0-SNAPSHOT.124</version>
+    <version>2.0.0-SNAPSHOT.125</version>
     <scope>compile</scope>
   </dependency>
   <dependency>
@@ -80,13 +80,13 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine</groupId>
     <artifactId>spine-flogger-grpc-context</artifactId>
-    <version>2.0.0-SNAPSHOT.206</version>
+    <version>2.0.0-SNAPSHOT.215</version>
     <scope>compile</scope>
   </dependency>
   <dependency>
     <groupId>io.spine</groupId>
     <artifactId>spine-logging</artifactId>
-    <version>2.0.0-SNAPSHOT.206</version>
+    <version>2.0.0-SNAPSHOT.215</version>
     <scope>compile</scope>
   </dependency>
   <dependency>
@@ -98,7 +98,7 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine.validation</groupId>
     <artifactId>spine-validation-java-runtime</artifactId>
-    <version>2.0.0-SNAPSHOT.99</version>
+    <version>2.0.0-SNAPSHOT.104</version>
     <scope>compile</scope>
   </dependency>
   <dependency>
@@ -186,7 +186,7 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>com.google.protobuf</groupId>
     <artifactId>protoc</artifactId>
-    <version>3.23.4</version>
+    <version>3.24.1</version>
   </dependency>
   <dependency>
     <groupId>com.puppycrawl.tools</groupId>
@@ -201,17 +201,17 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.grpc</groupId>
     <artifactId>protoc-gen-grpc-java</artifactId>
-    <version>1.56.1</version>
+    <version>1.57.2</version>
   </dependency>
   <dependency>
     <groupId>io.spine.protodata</groupId>
     <artifactId>protodata-fat-cli</artifactId>
-    <version>0.9.11</version>
+    <version>0.11.4</version>
   </dependency>
   <dependency>
     <groupId>io.spine.protodata</groupId>
     <artifactId>protodata-protoc</artifactId>
-    <version>0.9.11</version>
+    <version>0.11.4</version>
   </dependency>
   <dependency>
     <groupId>io.spine.tools</groupId>
@@ -221,43 +221,43 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-mc-java-annotation</artifactId>
-    <version>2.0.0-SNAPSHOT.168</version>
+    <version>2.0.0-SNAPSHOT.170</version>
   </dependency>
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-mc-java-base</artifactId>
-    <version>2.0.0-SNAPSHOT.168</version>
+    <version>2.0.0-SNAPSHOT.170</version>
   </dependency>
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-mc-java-checks</artifactId>
-    <version>2.0.0-SNAPSHOT.168</version>
+    <version>2.0.0-SNAPSHOT.170</version>
     <scope>provided</scope>
   </dependency>
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-mc-java-plugins</artifactId>
-    <version>2.0.0-SNAPSHOT.168</version>
+    <version>2.0.0-SNAPSHOT.170</version>
   </dependency>
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-mc-java-rejection</artifactId>
-    <version>2.0.0-SNAPSHOT.168</version>
+    <version>2.0.0-SNAPSHOT.170</version>
   </dependency>
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-tool-base</artifactId>
-    <version>2.0.0-SNAPSHOT.182</version>
+    <version>2.0.0-SNAPSHOT.184</version>
   </dependency>
   <dependency>
     <groupId>io.spine.validation</groupId>
     <artifactId>spine-validation-java</artifactId>
-    <version>2.0.0-SNAPSHOT.99</version>
+    <version>2.0.0-SNAPSHOT.104</version>
   </dependency>
   <dependency>
     <groupId>io.spine.validation</groupId>
     <artifactId>spine-validation-java-bundle</artifactId>
-    <version>2.0.0-SNAPSHOT.99</version>
+    <version>2.0.0-SNAPSHOT.104</version>
   </dependency>
   <dependency>
     <groupId>net.sourceforge.pmd</groupId>

server/src/main/java/io/spine/server/entity/AbstractEntity.java

@@ -104,8 +104,12 @@ public abstract class AbstractEntity<I, S extends EntityState<I>>
      *
      * <p>Assigned either through the {@linkplain #AbstractEntity(Object) constructor which
      * accepts the ID}, or via {@link #setId(Object)}. Is never {@code null}.
+     *
+     * @apiNote The field is named with the underscore prefix to avoid
+     *          name clash with the extension property name in Kotlin.
      */
-    private @MonotonicNonNull I id;
+    @SuppressWarnings("FieldNamingConvention") // See `apiNote` above.
+    private @MonotonicNonNull I _id;
 
     /** Cached version of string ID. */
     @LazyInit
@@ -117,14 +121,26 @@ public abstract class AbstractEntity<I, S extends EntityState<I>>
      * <p>Lazily initialized to the {@linkplain #defaultState() default state},
      * if {@linkplain #state() accessed} before {@linkplain #setState(EntityState)}
      * initialization}.
+     *
+     * @apiNote The field is named with the underscore prefix to avoid
+     *          name clash with the extension property name in Kotlin.
      */
+    @SuppressWarnings("FieldNamingConvention") // See `apiNote` above.
     @LazyInit
-    private volatile @MonotonicNonNull S state;
+    private volatile @MonotonicNonNull S _state;
 
-    /** The version of the entity. */
-    private volatile Version version;
+    /**
+     * The version of the entity.
+     *
+     * @apiNote The field is named with the underscore prefix to avoid
+     *          name clash with the extension property name in Kotlin.
+     */
+    @SuppressWarnings("FieldNamingConvention") // See `apiNote` above.
+    private volatile Version _version;
 
-    /** The lifecycle flags of the entity. */
+    /**
+     * The lifecycle flags of the entity.
+     */
     private volatile @MonotonicNonNull LifecycleFlags lifecycleFlags;
 
     /**
@@ -135,9 +151,16 @@ public abstract class AbstractEntity<I, S extends EntityState<I>>
      */
     private volatile boolean lifecycleFlagsChanged;
 
+    /**
+     * A context for the logging operations performed by the entity in a receptor.
+     *
+     * <p>This field is {@code null}, if the entity is not being accessed through a receptor.
+     *
+     * @see #beforeInvoke(Receptor)
+     * @see #afterInvoke(Receptor)
+     */
     private @Nullable AutoCloseable loggingContext = null;
 
-
     /**
      * Creates a new instance with the zero version and cleared lifecycle flags.
      *
@@ -163,12 +186,12 @@ protected AbstractEntity(I id) {
     @SuppressWarnings("InstanceVariableUsedBeforeInitialized") // checked in `if`
     final void setId(I id) {
         checkNotNull(id);
-        if (this.id != null) {
-            checkState(id.equals(this.id),
+        if (this._id != null) {
+            checkState(id.equals(this._id),
                        "Entity ID already assigned to `%s`." +
-                               " Attempted to reassign to `%s`.", this.id, id);
+                               " Attempted to reassign to `%s`.", this._id, id);
         }
-        this.id = id;
+        this._id = id;
     }
 
     /**
@@ -188,7 +211,7 @@ protected AbstractEntity(I id, Function<I, S> defaultState) {
 
     @Override
     public I id() {
-        return checkNotNull(id);
+        return checkNotNull(_id);
     }
 
     /**
@@ -202,13 +225,13 @@ public I id() {
     @Override
     public final S state() {
         ensureAccessToState();
-        var result = state;
+        var result = _state;
         if (result == null) {
             synchronized (this) {
-                result = state;
+                result = _state;
                 if (result == null) {
-                    state = defaultState();
-                    result = state;
+                    _state = defaultState();
+                    result = _state;
                 }
             }
         }
@@ -264,7 +287,7 @@ public EntityClass<?> modelClass() {
      * Sets the entity state to the passed value.
      */
     void setState(S newState) {
-        this.state = checkNotNull(newState);
+        this._state = checkNotNull(newState);
     }
 
     /**
@@ -493,7 +516,7 @@ protected int versionNumber() {
     final void updateVersion(Version newVersion) {
         checkNotNull(newVersion);
         check(newVersion);
-        if (version.equals(newVersion)) {
+        if (_version.equals(newVersion)) {
             return;
         }
         var currentVersionNumber = versionNumber();
@@ -525,7 +548,7 @@ void incrementState(S newState) {
     }
 
     void setVersion(Version version) {
-        this.version = version;
+        this._version = version;
     }
 
     private Version incrementedVersion() {
@@ -540,7 +563,7 @@ private Version incrementedVersion() {
      */
     @Override
     public Version version() {
-        return version;
+        return _version;
     }
 
     /**
@@ -550,14 +573,14 @@ public Version version() {
      */
     int incrementVersion() {
         setVersion(incrementedVersion());
-        return version.getNumber();
+        return _version.getNumber();
     }
 
     /**
      * Obtains timestamp of the entity version.
      */
     public Timestamp whenModified() {
-        return version.getTimestamp();
+        return _version.getTimestamp();
     }
 
     /**

server/src/main/kotlin/io/spine/server/ServerEnvironmentExtensions.kt → server/src/main/kotlin/io/spine/server/ServerEnvironmentExts.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022, TeamDev. All rights reserved.
+ * Copyright 2023, TeamDev. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -44,8 +44,9 @@ import io.spine.environment.EnvironmentType
  *     }
  * ```
  *
- * @apiNote This function allows to avoid calling [ServerEnvironment.when] from Kotlin, which
- * requires backticking `when` because it is a reserved word.
+ * ### API NOTE
+ * This function allows to avoid calling [ServerEnvironment.when] from Kotlin, which
+ * requires backticking `"when"` because it is a reserved word.
  */
 public inline fun <reified E : EnvironmentType<*>>
         under(block: ServerEnvironment.TypeConfigurator.() -> Unit) {