Skip to content

Commit 49a5723

Browse files
ctruedenclaude
andcommitted
The legacy bridge, and the split package it found
`scijava-bridge` presents SciJava Common's modules as SciJava3 commands, so an application can show, harvest and run everything the old world already knows about -- every ImageJ2 command, every Fiji plugin ported to the module system -- beside its own commands and its scripts, in its own menus and dialogs, with neither side changed. It is the only component that depends on SciJava Common, and the dependency goes one way. Before any of it could work: **org.scijava.command was a split package**. SciJava Common owns it and SciJava3 had claimed it too. Two modules containing one package is a JVM that refuses to start; on the classpath it is worse, two different `Command` interfaces under one name with the first jar winning. Fiji could never have loaded both. The incarnation rule was applied to io3, convert3 and script3 and simply missed here, so this renames the component to scijava-command3 / org.scijava.command3, version 3.0.0-SNAPSHOT. Checking all 77 SciJava Common packages against all 34 SciJava3 ones: that was the only collision. What else the bridge turned up, each of which is a translation rather than a compromise: - SciJava Common's @parameter means both "this is an input" and "inject this service"; its harvester tells them apart by having preprocessors fill the services first. SciJava3 split the annotations so the question never arises, so the bridge answers it once: a Service or Context parameter is the legacy context's business and never reaches a dialog. Without this, every DynamicCommand dialog would show four spurious rows. - DynamicCommand needs no SciJava3 equivalent to be supported. Its parameters live on the module's own description, so the bridge initializes at create() time, as InitPreprocessor does, and reads that description. What SciJava3 declines to offer as a way of writing commands, it presents without trouble. - Callbacks and validators resolve by name through behavior(String) -- the SPI that exists so scripts could have callbacks turns out to be exactly what legacy commands need. SciJava Common's two validator protocols (throw, or return a message) collapse into SciJava3's one, and its "Error executing method" wrapper is unwrapped so the user sees what the validator actually said. - Accelerators are translated rather than passed through: Accelerator.toString() renders Swing's "control L", which Swing parses back and JavaFX does not. Written ^L, all three bindings agree. - Menu paths are rebuilt from their entries, getMenuString() rendering "A > B > C" with spaces that would end up inside the labels. - LegacyContext keeps SciJava Common types out of the bridge's signatures: a JPMS module would otherwise need `requires org.scijava` merely to hold the context, and a test-scoped use cannot say that at all. The bridge's tests stop at the dialog *model*, which is where its claim ends; that a correct model becomes correct widgets is what the bindings' shared conformance suite already establishes three times over. NB: the monorepo already has a scijava-legacy, for ops and ImageJ2 interop, which `requires net.imagej`. Keeping the command bridge separate is deliberate: an application wanting Fiji's existing commands in its menus should not thereby acquire ImageJ2. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 7df0f46 commit 49a5723

52 files changed

Lines changed: 1714 additions & 91 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/migration-plan.md‎

Lines changed: 49 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -693,7 +693,7 @@ unless it says there is no replacement at all, which it says explicitly.
693693
| Layer | Contents | Depends on |
694694
| --- | --- | --- |
695695
| **0. Foundation** (built) | `spi`, `common3`, `collections`, `priority`, `progress`, `concurrent`, `discovery`, `index`, `struct`, `io3`, `events`, `context`, `execute` | nothing above |
696-
| **1. Application model** (built, less `scijava-desktop`) | `scijava-command` (a struct plus presentation metadata, the menu tree and its walk), `scijava-ui3` (toolkit-agnostic contracts), `scijava-desktop` | layer 0 |
696+
| **1. Application model** (built, less `scijava-desktop`) | `scijava-command3` (a struct plus presentation metadata, the menu tree and its walk), `scijava-ui3` (toolkit-agnostic contracts), `scijava-desktop` | layer 0 |
697697
| **2. Toolkit bindings** | `scijava-awt` (and the AWT platform layer the others use), `scijava-swing`, `scijava-javafx`, headless | layer 1 |
698698
| **3. Application** | Fiji: which menus exist, branding, update sites, defaults | layer 2 |
699699

