Skip to content

Commit 95b4e57

Browse files
ctruedenclaude
andcommitted
docs: say how Fiji gets built on SciJava3
The plan kept saying "drop" about the application shell without saying where it goes instead, which reads as though Fiji loses its menus. It does not: the problem with SciJava Common was never that it had menus, but that the core had them, so a library wanting only plugin discovery inherited MenuPath, Display and a transitive AWT flavour. Adds a layering section: foundation (built) / application model / toolkit bindings / application, with only the bindings importing AWT or Swing. All of the presentation metadata survives -- menu path, label, icon, accelerator, weight, selection group, visibility, enablement -- since Fiji's menus are built from it. What changes is that it becomes attributes in the annotation index rather than the BasicDetails/UIDetails/AbstractUIDetails inheritance chain every plugin extends. Notes that the expensive part is already solved: SciJava Common builds its menu from ModuleInfo, naming classes without loading them and loading on demand, which is exactly the implClassName()/type()/get() split of Discovery. The other seams -- harvesting as a Preprocessor, displays as a Postprocessor, input events with Consumable -- were built in phases 1-3 with this in mind. Also records that the real risk is migration rather than architecture: hundreds of commands across dozens of repositories cannot update on a flag day, so the one-way legacy bridge matters more than its deferral implies and should be sequenced with layer 1 rather than after it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 1e1e662 commit 95b4e57

2 files changed

Lines changed: 91 additions & 5 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 89 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -674,6 +674,90 @@ No application context required by anything in this phase.
674674
`#@` parameters parse into structs. The external `scripting-*` repositories
675675
migrate onto the facade.
676676

677+
## Layering: how Fiji gets built on SJ3
678+
679+
The problem with SciJava Common was never that it had menus. It is that the
680+
*core* had them: one artifact bundles the plugin framework, the application
681+
container, menus, displays, tools and a UI opinion, so a library wanting only
682+
plugin discovery inherits `MenuPath`, `Display` and a transitive AWT flavour.
683+
684+
The remedy is **stratification, not deletion**. Everything Fiji needs still
685+
exists; it moves to a layer that can be depended on separately. Where this
686+
document says a subsystem is "dropped", that means *dropped from the core* —
687+
unless it says there is no replacement at all, which it says explicitly.
688+
689+
| Layer | Contents | Depends on |
690+
| --- | --- | --- |
691+
| **0. Foundation** (built) | `spi`, `common3`, `collections`, `priority`, `progress`, `concurrent`, `discovery`, `index`, `struct`, `io3`, `events`, `context`, `execute` | nothing above |
692+
| **1. Application model** (to build) | `scijava-command` (a struct plus presentation metadata), `scijava-menu` (the menu tree), `scijava-ui-api` (toolkit-agnostic contracts), `scijava-desktop` | layer 0 |
693+
| **2. Toolkit bindings** | `scijava-ui-swing`, JavaFX, headless | layer 1 |
694+
| **3. Application** | Fiji: which menus exist, branding, update sites, defaults | layer 2 |
695+
696+
Only layer 2 imports AWT or Swing. Layer 0 never mentions a user interface, so
697+
headless is not a mode — it is what the core does.
698+
699+
### The mechanisms are already in place
700+
701+
The machinery the application shell needs was built in phases 1-3, and in
702+
several cases was built *because* of it:
703+
704+
| Fiji needs | Built |
705+
| --- | --- |
706+
| Menus over hundreds of commands, without loading their classes | the `@Plugin` index, and `Discovery.implClassName()`/`attrs()` before `type()`/`get()` |
707+
| Parameter dialogs | `Preprocessor`: harvesting is a preprocessing step |
708+
| "The user pressed Cancel" | `Execution.decline(reason)`, reported by `ExecutionResult` |
709+
| Showing outputs | `Postprocessor`: the `DisplayPostprocessor` seam |
710+
| Tool and input events, one handler claiming a keystroke | `scijava-events`, with `Consumable` |
711+
| Menu ordering | `scijava-priority`, plus a weight attribute in the index |
712+
713+
NB: SciJava Common builds its menu from `ModuleInfo`, whose
714+
`getDelegateClassName()` names the class without loading it and whose
715+
`loadDelegateClass()` loads on demand. That is exactly the
716+
`implClassName()`/`type()`/`get()` split of `Discovery`, so the expensive part
717+
of the menu story is already solved and tested.
718+
719+
### What changes, and what does not
720+
721+
**All of the presentation metadata survives** — menu path, label, icon,
722+
accelerator, weight, selection group, visibility, enablement. Fiji's menus are
723+
built from it, and hundreds of commands depend on it.
724+
725+
**It becomes data rather than an inheritance chain.** SciJava Common has
726+
`BasicDetails` → `UIDetails` → `AbstractUIDetails`, which every plugin extends
727+
in order to carry a label. Here it is attributes in the annotation index, read
728+
without loading, with a command-info view over `Discovery`. The same
729+
information, fewer types, a faster menu build. Expect commands to look like:
730+
731+
```java
732+
@Command(menuPath = "Image>Adjust>Brightness/Contrast...", weight = 12,
733+
accelerator = "^C", iconPath = "/icons/bc.png")
734+
public class BrightnessContrast implements Runnable {
735+
@Parameter private Dataset image;
736+
}
737+
```
738+
739+
`@Command` as its own `@Indexable` annotation: `IndexDiscoverer` is generic
740+
over the annotation type, so a dedicated, self-documenting annotation costs
741+
nothing compared with stuffing this into `@Plugin` attributes.
742+
743+
**Reworked rather than ported:** `AbstractUIDetails`'s inheritance, the
744+
`display` package's `DisplayService`/`Display`/`DisplayViewer`/`DisplayPanel`
745+
layering, and the `Gateway`/`SciJava` convenience object. Those are shape
746+
problems; the capabilities survive.
747+
748+
### The real risk is migration, not architecture
749+
750+
Hundreds of commands live across dozens of repositories with different
751+
maintainers. Per command the change is mechanical, but there is no flag day on
752+
which they all update.
753+
754+
So the **one-way legacy bridge matters more than its deferral implies**: for
755+
Fiji to run on SJ3 before every command is ported, an SJ3 application must
756+
present SciJava Common `ModuleInfo`s as SJ3 commands — metadata flowing both
757+
ways, dependency flowing one way. That is what makes the migration incremental
758+
rather than a big bang, and it should be sequenced *with* layer 1 rather than
759+
after it.
760+
677761
### Phase 4 — UI and desktop
678762

