Skip to content

Commit 7df0f46

Browse files
ctruedenclaude
andcommitted
Name the general thing what users call it: CommandInfo
A command is anything a user can run, with declared parameters -- whether its implementation is a class or a script. So that is what `CommandInfo` means now, and the class-based kind is `ClassCommandInfo`. The old names said the opposite. `Command` claimed in its javadoc that a script is a command whose implementation is source in some language, while the type system had `Command` meaning the Java-class kind specifically and scripts attaching one level lower, at `Executable`. The javadoc was the intent; the types were what got built when scripts arrived after the command layer. This reconciles them in the direction of the intent. Not `JavaCommandInfo`: Kotlin, Groovy and Scala classes implement `Command` just as well, so the distinction is class versus script, not Java versus everything. And `ClassCommandInfo` rather than `CommandClassInfo`, so that the family reads as a series -- the siblings coming are `ScriptCommandInfo` and `LegacyCommandInfo`. The alternative was to believe the types instead: call the general thing `ExecutableInfo` and let "command" keep meaning the class kind. That is SciJava Common's design with "executable" substituted for "module" -- one word users do not say traded for another. `Command` the interface is now documented as what it is: the way to write a command as a class, not the definition of one. A script implements nothing at all and is no less a command for it. docs/migration-plan.md gains an "On the words" table, so the vocabulary stops drifting: command, class command, script command, executable, module (JPMS only), plugin. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent d8b632f commit 7df0f46

20 files changed

Lines changed: 426 additions & 381 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -762,6 +762,32 @@ ways, dependency flowing one way. That is what makes the migration incremental
762762
rather than a big bang, and it should be sequenced *with* layer 1 rather than
763763
after it.
764764

765+
### On the words
766+
767+
The vocabulary is settled, and deliberately smaller than SciJava Common's:
768+
769+
| word | means |
770+
| --- | --- |
771+
| **command** | anything a user can run, with declared parameters: `CommandInfo` |
772+
| **class command** | one whose implementation is a class - Java, Kotlin, Groovy, any of them: `ClassCommandInfo`, read from the annotation index |
773+
| **script command** | one whose implementation is source in some language, read by `scijava-script3` |
774+
| **executable** | the layer below: something with parameters that runs, knowing nothing of menus or discovery (`org.scijava.execute.Executable`) |
775+
| **module** | a JPMS module, and nothing else |
776+
| **plugin** | anything discovered by `@Plugin` - a widget factory, a converter, a preprocessor. A command is one kind |
777+
778+
What went away: *module* in SciJava Common's sense (it is now "command",
779+
which is what users already called it); *macro*, which now means the ImageJ
780+
1.x macro language and nothing here; and *extension*, which was never a
781+
technical term.
782+
783+
The `Command` interface is **not** the definition of a command - `CommandInfo`
784+
is. It is how to write one as a class, and a script implements nothing at all
785+
while being no less a command. Which is why the general type went from
786+
`ExecutableInfo` to `CommandInfo`, and the class-based one from `CommandInfo`
787+
to `ClassCommandInfo`: naming the general thing after what users actually call
788+
it costs one word, and the alternative was SciJava Common's design with
789+
"executable" substituted for "module".
790+
765791
### Conversion
766792

767793
**`scijava-convert3`** (`org.scijava.convert3`) is built, and deliberately
@@ -850,8 +876,8 @@ widgets and watching its callbacks fire.
850876
a `#!` line, which is what settles the languages sharing an extension -
851877
`.py` being Jython or Python depending on which is meant. Saying nothing
852878
means the extension decides, as before.
853-
- **`ExecutableInfo` is how an application takes more than one source.** A
854-
`CommandInfo` is one; `ExecutableInfo.of(executable, attrs)` makes one out
879+
- **`CommandInfo` is how an application takes more than one source.** A
880+
`ClassCommandInfo` is one; `CommandInfo.of(executable, attrs)` makes one out
855881
of a script and its directives; a SciJava Common `ModuleInfo` will make one
856882
through the bridge. An application gathers what it can run from as many
857883
sources as it has, and nothing downstream learns there was more than one.

