SOLR-18248 : Migration of Tasks V2 APIs to JAX-RS Constructs by jaykay12 · Pull Request #4452 · apache/solr

jaykay12 · 2026-05-19T20:09:07Z

https://issues.apache.org/jira/browse/SOLR-18248

Description

Migrating 2 out of the 3 V2 APIs of Tasks, from existing homegrown annotations to JAX-RS Standard constructs & annotations

List Tasks API
Task Status API

Solution

Have exposed 1 new interface: ListActiveTasksApi which serves the /lists/task as well as /list/task/<taskId> endpoints.
ListActiveTasks is the main class which takes on the responsibility for v2 path as well as also for the v1 api path via ActiveTasksListHandler
2 new DTO for List Task API
1 new DTO for Task Status API
Removed the now deprecated files: ListActiveTasksAPI & ActiveTasksListComponent from the codebase.

No Coding Agent used.

Tests

Please describe the tests you've developed or run to confirm this patch implements the feature or solves the problem.

Checklist

Please review the following and check all that apply:

I have reviewed the guidelines for How to Contribute and my code conforms to the standards described there to the best of my ability.
I have created a Jira issue and added the issue ID to my pull request title.
I have given Solr maintainers access to contribute to my PR branch. (optional but recommended, not available for branches on forks living under an organisation)
I have developed this patch against the main branch.
I have run ./gradlew check.
I have added tests for my changes.
I have added documentation for the Reference Guide
I have added a changelog entry for my change

epugh · 2026-05-19T21:11:15Z

+
+import static org.apache.solr.client.api.util.Constants.INDEX_PATH_PREFIX;
+
+@Path(INDEX_PATH_PREFIX + "/tasks/listjalaz")


;-) Look slike you have some debugging?

yeah, started with firstly wiring this api to give any random response, & now using this to compare my V2 response with the original V2 response, 😄 thus, kept a different api endpoint for now to do response comparision.

will surely update this during self-review before raising for formal review 💯

epugh

Thanks for getting started on this, I went ahead and put some comments in that may be too early to be added ;-)

epugh · 2026-05-19T21:12:13Z

+  @GET
+  @StoreApiParameters
+  @Operation(
+      summary = "Lists all the currently running tasks or status of any taskUUID being passed as queryParam",


So, I think we would revamp this api... if you look at the desired api, ListActiveTasks would just list all tasks. If you wanted a specfific task, then it would be a idfferent end point with a /taskUUID.

yes, have updated this Api class for now, handling the taskUUID as a path param now, it was queryParam in the V1 as well as homegrown v2.

epugh · 2026-05-19T21:13:04Z

+
+public class ListActiveTaskResponse extends SolrJerseyResponse {
+  @JsonProperty
+  public Map<String, String> taskList;


We are trying to move to more strongly typed responses so taht we don't have Map everywhere. Go ahead and specify out the return properties!

Yes, have done so.

epugh · 2026-05-19T21:17:40Z

+
+  }
+
+  private void handleStandAloneMode(ListActiveTaskResponse response, String taskUUID) {


One thing we are trying to do is move the V1 API logic into the V2 code base, and have the V1 call the V2 version, this way, as these apis evolve, we know that v1 and v2 stay in sync till we get rid of V1. I believe that ideally we would want ActiveTasksListComponent to delegate to the same code as this V2 api. Now, maybe it's so simple that both can just call core getCancellableQueryTracker().getActiveQueriesGenerated. In other V2 apis, you can see the code live in the V2 and then V1 calls it...

understood this part, have made suitable changes.

epugh · 2026-05-19T21:18:23Z

+        log.debug("solr cloud");
+      }
+      handleSolrCloudMode(response, taskUUID);
+    } else {


not quite sure I see the differences in the two paths yet?

yea, i am also checking this up.
I have tested this endpoint by running on cloud example which we have in examples, it worked fine. It should work fine for standalone as well, will remove the current conditional branching done once that's verified.

jaykay12 · 2026-05-19T22:50:58Z

Thanks for getting started on this, I went ahead and put some comments in that may be too early to be added ;-)

thank you so much @epugh for the prompt reviews & initial guidance, much appreciated.

I will keep addressing your comments as we go, I kept this PR as draft for now as per our community guidelines, but yea thanks again for reviewing this at such initial state, so that i can course correct myself promptly. ✨

jaykay12

self review ✅
tests added ✅

epugh

