fix(jobs): trigger-now runs a job on the engine it declares (#6305) (#6625)

#6375 made client-Java `@Scheduled` / `JobHandler` jobs first-class `Job`
definitions on the shared Quartz scheduler, so they are listed, monitored
and manageable in the Jobs perspective like any `.job`. One half of that
was still missing: the Jobs perspective's Trigger action.

`JobService.trigger` — the manual path behind `POST /services/jobs/trigger`
— ran the handler through the JavaScript code runner unconditionally,
ignoring the job's `engine`. A client-Java job's handler is a class name,
not a repository path to a JS module, so triggering one answered 500 while
the same job ran fine on its cron.

The dispatch now lives in exactly one place, `JobHandlerRunner`, used by
both ways a job can start: the scheduled fire (`JobExecutionService`) and
the manual trigger. That is the actual defect — the two dispatches were
written out separately and drifted.

The engine-java guide's job bullet was also still describing the private
`ThreadPoolTaskScheduler` that #6375 replaced; it now records the shared
Quartz registration and this single dispatch point.

Verified against the client-Java job sample: `JavaJobDecoratorSampleProjectIT`
triggers a listed `engine: java` job over REST and fails on the pre-fix code
with "Expected status code <200> but was <500>", passing with the fix.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: delchev

components/engine/engine-java/CLAUDE.md

@@ -94,7 +94,15 @@ instantiate client classes.
 - `EntityClassConsumer` (data-store-java) — `@Entity` → `JavaEntityManager` (Hibernate dynamic-map).
 - `ControllerClassConsumer` — `@Controller` → `ControllerRouter` + OpenAPI via
   `JavaControllerOpenApiPublisher`. (A `@Controller` must not also implement `JavaHandler`.)
-- `ScheduledClassConsumer` — jobs (see two styles below) → cron via a dedicated `ThreadPoolTaskScheduler`.
+- `ScheduledClassConsumer` — jobs (see two styles below) → a real `Job` row per tenant on the platform's
+  **shared Quartz scheduler** (#6375), under the synthetic `RUNTIME_LOCATION_PREFIX` location so the job
+  synchronizer does not reap it as a registry orphan. So a client-Java job is listed, enable/disable-able,
+  trigger-now-able and job-logged in the Jobs perspective like any `.job`, and fires **once cluster-wide**
+  — not once per JVM, as the private `ThreadPoolTaskScheduler` this replaced did. At fire time the jobs
+  engine dispatches back through the `JavaJobExecutor` SPI (engine `java`); both that path and the manual
+  trigger go through `JobHandlerRunner`, which is the ONLY place the engine→runner dispatch lives —
+  trigger-now was written out separately once and stayed JavaScript-only, so triggering a client-Java job
+  ran its class name as a JS path and 500'd (#6305).
 - `ListenerClassConsumer` — listeners → ActiveMQ; re-establishes the message's tenant context.
 - `WebsocketClassConsumer` + `JavaWebsocketRegistry` — websockets; `WebsocketProcessor`
   (`engine-websockets`) calls `JavaWebsocketRegistry.dispatch(...)` reflectively (keeps that module free

components/engine/engine-jobs/src/main/java/org/eclipse/dirigible/components/jobs/handler/JobExecutionService.java

@@ -14,15 +14,13 @@
 import org.eclipse.dirigible.components.jobs.domain.JobLog;
 import org.eclipse.dirigible.components.jobs.service.JobLogService;
 import org.eclipse.dirigible.components.jobs.tenant.JobNameCreator;
-import org.eclipse.dirigible.graalium.core.DirigibleJavascriptCodeRunner;
 import org.quartz.JobDataMap;
 import org.quartz.JobExecutionContext;
 import org.quartz.JobExecutionException;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.stereotype.Service;
 
-import java.nio.file.Path;
 import java.util.Date;
 
 @Service
@@ -35,14 +33,14 @@ public class JobExecutionService {
     private final JobLogService jobLogService;
     private final JobNameCreator jobNameCreator;
     private final DataSourcesManager dataSourcesManager;
-    private final org.springframework.beans.factory.ObjectProvider<JavaJobExecutor> javaJobExecutor;
+    private final JobHandlerRunner jobHandlerRunner;
 
     JobExecutionService(JobLogService jobLogService, JobNameCreator jobNameCreator, DataSourcesManager dataSourcesManager,
-            org.springframework.beans.factory.ObjectProvider<JavaJobExecutor> javaJobExecutor) {
+            JobHandlerRunner jobHandlerRunner) {
         this.jobLogService = jobLogService;
         this.jobNameCreator = jobNameCreator;
         this.dataSourcesManager = dataSourcesManager;
-        this.javaJobExecutor = javaJobExecutor;
+        this.jobHandlerRunner = jobHandlerRunner;
     }
 
     public void executeJob(JobExecutionContext context) throws JobExecutionException {
@@ -70,21 +68,10 @@ private void executeJobInternal(JobExecutionContext context) throws JobExecution
 
             if (triggered != null) {
                 context.put("handler", handler);
-                if (java) {
-                    // Client-Java scheduled job: dispatch to the Java engine's executor (the client
-                    // bean resolved + invoked there). Same JobLog wrapping as the JS path below, so
-                    // it is equally visible/monitored in the Jobs perspective.
-                    JavaJobExecutor executor = javaJobExecutor.getIfAvailable();
-                    if (executor == null) {
-                        throw new IllegalStateException("No JavaJobExecutor is available to run the Java job [" + handler + "]");
-                    }
-                    executor.execute(handler);
-                } else {
-                    Path handlerPath = Path.of(handler);
-                    try (DirigibleJavascriptCodeRunner runner = new DirigibleJavascriptCodeRunner()) {
-                        runner.run(handlerPath);
-                    }
-                }
+                // A client-Java job dispatches to the Java engine's executor, a JS one to the code
+                // runner - inside the same JobLog wrapping either way, so both are equally
+                // visible/monitored in the Jobs perspective.
+                jobHandlerRunner.run(handler, engine);
             }
 
             registeredFinished(name, handler, triggered);

components/engine/engine-jobs/src/main/java/org/eclipse/dirigible/components/jobs/handler/JobHandlerRunner.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2010-2026 Eclipse Dirigible contributors
+ *
+ * All rights reserved. This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v2.0 which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v20.html
+ *
+ * SPDX-FileCopyrightText: Eclipse Dirigible contributors SPDX-License-Identifier: EPL-2.0
+ */
+package org.eclipse.dirigible.components.jobs.handler;
+
+import java.nio.file.Path;
+
+import org.eclipse.dirigible.graalium.core.DirigibleJavascriptCodeRunner;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.stereotype.Component;
+
+/**
+ * Runs a job's handler on the engine the job declares: {@value JavaJobExecutor#ENGINE_JAVA} routes
+ * to the client-Java executor, anything else to the JavaScript runner (the handler is then a
+ * repository path).
+ *
+ * <p>
+ * Shared by both ways a job can start - the scheduled fire ({@link JobExecutionService}) and the
+ * manual trigger-now ({@code JobService.trigger}) - so a job runs the same way however it was
+ * started. The two dispatches used to be written out separately and drifted: trigger-now stayed
+ * JavaScript-only, so triggering a client-Java job from the Jobs perspective tried to run its class
+ * name as a JavaScript file and failed (dirigible #6305).
+ */
+@Component
+public class JobHandlerRunner {
+
+    private final ObjectProvider<JavaJobExecutor> javaJobExecutor;
+
+    JobHandlerRunner(ObjectProvider<JavaJobExecutor> javaJobExecutor) {
+        this.javaJobExecutor = javaJobExecutor;
+    }
+
+    /**
+     * Run the handler.
+     *
+     * @param handler the job's handler - a client-Java FQN (optionally {@code #method}) for the Java
+     *        engine, a repository path to a JavaScript module otherwise
+     * @param engine the job's engine, or {@code null} for the default JavaScript one
+     * @throws Exception when the job body throws, so the caller can log the run as failed
+     */
+    public void run(String handler, String engine) throws Exception {
+        if (JavaJobExecutor.ENGINE_JAVA.equals(engine)) {
+            JavaJobExecutor executor = javaJobExecutor.getIfAvailable();
+            if (executor == null) {
+                throw new IllegalStateException("No JavaJobExecutor is available to run the Java job [" + handler + "]");
+            }
+            executor.execute(handler);
+            return;
+        }
+        try (DirigibleJavascriptCodeRunner runner = new DirigibleJavascriptCodeRunner()) {
+            runner.run(Path.of(handler));
+        }
+    }
+}

components/engine/engine-jobs/src/main/java/org/eclipse/dirigible/components/jobs/service/JobService.java

@@ -10,16 +10,15 @@
 package org.eclipse.dirigible.components.jobs.service;
 
 import static java.text.MessageFormat.format;
-import java.nio.file.Path;
 import java.util.HashMap;
 import java.util.Map;
 import org.eclipse.dirigible.commons.config.Configuration;
 import org.eclipse.dirigible.components.base.artefact.BaseArtefactService;
 import org.eclipse.dirigible.components.jobs.domain.Job;
 import org.eclipse.dirigible.components.jobs.email.JobEmailProcessor;
+import org.eclipse.dirigible.components.jobs.handler.JobHandlerRunner;
 import org.eclipse.dirigible.components.jobs.manager.JobsManager;
 import org.eclipse.dirigible.components.jobs.repository.JobRepository;
-import org.eclipse.dirigible.graalium.core.DirigibleJavascriptCodeRunner;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
@@ -36,17 +35,23 @@ public class JobService extends BaseArtefactService<Job, Long> {
     /** The jobs manager. */
     private final JobsManager jobsManager;
 
+    /** Runs a job's handler on the engine it declares - shared with the scheduled fire. */
+    private final JobHandlerRunner jobHandlerRunner;
+
     /**
      * Instantiates a new job service.
      *
      * @param repository the repository
      * @param jobEmailProcessor the job email processor
      * @param jobsManager the jobs manager
+     * @param jobHandlerRunner the job handler runner
      */
-    public JobService(JobRepository repository, JobEmailProcessor jobEmailProcessor, JobsManager jobsManager) {
+    public JobService(JobRepository repository, JobEmailProcessor jobEmailProcessor, JobsManager jobsManager,
+            JobHandlerRunner jobHandlerRunner) {
         super(repository);
         this.jobEmailProcessor = jobEmailProcessor;
         this.jobsManager = jobsManager;
+        this.jobHandlerRunner = jobHandlerRunner;
     }
 
     /**
@@ -140,14 +145,9 @@ public boolean trigger(String name, Map<String, String> parametersMap) throws Ex
                 Configuration.set(entry.getKey(), entry.getValue());
             }
 
-            String handler = job.getHandler();
-            Path handlerPath = Path.of(handler);
-
-            try (DirigibleJavascriptCodeRunner runner = new DirigibleJavascriptCodeRunner()) {
-                runner.run(handlerPath);
-            } catch (Exception e) {
-                throw new Exception(e);
-            }
+            // Run it on the engine the job declares - the same dispatch the scheduled fire uses. A
+            // client-Java job's handler is a class name, not a JavaScript path (dirigible #6305).
+            jobHandlerRunner.run(job.getHandler(), job.getEngine());
         } finally {
             for (Map.Entry<String, String> entry : memento.entrySet()) {
                 Configuration.set(entry.getKey(), entry.getValue());

components/engine/engine-jobs/src/test/java/org/eclipse/dirigible/components/jobs/handler/JobHandlerRunnerTest.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) 2010-2026 Eclipse Dirigible contributors
+ *
+ * All rights reserved. This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v2.0 which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v20.html
+ *
+ * SPDX-FileCopyrightText: Eclipse Dirigible contributors SPDX-License-Identifier: EPL-2.0
+ */
+package org.eclipse.dirigible.components.jobs.handler;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.ObjectProvider;
+
+/**
+ * Dispatching a job's handler to the engine it declares. The Java branch is what the manual
+ * trigger-now path was missing (#6305); the JavaScript branch runs a Graal code runner and is
+ * covered end-to-end by the job integration tests instead.
+ */
+class JobHandlerRunnerTest {
+
+    @SuppressWarnings("unchecked")
+    private static ObjectProvider<JavaJobExecutor> provider(JavaJobExecutor executor) {
+        ObjectProvider<JavaJobExecutor> provider = mock(ObjectProvider.class);
+        when(provider.getIfAvailable()).thenReturn(executor);
+        return provider;
+    }
+
+    @Test
+    void aJavaJobIsRunByTheJavaExecutor() throws Exception {
+        JavaJobExecutor executor = mock(JavaJobExecutor.class);
+
+        new JobHandlerRunner(provider(executor)).run("app.jobs.CleanupJob", JavaJobExecutor.ENGINE_JAVA);
+
+        verify(executor).execute("app.jobs.CleanupJob");
+    }
+
+    @Test
+    void aJavaJobWithoutAnExecutorFailsLoudly() {
+        JobHandlerRunner runner = new JobHandlerRunner(provider(null));
+
+        // Rather than silently doing nothing - the caller logs the run as failed, so the Jobs
+        // perspective shows it instead of reporting a run that never happened.
+        assertThrows(IllegalStateException.class, () -> runner.run("app.jobs.CleanupJob", JavaJobExecutor.ENGINE_JAVA));
+    }
+
+    @Test
+    void aJavaScriptJobNeverReachesTheJavaExecutor() {
+        JavaJobExecutor executor = mock(JavaJobExecutor.class);
+        JobHandlerRunner runner = new JobHandlerRunner(provider(executor));
+
+        // No engine (a plain .job artefact) means the JavaScript runner - which needs a repository, so
+        // it throws here. What this asserts is that the Java executor was not consulted.
+        assertThrows(Exception.class, () -> runner.run("project/job.mjs", null));
+
+        verifyNoInteractions(executor);
+    }
+}

tests/tests-integrations/src/main/java/org/eclipse/dirigible/integration/tests/ui/tests/sample/JavaJobDecoratorSampleProjectIT.java

@@ -16,6 +16,7 @@
 import java.util.concurrent.TimeUnit;
 
 import org.eclipse.dirigible.tests.framework.logging.LogsAsserter;
+import io.restassured.http.ContentType;
 import org.eclipse.dirigible.tests.framework.util.SynchronizationUtil;
 import org.junit.jupiter.api.BeforeEach;
 
@@ -65,6 +66,34 @@ protected void verifyProject() {
                                                  .then()
                                                  .statusCode(200)
                                                  .body("findAll { it.engine == 'java' }.size()", greaterThanOrEqualTo(2)));
+
+        verifyTriggerNowRunsTheClientJavaJob();
+    }
+
+    /**
+     * Trigger-now (the Jobs perspective's play button) must run a client-Java job on the Java engine.
+     * The manual path used to be JavaScript-only, so it tried to run the job's CLASS NAME as a
+     * repository path to a JS module and answered 500 (dirigible #6305).
+     *
+     * <p>
+     * The status is the whole assertion: the Java dispatch either resolves the client bean and invokes
+     * it, or throws (an unknown bean, a job body that fails) - and either way the endpoint surfaces
+     * that as a 500. It cannot answer 200 without having run the job.
+     */
+    private void verifyTriggerNowRunsTheClientJavaJob() {
+        String name = restAssuredExecutor.executeWithResult(() -> given().when()
+                                                                         .get("/services/jobs")
+                                                                         .then()
+                                                                         .statusCode(200)
+                                                                         .extract()
+                                                                         .path("find { it.engine == 'java' }.name"));
+
+        restAssuredExecutor.execute(() -> given().contentType(ContentType.JSON)
+                                                 .body("[]")
+                                                 .when()
+                                                 .post("/services/jobs/trigger/" + name)
+                                                 .then()
+                                                 .statusCode(200));
     }
 
 }