SOLR-16395: Convert v2 "schema" modification APIs to JAX-RS

dev-docs/v2-api-conventions.adoc

@@ -103,3 +103,39 @@ Please use the following conventions when implementing similar endpoints:
 2. Interface methods should return a type that implements the JAX-RS `StreamingOutput` interface.
 
 See the `fetchFile()` method in `ReplicationApis.java` for a concrete example.
+
+== Dynamic and Partially-Dynamic Request POJOs
+
+Many Solr APIs have a request body that is fully dynamic or open-ended, with users able to specify any property name and value.
+In these cases, the request-body should be represented in JAX-RS by using a map: typically a `Map<String,Object>`.
+
+Slightly more difficult are cases where the request-body allows dynamic/open-ended fields, but also has some fields that are known statically.
+In these cases, developers may:
+1. Represent the request-body using a POJO class.  The "known" fields can be annotated with `@JsonProperty` as in standard POJOs.  Dynamic fields can be allowed using Jackson's `@JsonAnyGetter` and `@JsonAnySetter` annotations as below:
++
+```
+  private Map<String, Object> additionalProperties = new HashMap<>();
+
+  @JsonAnyGetter
+  public Map<String, Object> getAdditionalProperties() {
+    return additionalProperties;
+  }
+
+  @JsonAnySetter
+  public void setAdditionalProperty(String field, Object value) {
+    additionalProperties.put(field, value);
+  }
+```
+2. Annotate the request-body parameter with the `ADDTL_FIELDS_PROPERTY` Swagger extension when declaring the request body.  This tells our code-generation templates that the request-body takes additional properties the setters should be generated for.
++
+```
+  SolrJerseyResponse addField(
+      @PathParam("fieldName") String fieldName,
+      @RequestBody(
+              extensions = {
+                @Extension(
+                    properties = {@ExtensionProperty(name = ADDTL_FIELDS_PROPERTY, value = "true")})
+              })
+          AddFieldOperation requestBody)
+      throws Exception;
+```

solr/api/build.gradle

@@ -70,7 +70,10 @@ dependencies {
 
     testImplementation project(':solr:test-framework')
     testImplementation project(':solr:api')
+    testImplementation libs.junit.junit
+    testImplementation libs.hamcrest.hamcrest
     testImplementation libs.apache.lucene.testframework
+    testImplementation libs.fasterxml.jackson.core.databind
 
     swaggerBuild libs.swagger3.jaxrs2.jakarta
 }

solr/api/gradle.lockfile

@@ -6,9 +6,9 @@ com.carrotsearch:hppc:0.10.0=jarValidation,testRuntimeClasspath
 com.fasterxml.jackson.core:jackson-annotations:2.16.2=swaggerDeps
 com.fasterxml.jackson.core:jackson-annotations:2.18.2=apiHelper,compileClasspath,jarValidation,runtimeClasspath,swaggerBuild,testCompileClasspath,testRuntimeClasspath
 com.fasterxml.jackson.core:jackson-core:2.16.2=swaggerDeps
-com.fasterxml.jackson.core:jackson-core:2.18.2=jarValidation,swaggerBuild,testRuntimeClasspath
+com.fasterxml.jackson.core:jackson-core:2.18.2=jarValidation,swaggerBuild,testCompileClasspath,testRuntimeClasspath
 com.fasterxml.jackson.core:jackson-databind:2.16.2=swaggerDeps
-com.fasterxml.jackson.core:jackson-databind:2.18.2=jarValidation,swaggerBuild,testRuntimeClasspath
+com.fasterxml.jackson.core:jackson-databind:2.18.2=jarValidation,swaggerBuild,testCompileClasspath,testRuntimeClasspath
 com.fasterxml.jackson.dataformat:jackson-dataformat-cbor:2.18.2=jarValidation,testRuntimeClasspath
 com.fasterxml.jackson.dataformat:jackson-dataformat-smile:2.18.2=jarValidation,testRuntimeClasspath
 com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.16.2=swaggerDeps

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

