SOLR-16825: Generate v2 API SolrRequest bindings (apache#1793)

Prior to this commit, SolrJ had no real coverage of v2 APIs beyond the
generic V2Request class.  This commit introduces the first request-
specific v2 SolrRequest implementations to SolrJ.

Rather than duplicating details about the API here in SolrJ so that both
the server-side API definition and the client objects need maintained
by hand, this commit generates the v2 SolrRequest classes from the
OpenAPI specification (which in turn is generated from the server-side
API definition).  This ensures that there's only one "source of truth"
that needs maintained for each API.

To achieve this, this commit introduces a new gradle module, 'api', to
hold interfaces (representing Solr's APIs) and POJOs (representing the
API's inputs and outputs).  This module is all that is needed to generate
Solr's OpenAPI spec, and for SolrJ in turn to generate SolrRequest
implementations from that spec.

This commit restricts v2 SolrRequest generation to a few example APIs
to prove the approach.  Additional APIs will be added in subsequent
commits.

---------

Co-authored-by: Houston Putman <[email protected]>

dev-tools/scripts/smokeTestRelease.py

@@ -606,7 +606,7 @@ def verifyUnpacked(java, artifact, unpackPath, gitRevision, version, testArgs):
     expected_src_root_folders = ['buildSrc', 'dev-docs', 'dev-tools', 'gradle', 'help', 'solr']
     expected_src_root_files = ['build.gradle', 'gradlew', 'gradlew.bat', 'settings.gradle', 'versions.lock', 'versions.props']
     expected_src_solr_files = ['build.gradle']
-    expected_src_solr_folders = ['benchmark',  'bin', 'modules', 'core', 'docker', 'documentation', 'example', 'licenses', 'packaging', 'distribution', 'prometheus-exporter', 'server', 'solr-ref-guide', 'solrj', 'solrj-streaming', 'solrj-zookeeper', 'test-framework', 'webapp', '.gitignore', '.gitattributes']
+    expected_src_solr_folders = ['benchmark',  'bin', 'modules', 'api', 'core', 'docker', 'documentation', 'example', 'licenses', 'packaging', 'distribution', 'prometheus-exporter', 'server', 'solr-ref-guide', 'solrj', 'solrj-streaming', 'solrj-zookeeper', 'test-framework', 'webapp', '.gitignore', '.gitattributes']
     is_in_list(in_root_folder, expected_src_root_folders)
     is_in_list(in_root_folder, expected_src_root_files)
     is_in_list(in_solr_folder, expected_src_solr_folders)

gradle/maven/defaults-maven.gradle

@@ -24,6 +24,7 @@
 configure(rootProject) {
   ext {
     published = [
+        ":solr:api",
         ":solr:core",
         ":solr:solrj",
         ":solr:solrj-streaming",

gradle/solr/packaging.gradle

@@ -58,6 +58,7 @@ configure(allprojects.findAll {project -> project.path.startsWith(":solr:modules
     dependencies {
       solrPlatformLibs project(":solr:core")
       solrPlatformLibs project(":solr:solrj")
+      solrPlatformLibs project(":solr:api")
       solrPlatformLibs project(":solr:solrj-zookeeper")
       // libExt has logging libs, which we don't want.  Lets users decide what they want.
       solrPlatformLibs project(path: ":solr:server", configuration: 'libExt')

gradle/validation/spotless.gradle

@@ -26,18 +26,32 @@ configure(project(":solr").subprojects) { prj ->
   plugins.withType(JavaPlugin) {
     prj.apply plugin: 'com.diffplug.spotless'
 
-    spotless {
-      java {
-        toggleOffOn() // obviously, only to be used sparingly.
+    ext {
+      spotlessJavaSetup = (Action){
+        it.toggleOffOn() // obviously, only to be used sparingly.
         // TODO: Work out how to support multiple different header files (we have
         // classes in the codebase that have original headers). We currently use
         // Apache RAT to enforce headers so this is of lesser priority.
         //
-        // licenseHeaderFile file("${resources}/asl-header.txt"), '^(\\s*package)'
+        // it.licenseHeaderFile(file("${resources}/asl-header.txt"), '^(\\s*package)')
+        it.setLineEndings(Enum.valueOf(rootProject.buildscript.classLoader.loadClass("com.diffplug.spotless.LineEnding"), "UNIX"))
+        it.endWithNewline()
+        it.googleJavaFormat('1.15.0')
 
-        lineEndings 'UNIX'
-        endWithNewline()
-        googleJavaFormat('1.15.0')
+        it.custom('Refuse wildcard imports', { line ->
+          // Wildcard imports can't be resolved by spotless itself.
+          // This will require the developer themselves to adhere to best practices.
+          if (line =~ /\nimport .*\*;/) {
+            throw new AssertionError("Do not use wildcard imports.  'spotlessApply' cannot resolve this issue.")
+          }
+          line
+        })
+      }
+    }
+
+    spotless {
+      java {
+        prj.ext.spotlessJavaSetup.execute(it)
 
         // Apply to all Java sources
         target "src/**/*.java"
@@ -62,14 +76,6 @@ configure(project(":solr").subprojects) { prj ->
             target "modules/**/examples/*.java"
             break
         }
-
-        custom 'Refuse wildcard imports', {
-          // Wildcard imports can't be resolved by spotless itself.
-          // This will require the developer themselves to adhere to best practices.
-          if (it =~ /\nimport .*\*;/) {
-            throw new AssertionError("Do not use wildcard imports.  'spotlessApply' cannot resolve this issue.")
-          }
-        }
       }
     }
 

settings.gradle

@@ -26,6 +26,7 @@ rootProject.name = "solr-root"
 
 includeBuild("dev-tools/solr-missing-doclet")
 
+include "solr:api"
 include "solr:solrj"
 include "solr:solrj-zookeeper"
 include "solr:solrj-streaming"

solr/CHANGES.txt

@@ -84,6 +84,11 @@ Improvements
   a HTTP 503 status. Switched to 510 so that CloudSolrClient will auto-retry it and probably succeed.
   (David Smiley, Alex Deparvu)
 
+* SOLR-16825: Solr now offers `SolrRequest` implementations for a subset of its v2 APIs.  These implementations
+  are experimental and should be used with caution, but may be preferable to their v1 counterparts in some
+  circumstances as they are generated and more likely to remain up-to-date with future API changes.
+  (Jason Gerlowski, David Smiley, Houston Putman)
+
 Optimizations
 ---------------------
 

solr/api/build.gradle

@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+plugins {
+  id 'io.swagger.core.v3.swagger-gradle-plugin' version '2.2.2'
+}
+
+apply plugin: 'java-library'
+
+description = 'API - Interfaces and classes used to represent Solrs APIs'
+
+ext {
+    openApiSpecDir = "${buildDir}/generated/openapi"
+    openApiSpecFile = "${project.openApiSpecDir}/openapi.json"
+}
+
+configurations {
+    openapiSpec {
+        canBeConsumed = true
+        canBeResolved = false
+    }
+}
+
+resolve {
+  classpath = sourceSets.main.runtimeClasspath
+  outputDir = file(project.openApiSpecDir)
+  prettyPrint = true
+}
+
+dependencies {
+    runtimeOnly 'org.slf4j:slf4j-api'
+
+    implementation 'jakarta.ws.rs:jakarta.ws.rs-api'
+    implementation 'com.fasterxml.jackson.core:jackson-annotations'
+    api 'io.swagger.core.v3:swagger-annotations'
+    implementation 'org.semver4j:semver4j'
+
+    testImplementation project(':solr:test-framework')
+    testImplementation project(':solr:api')
+    testImplementation 'org.apache.lucene:lucene-test-framework'
+}
+
+artifacts {
+    openapiSpec resolve.outputDir, {
+        builtBy resolve
+    }
+}

solr/api/src/java/org/apache/solr/client/api/endpoint/AddReplicaPropertyApi.java

@@ -0,0 +1,60 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.solr.client.api.endpoint;
+
+import static org.apache.solr.client.api.util.Constants.BINARY_CONTENT_TYPE_V2;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.parameters.RequestBody;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import org.apache.solr.client.api.model.AddReplicaPropertyRequestBody;
+import org.apache.solr.client.api.model.SolrJerseyResponse;
+
+@Path("/collections/{collName}/shards/{shardName}/replicas/{replicaName}/properties/{propName}")
+public interface AddReplicaPropertyApi {
+
+  @PUT
+  @Produces({"application/json", "application/xml", BINARY_CONTENT_TYPE_V2})
+  @Operation(
+      summary = "Adds a property to the specified replica",
+      tags = {"replicas"})
+  public SolrJerseyResponse addReplicaProperty(
+      @Parameter(
+              description = "The name of the collection the replica belongs to.",
+              required = true)
+          @PathParam("collName")
+          String collName,
+      @Parameter(description = "The name of the shard the replica belongs to.", required = true)
+          @PathParam("shardName")
+          String shardName,
+      @Parameter(description = "The replica, e.g., `core_node1`.", required = true)
+          @PathParam("replicaName")
+          String replicaName,
+      @Parameter(description = "The name of the property to add.", required = true)
+          @PathParam("propName")
+          String propertyName,
+      @RequestBody(
+              description = "The value of the replica property to create or update",
+              required = true)
+          AddReplicaPropertyRequestBody requestBody)
+      throws Exception;
+}

solr/api/src/java/org/apache/solr/client/api/endpoint/DeleteAliasApi.java

@@ -0,0 +1,45 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.solr.client.api.endpoint;
+
+import static org.apache.solr.client.api.util.Constants.BINARY_CONTENT_TYPE_V2;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import org.apache.solr.client.api.model.SolrJerseyResponse;
+
+@Path("/aliases/{aliasName}")
+public interface DeleteAliasApi {
+
+  @DELETE
+  @Produces({"application/json", "application/xml", BINARY_CONTENT_TYPE_V2})
+  @Operation(
+      summary = "Deletes an alias by its name",
+      tags = {"aliases"})
+  SolrJerseyResponse deleteAlias(
+      @Parameter(description = "The name of the alias to delete", required = true)
+          @PathParam("aliasName")
+          String aliasName,
+      @QueryParam("async") String asyncId)
+      throws Exception;
+}

solr/api/src/java/org/apache/solr/client/api/endpoint/DeleteCollectionApi.java

@@ -0,0 +1,47 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.solr.client.api.endpoint;
+
+import static org.apache.solr.client.api.util.Constants.BINARY_CONTENT_TYPE_V2;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import org.apache.solr.client.api.model.SubResponseAccumulatingJerseyResponse;
+
+@Path("/collections/{collectionName}")
+public interface DeleteCollectionApi {
+
+  @DELETE
+  @Produces({"application/json", "application/xml", BINARY_CONTENT_TYPE_V2})
+  @Operation(
+      summary = "Deletes a collection from SolrCloud",
+      tags = {"collections"})
+  SubResponseAccumulatingJerseyResponse deleteCollection(
+      @Parameter(description = "The name of the collection to be deleted.", required = true)
+          @PathParam("collectionName")
+          String collectionName,
+      @QueryParam("followAliases") Boolean followAliases,
+      @Parameter(description = "An ID to track the request asynchronously") @QueryParam("async")
+          String asyncId)
+      throws Exception;
+}

solr/api/src/java/org/apache/solr/client/api/endpoint/package-info.java

@@ -0,0 +1,19 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** Interfaces representing individual Solr v2 APIs. */
+package org.apache.solr.client.api.endpoint;

solr/api/src/java/org/apache/solr/client/api/model/AddReplicaPropertyRequestBody.java

@@ -0,0 +1,41 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.solr.client.api.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.apache.solr.client.api.util.ReflectWritable;
+
+public class AddReplicaPropertyRequestBody implements ReflectWritable {
+  public AddReplicaPropertyRequestBody() {}
+
+  public AddReplicaPropertyRequestBody(String value) {
+    this.value = value;
+  }
+
+  @Schema(description = "The value to assign to the property.", required = true)
+  @JsonProperty("value")
+  public String value;
+
+  @Schema(
+      description =
+          "If `true`, then setting this property in one replica will remove the property from all other replicas in that shard. The default is `false`.\\nThere is one pre-defined property `preferredLeader` for which `shardUnique` is forced to `true` and an error returned if `shardUnique` is explicitly set to `false`.",
+      defaultValue = "false")
+  @JsonProperty("shardUnique")
+  public Boolean shardUnique;
+}

solr/core/src/java/org/apache/solr/jersey/AsyncJerseyResponse.java → solr/api/src/java/org/apache/solr/client/api/model/AsyncJerseyResponse.java

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 
-package org.apache.solr.jersey;
+package org.apache.solr.client.api.model;
 
 import com.fasterxml.jackson.annotation.JsonProperty;