Good progress. There are definitly some changes to make this more restful, and to reuse our SolrJ methods in the tests. This appears to currently focus on listing of tasks and status of a single task, I don't see cancellation supported. That's just fine, we can do that one in a seperate PR!

epugh · 2026-05-27T21:42:54Z

+import org.apache.solr.client.api.util.StoreApiParameters;
+
+@Path(INDEX_PATH_PREFIX + "/tasks/list")
+public interface ListActiveTasksApi {


I am looking at the org.apache.solr.client.api.endpoint.ConfigSetsApi and liking it's pattern a bit better. I'll try and provide some detailed feedback! I think there is an opportunity to have line 30 be /tasks

took reference of the ConfigSetsApi, & have changed the contracts accordingly.

epugh · 2026-05-27T21:43:33Z

+@Path(INDEX_PATH_PREFIX + "/tasks/list")
+public interface ListActiveTasksApi {
+
+  // Handles: .../tasks/list (Lists all)


i don't think we need this comment.

have removed this.

epugh · 2026-05-27T21:44:10Z

+import org.apache.solr.client.api.model.TaskStatusResponse;
+import org.apache.solr.client.api.util.StoreApiParameters;
+
+@Path(INDEX_PATH_PREFIX + "/tasks/list")


if the path here is /tasks then we don't need the /list, as the pattern is GET /tasks will list all the tasks. This is more restful.

understood, have addressed.

epugh · 2026-05-27T21:44:24Z

+import org.apache.solr.client.api.util.StoreApiParameters;
+
+@Path(INDEX_PATH_PREFIX + "/tasks/list")
+public interface ListActiveTasksApi {


Maybe this is TasksApi ?

yes, makes sense. have addressed this.

epugh · 2026-05-27T21:46:06Z

+      tags = {"tasks"})
+  ListActiveTaskResponse listAllActiveTasks() throws Exception;
+
+  // Handles: .../tasks/list/slow-task-id (Lists specific)


i don't think we need this comment, and I think this should be GET /tasks/taskId

done., comment removed. GET endpoint updated.

epugh · 2026-05-27T21:50:21Z

I am expecting a DELETE /tasks/{taskId} for cancelling a running task. Or... we need a PATCH that does the cancel PATCH /tasks/{taskId}/cancel

yes, in this PR scope, #4452 (comment) took only 2 out of 3 API related to Tasks.

Cancel Running task API migration will be a follow-up, independent PR of itself.

Awesome! Smart!

epugh · 2026-05-27T21:55:45Z

+  public ActiveTaskDetails() {}
+
+  public ActiveTaskDetails(String taskUUID, String taskQuery) {
+    this.taskUUID = taskUUID;


you know, maybe we just keep taskUUID for now... just to reduce churn. Even though I don't like it as a name.

have addressed this.

epugh · 2026-05-27T21:57:44Z

+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class TaskStatusResponse extends SolrJerseyResponse {
+  @JsonProperty public String taskStatus;


maybe an oppotunity to use an enum for the various taskStatus????

also, I am getting the feeling that taskStatus isnt' actually a good format as currently defined. I looked int he docs: { "responseHeader":{ "status":0, "QTime":16}, "taskStatus":"id:5, status: active"}
and at a minimum, it should just be:

{ "responseHeader":{ "status":0, "QTime":16}, "taskStatus":"active"}

because we already know the id. Now, if we are listing, we should have something like:

{ "responseHeader":{ "status":0, "QTime":16}, "tasks":[ "taskId":"5", "status":"active"} ] }

maybe an oppotunity to use an enum for the various taskStatus????

yes, thanks. have made taskStatus as enum.

Now, if we are listing, we should have something like:

we are not returning list, in case of getTaskStatus API, its taskId & the status in String format in v1 API, in V2 we will be returning just the taskStatus enum.

epugh · 2026-05-27T22:13:36Z

+    params.set("taskUUID", "5");
+
+    var request =
+        new GenericSolrRequest(


When I see GSR, generally that is an opportunity for us to use our SolrJ generated API instead. This gets us testing of the SolrJ response code for free!

i added these 2 extra tests over here, since i felt earlier added assertions were not adequate enough. They were not covering GetStatusTaskAPI fully.

This test validates for the v1 api flow though, is what i feel.

epugh · 2026-05-27T22:14:35Z

+
+  @Test
+  public void testCheckSpecificQueryStatus_Inactive() throws Exception {
+    for (int i = 0; i < 10; i++) {


why do we need to execute 10 of these? Seems like a magic number!

not a magic number, i am just executing 10 queries during test & since each query gets fired with their index as taskID, so i am simply asserting for any taskId=5 which should be active since it is <10 & asserting for taskId=15, which should be inactive since its outside the range.

this number can be anything, should i keep this lower, like 2 or 3?

jaykay12

self-reviewed ✅
comments addressed ✅

epugh

Some great progress, I think we are getting closer.

One question, have you been able to fire up Solr and test these apis manually? I have a slight fear that the overall Task Management API might not be working at all ;-(. It would be nice to confirm in a running Solr that yes, this is all working.

epugh · 2026-05-28T22:02:02Z

-@Path(INDEX_PATH_PREFIX + "/tasks/list")
-public interface ListActiveTasksApi {
+@Path(INDEX_PATH_PREFIX)
+public interface TasksApi {


epugh · 2026-05-28T22:03:20Z

+    @Operation(
+        summary = "Status of a specific taskID passed as pathParam.",
+        tags = {"tasks"})
+    TaskStatusResponse getTaskStatus(@PathParam("taskID") String taskID) throws Exception;


We should remember to rationalize all our various "id" related attributes to have a similar pattern... across all the v2 apis... ;-)

yes, sure. 👍🏽

epugh · 2026-05-28T22:04:36Z

+    @GET
+    @StoreApiParameters
+    @Operation(
+        summary = "Lists all the currently running active tasks.",


I wonder if this should be Lists all the currently active tasks.. Running/not running, that really isn't an aspect. The task is either active or not, at least, that is how I read the TaskStatus enum! Nit picky, but now is the time.

have updated the summary to now: Lists all the active tasks.

Here via this API call, we invoke: getActiveQueriesGenerated(), thus keeping active fits here.

epugh · 2026-05-28T22:05:34Z

+    @GET
+    @StoreApiParameters
+    @Operation(
+        summary = "Status of a specific taskID passed as pathParam.",


I don't think we need the passed as pathParam, that is obvious from thow the docs are generated.. In fact, I would do Status of a specific task. and leave it at that.

understood, have corrected this now.

epugh · 2026-05-28T22:06:51Z

+
+    response.taskStatus =
+        (isTaskActive)
+            ? TaskStatusResponse.TaskStatus.ACTIVE


I think I would just import TaskStatusResponse to have a less nested strcutrure.

actually, we have that, so can we just refer to TaskSTatus?

thanks, this looks much better now, lesser visual noise.

epugh · 2026-05-28T22:07:26Z

 import org.apache.solr.request.SolrQueryRequest;

-public class ListActiveTasks extends JerseyResource implements ListActiveTasksApi {
+public class ListActiveTasks extends JerseyResource implements TasksApi.List {


this reads nicer.

epugh · 2026-05-28T22:08:37Z

- * Handles request for listing all active cancellable tasks All active tasks logic lives in the v2
- * {@link ListActiveTasks}; this handler is a thin v1 bridge that extracts request parameters and
- * delegates.
+ * Handles request for listing the active cancellable tasks and Status check of any particular task,


are there active tasks that are NOT cancellable?

also, maybe a typo of "Status" check? Lastly, this whole sentence maybe needs a period? Just appears a bit awkared.

In fact, i think we don't need the text about "actual logic", i don't think we do that in other apis? If we do, then great...

are there active tasks that are NOT cancellable?

there can be. since this is the kind of function that we invoke, having cancellable in the javadoc looks fine to me.
getCore().getCancellableQueryTracker().getActiveQueriesGenerated()

epugh · 2026-05-28T22:12:14Z

  @Override
  public void handleRequestBody(SolrQueryRequest req, SolrQueryResponse rsp) throws Exception {
-    String taskStatusCheckUUID = req.getParams().get(TASK_CHECK_UUID, null);
+    String taskStatusCheckID = req.getParams().get(TASK_CHECK_UUID, null);


so, we can't change any signatures of v1, so I don't know if TASK_CHECK_UUID changed? I think it's fine to leave "taskStatusCheckUUID", as we hope to get rid of it? Maybe just a comment? I dunno.

Or, we change taskStatusCheckID to just taskID internally if we are going to rename it?

have reverted this back to taskStatusCheckUUID

epugh

Getting close!

jaykay12

code comments addressed ✅

local verification of v1 & v2 APIs - ToBeAttached ❗

epugh · 2026-05-29T11:41:31Z

-        (isTaskActive)
-            ? TaskStatusResponse.TaskStatus.ACTIVE
-            : TaskStatusResponse.TaskStatus.INACTIVE;
+    response.taskStatus = (isTaskActive) ? TaskStatus.ACTIVE : TaskStatus.INACTIVE;


this reads much nicer!

epugh · 2026-05-29T11:46:56Z

code comments addressed ✅

local verification of v1 & v2 APIs - ToBeAttached ❗

Here is an example of sort of the testing I am looking for. In the reference PR I found a couple of commands that exercised the code externally, just to get more confidence. If you do the equivalent with some curl commands, that would give me more confidence. Plus, I'll run them and learn some stuff! #4320 (comment)

epugh · 2026-05-29T11:47:27Z

@jaykay12 oh, we need to update the Reference Guide for any changes we've made in the V2 outputs as well ;-). If you hate doing that, I can do that ;-).

Turns out I started this pattern, but it's not actually a pattern we want to support! So backing it out of the two places that have it.

jaykay12 added 9 commits May 16, 2026 03:35

initial changes

acccb16

testing

e426014

working api

7b15791

working setup

02c14b9

cleanup

177d2c6

cleanup

95ace8d

logging

7dc167a

minor

1a32bb1

Merge branch 'main' into SOLR-18248-list-tasks

6b6f536

github-actions Bot added cat:search cat:api labels May 19, 2026

jaykay12 changed the title ~~[SOLR-18248] | Migration of ListAllTasks & SingleTaskStatus V2 APIs to JAX-RS Constructs~~ SOLR-18248 : Migration of Tasks V2 APIs to JAX-RS Constructs May 19, 2026

epugh reviewed May 19, 2026

View reviewed changes

jaykay12 added 2 commits May 20, 2026 02:51

response model for 2nd API

d746e21

verifies for solr cloud

df5c428

jaykay12 added 7 commits May 20, 2026 23:51

changes related to pojo & duplicate code removal

354d0f5

removed older interfaces

1cad09d

removing debug

579925d

done

eb1cd97

self review

4e10720

added cl

eb9b51b

tidying done

adc7006

jaykay12 commented May 20, 2026

View reviewed changes

added apache license

996b45b

jaykay12 marked this pull request as ready for review May 20, 2026 22:33

jaykay12 requested a review from epugh May 20, 2026 22:33

jaykay12 added 2 commits May 23, 2026 03:32

tests

f6cb8f7

added 1 test

97e5afa

added license

3d72214

github-actions Bot added the tests label May 23, 2026

jaykay12 added 3 commits May 24, 2026 16:40

test corrections

68eec35

minor tidy

87204e2

test to check actual active/inactive

930312b

epugh requested changes May 27, 2026

View reviewed changes

jaykay12 added 4 commits May 28, 2026 22:30

Merge branch 'main' into SOLR-18248-list-tasks

ba79375

comments addressal

199cb24

comments addressed

24ca810

tidying it up

c583c38

jaykay12 commented May 28, 2026

View reviewed changes

jaykay12 requested a review from epugh May 28, 2026 21:33

epugh approved these changes May 28, 2026

View reviewed changes

epugh requested changes May 28, 2026

View reviewed changes

jaykay12 added 3 commits May 29, 2026 08:17

comments addressed

bb0f0f1

tidy up

d0ddec6

update

0905202

jaykay12 commented May 29, 2026

View reviewed changes

minor

d08d788

epugh reviewed May 29, 2026

View reviewed changes

epugh and others added 2 commits May 29, 2026 07:48

Remove "breadcrumb" pointer, we only do it in one other place.

1b0b81d

Turns out I started this pattern, but it's not actually a pattern we want to support! So backing it out of the two places that have it.

checking

200afba


		import static org.apache.solr.client.api.util.Constants.INDEX_PATH_PREFIX;

		@Path(INDEX_PATH_PREFIX + "/tasks/listjalaz")


		}

		private void handleStandAloneMode(ListActiveTaskResponse response, String taskUUID) {

Conversation

jaykay12 commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Solution

Tests

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaykay12 May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

epugh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaykay12 commented May 19, 2026

Uh oh!

jaykay12 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

epugh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaykay12 May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaykay12 commented May 19, 2026 •

edited

Loading

jaykay12 May 19, 2026 •

edited

Loading

jaykay12 left a comment •

edited

Loading

jaykay12 May 28, 2026 •

edited

Loading

jaykay12 May 28, 2026 •

edited

Loading

jaykay12 left a comment •

edited

Loading