Skip to content

Commit 1f0084d

Browse files
ctruedenclaude
andcommitted
One name per foreign library: scijava-compat, -ops-compat, -imagej-compat
scijava-bridge and the existing scijava-legacy were two names for what reads as the same job, which was going to confuse people. Now the compatibility components are named for the foreign thing each adapts to: scijava-compat SciJava Common's commands, usable from SciJava3 scijava-ops-compat SciJava3's ops, usable from a SciJava Common app scijava-imagej-compat ImageJ2's types, readable by scijava-types The first two are the same boundary in opposite directions, kept apart because their dependencies are disjoint: an application wanting Fiji's existing commands in its menus should not thereby acquire ops. Scrutinizing the dependencies, as suggested, is what shook the third one out. scijava-legacy held two SciJava Common/ops classes and one ImageJ2 type extractor, and its module-info said `requires net.imagej` for all of it -- so anyone wanting ops inside a SciJava Common application acquired ImageJ2 on account of a class that has nothing to do with SciJava Common. Being entirely about net.imagej.Dataset, it is a candidate for moving to an ImageJ repository; its own module-info says so. The split cost five build iterations, every one a dependency that no import names: - scijava-discovery, arriving through scijava-ops-api in one module and through scijava-types's `requires transitive` in the other; - net.imglib2, because Dataset's supertypes live there; - scijava-ops-engine, because OpEnvironment.build() finds its implementation through ServiceLoader. So module boundaries here cannot be drawn by reading imports, and single-module -pl builds cannot check them: they resolve released artifacts, some a year old, rather than this reactor's. Each restored dependency now carries an NB saying why it is there. The old POM already warned about exactly this, in a comment I pruned past before reading. Also: scijava-imagej-compat inherited an annotation-processor configuration for SciJava Common's processor, in a component whose whole point is that it has nothing to do with SciJava Common. Removed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 477a544 commit 1f0084d

27 files changed

Lines changed: 446 additions & 80 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 51 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -81,8 +81,10 @@ The deliverable is not a reimplementation of SJC. It is:
8181
on SJ3. Parity between an SJC class and its SJ3 replacement is *documented*,
8282
not enforced by delegation, and SJC bugfixes do not flow forward. This is
8383
acceptable for a component in wind-down.
84-
3. **`scijava-legacy` bridges the other way** (SJ3 → SJC), and is the only
85-
place in this repository permitted to depend on `scijava-common`.
84+
3. **The compatibility components bridge the other way.** `scijava-compat`
85+
(SJC commands usable from SJ3) and `scijava-ops-compat` (SJ3 ops usable
86+
from SJC) are the only components in this repository permitted to depend
87+
on `scijava-common`.
8688
4. **Every component POM must pin the version of every SciJava artifact it
8789
consumes, transitively included.** The modules here inherit from
8890
`pom-scijava`, not from this repository's aggregator POM, so a version
@@ -114,7 +116,8 @@ they need the corresponding SJC classes deprecated with pointers.
114116

115117
Remaining SJC usage inside this repository:
116118

117-
- `scijava-legacy` — intentional; it is the bridge.
119+
- `scijava-compat` and `scijava-ops-compat` — intentional; they are the
120+
bridges.
118121
- `scijava-ops-image` / `scijava-ops-flim` tests — `io.location.FileLocation`,
119122
imposed by SCIFIO's `ImgOpener` API. Gone once SCIFIO migrates; the utility
120123
usages were removed in Phase 0.
@@ -569,8 +572,8 @@ No application context required by anything in this phase.
569572
returns the subscriptions for the caller to close.
570573
- What a handler throws reaches the publisher unwrapped, rather than as an
571574
`InvocationTargetException`.
572-
- Still to do here: the one-way legacy bridge, and the core services
573-
themselves.
575+
- Still to do here: the core services themselves. The one-way legacy
576+
bridge is built, as `scijava-compat`; see below.
574577
- **Dependencies are not constructor arguments.** Constructor injection
575578
would publish every dependency in a signature, so changing an internal
576579
dependency would be an API change and a binary compatibility break unless
@@ -598,8 +601,9 @@ No application context required by anything in this phase.
598601
- **`scijava-cache`** moves into this repository, keeping the
599602
`org.scijava.cache` package, with its SJC dependency repointed to
600603
`scijava-context`. It never reached 1.0.0, so there is no SemVer concern.
601-
- **One-way bridge only:** a service hosting an SJC `Context` inside the SJ3
602-
context, plus preprocessors that inject legacy objects into existing
604+
- **One-way bridge only:** built as `scijava-compat`, which presents an SJC
605+
context's modules as SJ3 commands (see *The real risk is migration*, below).
606+
Still to do: preprocessors that inject legacy objects into existing
603607
scripts. Nothing is added to SJC.
604608
- Fiji startup can then construct the SJ3 `Context` instead of the SJC one.
605609