@@ -759,8 +759,52 @@ So the **one-way legacy bridge matters more than its deferral implies**: for
759759
Fiji to run on SJ3 before every command is ported, an SJ3 application must
760760
present SciJava Common `ModuleInfo`s as SJ3 commands — metadata flowing both
761761
ways, dependency flowing one way. That is what makes the migration incremental
762-
rather than a big bang, and it should be sequenced *with* layer 1 rather than
763-
after it.
762+
rather than a big bang.
763+
764+
**`scijava-bridge` is built**, and it is the only component that depends on
765+
SciJava Common. `Legacy.commands(context)` turns everything a legacy context
766+
can run into `CommandInfo`s, which go into an application's menus beside its
767+
own commands and its scripts; `LegacyContext.start()` does the same without
768+
the caller naming a SciJava Common type at all.
769+
770+
What it found, which is why bridges are worth building early:
771+
772+
- **`org.scijava.command` was a split package.** SciJava Common owns it, and
773+
SciJava3 had claimed it too. Two modules containing one package is a JVM
774+
that refuses to start, and on the classpath it is worse — two different
775+
`Command` interfaces with one name, first jar wins. The incarnation rule was
776+
applied to `io3`, `convert3` and `script3` and simply missed here. Hence
777+
`scijava-command3` / `org.scijava.command3`, and the two can now sit on the
778+
module path together. **No other package collides**: 77 SciJava Common
779+
packages against 34 SciJava3 ones, and that was the only one.
780+
- **SciJava Common's `@Parameter` means two things**, "this is an input" and
781+
"inject this service", and its harvester tells them apart by having
782+
preprocessors fill the services first. SciJava3 split the annotations so the
783+
question never arises, so the bridge answers it once: a parameter whose type
784+
is a `Service` or a `Context` is the legacy context's business and never
785+
reaches a dialog.
786+
- **`DynamicCommand` needs no equivalent to be supported.** Its parameters
787+
live on the *module's* own description rather than the shared one, so the
788+
bridge initializes at `create()` time (as SciJava Common's `InitPreprocessor`
789+
does) and reads the module's description. What SciJava3 declines to *offer*
790+
as a way of writing commands, it presents without trouble.
791+
- **Callbacks and validators translate by name.** SciJava3 names a behavior
792+
and asks the executable what the name means; for a legacy command it means a
793+
method on the delegate object, which SciJava Common knows how to invoke. A
794+
legacy dialog therefore behaves in a SciJava3 application exactly as it did
795+
in an ImageJ2 one. SciJava Common's two validator protocols — throw, or
796+
return a message — collapse into SciJava3's one, and the wrapper exception's
797+
unhelpful "Error executing method" is unwrapped so the user sees what the
798+
validator actually said.
799+
- **Accelerators are translated, not passed through.** `Accelerator.toString()`
800+
renders Swing's format (`"control L"`), which Swing would parse back and
801+
JavaFX would not; written as `^L`, all three bindings agree.
802+
- **Menu paths are rebuilt from their entries**, because
803+
`MenuPath.getMenuString()` renders `"A > B > C"` with spaces that would end
804+
up inside the menu labels.
805+
- **The bridge's own API names no SciJava Common type**, which is not tidiness:
806+
a JPMS module would otherwise have to `requires org.scijava` merely to hold
807+
the context, and a test-scoped use cannot say that at all.
764808

765809
### On the words
766810

@@ -1030,7 +1074,7 @@ widgets and watching its callbacks fire.
10301074
to put the whole stack together - commands found through the annotation
10311075
index, arranged by `MenuTree`, rendered by `SwingMenus`, run by `Runner`,
10321076
filled in by `SwingInputHarvester` - and starting it loads no command class.
1033-
`MenuCreator`/`Menus` (in `scijava-command`, beside the tree they walk) hold
1077+
`MenuCreator`/`Menus` (in `scijava-command3`, beside the tree they walk) hold
10341078
the toolkit-free part of the walk, so a second toolkit implements four
10351079
methods and inherits the rest.
10361080

@@ -1094,7 +1138,7 @@ widgets and watching its callbacks fire.
10941138
written the same bookkeeping - find the node in the *current* tree, write
10951139
through the model, do not mistake a refresh for the user typing. Two would
10961140
have been a coincidence.
1097-
- `Accelerator` moved into `scijava-command`, because Swing wants a
1141+
- `Accelerator` moved into `scijava-command3`, because Swing wants a
10981142
`KeyStroke`, JavaFX a `KeyCombination` and AWT a `MenuShortcut`: three ways
10991143
of *saying* a shortcut, one thing being said. A binding that parses `^+C`
11001144
itself is a binding that can disagree about what it means.

‎docs/migration.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ A **dropped** row is a successful outcome, not a gap.
8686
| `Contextual`, `AbstractContextual`, `NullContextException` | dropped — a service receives its context in `Service.initialize(Context)`, so it need not carry one, and there is no null-context state to report | dropped |
8787
| `Gateway`, `AbstractGateway`, `SciJava` | Phase 2, if retained at all | open |
8888
| `Instantiable`, `InstantiableException` | subsumed by `Discovery` | planned |
89-
| `BasicDetails`, `AbstractBasicDetails`, `UIDetails`, `AbstractUIDetails`, `MenuEntry`, `MenuPath` | `scijava-command` presentation metadata (layer 1). All of it survives — menu path, label, icon, accelerator, weight, selection group, visibility, enablement — but as attributes in the annotation index rather than an inheritance chain every plugin extends | planned |
89+
| `BasicDetails`, `AbstractBasicDetails`, `UIDetails`, `AbstractUIDetails`, `MenuEntry`, `MenuPath` | `scijava-command3` presentation metadata (layer 1). All of it survives — menu path, label, icon, accelerator, weight, selection group, visibility, enablement — but as attributes in the annotation index rather than an inheritance chain every plugin extends | planned |
9090
| `Validated`, `ValidityProblem` | execution layer (Phase 3) | open |
9191
| `Optional` | `scijava-optional` (satellite repo, moves in later) | open |
9292

