Extract analytics-api module for JDK 21 downstream consumers (opensearch-project#21574)

Creates sandbox/libs/analytics-api targeting JDK 21, containing only the
interface surface that downstream plugins (e.g. opensearch-sql) need to
compile against:

- org.opensearch.analytics.exec.QueryPlanExecutor (moved from analytics-framework)
- org.opensearch.analytics.schema.OpenSearchSchemaBuilder (moved from analytics-engine)

Motivation:

analytics-framework and analytics-engine use java.lang.foreign (FFM) APIs
that finalize only in JDK 22, so those modules must target JDK 25. Their
published Gradle Module Metadata declares org.gradle.jvm.version=25,
which blocks consumption from projects that target JVM 21 — most notably
opensearch-sql, which uses QueryPlanExecutor and OpenSearchSchemaBuilder
but does not touch FFM types.

Extracting these two interfaces into a JVM-21-targeted module unblocks
those consumers without forcing the whole sandbox to downgrade (FFM is
load-bearing for the engine).

Packages are unchanged (org.opensearch.analytics.{exec,schema}), so
existing imports in sandbox consumers (analytics-framework, analytics-engine,
dsl-query-executor, test-ppl-frontend) continue to resolve transitively
via the new `api project(':sandbox:libs:analytics-api')` edge in
analytics-framework/build.gradle.

thirdPartyAudit is disabled on analytics-api: it is a compile-time API
surface consumed transitively with the full Calcite runtime provided by
analytics-framework or analytics-engine, so there is no standalone runtime
where Calcite's optional references could load.

Verification:
- ./gradlew check -p sandbox -Dsandbox.enabled=true  (full sandbox check: BUILD SUCCESSFUL)
- analytics-api jar bytecode is class version 65 (JDK 21) as expected.
- Published Gradle Module Metadata declares org.gradle.jvm.version=21.
- Downstream sql prototype compiles against the new artifact from mavenLocal.

Signed-off-by: bowenlan-amzn <bowenlan23@gmail.com>

Author: bowenlan-amzn

sandbox/build.gradle

@@ -41,6 +41,7 @@ def patchedCalciteVersion = "${libVersions['calcite']}-opensearch-${libVersions[
 
 subprojects {
   group = 'org.opensearch.sandbox'
+  ext.patchedCalciteVersion = patchedCalciteVersion
 
   // The patched calcite-core / calcite-linq4j live in the OpenSearch
   // snapshots Maven repo; analytics-framework advertises them as `api`,

sandbox/libs/analytics-api/build.gradle

@@ -0,0 +1,30 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/*
+ * Analytics Engine API surface consumable from JDK 21 code paths.
+ */
+
+java { sourceCompatibility = JavaVersion.toVersion(21); targetCompatibility = JavaVersion.toVersion(21) }
+
+// no test for now, so disable
+testingConventions.enabled = false
+
+dependencies {
+  compileOnly project(':server')
+  // Declared compileOnly rather than api because analytics-api is never
+  // loaded standalone — downstream consumers should declare Calcite themselves.
+  compileOnly "org.apache.calcite:calcite-core:${patchedCalciteVersion}"
+  compileOnly "org.apache.calcite:calcite-linq4j:${patchedCalciteVersion}"
+
+  // Calcite bytecode references annotations from apiguardian (@API) and
+  // checker-framework (@EnsuresNonNullIf). compileOnlyApi propagates to
+  // consumers' compile/javadoc classpath without becoming a runtime dep.
+  compileOnlyApi 'org.apiguardian:apiguardian-api:1.1.2'
+  compileOnlyApi 'org.checkerframework:checker-qual:3.43.0'
+}

…ch/analytics/exec/QueryPlanExecutor.java …ch/analytics/exec/QueryPlanExecutor.javasandbox/libs/analytics-framework/src/main/java/org/opensearch/analytics/exec/QueryPlanExecutor.java renamed to sandbox/libs/analytics-api/src/main/java/org/opensearch/analytics/exec/QueryPlanExecutor.java sandbox/libs/analytics-framework/src/main/java/org/opensearch/analytics/exec/QueryPlanExecutor.java renamed to sandbox/libs/analytics-api/src/main/java/org/opensearch/analytics/exec/QueryPlanExecutor.java

@@ -16,8 +16,6 @@
 // for Janino parent CL); API surface is identical to upstream. The OpenSearch
 // Snapshots repo and the resolutionStrategy.force for this coordinate are
 // declared centrally in sandbox/build.gradle's subprojects block.
-def calciteVersion = "${versions.calcite}-opensearch-${versions.calcite_os_rev}"
-
 java { sourceCompatibility = JavaVersion.toVersion(25); targetCompatibility = JavaVersion.toVersion(25) }
 
 configurations {
@@ -39,9 +37,9 @@ dependencies {
   // interfaces declares its own runtime arrow dep (see analytics-backend-datafusion).
   compileOnly "org.apache.arrow:arrow-vector:${versions.arrow}"
   compileOnly "org.apache.arrow:arrow-memory-core:${versions.arrow}"
-  api "org.apache.calcite:calcite-core:${calciteVersion}"
+  api "org.apache.calcite:calcite-core:${patchedCalciteVersion}"
   // Calcite's expression tree and Enumerable runtime — required by calcite-core API
-  api "org.apache.calcite:calcite-linq4j:${calciteVersion}"
+  api "org.apache.calcite:calcite-linq4j:${patchedCalciteVersion}"
   // Calcite's JDBC abstraction layer — required by calcite-core internals
   runtimeOnly 'org.apache.calcite.avatica:avatica-core:1.27.0'
   // Guava — required by Calcite internally, forbidden on compile classpaths by OpenSearch policy

…nsearch/analytics/exec/package-info.java …nsearch/analytics/exec/package-info.javasandbox/libs/analytics-framework/src/main/java/org/opensearch/analytics/exec/package-info.java renamed to sandbox/libs/analytics-api/src/main/java/org/opensearch/analytics/exec/package-info.java sandbox/libs/analytics-framework/src/main/java/org/opensearch/analytics/exec/package-info.java renamed to sandbox/libs/analytics-api/src/main/java/org/opensearch/analytics/exec/package-info.java

@@ -45,8 +45,9 @@ tasks.named('missingJavadoc').configure {
 }
 
 dependencies {
-  // Shared types and SPI interfaces (QueryPlanExecutor, EngineBridge, AnalyticsBackEndPlugin, etc.)
-  // Also provides calcite-core transitively via api.
+  implementation project(':sandbox:libs:analytics-api')
+
+  // Shared SPI interfaces (EngineBridge, AnalyticsBackEndPlugin, etc.) + calcite-core transitively.
   api project(':sandbox:libs:analytics-framework')
 
   // Arrow — provided at runtime by the extended arrow-flight-rpc plugin (same classloader).

…tics/schema/OpenSearchSchemaBuilder.java …tics/schema/OpenSearchSchemaBuilder.javasandbox/plugins/analytics-engine/src/main/java/org/opensearch/analytics/schema/OpenSearchSchemaBuilder.java renamed to sandbox/libs/analytics-api/src/main/java/org/opensearch/analytics/schema/OpenSearchSchemaBuilder.java sandbox/plugins/analytics-engine/src/main/java/org/opensearch/analytics/schema/OpenSearchSchemaBuilder.java renamed to sandbox/libs/analytics-api/src/main/java/org/opensearch/analytics/schema/OpenSearchSchemaBuilder.java

@@ -29,6 +29,7 @@ sourceSets.test.compileClasspath += configurations.calciteCompile
 
 dependencies {
   compileOnly project(':server')
+  compileOnly project(':sandbox:libs:analytics-api')
   compileOnly project(':sandbox:libs:analytics-framework')
   compileOnly project(':sandbox:plugins:analytics-engine')
   // TODO: Consume Calcite dependency from Analytics Framework instead of declaring it separately.

…earch/analytics/schema/package-info.java …earch/analytics/schema/package-info.javasandbox/plugins/analytics-engine/src/main/java/org/opensearch/analytics/schema/package-info.java renamed to sandbox/libs/analytics-api/src/main/java/org/opensearch/analytics/schema/package-info.java sandbox/plugins/analytics-engine/src/main/java/org/opensearch/analytics/schema/package-info.java renamed to sandbox/libs/analytics-api/src/main/java/org/opensearch/analytics/schema/package-info.java

@@ -52,6 +52,7 @@ sourceSets.test.compileClasspath += configurations.calciteCompile
 
 dependencies {
   // Analytics framework + Calcite provided at runtime by analytics-engine (parent classloader via extendedPlugins)
+  compileOnly project(':sandbox:libs:analytics-api')
   compileOnly project(':sandbox:libs:analytics-framework')
 
   // Guava for compilation — Calcite API exposes guava types