Skip to content

Commit 282bcff

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 345d0f3 commit 282bcff

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
@@ -678,6 +678,90 @@ No application context required by anything in this phase.
678678
`#@` parameters parse into structs. The external `scripting-*` repositories
679679
migrate onto the facade.
680680

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

683767
- **Input harvesting is a headline deliverable**, not a port. It is the
@@ -688,8 +772,10 @@ No application context required by anything in this phase.
688772
and the prototype preserved on the `historical/scijava-ops-prototype` branch
689773
(`widget/`, `swing-widget/`), which is the design starting point rather than
690774
`org.scijava.widget` as written.
691-
- **Drop** the opinionated application shell: `ApplicationFrame`, `Desktop`,
692-
`StatusBar`, `ToolBar`. The SJ3 UI API is minimal.
775+
- **The application shell moves to layers 1 and 2**, it is not discarded:
776+
`ApplicationFrame`, `Desktop`, `StatusBar` and `ToolBar` are contracts in
777+
`scijava-ui-api` and implementations in the toolkit bindings. What the core
778+
drops is any knowledge that they exist.
693779
- **`input` and `tool`** are re-framed, not frozen: UI-agnostic facades over
694780
GUI concepts, layered on `scijava-events`, letting code listen for GUI
695781
events or implement interactive behavior (e.g. a pencil tool) without
@@ -722,7 +808,7 @@ No application context required by anything in this phase.
722808
| `module`, `command` | → execution layer (Phase 3) |
723809
| `script` | → scripting facade + adapters (Phase 3) |
724810
| `widget` | → input harvesting, redesigned (Phase 4) |
725-
| `ui`, `menu` | Minimal UI API; app shell dropped (Phase 4) |
811+
| `ui`, `menu` | `scijava-ui-api` contracts and `scijava-menu` (layer 1), with toolkit bindings in layer 2 (Phase 4) |
726812
| `input`, `tool` | Re-framed as UI-agnostic facades (Phase 4) |
727813
| `display` | Overhauled, not ported (Phase 4) |
728814
| `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)