@@ -121,14 +121,15 @@ 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` | `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 |
124+
| the legacy bridge | `org.scijava.bridge`: `LegacyCommandInfo` presents a SciJava Common `ModuleInfo` as a SciJava3 `CommandInfo`, so every existing ImageJ2 command and Fiji plugin appears in SciJava3 menus and runs through the SciJava3 runner, harvester and dialogs unchanged. Service and context parameters are filtered out (SciJava Common's `@Parameter` meant both "input" and "inject"); `DynamicCommand`s work because the module's own description is read after initialization; callbacks and validators resolve by name through `behavior(String)`. The dependency goes one way and lives only here | ported |
124125
| `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` - 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 |
126+
| `command` | `org.scijava.command3`: `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 |
126127
| `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 |
127128
| `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 |
128129
| `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 |
129130
| `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 |
130131
| `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`: `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 |
132+
| `menu` (`MenuCreator`, `AbstractMenuCreator`, `MenuService`, `ShadowMenu`) | `org.scijava.command3`: `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 |
132133
| `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 |
133134
| `input`, `tool` | UI-agnostic facades on `scijava-events` (Phase 4) | planned |
134135
| `display` | overhauled, not ported (Phase 4) | open |

‎pom.xml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,9 +58,10 @@
5858
<!-- End implicit dependencies -->
5959

6060
<module>scijava-awt</module>
61+
<module>scijava-bridge</module>
6162
<module>scijava-code-api</module>
6263
<module>scijava-collections</module>
63-
<module>scijava-command</module>
64+
<module>scijava-command3</module>
6465
<module>scijava-common3</module>
6566
<module>scijava-context</module>
6667
<module>scijava-convert3</module>

‎scijava-awt/pom.xml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@
8686
<license.copyrightOwners>SciJava developers.</license.copyrightOwners>
8787

8888
<!-- Note: These versions must match across all component POMs! -->
89-
<scijava-command.version>1.0.0-SNAPSHOT</scijava-command.version>
89+
<scijava-command3.version>3.0.0-SNAPSHOT</scijava-command3.version>
9090
<scijava-context.version>1.0.0-SNAPSHOT</scijava-context.version>
9191
<scijava-discovery.version>1.0.1-SNAPSHOT</scijava-discovery.version>
9292
<scijava-index.version>1.0.0-SNAPSHOT</scijava-index.version>
@@ -108,8 +108,8 @@
108108
</dependency>
109109
<dependency>
110110
<groupId>org.scijava</groupId>
111-
<artifactId>scijava-command</artifactId>
112-
<version>${scijava-command.version}</version>
111+
<artifactId>scijava-command3</artifactId>
112+
<version>${scijava-command3.version}</version>
113113
</dependency>
114114
<dependency>
115115
<groupId>org.scijava</groupId>

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@
3737

3838
requires transitive java.desktop;
3939
requires transitive org.scijava.ui3;
40-
requires transitive org.scijava.command;
40+
requires transitive org.scijava.command3;
4141
requires transitive org.scijava.context;
4242
requires org.scijava.discovery;
4343
requires org.scijava.priority;

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

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

40-
import org.scijava.command.Accelerator;
41-
import org.scijava.command.CommandInfo;
42-
import org.scijava.command.MenuCreator;
43-
import org.scijava.command.MenuTree;
44-
import org.scijava.command.Menus;
40+
import org.scijava.command3.Accelerator;
41+
import org.scijava.command3.CommandInfo;
42+
import org.scijava.command3.MenuCreator;
43+
import org.scijava.command3.MenuTree;
44+
import org.scijava.command3.Menus;
4545
import org.slf4j.Logger;
4646
import org.slf4j.LoggerFactory;
4747

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545

4646
import org.junit.jupiter.api.Test;
4747
import org.junit.jupiter.api.condition.DisabledIf;
48-
import org.scijava.command.MenuTree;
48+
import org.scijava.command3.MenuTree;
4949
import org.scijava.ui3.test.MenuConformance;
5050

5151
/**

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,9 @@
4242
import java.util.concurrent.Future;
4343
import java.util.stream.Collectors;
4444

45-
import org.scijava.command.Commands;
46-
import org.scijava.command.CommandInfo;
47-
import org.scijava.command.MenuTree;
45+
import org.scijava.command3.Commands;
46+
import org.scijava.command3.CommandInfo;
47+
import org.scijava.command3.MenuTree;
4848
import org.scijava.context.Context;
4949
import org.scijava.execute.ExecutionResult;
5050
import org.scijava.execute.Runner;

0 commit comments

Comments
 (0)