Skip to content

Commit 9084574

Browse files
ctruedenclaude
andcommitted
scijava-spi: add a module of framework-free interfaces
A new dependency-free module for interfaces that any object can implement without knowing about a SciJava framework, so that code wanting only these contracts takes on the smallest possible dependency. Contains Versioned and GenericTyped, moved out of scijava-common3, plus Named, Identifiable and Disposable ported from SciJava Common. No deprecated aliases are left in scijava-common3, which the repository's current adoption level permits. Method names are modernized rather than preserved: getIdentifier() is now id(), and Disposable.dispose() is abstract rather than a no-op default, since a default that does nothing means implementing the interface proves nothing to callers. Named exposes name() only -- mutability is a separate contract, rather than a setter that throws UnsupportedOperationException and forces every caller to feature-detect. Deliberately omitted for now, pending a consumer: - Locatable, whose only real content was a default implementation requiring common3.Classes.location, which this module cannot depend on. - Typed, which has no consumer until the plugin layer exists, and whose Class<T> type() would silently satisfy GenericTyped.type() as well, since Class implements Type. Both are cheap to add on demand and expensive to remove once published. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 4b8feff commit 9084574

30 files changed

Lines changed: 458 additions & 19 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,17 @@ The deliverable is not a reimplementation of SJC. It is:
6161
acceptable for a component in wind-down.
6262
3. **`scijava-legacy` bridges the other way** (SJ3 → SJC), and is the only
6363
place in this repository permitted to depend on `scijava-common`.
64+
4. **Every component POM must pin the version of every SciJava artifact it
65+
consumes, transitively included.** The modules here inherit from
66+
`pom-scijava`, not from this repository's aggregator POM, so a version
67+
property that is merely *absent* silently resolves the last *released*
68+
artifact instead of the reactor's snapshot. Nothing enforces the "these
69+
versions must match across all component POMs" convention, and the failure
70+
is invisible until an API changes — at which point it surfaces as
71+
`NoSuchMethodError` or `NoClassDefFoundError` at test time, far from its
72+
cause. Six components were found in this state while moving interfaces into
73+
`scijava-spi`. **An enforcer rule for this would pay for itself**; it is
74+
listed under open decisions.
6475

6576
## Current state
6677

@@ -217,11 +228,11 @@ SLF4J, used directly, as `scijava-types` and `scijava-ops-engine` already do.
217228

218229
No application context required by anything in this phase.
219230

220-
- **`scijava-spi`** (new): pure interfaces, no behavior, no dependencies —
221-
`Versioned`, `GenericTyped`, `Named`, `Identifiable`, `Locatable`, `Typed`,
222-
`Disposable`. `Versioned` and `GenericTyped` move here from `common3`, which
223-
retains deprecated sub-interfaces so implementors stay source-compatible.
224-
`common3` does **not** gain a transitive dependency on it.
231+
- **`scijava-spi`** (new): pure interfaces, no behavior, no dependencies.
232+
**Done**, with `Versioned`, `GenericTyped`, `Named`, `Identifiable` and
233+
`Disposable`. `Versioned` and `GenericTyped` moved here from `common3` and
234+
were **not** left behind as deprecated aliases, which the repository's
235+
current adoption level permits.
225236
- The test for membership: *if a class can implement it without knowing
226237
about any SciJava framework, it is SPI.* `Cancelable` fails that test
227238
(cancellation concerns a running thing — it belongs with the execution
@@ -231,6 +242,12 @@ No application context required by anything in this phase.
231242
- `Named` exposes `String name()` only. Mutability is a separate contract;
232243
a default `setName` that throws `UnsupportedOperationException` forces
233244
every caller to feature-detect.
245+
- **Deferred, pending a consumer:** `Locatable`, whose only real content was
246+
a default implementation that needs `common3.Classes.location` — which
247+
this module cannot depend on; and `Typed`, which has no consumer until the
248+
plugin layer exists, and whose `Class<T> type()` would collide awkwardly
249+
with `GenericTyped.type()` returning a `Type`. Both are cheap to add when
250+
something needs them; neither is cheap to remove once published.
234251
- **`scijava-common3`** absorbs the remaining general utilities: `ArrayUtils`,
235252
`StringUtils`, `Bytes`, `DigestUtils`, `NumberUtils`, `ProcessUtils`,
236253
`ListUtils`, `UnitUtils`, and the non-URL parts of `FileUtils`. It stays
@@ -393,4 +410,7 @@ independence and should not carry the `scijava-` prefix.
393410
the bridge content grows.
394411
- **`util.Timing` and `util.TreeNode`:** port or drop, pending evidence of
395412
downstream usage.
413+
- **A build-time check that every consumed SciJava artifact is version-pinned
414+
in the consuming POM** — see hard constraint 4. Today this is caught only by
415+
a full clean build after an API change.
396416
- **`display`:** what the redesigned output-presentation mechanism looks like.

‎docs/migration.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,12 @@ A **dropped** row is a successful outcome, not a gap.
7171
| SJC class | Replacement | Status |
7272
| --- | --- | --- |
7373
| `Priority`, `Prioritized` | `org.scijava.priority.*` | ported |
74-
| `Versioned` | `org.scijava.spi.Versioned` (Phase 1; currently `common3`) | planned |
75-
| `Named`, `Identifiable`, `Locatable`, `Typed`, `Disposable` | `org.scijava.spi.*` (Phase 1). `Named` becomes read-only — `String name()` — with mutability a separate contract | planned |
74+
| `Versioned` | `org.scijava.spi.Versioned` (moved out of `common3`) | ported |
75+
| `Named` | `org.scijava.spi.Named` — read-only `String name()`; mutability is a separate contract | ported |
76+
| `Identifiable` | `org.scijava.spi.Identifiable` — `getIdentifier()` is now `id()` | ported |
77+
| `Disposable` | `org.scijava.spi.Disposable` — `dispose()` is abstract, not a no-op default | ported |
78+
| `Locatable` | deferred — its only content was a default implementation needing `common3.Classes.location`, which `scijava-spi` cannot depend on | open |
79+
| `Typed` | deferred to the plugin layer — no consumer yet, and `Class<T> type()` collides with `GenericTyped.type()` | open |
7680
| `Initializable` | `scijava-context` (Phase 2) — a lifecycle hook, not an SPI contract | planned |
7781
| `Cancelable` | execution layer (Phase 3) — cancellation concerns a running thing | planned |
7882
| `ItemIO` | `org.scijava.struct.ItemIO` | ported |

‎pom.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@
7575
<module>scijava-ops-tutorial</module>
7676
<module>scijava-priority</module>
7777
<module>scijava-progress</module>
78+
<module>scijava-spi</module>
7879
<module>scijava-struct</module>
7980
<module>scijava-testutil</module>
8081
<module>scijava-types</module>

‎scijava-meta/pom.xml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@
9595

9696
<!-- Note: These versions must match across all component POMs! -->
9797
<scijava-common3.version>1.0.1-SNAPSHOT</scijava-common3.version>
98+
<scijava-spi.version>1.0.0-SNAPSHOT</scijava-spi.version>
9899
</properties>
99100

100101
<dependencies>
@@ -104,6 +105,11 @@
104105
<artifactId>scijava-common3</artifactId>
105106
<version>${scijava-common3.version}</version>
106107
</dependency>
108+
<dependency>
109+
<groupId>org.scijava</groupId>
110+
<artifactId>scijava-spi</artifactId>
111+
<version>${scijava-spi.version}</version>
112+
</dependency>
107113

108114
<!-- Test scope dependencies -->
109115
<dependency>

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
requires java.xml;
3232

3333
requires org.scijava.common3;
34+
requires transitive org.scijava.spi;
3435

3536
exports org.scijava.meta;
3637
}

