Support a Gradle Usage value 'java-api-jars'

The support on our side involves:

* using the new value for Maven publishing, as the 'maven-publish'
plugin now expects 'java-api-jars' for dependency scopes ordering where
it used to expect 'java-api'

* accepting the new value in KotlinUsages compatibility and
disambiguation rules

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/KotlinUsages.kt

@@ -37,7 +37,8 @@ object KotlinUsages {
 
     internal fun producerApiUsage(target: KotlinTarget) = target.project.usageByName(
         when (target.platformType) {
-            in jvmPlatformTypes -> JAVA_API
+            in jvmPlatformTypes ->
+                if (isGradleVersionAtLeast(5, 3)) "java-api-jars" else JAVA_API
             else -> KOTLIN_API
         }
     )
@@ -54,9 +55,10 @@ object KotlinUsages {
         // is 'java-runtime-jars'. This rule tells Gradle that Kotlin consumers can consume plain old JARs:
         override fun execute(details: CompatibilityCheckDetails<Usage>) = with(details) {
             when {
-                consumerValue?.name == KOTLIN_API && producerValue?.name == JAVA_API -> compatible()
-                consumerValue?.name in values &&
-                        producerValue?.name.let { it == JAVA_RUNTIME || it == JAVA_RUNTIME_JARS } -> compatible()
+                consumerValue?.name == KOTLIN_API && producerValue?.name.let { it == JAVA_API || it == "java-api-jars" } ->
+                    compatible()
+                consumerValue?.name in values && producerValue?.name.let { it == JAVA_RUNTIME || it == JAVA_RUNTIME_JARS } ->
+                    compatible()
             }
         }
     }
@@ -73,15 +75,16 @@ object KotlinUsages {
                 chooseCandidateByName(KOTLIN_RUNTIME)
             }
 
+            val javaApiUsages = setOf(JAVA_API, "java-api-jars")
             val javaRuntimeUsages = setOf(JAVA_RUNTIME_JARS, JAVA_RUNTIME)
 
-            if (JAVA_API in candidateNames &&
+            if (javaApiUsages.any { it in candidateNames } &&
                 javaRuntimeUsages.any { it in candidateNames } &&
                 values.none { it in candidateNames }
             ) {
                 when (consumerValue?.name) {
-                    KOTLIN_API, JAVA_API ->
-                        chooseCandidateByName(JAVA_API)
+                    KOTLIN_API, in javaApiUsages ->
+                        chooseCandidateByName(javaApiUsages.first { it in candidateNames })
                     null, KOTLIN_RUNTIME, in javaRuntimeUsages ->
                         chooseCandidateByName(javaRuntimeUsages.first { it in candidateNames })
                 }

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/kotlinTargets.kt

@@ -98,11 +98,11 @@ abstract class AbstractKotlinTarget(
     private fun createUsageContexts(
         producingCompilation: KotlinCompilation<*>
     ): Set<DefaultKotlinUsageContext> {
-        // Here, `JAVA_API` and `JAVA_RUNTIME_JARS` are used intentionally as Gradle needs this for
+        // Here, the Java Usage values are used intentionally as Gradle needs this for
         // ordering of the usage contexts (prioritizing the dependencies) when merging them into the POM;
         // These Java usages should not be replaced with the custom Kotlin usages.
         return listOfNotNull(
-            JAVA_API to apiElementsConfigurationName,
+            javaApiUsageForMavenScoping() to apiElementsConfigurationName,
             (JAVA_RUNTIME_JARS to runtimeElementsConfigurationName).takeIf { producingCompilation is KotlinCompilationToRunnableFiles }
         ).mapTo(mutableSetOf()) { (usageName, dependenciesConfigurationName) ->
             DefaultKotlinUsageContext(
@@ -154,6 +154,13 @@ abstract class AbstractKotlinTarget(
 internal fun KotlinTarget.disambiguateName(simpleName: String) =
     lowerCamelCaseName(targetName, simpleName)
 
+internal fun javaApiUsageForMavenScoping() =
+    if (isGradleVersionAtLeast(5, 3)) {
+        "java-api-jars"
+    } else {
+        JAVA_API
+    }
+
 open class KotlinOnlyTarget<T : KotlinCompilation<*>>(
     project: Project,
     override val platformType: KotlinPlatformType

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/mppDependencyRewritingUtils.kt

@@ -90,13 +90,13 @@ private fun associateDependenciesWithActualModuleDependencies(
                 // TODO handle Android configuration names in a general way once we drop AGP < 3.0.0
                 val variantName = compilation.name
                 when (usageContext.usage.name) {
-                    Usage.JAVA_API -> variantName + "CompileClasspath"
+                    Usage.JAVA_API, "java-api-jars" -> variantName + "CompileClasspath"
                     Usage.JAVA_RUNTIME_JARS -> variantName + "RuntimeClasspath"
                     else -> error("Unexpected Usage for usage context: ${usageContext.usage}")
                 }
             }
             else -> when (usageContext.usage.name) {
-                Usage.JAVA_API -> compilation.compileDependencyConfigurationName
+                Usage.JAVA_API, "java-api-jars" -> compilation.compileDependencyConfigurationName
                 Usage.JAVA_RUNTIME_JARS -> (compilation as KotlinCompilationToRunnableFiles).runtimeDependencyConfigurationName
                 else -> error("Unexpected Usage for usage context: ${usageContext.usage}")
             }

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/targets/android/KotlinAndroidTarget.kt

@@ -9,7 +9,6 @@ package org.jetbrains.kotlin.gradle.plugin.mpp
 import org.gradle.api.InvalidUserDataException
 import org.gradle.api.NamedDomainObjectContainer
 import org.gradle.api.Project
-import org.gradle.api.attributes.Usage.JAVA_API
 import org.gradle.api.attributes.Usage.JAVA_RUNTIME_JARS
 import org.jetbrains.kotlin.gradle.plugin.*
 import org.jetbrains.kotlin.gradle.utils.dashSeparatedName
@@ -187,11 +186,11 @@ open class KotlinAndroidTarget(
         val apiElementsConfigurationName = lowerCamelCaseName(variantName, "apiElements")
         val runtimeElementsConfigurationName = lowerCamelCaseName(variantName, "runtimeElements")
 
-        // Here, `JAVA_API` and `JAVA_RUNTIME_JARS` are used intentionally as Gradle needs this for
+        // Here, the Java Usage values are used intentionally as Gradle needs this for
         // ordering of the usage contexts (prioritizing the dependencies) when merging them into the POM;
         // These Java usages should not be replaced with the custom Kotlin usages.
         return listOf(
-            apiElementsConfigurationName to JAVA_API,
+            apiElementsConfigurationName to javaApiUsageForMavenScoping(),
             runtimeElementsConfigurationName to JAVA_RUNTIME_JARS
         ).mapTo(mutableSetOf()) { (dependencyConfigurationName, usageName) ->
             DefaultKotlinUsageContext(
@@ -202,4 +201,4 @@ open class KotlinAndroidTarget(
             )
         }
     }
-}
+}