Skip to content

Commit 1e1e662

Browse files
ctruedenclaude
andcommitted
scijava-execute: the pre/postprocessor chain
Runner.run is always asynchronous, returning Future<ExecutionResult>. One verb covers both cases, since a caller wanting to block writes run(...).get() -- as SciJava Common's ModuleService has long shown. Declining is not cancellation, and the two now have different shapes. A preprocessor may stop a run before it happens, because the user closed a dialog or a precondition is unmet; that is an ordinary outcome and comes back as a result carrying reason() and declinedBy(). Interrupting work already under way remains Future.cancel(true), surfacing as CancellationException. A test asserts both, side by side. ExecutionResult is deliberately not itself a Future: isCancelled() and get() are coupled by contract, so a declined run modelled as a cancelled future would be an exception again, which returning a result was meant to avoid. The asynchrony lives in the future, what happened lives in the result. declinedBy() returns the preprocessor instance rather than its class, since a chain may hold two instances of one class -- there is a test with exactly that, a permissive and a strict Gate, asserting the result names the one that objected. Declining lives on the execution rather than the preprocessor. SciJava Common put isCanceled()/getCancelReason() on the plugin, which made preprocessors stateful and unsafe to share between runs; that matters more here, since Context constructs a fresh plugin instance per call. Telling the execution keeps preprocessors stateless and gives declinedBy() the right instance for free. Required-input checking moves from binding time to after preprocessing, since supplying values the caller omitted is precisely what a preprocessor such as an input harvester is for. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 634d940 commit 1e1e662

11 files changed

Lines changed: 840 additions & 11 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -635,9 +635,32 @@ No application context required by anything in this phase.
635635
- **A required input must be supplied, not merely non-null.** Checking the
636636
field instead would let a missing required `double` run silently as `0.0`,
637637
since a primitive field is never null.
638-
- Still to do here: the pre/postprocessor chain, and factoring the
639-
framework-neutral member parsing out of `ops-engine` — which is a larger
640-
job than it looks, see below.
638+
- **The processor chain is done**: `Preprocessor` and `Postprocessor`
639+
plugins, and `Runner.run`, which is always asynchronous and returns
640+
`Future<ExecutionResult>`. One verb covers both cases, since a caller
641+
wanting to block writes `run(...).get()` — as SciJava Common's
642+
`ModuleService` has long demonstrated.
643+
- **Declining is not cancellation.** A preprocessor may stop a run before it
644+
happens — the user closed the dialog, or a precondition is unmet — which
645+
is an ordinary outcome, not an error and not interruption of work under
646+
way. It is reported by `ExecutionResult.isDeclined()`, with `reason()` for
647+
the user and `declinedBy()` naming the preprocessor.
648+
- **`ExecutionResult` is deliberately not a `Future`.** A future's
649+
`isCancelled()` and `get()` are coupled by contract — whenever the former
650+
is true the latter must throw — so modelling a declined run as a cancelled
651+
future turns it back into an exception, which returning a result was meant
652+
to avoid. The asynchrony lives in `Future<ExecutionResult>`; what happened
653+
lives in the result.
654+
- **`declinedBy()` returns the preprocessor instance, not its class**, since
655+
a chain may hold two instances of one class and the useful question is
656+
which of them objected.
657+
- **Declining lives on the execution, not the preprocessor.** SciJava Common
658+
put `isCanceled()`/`getCancelReason()` on the plugin, which made
659+
preprocessors stateful and unsafe to share across runs. Telling the
660+
execution keeps them stateless — which matters here, since `Context`
661+
constructs a fresh plugin instance per call.
662+
- Still to do here: factoring the framework-neutral member parsing out of
663+
`ops-engine` — which is a larger job than it looks, see below.
641664
- **Commands:** a struct, plus menu metadata, plus `run`. Commands and Ops
642665
remain separate concepts sharing this layer.
643666
- **Scripting:** `javax.script` is not general enough. GraalVM's Truffle

‎docs/migration.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,8 @@ A **dropped** row is a successful outcome, not a gap.
121121
| `app` | mostly `org.scijava.meta` for version and title metadata; the rest is app-shell material, dropped | planned |
122122
| `thread` | EDT dispatch belongs with the UI layer (Phase 4); parallelism is `org.scijava.concurrent` | planned |
123123
| `convert` | `scijava-convert3` (Phase 2) | planned |
124-
| `module`, `module.process`, `command` | execution layer on `scijava-struct` (Phase 3) | planned |
124+
| `module`, `module.process` | `org.scijava.execute`: `@Parameter` on fields, `Executables` for the plain case, and `Runner` for the processor chain. `ModuleService.run` becomes `Runner.run`, still returning a future, but of an `ExecutionResult` that reports a declined run with its reason and its author rather than through `ModulePreprocessor.isCanceled()` | ported |
125+
| `command` | still to come: a command is a struct plus menu metadata plus `run` | planned |
125126
| `script`, `script.process` | scripting facade + `javax.script` / GraalVM polyglot / Appose adapters (Phase 3) | planned |
126127
| `widget` | input harvesting on `scijava-struct`, with dynamic subgroups (Phase 4) | planned |
127128
| `ui`, `menu` | minimal UI API; `ApplicationFrame`/`Desktop`/`StatusBar`/`ToolBar` dropped (Phase 4) | planned |