‎scijava-meta/src/main/java/org/scijava/meta/Manifest.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
import java.util.jar.Attributes;
4040

4141
import org.scijava.common3.Classes;
42-
import org.scijava.common3.Versioned;
42+
import org.scijava.spi.Versioned;
4343

4444
/**
4545
* Helper class for working with JAR manifests.

‎scijava-meta/src/main/java/org/scijava/meta/POM.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
import org.scijava.common3.Apps;
3939
import org.scijava.common3.Classes;
4040
import org.scijava.common3.URLs;
41-
import org.scijava.common3.Versioned;
41+
import org.scijava.spi.Versioned;
4242

4343
/**
4444
* Helper class for working with Maven POMs.

‎scijava-ops-api/pom.xml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,7 @@
9999
<scijava-discovery.version>1.0.1-SNAPSHOT</scijava-discovery.version>
100100
<scijava-function.version>1.0.1-SNAPSHOT</scijava-function.version>
101101
<scijava-priority.version>1.0.1-SNAPSHOT</scijava-priority.version>
102+
<scijava-spi.version>1.0.0-SNAPSHOT</scijava-spi.version>
102103
<scijava-struct.version>1.0.1-SNAPSHOT</scijava-struct.version>
103104
<scijava-types.version>1.0.1-SNAPSHOT</scijava-types.version>
104105

@@ -126,6 +127,11 @@
126127
<artifactId>scijava-priority</artifactId>
127128
<version>${scijava-priority.version}</version>
128129
</dependency>
130+
<dependency>
131+
<groupId>org.scijava</groupId>
132+
<artifactId>scijava-spi</artifactId>
133+
<version>${scijava-spi.version}</version>
134+
</dependency>
129135
<dependency>
130136
<groupId>org.scijava</groupId>
131137
<artifactId>scijava-struct</artifactId>

‎scijava-ops-api/src/main/java/module-info.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
exports org.scijava.ops.api;
3232

3333
requires org.scijava.common3;
34+
requires transitive org.scijava.spi;
3435
requires org.scijava.function;
3536
requires transitive org.scijava.priority;
3637
requires transitive org.scijava.struct;

‎scijava-ops-api/src/main/java/org/scijava/ops/api/OpEnvironment.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -333,7 +333,7 @@ default OpBuilder op(final String opName, final Hints hints) {
333333
* contract of the stated {@code opType}.
334334
* @return An enriched version of the lambda object that embeds knowledge of
335335
* its generic type by implementing the
336-
* {@link org.scijava.common3.GenericTyped} interface.
336+
* {@link org.scijava.spi.GenericTyped} interface.
337337
*/
338338
<T> T typeLambda(Nil<T> opType, T lambda);
339339

0 commit comments

Comments
 (0)