‎docs/migration.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -122,13 +122,13 @@ A **dropped** row is a successful outcome, not a gap.
122122
| `thread` | EDT dispatch belongs with the UI layer (Phase 4); parallelism is `org.scijava.concurrent` | planned |
123123
| `convert` | `org.scijava.convert3`: `Converter` asks one question - can you turn *this value* into *that type* - where SciJava Common had eight `canConvert` overloads and a `ConversionRequest` to carry the combinations. `ConvertService` becomes `Converters`, backed by plain `ServiceLoader` so that conversion sits *below* the container: parameter binding converts, and a script or command line supplies strings for everything. `DefaultConverter`'s pile of special cases becomes one converter per concern (cast, number, string, to-string, array, collection, constructor, file/path), each contributable and orderable by priority. `Converter.of(String.class, Foo.class, Foo::parse)` covers the common case in a line | ported |
124124
| `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` | `org.scijava.command`: `Command` is a `Runnable` whose `@Parameter` fields are its struct; `@Menu` (repeatable) carries the presentation metadata, read from the annotation index without loading the class. `CommandInfo` replaces `ModuleInfo` and needs no `Context`; `MenuTree` replaces `ShadowMenu`. There is no `DynamicCommand`: see `choicesFrom` and `@Group(membersFrom)` | ported |
125+
| `command` | `org.scijava.command`: `Command` is a `Runnable` whose `@Parameter` fields are its struct; `@Menu` (repeatable) carries the presentation metadata, read from the annotation index without loading the class. `CommandInfo` replaces `ModuleInfo` and needs no `Context` - a command is anything a user can run, whether its implementation is a class (`ClassCommandInfo`, read from the index) or a script; `MenuTree` replaces `ShadowMenu`. There is no `DynamicCommand`: see `choicesFrom` and `@Group(membersFrom)` | ported |
126126
| `script`, `script.process` | `org.scijava.script3`: `ScriptLanguage`/`ScriptSession` are the SPI, with `JsrLanguage` making every JSR-223 engine on the classpath available for free; GraalVM polyglot and Appose are further languages, not replacements. `ScriptInfo`/`ScriptModule` become `ScriptExecutable`, an ordinary `Executable`, so a script runs through the same `Runner`, preprocessors, dialogs and menus as a Java command. `ScriptService` has no equivalent: `Scripts.get().of(path)` is a line. The `#@` header syntax is unchanged, and declaration lines are blanked rather than removed so the language's error messages keep pointing at the right line. The processor chain (`ScriptProcessor` and friends) is not ported: it existed to rewrite scripts before evaluation, and parameters plus a shebang are all it was actually used for. `ScriptREPL`, `ScriptInterpreter`, `AutoCompleter` and `CodeGenerator` await the script editor. `ScriptFinder` is ported: it reads `#@script` directives and falls back to the directory hierarchy for a menu path, handing an application metadata rather than menus, since this component knows nothing about menus | ported |
127127
| `widget` (`InputWidget`, `InputPanel`, `InputHarvester`, `WidgetModel`, `WidgetStyle`) | `org.scijava.ui3`: `Widget` is a view of a `ParameterNode`, `WidgetFactory` a discoverable `@Plugin`, `WidgetPanel` a widget holding widgets (so a group nests with no special case), and `WidgetPanels` walks the tree for every toolkit. `WidgetModel` has no equivalent - a widget reads the `ParameterModel` and the node directly, and `WidgetStyle`'s parsing is `Widgets.isStyle`/`styleValue`. `InputHarvester` is a `Preprocessor` that declines the run when the user dismisses the dialog, rather than setting a `canceled` flag on itself | ported |
128128
| `ui.awt` (satellite repo `scijava-ui-awt`) | `org.scijava.awt`: the widget set in pure `java.awt` - no spinner, so the number widget is a field and a scroll bar - plus `Edt`, the first of the AWT platform layer that the Swing binding shares. `AWTColors`, `AWTWindows`, `AWTClipboard`, `AWTInputEventDispatcher` and the drag-and-drop dispatchers belong there too, when the `input`/`tool` layer arrives; the `AWTUI`/`AWTApplicationFrame`/`AWTStatusBar` shell classes await the application layer | ported |
129129
| `ui.javafx` (satellite repo `scijava-ui-javafx`) | `org.scijava.javafx`: the same widget set as the Swing binding, plus `FxThread` for JavaFX's application thread. `JavaFXKeys`'s key-code mapping is worth keeping when the `input`/`tool` layer arrives; `JavaFXMenuCreator` is superseded by `FxMenus`, some 40 lines against `MenuCreator` | ported |
130130
| `ui.swing.widget` | `org.scijava.swing`: number (spinner, with an optional slider or scroll bar and labelled ticks), text (field, password, area, and `BigInteger`/`BigDecimal`, which a spinner cannot step), toggle, choice, file, message, and the panel and dialog. `SpinnerBigDecimalModel`, `SpinnerBigIntegerModel`, `SpinnerTypedNumberModel` and `SpinnerNumberModelFactory` have no equivalent: `SpinnerNumberModel` already steps in the type of the value it holds, and arbitrary precision goes to the text widget. MigLayout is gone, in favor of `GridBagLayout`: one fewer dependency, and one fewer automatic module. The button, color, date, file-list and radio-choice widgets are not ported yet - each earns its place when something asks for it | ported |
131-
| `menu` (`MenuCreator`, `AbstractMenuCreator`, `MenuService`, `ShadowMenu`) | `org.scijava.command`: `ExecutableInfo` is anything an application can run (a menu path being optional), `MenuTree` arranges the subset that has one, and `MenuCreator`/`Menus` are the toolkit-free walk, with `SwingMenus`, `FxMenus` and `AwtMenus` implementing it. `MenuService` has no equivalent: a menu bar is `MenuTree.of(Commands.discover(context))`, which is a line rather than a service | ported |
131+
| `menu` (`MenuCreator`, `AbstractMenuCreator`, `MenuService`, `ShadowMenu`) | `org.scijava.command`: `CommandInfo` is anything a user can run (a menu path being optional), `MenuTree` arranges the subset that has one, and `MenuCreator`/`Menus` are the toolkit-free walk, with `SwingMenus`, `FxMenus` and `AwtMenus` implementing it. `MenuService` has no equivalent: a menu bar is `MenuTree.of(Commands.discover(context))`, which is a line rather than a service | ported |
132132
| `ui`, `menu` | `scijava-ui3` (toolkit-agnostic contracts) and `scijava-menu` (the menu tree), with `ApplicationFrame`/`Desktop`/`StatusBar`/`ToolBar` as contracts there and implementations in the toolkit bindings. Dropped from the *core*, not from the stack — see the layering section of [migration-plan.md](migration-plan.md) | planned |
133133
| `input`, `tool` | UI-agnostic facades on `scijava-events` (Phase 4) | planned |
134134
| `display` | overhauled, not ported (Phase 4) | open |

