Merge pull request #812 from SpineEventEngine/runtime-retention-for-a…

…pi-annotations

`RUNTIME` retention for API level annotations

buildSrc/src/main/kotlin/DokkaExts.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023, TeamDev. All rights reserved.
+ * Copyright 2024, 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.
@@ -182,3 +182,21 @@ fun Project.dokkaJavaJar(): TaskProvider<Jar> = tasks.getOrCreate("dokkaJavaJar"
         this@getOrCreate.dependsOn(dokkaTask)
     }
 }
+
+/**
+ * Disables Dokka and Javadoc tasks in this `Project`.
+ *
+ * This function could be useful to improve build speed when building subprojects containing
+ * test environments or integration test projects.
+ */
+@Suppress("unused")
+fun Project.disableDocumentationTasks() {
+    gradle.taskGraph.whenReady {
+        tasks.forEach { task ->
+            val lowercaseName = task.name.toLowerCase()
+            if (lowercaseName.contains("dokka") || lowercaseName.contains("javadoc")) {
+                task.enabled = false
+            }
+        }
+    }
+}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023, TeamDev. All rights reserved.
+ * Copyright 2024, 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.
@@ -65,7 +65,7 @@ object ProtoData {
      * The version of ProtoData dependencies.
      */
     val version: String
-    private const val fallbackVersion = "0.16.0"
+    private const val fallbackVersion = "0.16.1"
 
     /**
      * The distinct version of ProtoData used by other build tools.
@@ -74,7 +74,7 @@ object ProtoData {
      * transitional dependencies, this is the version used to build the project itself.
      */
     val dogfoodingVersion: String
-    private const val fallbackDfVersion = "0.16.0"
+    private const val fallbackDfVersion = "0.16.1"
 
     /**
      * The artifact for the ProtoData Gradle plugin.

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023, TeamDev. All rights reserved.
+ * Copyright 2024, 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.
@@ -45,7 +45,7 @@ object Spine {
          *
          * @see <a href="https://github.com/SpineEventEngine/base">spine-base</a>
          */
-        const val base = "2.0.0-SNAPSHOT.194"
+        const val base = "2.0.0-SNAPSHOT.195"
 
         /**
          * The version of [Spine.reflect].
@@ -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.191"
+        const val toolBase = "2.0.0-SNAPSHOT.192"
 
         /**
          * The version of [Spine.javadocTools].

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023, TeamDev. All rights reserved.
+ * Copyright 2024, 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.
@@ -33,7 +33,7 @@ package io.spine.internal.dependency
  */
 @Suppress("unused", "ConstPropertyName")
 object Validation {
-    const val version = "2.0.0-SNAPSHOT.110"
+    const val version = "2.0.0-SNAPSHOT.123"
     const val group = "io.spine.validation"
     const val runtime = "$group:spine-validation-java-runtime:$version"
     const val java = "$group:spine-validation-java:$version"

dependencies.md

@@ -1,6 +1,6 @@
 
 
-# Dependencies of `io.spine:spine-base:2.0.0-SNAPSHOT.195`
+# Dependencies of `io.spine:spine-base:2.0.0-SNAPSHOT.196`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -771,4 +771,4 @@
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Tue Jan 02 17:30:00 WET 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Mon Jan 08 14:50:35 WET 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).

pom.xml

@@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject.
  -->
 <groupId>io.spine</groupId>
 <artifactId>base</artifactId>
-<version>2.0.0-SNAPSHOT.195</version>
+<version>2.0.0-SNAPSHOT.196</version>
 
 <inceptionYear>2015</inceptionYear>
 

src/main/java/io/spine/annotation/Beta.java

@@ -42,7 +42,7 @@
  * It is generally safe for applications to depend on beta APIs at the cost of some extra work
  * during upgrades.
  */
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.RUNTIME)
 @Target({
         ElementType.ANNOTATION_TYPE,
         ElementType.CONSTRUCTOR,

src/main/java/io/spine/annotation/Experimental.java

@@ -43,7 +43,7 @@
  *   <li>removing this annotation from an API gives it a stable status.
  * </ol>
  */
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.RUNTIME)
 @Target({
         ElementType.ANNOTATION_TYPE,
         ElementType.CONSTRUCTOR,

src/main/java/io/spine/annotation/SPI.java

@@ -43,7 +43,7 @@
  * service provider framework pattern.
  */
 @SPI
-@Retention(RetentionPolicy.SOURCE)
+@Retention(RetentionPolicy.RUNTIME)
 @Target({
         ElementType.ANNOTATION_TYPE,
         ElementType.CONSTRUCTOR,

src/main/java/io/spine/code/java/ClassName.java

@@ -61,7 +61,7 @@ public final class ClassName extends StringTypeValue {
     private static final char DOT_SEPARATOR = '.';
 
     /**
-     * Separates nested class name from the name of the outer class in a fully-qualified name.
+     * Separates nested class name from the name of the outer class in a fully qualified name.
      */
     private static final char OUTER_CLASS_DELIMITER = '$';
 
@@ -165,7 +165,9 @@ public static ClassName from(EnumDescriptor enumType) {
      * @return new instance of {@code ClassName}
      */
     public static ClassName from(ServiceDescriptor serviceType) {
-        return construct(serviceType.getFile(), serviceType.getName() + GRPC_POSTFIX, null);
+        var packageName = PackageName.resolve(serviceType.getFile().toProto());
+        var simpleName = SimpleClassName.create(serviceType.getName() + GRPC_POSTFIX);
+        return of(packageName, simpleName);
     }
 
     private static String javaPackageName(FileDescriptor file) {
@@ -192,7 +194,7 @@ private static String outerClassPrefix(FileDescriptor file) {
 
     /**
      * Obtains prefix for a type which is enclosed into the passed message.
-     * If null value is passed, returns an empty string.
+     * If a {@code null} value is passed, returns an empty string.
      */
     private static String containingClassPrefix(@Nullable Descriptor containingMessage) {
         if (containingMessage == null) {
@@ -282,7 +284,7 @@ private static ClassName construct(FileDescriptor file,
     }
 
     /**
-     * Converts fully-qualified name to simple name. If the class is nested inside one or more
+     * Converts fully qualified name to simple name. If the class is nested inside one or more
      * classes, the most nested name will be returned.
      */
     public SimpleClassName toSimple() {

src/main/proto/spine/options.proto

@@ -495,17 +495,34 @@ extend google.protobuf.FileOptions {
     // For more information on such restrictions please see the documentation of
     // the type option called `internal_type`.
     //
+    // If a file contains a declaration of a `service`, this option will NOT be applied to it.
+    // A service is not a data type, and therefore, this option does not apply to it.
+    // Internal services are not supported.
+    //
     bool internal_all = 73942;
 
     // Indicates a file which contains elements of Service Provider Interface (SPI).
+    //
+    // This option applies to messages, enums, and services.
+    //
     bool SPI_all = 73943;
 
-    // Indicates a public API that can change at any time, and has no guarantee of
-    // API stability and backward-compatibility.
+    // Indicates a file declaring public data type API which that can change at any time,
+    // has no guarantee of API stability and backward-compatibility.
+    //
+    // If a file contains a declaration of a `service`, this option will NOT be applied to it.
+    // A service is not a data type, and therefore, this option does not apply to it.
+    // Experimental services are not supported.
+    //
     bool experimental_all = 73944;
 
-    // Signifies that a public API is subject to incompatible changes, or even removal,
+    // Signifies that a public data type API is subject to incompatible changes, or even removal,
     // in a future release.
+    //
+    // If a file contains a declaration of a `service`, this option will NOT be applied to it.
+    // A service is not a data type, and therefore, this option does not apply to it.
+    // Beta services are not supported.
+    //
     bool beta_all = 73945;
 
     // Specifies a characteristic common for all the message types in the given file.

src/test/kotlin/io/spine/annotation/AnnotationsSpec.kt

@@ -39,30 +39,29 @@ import org.junit.jupiter.api.Test
 @DisplayName("`io.spine.annotation` package should")
 internal class AnnotationsSpec {
 
+    /**
+     * Tests that API level annotation classes have the [RUNTIME] retention policy.
+     *
+     * The [RUNTIME] level is required to:
+     *  1. Ease the usage in tests.
+     *  2. Allow handling `Internal` types in inbound and outbound communications.
+     */
     @Test
-    fun `have 'Beta' annotation`() {
-        Beta::class.java.retention() shouldBe SOURCE
-    }
-
-    @Test
-    fun `have 'Experimental' annotation`() {
-        Experimental::class.java.retention() shouldBe SOURCE
+    fun `have API level annotations with 'RUNTIME' retention`() {
+        arrayOf(
+            Beta::class.java,
+            Experimental::class.java,
+            Internal::class.java,
+            SPI::class.java
+        ).forEach {
+            it.retention() shouldBe RUNTIME
+        }
     }
 
     @Test
     fun `have 'GeneratedMixin' annotation`() {
         GeneratedMixin::class.java.retention() shouldBe SOURCE
     }
-
-    @Test
-    fun `have 'Internal' annotation`() {
-        Internal::class.java.retention() shouldBe RUNTIME
-    }
-
-    @Test
-    fun `have 'SPI' annotation`() {
-        SPI::class.java.retention() shouldBe SOURCE
-    }
 }
 
 private fun <T: Annotation> Class<in T>.retention() =

version.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023, TeamDev. All rights reserved.
+ * Copyright 2024, 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.
@@ -24,4 +24,4 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-val versionToPublish: String by extra("2.0.0-SNAPSHOT.195")
+val versionToPublish: String by extra("2.0.0-SNAPSHOT.196")