Skip to content

Commit ae3cf2f

Browse files
ctruedenclaude
andcommitted
scijava-harvest: prototype the parameter dialog model
The model behind a parameter dialog -- groups, dependencies between parameters, validation -- with no toolkit anywhere, so it is testable headless and a Swing or JavaFX binding renders it. Prototyped against the four dialog behaviours actually asked for, each of which taught something. A chosen implementation brings its own parameters, and expansion must be driven by the value's class rather than the declared type: the field says Joke, the value is a knock-knock joke, and it is the joke's parameters that appear. Expanding the declared type finds nothing, an interface having no fields, so Structs.expand and its static childStruct() are not enough. Static nesting is then the degenerate case where the value's class never varies, which is what makes one concept cover both. A group whose size depends on a value cannot be fields at all, since a class's fields are fixed when it is compiled. It needs parameters built at runtime -- exactly what a script header needs -- so both are now served by Parameters.builder(), members over a map. Two requirements that looked unrelated turned out to be one primitive, and the fake-script test written earlier as a throwaway became the shipped mechanism. Callbacks now work for scripts, which SciJava Common never managed: it resolved callback names by Java reflection, so a script had nothing to name. ExecutableInstance.behavior(String) resolves a name however that kind of code does. Cascading callbacks terminate: a callback may change anything, and two parameters that set each other -- Celsius and Fahrenheit -- would otherwise never stop, so each callback runs at most once per set. Validation has one protocol: return a message, or do not. Allowing a validator to either throw or return a string is why SciJava Common needs both validate and validateMessage. Two bugs found on the way: only one of the two executable paths resolved behaviors, so visibleWhen and generators silently did nothing; and the no-container reflection path needed addReads for the same reason the container's does, which fully open modules disguised until now. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 010b68a commit ae3cf2f

21 files changed

Lines changed: 2288 additions & 7 deletions

‎docs/migration-plan.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -764,6 +764,51 @@ after it.
764764

765765
### Phase 4 — UI and desktop
766766

767+
- **`scijava-harvest`** (`org.scijava.harvest`): the model behind a parameter
768+
dialog — groups, dependencies between parameters, validation — with no
769+
toolkit anywhere, so it is testable headless and a Swing or JavaFX binding
770+
renders it. **Prototyped**, against the four dialog behaviours actually
771+
asked for, and each taught something:
772+
- **A chosen implementation brings its own parameters.** Expansion is driven
773+
by the **value's class**, not the declared type: the field says `Joke`, the
774+
value is a knock-knock joke, and it is the joke's parameters that appear.
775+
Expanding the declared type finds nothing, an interface having no fields —
776+
so `Structs.expand`, which uses the static `childStruct()`, is not enough.
777+
- **Static nesting is then the degenerate case** where the value's class
778+
never varies. One concept covers both, and the reason is the value-driven
779+
expansion rather than anything about `isStruct()`.
780+
- **A group whose size depends on a value cannot be fields at all**, since a
781+
class's fields are fixed when it is compiled. It needs parameters built at
782+
runtime — which is exactly what a script header needs, so both are served
783+
by `Parameters.builder()`, members over a map. Two requirements that looked
784+
unrelated turned out to be one primitive.
785+
- **An "advanced" toggle** is a group with a `visibleWhen` behavior; a
786+
hidden group disappears rather than showing as an empty box.
787+
- **Callbacks work for scripts**, which SciJava Common never managed: it
788+
resolved `callback = "foo"` by Java reflection, leaving a script nothing to
789+
name. `ExecutableInstance.behavior(String)` resolves a name however that
790+
kind of code does — Java reflects a method, a script asks its engine for a
791+
function.
792+
- **Cascading callbacks terminate.** A callback may change any parameter, so
793+
changes cascade, and two that set each other — Celsius and Fahrenheit, a
794+
real case — would never stop. Each parameter's callback runs at most once
795+
per `set`.
796+
- **Validation has one protocol**: return a message, or do not. SciJava
797+
Common allows either throwing *or* returning a non-empty string, which is
798+
why it needs both `validate` and `validateMessage`; with one protocol a
799+
thrown exception means the validator is broken, rather than being a second
800+
way to report a bad value.
801+
- **`ObjectService` is not the mechanism** after all. A subgroup's parameters
802+
come from whatever object the parameter holds; where that object came from
803+
is a separate question, for a chooser widget's candidate list. It is one
804+
source among several, so the harvester is not blocked on it.
805+
- **Known rough edges**: group placement is provisional (a group appears
806+
where its first member would, and a generated group needs an explicit
807+
`after` anchor); `ParameterModel` decides the tree changed by comparing
808+
`toString()`, which is right for correctness and wrong for a UI that should
809+
patch rather than rebuild; and nothing here has met a toolkit yet, which is
810+
where the prototype's `WidgetFactory`/`WidgetPanelFactory` return.
811+
767812
- **Input harvesting is a headline deliverable**, not a port. It is the
768813
workhorse that lets Fiji users write scripts without UI-specific concerns.
769814
Build it on `scijava-struct`, and complete the long-requested