679763
- **Input harvesting is a headline deliverable**, not a port. It is the
@@ -684,8 +768,10 @@ No application context required by anything in this phase.
684768
and the prototype preserved on the `historical/scijava-ops-prototype` branch
685769
(`widget/`, `swing-widget/`), which is the design starting point rather than
686770
`org.scijava.widget` as written.
687-
- **Drop** the opinionated application shell: `ApplicationFrame`, `Desktop`,
688-
`StatusBar`, `ToolBar`. The SJ3 UI API is minimal.
771+
- **The application shell moves to layers 1 and 2**, it is not discarded:
772+
`ApplicationFrame`, `Desktop`, `StatusBar` and `ToolBar` are contracts in
773+
`scijava-ui-api` and implementations in the toolkit bindings. What the core
774+
drops is any knowledge that they exist.
689775
- **`input` and `tool`** are re-framed, not frozen: UI-agnostic facades over
690776
GUI concepts, layered on `scijava-events`, letting code listen for GUI
691777
events or implement interactive behavior (e.g. a pencil tool) without
@@ -718,7 +804,7 @@ No application context required by anything in this phase.
718804
| `module`, `command` | → execution layer (Phase 3) |
719805
| `script` | → scripting facade + adapters (Phase 3) |
720806
| `widget` | → input harvesting, redesigned (Phase 4) |
721-
| `ui`, `menu` | Minimal UI API; app shell dropped (Phase 4) |
807+
| `ui`, `menu` | `scijava-ui-api` contracts and `scijava-menu` (layer 1), with toolkit bindings in layer 2 (Phase 4) |
722808
| `input`, `tool` | Re-framed as UI-agnostic facades (Phase 4) |
723809
| `display` | Overhauled, not ported (Phase 4) |
724810
| `platform`, `ui.dnd` | `scijava-desktop` modernization (Phase 4) |

‎docs/migration.md‎

Lines changed: 2 additions & 2 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` | plugin/module metadata (Phases 2–4) | open |
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 |
9090
| `Validated`, `ValidityProblem` | execution layer (Phase 3) | open |
9191
| `Optional` | `scijava-optional` (satellite repo, moves in later) | open |
9292

@@ -125,7 +125,7 @@ A **dropped** row is a successful outcome, not a gap.
125125
| `command` | still to come: a command is a struct plus menu metadata plus `run` | planned |
126126
| `script`, `script.process` | scripting facade + `javax.script` / GraalVM polyglot / Appose adapters (Phase 3) | planned |
127127
| `widget` | input harvesting on `scijava-struct`, with dynamic subgroups (Phase 4) | planned |
128-
| `ui`, `menu` | minimal UI API; `ApplicationFrame`/`Desktop`/`StatusBar`/`ToolBar` dropped (Phase 4) | planned |
128+
| `ui`, `menu` | `scijava-ui-api` (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 |
129129
| `input`, `tool` | UI-agnostic facades on `scijava-events` (Phase 4) | planned |
130130
| `display` | overhauled, not ported (Phase 4) | open |
131131
| `platform`, `ui.dnd` | `scijava-desktop` modernization (Phase 4) | planned |

0 commit comments

Comments
 (0)