@@ -0,0 +1,142 @@
+/*
+ * 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.ADDTL_FIELDS_PROPERTY;
+import static org.apache.solr.client.api.util.Constants.INDEX_PATH_PREFIX;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.extensions.Extension;
+import io.swagger.v3.oas.annotations.extensions.ExtensionProperty;
+import io.swagger.v3.oas.annotations.parameters.RequestBody;
+import jakarta.ws.rs.DELETE;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import java.util.List;
+import org.apache.solr.client.api.model.SchemaChange;
+import org.apache.solr.client.api.model.SolrJerseyResponse;
+import org.apache.solr.client.api.model.UpsertDynamicFieldOperation;
+import org.apache.solr.client.api.model.UpsertFieldOperation;
+import org.apache.solr.client.api.model.UpsertFieldTypeOperation;
+import org.apache.solr.client.api.util.StoreApiParameters;
+
+@Path(INDEX_PATH_PREFIX + "/schema")
+public interface UpdateSchemaApi {
+  @PUT
+  @Path("/fields/{fieldName}")
+  @StoreApiParameters
+  @Operation(
+      summary = "Add a standard (i.e. non-dynamic) field with the specified name.",
+      tags = {"schema"})
+  SolrJerseyResponse addField(
+      @PathParam("fieldName") String fieldName,
+      @RequestBody(
+              extensions = {
+                @Extension(
+                    properties = {@ExtensionProperty(name = ADDTL_FIELDS_PROPERTY, value = "true")})
+              })
+          UpsertFieldOperation requestBody)
+      throws Exception;
+
+  @DELETE
+  @Path("/fields/{fieldName}")
+  @StoreApiParameters
+  @Operation(
+      summary = "Remove the non-dynamic field with the specified name.",
+      tags = {"schema"})
+  SolrJerseyResponse deleteField(@PathParam("fieldName") String fieldName) throws Exception;
+
+  @PUT
+  @Path("/dynamicfields/{dynamicFieldName}")
+  @StoreApiParameters
+  @Operation(
+      summary = "Create a new dynamic field with the specified name.",
+      tags = {"schema"})
+  SolrJerseyResponse addDynamicField(
+      @PathParam("dynamicFieldName") String dynamicFieldName,
+      @RequestBody(
+              extensions = {
+                @Extension(
+                    properties = {@ExtensionProperty(name = ADDTL_FIELDS_PROPERTY, value = "true")})
+              })
+          UpsertDynamicFieldOperation requestBody)
+      throws Exception;
+
+  @DELETE
+  @Path("/dynamicfields/{dynamicFieldName}")
+  @StoreApiParameters
+  @Operation(
+      summary = "Remove the dynamic field with the specified name.",
+      tags = {"schema"})
+  SolrJerseyResponse deleteDynamicField(@PathParam("dynamicFieldName") String dynamicFieldName)
+      throws Exception;
+
+  @PUT
+  @Path("/fieldtypes/{fieldTypeName}")
+  @StoreApiParameters
+  @Operation(
+      summary = "Add a new field-type with the specified name.",
+      tags = {"schema"})
+  SolrJerseyResponse addFieldType(
+      @PathParam("fieldTypeName") String fieldTypeName,
+      @RequestBody(
+              extensions = {
+                @Extension(
+                    properties = {@ExtensionProperty(name = ADDTL_FIELDS_PROPERTY, value = "true")})
+              })
+          UpsertFieldTypeOperation requestBody)
+      throws Exception;
+
+  @DELETE
+  @Path("/fieldtypes/{fieldTypeName}")
+  @StoreApiParameters
+  @Operation(
+      summary = "Remove the field type with the specified name.",
+      tags = {"schema"})
+  SolrJerseyResponse deleteFieldType(@PathParam("fieldTypeName") String fieldTypeName)
+      throws Exception;
+
+  // TODO Gah! Copyfields don't currently have names for us to create/delete by name in an API like
+  // /schema/copyfields/{copyFieldName}...figure out how to address this in a way consistent with
+  // all our other APIs.  (In the meantime, the functionality is exposed through the bulk API at
+  // least.
+  //    @POST
+  //    @Path("/copyfields/{copyFieldName}")
+  //    @StoreApiParameters
+  //    @Operation(
+  //            summary = "Add a new copy-field with the specified name.",
+  //            tags = {"schema"})
+  //    SolrJerseyResponse addCopyField(@PathParam("copyFieldName") String copyFieldName,
+  // @RequestBody SchemaChangeOperation.AddCopyField requestBody) throws Exception;
+  //
+  //    @DELETE
+  //    @Path("/copyfields/{copyFieldName}")
+  //    @StoreApiParameters
+  //    @Operation(summary = "Remove the copy-field with the specified name.", tags = {"schema"})
+  //    SolrJerseyResponse deleteCopyField(@PathParam("copyFieldName") String copyFieldName) throws
+  // Exception;
+
+  @POST
+  @Path("/bulk")
+  @StoreApiParameters
+  @Operation(
+      summary = "Perform the specified schema modifications.",
+      tags = {"schema"})
+  SolrJerseyResponse bulkSchemaModification(List<SchemaChange> requestBody) throws Exception;
+}

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

@@ -0,0 +1,32 @@
+/*
+ * 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.JsonAlias;
+import com.fasterxml.jackson.annotation.JsonFormat;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.List;
+
+public class AddCopyFieldOperation extends SchemaChange {
+  @JsonProperty public String source;
+
+  @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
+  @JsonAlias("dest")
+  public List<String> destinations;
+
+  @JsonProperty public Integer maxChars;
+}

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

@@ -0,0 +1,30 @@
+/*
+ * 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.JsonAlias;
+import com.fasterxml.jackson.annotation.JsonFormat;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.List;
+
+public class DeleteCopyFieldOperation extends SchemaChange {
+  @JsonProperty public String source;
+
+  @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
+  @JsonAlias("dest")
+  public List<String> destinations;
+}

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

@@ -0,0 +1,23 @@
+/*
+ * 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;
+
+public class DeleteDynamicFieldOperation extends SchemaChange {
+  @JsonProperty public String name;
+}

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

@@ -0,0 +1,23 @@
+/*
+ * 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;
+
+public class DeleteFieldOperation extends SchemaChange {
+  @JsonProperty public String name;
+}

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

@@ -0,0 +1,23 @@
+/*
+ * 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;
+
+public class DeleteFieldTypeOperation extends SchemaChange {
+  @JsonProperty public String name;
+}

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

@@ -0,0 +1,52 @@
+/*
+ * 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 com.fasterxml.jackson.annotation.JsonSubTypes;
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import com.fasterxml.jackson.annotation.OptBoolean;
+
+/** Modifications that can be made to elements of a schema, either individually or in bulk. */
+@JsonTypeInfo(
+    use = JsonTypeInfo.Id.NAME,
+    property = SchemaChange.OPERATION_TYPE_PROP,
+    requireTypeIdForSubtypes = OptBoolean.FALSE,
+    visible = true)
+@JsonSubTypes({
+  @JsonSubTypes.Type(
+      value = UpsertFieldTypeOperation.class,
+      names = {"add-field-type", "replace-field-type"}),
+  @JsonSubTypes.Type(
+      value = UpsertFieldOperation.class,
+      names = {"add-field", "replace-field"}),
+  @JsonSubTypes.Type(
+      value = UpsertDynamicFieldOperation.class,
+      names = {"add-dynamic-field", "replace-dynamic-field"}),
+  @JsonSubTypes.Type(value = DeleteFieldTypeOperation.class, name = "delete-field-type"),
+  @JsonSubTypes.Type(value = DeleteFieldOperation.class, name = "delete-field"),
+  @JsonSubTypes.Type(value = DeleteDynamicFieldOperation.class, name = "delete-dynamic-field"),
+  @JsonSubTypes.Type(value = AddCopyFieldOperation.class, name = "add-copy-field"),
+  @JsonSubTypes.Type(value = DeleteCopyFieldOperation.class, name = "delete-copy-field"),
+})
+public class SchemaChange {
+
+  public static final String OPERATION_TYPE_PROP = "operationType";
+
+  @JsonProperty(OPERATION_TYPE_PROP)
+  public String operationType;
+}