‎pom.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@
6969
<module>scijava-events</module>
7070
<module>scijava-execute</module>
7171
<module>scijava-function</module>
72+
<module>scijava-harvest</module>
7273
<module>scijava-index</module>
7374
<module>scijava-io3</module>
7475
<module>scijava-legacy</module>
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
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+
/**
33+
* A named piece of behavior belonging to an executable: a callback run when a
34+
* parameter changes, a validator, a function generating parameters.
35+
* <p>
36+
* The point of naming behavior rather than reflecting a Java method is that a
37+
* script has no Java methods. SciJava Common's callbacks, initializers and
38+
* validaters were method-name strings resolved through Java reflection, which
39+
* is exactly why they were never finished for scripts. An
40+
* {@link ExecutableInstance} resolves a name however its own kind of code
41+
* does: a Java class by reflecting a method, a script by asking its engine for
42+
* a function.
43+
* </p>
44+
*
45+
* @author Curtis Rueden
46+
* @see ExecutableInstance#behavior(String)
47+
*/
48+
@FunctionalInterface
49+
public interface Behavior {
50+
51+
/**
52+
* Invokes this behavior.
53+
*
54+
* @param args the arguments, if it takes any
55+
* @return whatever it returns, or null
56+
* @throws BehaviorException if it fails
57+
*/
58+
Object invoke(Object... args);
59+
}
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
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+
/** Thrown when a named {@link Behavior} cannot be invoked, or fails. */
33+
public class BehaviorException extends RuntimeException {
34+
35+
private static final long serialVersionUID = 1L;
36+
37+
public BehaviorException(final String message) {
38+
super(message);
39+
}
40+
41+
public BehaviorException(final String message, final Throwable cause) {
42+
super(message, cause);
43+
}
44+
}

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@
2929

3030
package org.scijava.execute;
3131

32+
import java.util.Optional;
33+
3234
import org.scijava.struct.StructInstance;
3335

3436
/**
@@ -50,4 +52,21 @@ public interface ExecutableInstance {
5052

5153
/** Runs it, with whatever values its parameters currently hold. */
5254
void run();
55+
56+
/**
57+
* Looks up a named piece of behavior belonging to this instance - a
58+
* callback, a validator, a function generating parameters.
59+
* <p>
60+
* A Java executable resolves the name by reflecting a method; a script
61+
* resolves it by asking its engine for a function of that name. Naming
62+
* behavior rather than reflecting a method is what lets both work, where
63+
* SciJava Common's callbacks were Java-only.
64+
* </p>
65+
*
66+
* @param name the behavior's name
67+
* @return the behavior, or empty if this instance has none by that name
68+
*/
69+
default Optional<Behavior> behavior(final String name) {
70+
return Optional.empty();
71+
}
5372
}

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,12 @@ public StructInstance<?> parameters() {
126126
public void run() {
127127
object.run();
128128
}
129+
130+
@Override
131+
public java.util.Optional<Behavior> behavior(final String name) {
132+
return JavaExecutable.behaviorOf(object.getClass(), null, object,
133+
name);
134+
}
129135
};
130136
}
131137
};

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

Lines changed: 39 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,9 @@
3737

3838
import org.scijava.common3.Types;
3939
import org.scijava.struct.ItemIO;
40-
import org.scijava.struct.Member;
40+
import java.util.LinkedHashMap;
41+
import java.util.Map;
42+
4143
import org.scijava.struct.MemberInstance;
4244
import org.scijava.struct.ValueAccessible;
4345
import org.scijava.struct.ValueAccessibleMemberInstance;
@@ -47,7 +49,9 @@
4749
*
4850
* @author Curtis Rueden
4951
*/
50-
public class FieldParameterMember<T> implements Member<T>, ValueAccessible<T> {
52+
public class FieldParameterMember<T> implements ParameterMember<T>,
53+
ValueAccessible<T>
54+
{
5155

5256
private final Field field;
5357
private final Parameter parameter;
@@ -119,9 +123,21 @@ public MemberInstance<T> createInstance(final Object o) {
119123
return new ValueAccessibleMemberInstance<>(this, o);
120124
}
121125

122-
/** Gets the label to display, falling back to the field name. */
123-
public String label() {
124-
return parameter.label().isEmpty() ? key() : parameter.label();
126+
@Override
127+
public Map<String, String> attrs() {
128+
final Map<String, String> attrs = new LinkedHashMap<>();
129+
put(attrs, LABEL, parameter.label());
130+
put(attrs, CALLBACK, parameter.callback());
131+
put(attrs, VALIDATOR, parameter.validator());
132+
put(attrs, VISIBLE_WHEN, parameter.visibleWhen());
133+
put(attrs, GROUP, parameter.group());
134+
return attrs;
135+
}
136+
137+
private static void put(final Map<String, String> attrs, final String key,
138+
final String value)
139+
{
140+
if (!value.isEmpty()) attrs.put(key, value);
125141
}
126142

127143
@Override
@@ -140,8 +156,7 @@ private synchronized VarHandle handle() {
140156
if (handle == null) {
141157
try {
142158
final Lookup access = lookup != null ? lookup //
143-
: MethodHandles.privateLookupIn(field.getDeclaringClass(),
144-
MethodHandles.lookup());
159+
: ownLookupIn(field.getDeclaringClass());
145160
handle = access.unreflectVarHandle(field);
146161
}
147162
catch (final RuntimeException | IllegalAccessException exc) {
@@ -151,6 +166,23 @@ private synchronized VarHandle handle() {
151166
return handle;
152167
}
153168

169+
/**
170+
* Gets a lookup into the given class using this module's own access.
171+
* <p>
172+
* NB: {@code privateLookupIn} requires this module to <em>read</em> the
173+
* target's module as well as the package being open to it. A library never
174+
* declares a read edge to its callers, so it has to add one at runtime -
175+
* which only its own code may do. Callers with a container avoid all this
176+
* by passing a lookup from there instead.
177+
* </p>
178+
*/
179+
private static Lookup ownLookupIn(final Class<?> type)
180+
throws IllegalAccessException
181+
{
182+
FieldParameterMember.class.getModule().addReads(type.getModule());
183+
return MethodHandles.privateLookupIn(type, MethodHandles.lookup());
184+
}
185+
154186
private String cannotAccess() {
155187
return "Cannot access " + field.getDeclaringClass().getName() + "." + //
156188
field.getName() + ". Does its module declare `opens " + field

0 commit comments

Comments
 (0)