SOLR-16825: Generate v2 API SolrRequest bindings

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;