@@ -751,17 +755,17 @@ Hundreds of commands live across dozens of repositories with different
751755
maintainers. Per command the change is mechanical, but there is no flag day on
752756
which they all update.
753757

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+
So the **one-way legacy bridge matters more than its place in the phases
759+
implies**: for Fiji to run on SJ3 before every command is ported, an SJ3
760+
application must present SciJava Common `ModuleInfo`s as SJ3 commands —
761+
metadata flowing both ways, dependency flowing one way. That is what makes the migration incremental
758762
rather than a big bang.
759763

760-
**`scijava-bridge` is built**, and it is the only component that depends on
761-
SciJava Common. `Legacy.commands(context)` turns everything a legacy context
762-
can run into `CommandInfo`s, which go into an application's menus beside its
763-
own commands and its scripts; `LegacyContext.start()` does the same without
764-
the caller naming a SciJava Common type at all.
764+
**`scijava-compat` is built**, and it is the only component that depends on
765+
SciJava Common in this direction. `Legacy.commands(context)` turns everything
766+
a legacy context can run into `CommandInfo`s, which go into an application's
767+
menus beside its own commands and its scripts; `LegacyContext.start()` does the
768+
same without the caller naming a SciJava Common type at all.
765769

766770
What it found, which is why bridges are worth building early:
767771

@@ -802,6 +806,35 @@ What it found, which is why bridges are worth building early:
802806
a JPMS module would otherwise have to `requires org.scijava` merely to hold
803807
the context, and a test-scoped use cannot say that at all.
804808

809+
**The compatibility components are named for the foreign thing each adapts
810+
to**, which settled a name clash and shook out a mixed module:
811+
812+
| component | what it does | depends on |
813+
| --- | --- | --- |
814+
| `scijava-compat` | SciJava Common's commands, usable from SciJava3 | scijava-common, command3 |
815+
| `scijava-ops-compat` | SciJava3's ops, usable from a SciJava Common application | scijava-common, ops-api, progress |
816+
| `scijava-imagej-compat` | teaches `scijava-types` to read a `Dataset`'s generic type | imagej-common, imglib2, types |
817+
818+
The first two are the same boundary in opposite directions, and separate
819+
because their dependencies are disjoint: an application wanting Fiji's
820+
existing commands in its menus should not thereby acquire ops. The third was
821+
hiding inside the old `scijava-legacy`, whose `module-info` said
822+
`requires net.imagej` for *all* of it — so anyone wanting ops inside a
823+
SciJava Common application was acquiring ImageJ2 to get it, on account of one
824+
class that has nothing to do with SciJava Common at all. It is a candidate for
825+
moving into an ImageJ repository entirely.
826+
827+
Splitting it cost five build iterations, every one of them a dependency that
828+
**no `import` names**: `scijava-discovery` arriving through `scijava-ops-api`
829+
in one module and through `scijava-types`'s `requires transitive` in the
830+
other; `net.imglib2`, because `Dataset`'s supertypes live there;
831+
`scijava-ops-engine`, because `OpEnvironment.build()` finds its implementation
832+
through `ServiceLoader`. **Module boundaries here cannot be drawn by reading
833+
imports**, and single-module `-pl` builds cannot check them - they resolve
834+
released artifacts, some of them a year old, rather than the reactor's own.
835+
The old POM already carried a warning to this effect, which was pruned past
836+
before it was read.
837+
805838
### On the words
806839

807840
The vocabulary is settled, and deliberately smaller than SciJava Common's:
@@ -1234,7 +1267,8 @@ widgets and watching its callbacks fire.
12341267

12351268
1. Port the code and tests (JUnit 4 → JUnit 5) with a `module-info.java`, no
12361269
SJC dependency, and no split packages.
1237-
2. Add an adapter in `scijava-legacy` only if a concrete need exists.
1270+
2. Add an adapter in `scijava-compat` (or `scijava-ops-compat`, for the
1271+
opposite direction) only if a concrete need exists.
12381272
3. Mark the SJC counterpart `@deprecated` with a pointer, and add rows to
12391273
[migration.md](migration.md).
12401274
4. Update the downstream components that were using it.
@@ -1316,10 +1350,6 @@ design settled now, so that Phase 4 inherits decisions rather than a debate:
13161350
## Open decisions
13171351

13181352
- **Names:** the execution-layer module, and `scijava-convert3`.
1319-
- **Splitting `scijava-legacy`** into an SJC-only bridge and a separate
1320-
ImageJ-specific module, so that a bridge needing only SJC does not drag in
1321-
`imagej-common`. Agreed in principle; not blocking, so it is deferred until
1322-
the bridge content grows.
13231353
- **`util.Timing` and `util.TreeNode`:** port or drop, pending evidence of
13241354
downstream usage.
13251355
- **A build-time check that every consumed SciJava artifact is version-pinned