‎scijava-execute/pom.xml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@
8787

8888
<!-- Note: These versions must match across all component POMs! -->
8989
<scijava-common3.version>1.0.1-SNAPSHOT</scijava-common3.version>
90+
<scijava-priority.version>1.0.1-SNAPSHOT</scijava-priority.version>
9091
<scijava-struct.version>1.0.1-SNAPSHOT</scijava-struct.version>
9192
</properties>
9293

@@ -96,6 +97,11 @@
9697
<artifactId>scijava-common3</artifactId>
9798
<version>${scijava-common3.version}</version>
9899
</dependency>
100+
<dependency>
101+
<groupId>org.scijava</groupId>
102+
<artifactId>scijava-priority</artifactId>
103+
<version>${scijava-priority.version}</version>
104+
</dependency>
99105
<dependency>
100106
<groupId>org.scijava</groupId>
101107
<artifactId>scijava-struct</artifactId>

‎scijava-execute/src/main/java/module-info.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
exports org.scijava.execute;
3333

3434
requires org.scijava.common3;
35+
requires transitive org.scijava.priority;
3536
requires transitive org.scijava.struct;
3637

3738
}

‎scijava-execute/src/main/java/org/scijava/execute/Executables.java‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ public static Struct struct(final Class<?> type) {
8585
public static Map<String, Object> run(final Runnable executable,
8686
final Map<String, Object> inputs)
8787
{
88-
final StructInstance<?> instance = bind(executable, inputs);
88+
final StructInstance<?> instance = bind(executable, inputs, true);
8989
checkCancellation();
9090
executable.run();
9191
checkCancellation();
@@ -106,9 +106,15 @@ public static Callable<Map<String, Object>> callable(
106106
return () -> run(executable, inputs);
107107
}
108108

109-
/** Binds the given input values onto the object's parameters. */
110-
private static StructInstance<?> bind(final Object executable,
111-
final Map<String, Object> inputs)
109+
/**
110+
* Binds the given input values onto the object's parameters.
111+
*
112+
* @param requireInputs whether to insist that required inputs be supplied
113+
* now. A {@link Runner} passes false, since a preprocessor may
114+
* supply them later.
115+
*/
116+
static StructInstance<?> bind(final Object executable,
117+
final Map<String, Object> inputs, final boolean requireInputs)
112118
{
113119
final Struct struct = struct(executable.getClass());
114120
final StructInstance<?> instance = struct.createInstance(executable);
@@ -125,7 +131,7 @@ private static StructInstance<?> bind(final Object executable,
125131
if (inputs.containsKey(key)) {
126132
member.set(inputs.get(key));
127133
}
128-
else if (member.member().isRequired()) {
134+
else if (requireInputs && member.member().isRequired()) {
129135
// NB: require the value to be supplied, rather than checking
130136
// whether the field is null. A primitive field is never null -- a
131137
// missing required `double` would silently run as 0.0.
@@ -137,7 +143,7 @@ else if (member.member().isRequired()) {
137143
}
138144

139145
/** Collects the object's output values. */
140-
private static Map<String, Object> outputs(final StructInstance<?> instance) {
146+
static Map<String, Object> outputs(final StructInstance<?> instance) {
141147
final Map<String, Object> outputs = new LinkedHashMap<>();
142148
for (final MemberInstance<?> member : instance.members()) {
143149
if (member.member().isOutput()) outputs.put(member.member().key(), //
@@ -155,7 +161,7 @@ private static String names(final Struct struct) {
155161
return sb.length() == 0 ? "no parameters" : sb.toString();
156162
}
157163

158-
private static void checkCancellation() {
164+
static void checkCancellation() {
159165
// NB: cancellation is thread interruption; restore the flag so callers
160166
// further up still see it.
161167
if (Thread.interrupted()) {
Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
/*
2+
* #%L
3+
* Running things that declare their inputs and outputs.
4+
* %%
5+
* Copyright (C) 2026 SciJava developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
package org.scijava.execute;
31+
32+
import java.util.Map;
33+
import java.util.Optional;
34+
35+
import org.scijava.struct.StructInstance;
36+
37+
/**
38+
* One run in progress, handed to each {@link Preprocessor} and
39+
* {@link Postprocessor}.
40+
*
41+
* @author Curtis Rueden
42+
*/
43+
public interface Execution {
44+
45+
/** Gets the object being run. */
46+
Object executable();
47+
48+
/** Gets its parameters, bound to their values. */
49+
StructInstance<?> instance();
50+
51+
/**
52+
* Declines this run: it will not happen, and the result will say so.
53+
* <p>
54+
* This is how a preprocessor reports that the user cancelled a dialog, or
55+
* that a precondition is not met. It is not an error, and it is not
56+
* {@linkplain java.util.concurrent.Future#cancel(boolean) cancellation} of
57+
* work already under way - nothing has run yet.
58+
* </p>
59+
* <p>
60+
* NB: SciJava Common put this on the preprocessor itself, as
61+
* {@code isCanceled()}/{@code getCancelReason()}, which made preprocessors
62+
* stateful and unsafe to share between runs. Telling the execution instead
63+
* keeps them stateless, and lets the result record <em>which</em>
64+
* preprocessor declined, even where two instances of one class are in the
65+
* same chain.
66+
* </p>
67+
*
68+
* @param reason why this run should not happen, for the user to read
69+
*/
70+
void decline(String reason);
71+
72+
/** Gets whether this run has been declined. */
73+
boolean isDeclined();
74+
75+
/** Gets why this run was declined, if it was. */
76+
Optional<String> reason();
77+
78+
/**
79+
* Gets the outputs produced so far. Empty until the object has run, so this
80+
* is for postprocessors.
81+
*/
82+
Map<String, Object> outputs();
83+
}
Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
/*
2+
* #%L
3+
* Running things that declare their inputs and outputs.
4+
* %%
5+
* Copyright (C) 2026 SciJava developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
package org.scijava.execute;
31+
32+
import java.util.Collections;
33+
import java.util.Map;
34+
import java.util.Optional;
35+
36+
/**
37+
* What came of a run: its outputs, or why it did not happen.
38+
* <p>
39+
* NB: this is deliberately not itself a {@link java.util.concurrent.Future}.
40+
* A future's {@code isCancelled()} and {@code get()} are coupled by contract -
41+
* whenever the former is true the latter must throw - so a declined run
42+
* modelled as a cancelled future would be an exception again, which is what
43+
* returning a result avoids. The asynchrony lives in
44+
* {@code Future<ExecutionResult>}, and what happened lives here.
45+
* </p>
46+
*
47+
* @author Curtis Rueden
48+
*/
49+
public class ExecutionResult {
50+
51+
private final Map<String, Object> outputs;
52+
private final String reason;
53+
private final Preprocessor declinedBy;
54+
55+
private ExecutionResult(final Map<String, Object> outputs,
56+
final String reason, final Preprocessor declinedBy)
57+
{
58+
this.outputs = outputs;
59+
this.reason = reason;
60+
this.declinedBy = declinedBy;
61+
}
62+
63+
/** Creates the result of a run that happened. */
64+
public static ExecutionResult completed(final Map<String, Object> outputs) {
65+
return new ExecutionResult(Map.copyOf(outputs), null, null);
66+
}
67+
68+
/** Creates the result of a run that was declined before it happened. */
69+
public static ExecutionResult declined(final String reason,
70+
final Preprocessor declinedBy)
71+
{
72+
return new ExecutionResult(Collections.emptyMap(), reason, declinedBy);
73+
}
74+
75+
/** Gets whether the run happened. */
76+
public boolean isCompleted() {
77+
return declinedBy == null && reason == null;
78+
}
79+
80+
/** Gets whether the run was declined before it happened. */
81+
public boolean isDeclined() {
82+
return !isCompleted();
83+
}
84+
85+
/** Gets why the run was declined, if it was, for the user to read. */
86+
public Optional<String> reason() {
87+
return Optional.ofNullable(reason);
88+
}
89+
90+
/**
91+
* Gets which preprocessor declined the run, if one did.
92+
* <p>
93+
* NB: the instance rather than its class, since a chain may hold several
94+
* instances of one class and the useful question is which of them objected.
95+
* </p>
96+
*/
97+
public Optional<Preprocessor> declinedBy() {
98+
return Optional.ofNullable(declinedBy);
99+
}
100+
101+
/** Gets the outputs, by name. Empty if the run was declined. */
102+
public Map<String, Object> outputs() {
103+
return outputs;
104+
}
105+
106+
@Override
107+
public String toString() {
108+
return isDeclined() ? "declined: " + reason : "completed: " + outputs;
109+
}
110+
}
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
/*
2+
* #%L
3+
* Running things that declare their inputs and outputs.
4+
* %%
5+
* Copyright (C) 2026 SciJava developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
package org.scijava.execute;
31+
32+
import org.scijava.priority.Priority;
33+
34+
/**
35+
* Handles the outputs of a run that has finished - displaying them, recording
36+
* them, converting them.
37+
* <p>
38+
* A postprocessor cannot decline: the work has already happened and its
39+
* outputs exist, so declining would be a lie. To report a problem, throw.
40+
* </p>
41+
*
42+
* @author Curtis Rueden
43+
*/
44+
public interface Postprocessor {
45+
46+
/** Handles the outputs of the given run. */
47+
void process(Execution execution);
48+
49+
/** Sorts postprocessors, highest first. See {@link Priority}. */
50+
default double priority() {
51+
return Priority.NORMAL;
52+
}
53+
}

0 commit comments

Comments
 (0)