‎scijava-awt/src/main/java/org/scijava/awt/AwtMenus.java‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
import java.util.function.Consumer;
3939

4040
import org.scijava.command.Accelerator;
41-
import org.scijava.command.ExecutableInfo;
41+
import org.scijava.command.CommandInfo;
4242
import org.scijava.command.MenuCreator;
4343
import org.scijava.command.MenuTree;
4444
import org.scijava.command.Menus;
@@ -54,15 +54,15 @@ public class AwtMenus implements MenuCreator<MenuBar, Menu> {
5454

5555
private static final Logger log = LoggerFactory.getLogger(AwtMenus.class);
5656

57-
private final Consumer<ExecutableInfo> onSelect;
57+
private final Consumer<CommandInfo> onSelect;
5858

59-
public AwtMenus(final Consumer<ExecutableInfo> onSelect) {
59+
public AwtMenus(final Consumer<CommandInfo> onSelect) {
6060
this.onSelect = onSelect;
6161
}
6262

6363
/** Builds a menu bar holding the given menu tree. */
6464
public static MenuBar create(final MenuTree root,
65-
final Consumer<ExecutableInfo> onSelect)
65+
final Consumer<CommandInfo> onSelect)
6666
{
6767
return Menus.build(root, new MenuBar(), new AwtMenus(onSelect));
6868
}
@@ -83,7 +83,7 @@ public Menu subMenu(final MenuTree node, final Menu parent) {
8383

8484
@Override
8585
public void item(final MenuTree leaf, final Menu parent) {
86-
final ExecutableInfo command = leaf.entry().orElseThrow();
86+
final CommandInfo command = leaf.entry().orElseThrow();
8787
final MenuItem item = new MenuItem(leaf.label());
8888
shortcut(command.accelerator().orElse(null)).ifPresent(item::setShortcut);
8989
// NB: AWT menu items have no icon at all, so iconPath is ignored here.

‎scijava-awt/src/test/java/org/scijava/awt/AwtShell.java‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@
4343
import java.util.stream.Collectors;
4444

4545
import org.scijava.command.Commands;
46-
import org.scijava.command.ExecutableInfo;
46+
import org.scijava.command.CommandInfo;
4747
import org.scijava.command.MenuTree;
4848
import org.scijava.context.Context;
4949
import org.scijava.execute.ExecutionResult;
@@ -72,15 +72,15 @@
7272
public class AwtShell {
7373

7474
private final Context context = Context.create();
75-
private final java.util.List<ExecutableInfo> commands = entries();
75+
private final java.util.List<CommandInfo> commands = entries();
7676
private final Runner runner;
7777

7878
private final Frame frame = new Frame("SciJava");
7979
private final Label status = new Label("Ready");
8080
private final TextField search = new TextField(24);
8181
private final List matches = new List(8);
8282

83-
private java.util.List<ExecutableInfo> shown = java.util.List.of();
83+
private java.util.List<CommandInfo> shown = java.util.List.of();
8484

8585
public AwtShell() {
8686
runner = Runner.of(java.util.List.of(AwtInputHarvester.of(context)),
@@ -118,14 +118,14 @@ public static void main(final String... args) {
118118
// -- Helper methods --
119119

120120
/** Gathers what this application can run: commands, and scripts. */
121-
private java.util.List<ExecutableInfo> entries() {
122-
final java.util.List<ExecutableInfo> entries = new java.util.ArrayList<>(
121+
private java.util.List<CommandInfo> entries() {
122+
final java.util.List<CommandInfo> entries = new java.util.ArrayList<>(
123123
Commands.discover(context));
124124
final java.net.URL url = AwtShell.class.getResource("/scripts");
125125
if (url != null) {
126126
try {
127127
new org.scijava.script3.ScriptFinder().find(java.nio.file.Paths.get(url
128-
.toURI())).forEach(found -> entries.add(ExecutableInfo.of(found.script(),
128+
.toURI())).forEach(found -> entries.add(CommandInfo.of(found.script(),
129129
found.metadata())));
130130
}
131131
catch (final java.net.URISyntaxException exc) {
@@ -153,7 +153,7 @@ private void runSelected() {
153153
}
154154

155155
/** Runs a command, and says what came back. */
156-
private void run(final ExecutableInfo command) {
156+
private void run(final CommandInfo command) {
157157
status.setText("Running " + command.label() + "...");
158158
final Future<ExecutionResult> future = runner.run(command, Map.of());
159159
new Thread(() -> {
@@ -162,7 +162,7 @@ private void run(final ExecutableInfo command) {
162162
}, "shell-" + command.name()).start();
163163
}
164164

165-
private static String describe(final ExecutableInfo command) {
165+
private static String describe(final CommandInfo command) {
166166
return command.menuPath().map(path -> path.replace(">", " ▸ ")) //
167167
.orElseGet(() -> command.label() + " (not in any menu)");
168168
}
Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
/*
2+
* #%L
3+
* Discoverable commands, with the metadata a menu is built from.
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.command;
31+
32+
import java.util.Map;
33+
import java.util.Optional;
34+
35+
import org.scijava.context.Access;
36+
import org.scijava.discovery.Discovery;
37+
import org.scijava.execute.Executable;
38+
import org.scijava.execute.ExecutableInstance;
39+
import org.scijava.execute.Executables;
40+
import org.scijava.struct.Struct;
41+
42+
/**
43+
* A command as the application knows it before running one: its identity, its
44+
* parameters, and how it should appear in a menu.
45+
* <p>
46+
* The presentation metadata is read from the annotation index, so listing
47+
* every command and building a menu from them loads no command classes at all.
48+
* {@link #struct()} and {@link #create()} are the points at which the class is
49+
* finally needed.
50+
* </p>
51+
* <p>
52+
* NB: SciJava Common called this {@code ModuleInfo}, and its
53+
* {@code ClassCommandInfo} was one implementation. The names have shifted by one:
54+
* "module" is now a JPMS module, so the general description is
55+
* {@link Executable}, and this is the command-shaped view of it.
56+
* </p>
57+
* <p>
58+
* NB: a command whose implementation is a <em>class</em> - which is not the
59+
* same as a Java class, Kotlin and Groovy and Scala classes being just as
60+
* welcome. The other kind is a script, which reaches the same menus as a
61+
* {@link CommandInfo} built by {@link CommandInfo#of}.
62+
* </p>
63+
*
64+
* @author Curtis Rueden
65+
*/
66+
public class ClassCommandInfo implements CommandInfo {
67+
68+
private final Discovery<Command> discovery;
69+
private final Map<String, String> menu;
70+
private Executable delegate;
71+
72+
ClassCommandInfo(final Discovery<Command> discovery,
73+
final Map<String, String> menu)
74+
{
75+
this.discovery = discovery;
76+
this.menu = menu;
77+
}
78+
79+
// -- Metadata, readable without loading the class --
80+
81+
/** Gets the command's implementation class name. */
82+
public String className() {
83+
return discovery.implClassName();
84+
}
85+
86+
/** Gets where this command sits in the menus, if anywhere. */
87+
@Override
88+
public Optional<String> menuPath() {
89+
return attr("path");
90+
}
91+
92+
/** Gets the label to display, defaulting to the last menu path element. */
93+
@Override
94+
public String label() {
95+
return menuPath() //
96+
.map(path -> path.substring(path.lastIndexOf('>') + 1)) //
97+
.orElseGet(this::name);
98+
}
99+
100+
/** Gets this command's keyboard shortcut, if it has one. */
101+
@Override
102+
public Optional<String> accelerator() {
103+
return attr("accelerator");
104+
}
105+
106+
/** Gets this command's icon resource, if it has one. */
107+
@Override
108+
public Optional<String> iconPath() {
109+
return attr("iconPath");
110+
}
111+
112+
/** Gets how this command sorts among its menu siblings. */
113+
@Override
114+
public double weight() {
115+
return attr("weight").map(Double::parseDouble) //
116+
.orElse(Double.POSITIVE_INFINITY);
117+
}
118+
119+
/** Gets whether this command should appear in menus. */
120+
@Override
121+
public boolean isVisible() {
122+
return !"false".equals(menu.get("visible"));
123+
}
124+
125+
/** Gets the priority with which this command was declared. */
126+
public double priority() {
127+
return discovery.priority();
128+
}
129+
130+
/** Gets a menu attribute by name. */
131+
public Optional<String> attr(final String key) {
132+
final String value = menu.get(key);
133+
return value == null || value.isEmpty() ? Optional.empty() //
134+
: Optional.of(value);
135+
}
136+
137+
// -- Executable methods --
138+
139+
@Override
140+
public String name() {
141+
return className();
142+
}
143+
144+
@Override
145+
public Struct struct() {
146+
return delegate().struct();
147+
}
148+
149+
@Override
150+
public ExecutableInstance create() {
151+
return delegate().create();
152+
}
153+
154+
@Override
155+
public String toString() {
156+
return className() + menuPath().map(p -> " [" + p + "]").orElse("");
157+
}
158+
159+
/**
160+
* Gets the executable behind this command, loading the class on first use.
161+
* <p>
162+
* NB: everything above this line answers from the index alone. This is
163+
* where a menu stops being free.
164+
* </p>
165+
*/
166+
private synchronized Executable delegate() {
167+
if (delegate == null) {
168+
final Class<? extends Command> type = discovery.type();
169+
// NB: the lookup comes from the context, so a command's package need
170+
// only be opened to org.scijava.context -- not additionally to the
171+
// execution layer that reads its @Parameter fields.
172+
delegate = Executables.of(type, Access.lookupIn(type));
173+
}
174+
return delegate;
175+
}
176+
}

0 commit comments

Comments
 (0)