‎docs/migration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ 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 |
124+
| the legacy bridge | `org.scijava.compat`: `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 |
125125
| `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 |
126126
| `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 |
127127
| `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 |

‎pom.xml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@
5959

6060
<module>scijava-awt</module>
6161
<module>scijava-bridge</module>
62+
<module>scijava-compat</module>
6263
<module>scijava-collections</module>
6364
<module>scijava-command3</module>
6465
<module>scijava-common3</module>
@@ -75,7 +76,8 @@
7576
<module>scijava-index</module>
7677
<module>scijava-io3</module>
7778
<module>scijava-javafx</module>
78-
<module>scijava-legacy</module>
79+
<module>scijava-imagej-compat</module>
80+
<module>scijava-ops-compat</module>
7981
<module>scijava-meta</module>
8082
<module>scijava-ops-api</module>
8183
<module>scijava-ops-engine</module>
Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,16 @@
99
<relativePath />
1010
</parent>
1111

12-
<artifactId>scijava-bridge</artifactId>
12+
<artifactId>scijava-compat</artifactId>
1313
<!--
1414
NB: the major version tracks the incarnation, per the incubator README.
1515
The 1.x.y of the other components is a legacy of the first monoversioned
1616
release, not the intended scheme.
1717
-->
18-
<version>3.0.0-SNAPSHOT</version>
18+
<version>1.0.0-SNAPSHOT</version>
1919

20-
<name>SciJava Bridge</name>
21-
<description>Presenting SciJava Common's modules as SciJava3 commands.</description>
20+
<name>SciJava Compat</name>
21+
<description>Backwards compatibility with SciJava Common.</description>
2222
<url>https://github.com/scijava/scijava</url>
2323
<inceptionYear>2026</inceptionYear>
2424
<organization>
@@ -85,7 +85,7 @@
8585
</ciManagement>
8686

8787
<properties>
88-
<package-name>org.scijava.bridge</package-name>
88+
<package-name>org.scijava.compat</package-name>
8989

9090
<license.licenseName>bsd_2</license.licenseName>
9191
<license.copyrightOwners>SciJava developers.</license.copyrightOwners>

scijava-bridge/src/main/java/module-info.java renamed to scijava-compat/src/main/java/module-info.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@
3838
* package is a JVM that refuses to start.
3939
* </p>
4040
*/
41-
open module org.scijava.bridge {
41+
open module org.scijava.compat {
4242

43-
exports org.scijava.bridge;
43+
exports org.scijava.compat;
4444

4545
requires transitive org.scijava;
4646
requires transitive org.scijava.command3;

scijava-bridge/src/main/java/org/scijava/bridge/Legacy.java renamed to scijava-compat/src/main/java/org/scijava/compat/Legacy.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
* #L%
2828
*/
2929

30-
package org.scijava.bridge;
30+
package org.scijava.compat;
3131

3232
import java.util.Comparator;
3333
import java.util.List;

scijava-bridge/src/main/java/org/scijava/bridge/LegacyCommandInfo.java renamed to scijava-compat/src/main/java/org/scijava/compat/LegacyCommandInfo.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
* #L%
2828
*/
2929

30-
package org.scijava.bridge;
30+
package org.scijava.compat;
3131

3232
import java.util.ArrayList;
3333
import java.util.List;

scijava-bridge/src/main/java/org/scijava/bridge/LegacyContext.java renamed to scijava-compat/src/main/java/org/scijava/compat/LegacyContext.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
* #L%
2828
*/
2929

30-
package org.scijava.bridge;
30+
package org.scijava.compat;
3131

3232
import java.util.List;
3333

scijava-bridge/src/main/java/org/scijava/bridge/LegacyMember.java renamed to scijava-compat/src/main/java/org/scijava/compat/LegacyMember.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
* #L%
2828
*/
2929

30-
package org.scijava.bridge;
30+
package org.scijava.compat;
3131

3232
import java.lang.reflect.Type;
3333
import java.util.LinkedHashMap;

scijava-bridge/src/test/java/org/scijava/bridge/LegacyBridgeTest.java renamed to scijava-compat/src/test/java/org/scijava/compat/LegacyBridgeTest.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
* #L%
2828
*/
2929

30-
package org.scijava.bridge;
30+
package org.scijava.compat;
3131

3232
import static org.junit.jupiter.api.Assertions.assertEquals;
3333
import static org.junit.jupiter.api.Assertions.assertFalse;

0 commit comments

Comments
 (0)