This document plans the migration of the remaining SciJava Common (SJC) subsystems into this repository (SciJava3, SJ3).
Companion document: migration.md — the class-by-class mapping table from SJC to its SJ3 replacement (or to "dropped", or to a standard library equivalent).
Deprecate all of SciJava Common. Port only what earns its place.
The deliverable is not a reimplementation of SJC. It is:
- a set of small, layered, dependency-light SJ3 modules covering the functionality that is still worth having;
- an
@deprecatedjavadoc pointer on every SJC class, naming its replacement — in SJ3, in the Java standard library, or nowhere; - a documented path by which each downstream component drops its
scijava-commondependency.
- Every line of code is a liability. If the Java standard library covers
it, recommend that instead and drop the class. A row in
migration.md reading "use
java.util.X" or "no replacement" is a successful outcome, not a gap. - Classpath-first, module-path-clean. Fiji runs on the classpath, so JPMS
strictness binds only those who deliberately modularize. Design so that
modularization is possible without contorting for it: no split packages,
resources under
META-INF/, and a qualifiedopensto the container where a module wants its implementations injected. Notably we give up nothing here: implementation packages stay unexported and encapsulated, and declarative field injection keeps working. See the JPMS section below for the measurements behind this. - Leave SJC alone. No functional changes, no Java version bump, no
delegation layer. Only
@deprecatedjavadoc. - One-way migration. Downstream components migrate by swapping the dependency, updating imports, adjusting to API changes, and bumping their major version. There is no two-way bridge.
- Build bridges on demand. Adapters between SJC and SJ3 are written when a concrete need appears, not on a schedule.
- Incarnational versioning. The
3incommon3andio3is not a workaround for a package collision; it is the component's incarnation. Breaking changes are made by forking to a new incarnation with a new artifactId and package prefix, so both incarnations can sit on one classpath and downstream code keeps working. See versioning.md.- A major version bump within one incarnation should never happen. If compatibility must break, bump the incarnation digit — artifactId, package prefix and major version together — so the old one can stay loaded alongside.
- Ideally the major version equals the incarnation number
(
scijava-common3at3.x.y). Today it is at1.x.y, because the first release of this reactor was a single monoversioned1.0.0big bang: releasing a multi-module reactor piecemeal with heterogeneous versions needs tooling support thatrelease-version.shdoes not yet have. The realignment opportunity is the removal of the interfaces that moved toscijava-spi, which breaks compatibility anyway and could land as3.0.0.scijava-io3is unreleased, so it starts at3.0.0-SNAPSHOTalready; releasing a reactor with heterogeneous versions still awaits therelease-version.shwork.
- Names are otherwise case by case. Where an SJ3 package would collide with an SJC one and no incarnation digit applies, pick a natural collision-free noun. Every decision is recorded in migration.md.
- SJ3 cannot reuse SJC package names. Fiji will have both on the
classpath for years, and SJC's automatic module name is
org.scijava, so any shared package is a JPMS split-package error. Nothing new may live in the rootorg.scijavapackage, nor inorg.scijava.{log, event, plugin, service, convert, io, script, module, ui, widget, command, prefs, thread, app, display, input, tool, menu, console, main, run, startup, text, download, options, object, cache, parse, platform, task, annotations, welcome}. - SJC targets Java 8 and will not be bumped. It therefore cannot depend on SJ3. Parity between an SJC class and its SJ3 replacement is documented, not enforced by delegation, and SJC bugfixes do not flow forward. This is acceptable for a component in wind-down.
- The compatibility components bridge the other way.
scijava-compat(SJC commands usable from SJ3) andscijava-ops-compat(SJ3 ops usable from SJC) are the only components in this repository permitted to depend onscijava-common. - Every component POM must pin the version of every SciJava artifact it
consumes, transitively included. The modules here inherit from
pom-scijava, not from this repository's aggregator POM, so a version property that is merely absent silently resolves the last released artifact instead of the reactor's snapshot. Nothing enforces the "these versions must match across all component POMs" convention, and the failure is invisible until an API changes — at which point it surfaces asNoSuchMethodErrororNoClassDefFoundErrorat test time, far from its cause. Six components were found in this state while moving interfaces intoscijava-spi. An enforcer rule for this would pay for itself; it is listed under open decisions.
These SJ3 modules already cover SJC subsystems. They do not need migrating — they need the corresponding SJC classes deprecated with pointers.
| SJ3 module | Supersedes in SJC |
|---|---|
scijava-common3 |
util.ClassUtils, util.GenericUtils, util.Types, util.AppUtils, util.PlatformUtils, util.DebugUtils, util.MersenneTwisterFast, parts of util.FileUtils |
scijava-collections |
util.*Array |
scijava-meta |
util.POM, util.XML, util.Manifest, util.VersionUtils |
scijava-priority |
Priority, Prioritized |
scijava-progress |
task (roughly) |
scijava-struct |
the item model of module (ModuleItem, ItemIO) |
scijava-discovery |
the discovery role of plugin + annotations |
scijava-concurrent |
part of thread |
| SLF4J (used directly) | log |
Remaining SJC usage inside this repository:
scijava-compatandscijava-ops-compat— intentional; they are the bridges.scijava-ops-image/scijava-ops-flimtests —io.location.FileLocation, imposed by SCIFIO'sImgOpenerAPI. Gone once SCIFIO migrates; the utility usages were removed in Phase 0.scijava-ops-benchmarks— three imports.
- Services are discovered via
ServiceLoader+module-info/META-INF/services. Services are a small, framework-level set written by developers who can manage aprovidesline. This gives JPMS-correctuses/provideswiring, and it breaks the bootstrap circularity in SJC wherePluginServiceis itself a plugin found by an index. - The long tail — commands, converters, widgets, formats, tools — is
discovered via
@Pluginand the generated index. This is where the zero-configuration ergonomics matter, and where reading metadata without loading classes matters (Fiji menu construction). Servicedoes not extendSciJavaPlugin.
Both tiers surface through one Discoverer API, so consumers never care which
mechanism found a thing.
The current signature <U> List<U> discover(Class<U>) returns constructed
objects. That forces eager instantiation, provides no metadata without class
loading, and carries no priority, attributes or provenance. An index-backed
Discoverer under this signature would have to throw away the index's one
advantage.
Change it to yield lazy descriptors:
interface Discovery<T> {
String implClassName(); // no class loading
Map<String, String> attrs(); // menu path, label, priority, ...
double priority();
Class<? extends T> type(); // loads the class
T get(); // instantiates
}All three mechanisms map cleanly: ServiceLoader.stream() supplies
Provider::type (loads without instantiating) and Provider::get; the
@Plugin index supplies implClassName and attrs with no loading at all;
op YAML files already have this shape.
A JPMS constraint discovered while implementing this: ServiceLoader
resolves uses declarations against the module of its caller, so
scijava-discovery cannot perform a ServiceLoader lookup on another
module's behalf — doing so fails for every type that org.scijava.discovery
does not itself declare uses for. The lookup function must therefore be
supplied by the consuming module:
Discoverer.usingProviders(c -> ServiceLoader.load(c).stream())The one exception is Discoverer.all(), which looks up Discoverer itself —
a type this module does declare uses for — and so can be a no-argument
convenience. This is a real constraint on any generic discovery facade under
JPMS, not an artifact of our design.
This refactor should land before scijava-context is built on top of
Discoverer. It is mechanical now and expensive later. ManualDiscoverer
— hand-feeding implementations, which is valuable for tests, scripts and
embedding — is preserved.
@Plugin is retained: adding one annotation and having everything work,
with no configuration files, has been of large value to the SciJava community.
The risks are in downstream builds, not ours:
- Java 23+ no longer runs annotation processors found on the classpath
implicitly.
pom-scijava-basesets this up for SciJava components, but a hand-rolled Maven or Gradle build silently produces no index, and the plugin simply never appears.
Mitigations to build:
- Generate the index from a Maven plugin as well as from the annotation processor, so a build that misses annotation processing still works.
- Emit a loud runtime diagnostic when a
@Plugin-annotated class is absent from the index, naming the exact fix. This converts a silent failure into a one-line answer.
annotations.EclipseHelper is not ported: modern m2e .factorypath
generation covers it, and the directory-indexing capability belongs in the
Maven plugin (under a name that does not say "Eclipse", since it runs
elsewhere too).
These were measured, not reasoned about, with a three-module test project
(javac --module-source-path, run on the module path, JDK 21):
| Situation | Result |
|---|---|
Index resources (META-INF/json/...) read via ClassLoader.getResources |
works — META-INF is not a valid package name, so it is never encapsulated |
ServiceLoader finding a provider declared with provides, in a package that is neither exported nor opened |
works — the provides declaration itself grants the access |
Reflective newInstance on a public class in a package that is neither exported nor opened |
fails: IllegalAccessException |
The same, with a qualified opens <pkg> to <container> |
works |
setAccessible injection into a private field, with that qualified opens |
works |
| An ordinary module importing a class from that opened-but-unexported package | compile error: "package ... is declared in module ..., which does not export it" |
A service with a private constructor plus a public static provider() factory |
works — ServiceLoader prefers the factory |
| Reflective construction of a class in a package opened to the container, performed by a different module (e.g. a shared discovery library) | fails: IllegalAccessException — the check is against the module that performs it |
The load-bearing conclusion is the second-to-last row: opens is not
exports. A qualified opens grants the container deep reflective access at
runtime while leaving the package invisible to ordinary callers at compile
time. Implementations therefore stay encapsulated — callers cannot import
them, cannot cast to them, and cannot call their non-API methods — and the
container can still construct and inject them.
That last row is easy to design past and costly to discover late: it is not
enough to know that reflection needs an opens, one must know which
module the opens names. Generic discovery code cannot construct a plugin on
a container's behalf, so the container passes an instantiator defined in its
own module, and users open their packages to the container. Discovery.of and
IndexDiscoverer therefore take an optional instantiator.
So the SJ3 context keeps declarative field injection, as SciJava Common has always had. The cost to a plugin module is one line:
opens my.plugins.impl to org.scijava.context;SciJava has invented several cancellation APIs over the years — Cancelable
in SJC's module package and across ImageJ Ops, the cancel half of
task.Task, and Appose's cancel(). SciJava Ops deliberately shipped without
any of them. The replacement is the platform's own mechanism, not a fourth
invention.
- Mechanism: thread interruption. Every interruptible JDK blocking call
already honors it —
Thread.sleep,Object.wait,BlockingQueue,Lock.lockInterruptibly, NIO channels — and Java 21'sStructuredTaskScopecancels its subtasks by interrupting them, so this stays current. - Client API:
ExecutorService.submit()→Future.cancel(true). That is what a caller holds: cancellation, completion and result in one object every Java developer already knows. - No
Cancelable, and no cancellation token parameter. Every scheme is cooperative, so that is not the differentiator; composition is. An ambient thread flag is honored by code we did not write, while anisCanceled()interface only works for code that knows about it, and a token pollutes every signature while still being unable to abort a JDK blocking call.
An interrupt carries no reason. Thread.interrupt() takes no argument and
the JDK constructs InterruptedException with a null message, so a reason
cannot ride along. A reason belongs to the requesting side — the Future, or
the caller's own record of why it cancelled — not to the exception.
Ops are Function, Computers.Arity* and similar, whose methods declare no
checked exceptions, so an op cannot throw InterruptedException. The idiom:
if (Thread.interrupted()) { // NB: this clears the flag...
Thread.currentThread().interrupt(); // ...so restore it
throw new CancellationException("op cancelled");
}java.util.concurrent.CancellationException is unchecked and is what
Future.get() already throws for a cancelled task, so callers see one type.
Progress.update() is the checkpoint. Ops that do long work already call
it periodically, so making it check for interruption gives cancellation with
no new API, no extra parameter, and no per-op work. Progress and cancellation
are both ambient and thread-scoped; they belong on the same rail. An op that
reports no progress is not cancellable, which is honest, and a nudge toward
reporting progress.
CompletableFuture.cancel()does not interrupt the running thread; it only completes the future exceptionally. ExposeExecutorServicefutures where cancellation must reach a compute loop.- The interrupt flag is thread-bound and does not inherit, unlike
Progress, which is anInheritableThreadLocal. Propagation to workers is therefore deliberate. InTaskExecutorsmost of it was already there:ExecutorService.invokeAllcancels its unfinished tasks — interrupting them — when the awaiting thread is interrupted. What was missing was the other half: theInterruptedExceptionwas wrapped in a plainRuntimeExceptionand the caller's own flag was never restored, so cancellation died at that layer. It now restores the flag and throwsCancellationException. - Plain
InputStream/FileInputStreamreads are not interruptible; only NIO channels are. Blocking I/O therefore aborts between operations, not during one. - Native code ignores interrupts: a long OpenCV call cannot be cancelled mid-call.
- The common practical hazard is library code that catches
InterruptedExceptionand swallows it. The rule is always: propagate it, or restore the flag.
Interruption cannot cross one, so Appose's explicit cancel() is correct as
it stands. In-process: interruption. Across processes: an explicit protocol.
Cancelableis not ported (see migration.md).- The Phase 3 execution layer hands back a
Future; module and op execution submit to an executor, and cancellation isfuture.cancel(true). Progress.update()checks for interruption and throwsCancellationException.Parallelizationpropagates cancellation to its workers:TaskExecutorsrestores the interrupt flag and throwsCancellationExceptionrather than swallowing the interrupt in aRuntimeException.DataHandles.copychecks once per block and throwsjava.io.InterruptedIOException, which is anIOException— so it fits the existing signature — and whosebytesTransferredfield reports the partial copy. The granularity is per-block, identical to thetask.isCanceled()check it replaces.
SLF4J, used directly, as scijava-types and scijava-ops-engine already do.
log is not ported. An SJC LogService → SLF4J bridge is built if needed.
- Remove SJC usage where an SJ3 replacement already exists: switch the
ops-image/ops-flimtests tocommon3.MersenneTwisterFastandcollections.LongArray, replaceListUtils. Done. Note that the remainingio.location.FileLocationusage in theops-imageandops-flimtests is imposed by SCIFIO'sImgOpenerAPI, so it cannot go away until SCIFIO migrates;scijava-ops-tutorialturned out to have no SJC usage. - Add
@deprecatedjavadoc pointers in SJC for everything already superseded (see the table above). - Start migration.md, scripting the mapping where possible.
Note that
common3.Typesis not a superset ofutil.Types:box,field,isBooleanand friends moved toClasses, andenumFromString/argswere dropped. - Refactor
Discovererto theDiscoverydescriptor API (see above). Done.
No application context required by anything in this phase.
scijava-spi(new): pure interfaces, no behavior, no dependencies. Done, withVersioned,GenericTyped,Named,IdentifiableandDisposable.VersionedandGenericTypedmoved here fromcommon3and were not left behind as deprecated aliases, which the repository's current adoption level permits.- The test for membership: if a class can implement it without knowing
about any SciJava framework, it is SPI.
Cancelablefails that test — and is not ported at all, since cancellation is thread interruption — as doValidated,BasicDetails,UIDetailsandPlugin(metadata bags for the plugin/module layer) andInitializable(lifecycle, so it belongs withscijava-context). NamedexposesString name()only. Mutability is a separate contract; a defaultsetNamethat throwsUnsupportedOperationExceptionforces every caller to feature-detect.- Deferred, pending a consumer:
Locatable, whose only real content was a default implementation that needscommon3.Classes.location— which this module cannot depend on; andTyped, which has no consumer until the plugin layer exists, and whoseClass<T> type()would collide awkwardly withGenericTyped.type()returning aType. Both are cheap to add when something needs them; neither is cheap to remove once published.
- The test for membership: if a class can implement it without knowing
about any SciJava framework, it is SPI.
scijava-common3absorbs the remaining general utilities:ArrayUtils,StringUtils,Bytes,DigestUtils,NumberUtils,ProcessUtils,ListUtils,UnitUtils, and the non-URL parts ofFileUtils. It stays dependency-free. (Timingis on hold — unclear downstream usage.)scijava-index(new,org.scijava.index): portsannotations— the annotation processor and index reader — plusIndexDiscoverer, aDiscovererbacked by the index. Done. This is what supplies plugin metadata without loading classes, and it is what theDiscoveryrefactor was for: a test proves that discovery never asks the class loader for an implementation class, using a recording class loader rather than a static flag, since reading such a flag would itself load the class.- The index format (
META-INF/json/<annotation>) is deliberately unchanged from SJC, so an index written by either side is readable by the other. - Which type an indexed item provides must be answerable from metadata,
so
IndexDiscoverertakes a function for it; for an annotation shaped like@Plugin(type = Service.class)that isitem -> item.annotation().type().getName(), which loads the declared type but never the implementation. - The component sets
maven.compiler.proctononefor itself: javac readsMETA-INF/servicesbefore the processor class it names exists. SJC has the same constraint, and solves it the same way. - Still to do: the loud runtime diagnostic for an annotated class missing from the index. It belongs with whichever component defines the annotation, so it lands in Phase 2.
- The index format (
scijava-io3(new,org.scijava.io3.{location, handle, nio}): portsio.location,io.handle,io.nioandByteBank. Locations are done; handles are next. The externalscijava-io-httpfolds in later asorg.scijava.io3.http.- This component stays standalone: it is broadly useful on its own — to
Bio-Formats, for instance — so it depends on nothing but
scijava-collections, and resolvers are discovered with plainServiceLoaderrather thanDiscovereror a container. Nothing here requires buying into a framework. - That works because the
uses-resolves-against-the-caller constraint only bites a generic facade discovering arbitrary types on another module's behalf. This component knows its own service type, so it declaresuses org.scijava.io3.location.LocationResolverin its ownmodule-info.javaand is self-contained. LocationResolvercarries its ownpriority()as a plaindoublerather than depending onscijava-priority; thePriorityconstants are compatible with it.Locationscan also be constructed with an explicit resolver list, for embedding and testing.- Handles are done too, on the same pattern:
DataHandleabsorbs the tinyWrapperPlugincontract (locationType,supports,set,get,priority) instead of extending the plugin framework, andDataHandleServicebecomesDataHandles. - Note that discovered handles are prototypes: a handle carries the
position and buffers of one open stream, so
create()instantiates a fresh one per call. SciJava Common got this fromWrapperService; here it is explicit, and tested. DataHandles.copytook aTask, which carried both progress and cancellation; its replacementLongConsumercarries only progress. Cancellation is thread interruption instead — see the cancellation section — socopychecks the flag once per block and throwsInterruptedIOException.- From
io.nio,ByteBufferByteBankis ported: a direct buffer is off-heap, so its bytes reach native code and shared memory without a copy — which matters increasingly for Appose's named shared memory blocks.NIOServiceis dropped, being two JDK calls behind a system-property switch; nothing in the ported architecture precludes reintroducingFileChannellater, since a handle may open a channel and a bank may be backed by a mapped buffer. This component is therefore complete.
- This component stays standalone: it is broadly useful on its own — to
Bio-Formats, for instance — so it depends on nothing but
scijava-events(new,org.scijava.events): a clean-room typed event bus. Done. Not a port of the bushe fork, so the attribution obligation is gone. The externalscijava-listenersstays a separate concern: a listener list is the right primitive for "this object notifies its observers", and is not a bus.- Lambdas, not annotations.
subscribe(Class<E>, Consumer<? super E>)is type-safe, needs no reflection, and so needs noopens.@EventHandlerergonomics are not lost:scijava-contextalready reflects over services, so it can scan annotated methods, register them as lambdas, and hold the subscriptions. The convenience lives in the tier that already pays for reflection. - Strong references plus an explicit
Subscription. SciJava Common held subscribers weakly, which produced handlers that silently stopped firing and forced aWeakHashMapnamedkeepEmwhose only job was stopping the proxies from being collected too early — the implementation fighting its own design. Cleanup is structural instead:EventBus.close()drops every subscription, and a context calls it on dispose, so a service that subscribes never arranges its own cleanup. - No shared instance, deliberately. A bus is nothing but shared mutable
subscriber state, so an ambient singleton would let two application
contexts hear each other's events. Each context owns one bus. NB: this is
the opposite call from
Locations.get()andDataHandles.get(), which are safe to share precisely because they hold no such state. - Class-hierarchy dispatch is retained — it is what makes a bus more than a listener list — and any object may be an event, with no marker interface, so a type from another library can be one.
- Consumption is opt-in, via a
Consumableinterface on the event, on the model of AWT'sInputEvent.consume(). Toolkit-style input events can then stop propagation without every event paying for the concept. - Subscriber order is by
scijava-priority, descending, ties broken by subscription order. It matters most for consumable events, where an earlier subscriber gets first refusal. - A failing subscriber does not truncate delivery. Everyone still
receives the event, and the failures are thrown together afterward as an
EventDeliveryException— first as cause, rest suppressed, none lost. Cancellation is the exception: an interrupted subscriber, or one throwingCancellationException, stops delivery at once, since an interrupt means this thread is being cancelled and must not be buried among unrelated failures. EventHistoryis dropped. The real need behind it — a macro recorder that tracks module executions so a user can review what they did — is better served by an explicit layer later; note that SciJava Ops already tracks execution provenance per output object (OpHistory.executionsUpon), which answers "what produced this?" rather than "what happened?".
- Lambdas, not annotations.
- Key/value parsing moves to Parsington, not into a SJ3 module. The whole
SJC
parsepackage is 319 lines whose only non-Parsington dependency isObjectArray(replaceable withArrayList), and Parsington already carries anevalpackage and a CLI. This adds no dependencies there and deletes a module from this plan. - Not ported:
log(SLF4J),cache(see Phase 2), build-time and obsolete utilities (Combiner,MetaInfCombiner,ServiceCombiner,CheckSezpoz,MirrorWebsite,TunePlayer,ReflectedUniverse,util.Prefs,ConversionUtils), and the collection odds and ends (LastRecentlyUsed→LinkedHashMapwithaccessOrder;IteratorPlus→ nothing;SizableArrayList→ nothing, as its reflective resizing rationale died with Java 17;TreeNode→ on hold, onlyimagej-commonuses it).
scijava-context(new,org.scijava.context): services with a lifecycle and dependency injection; plugin metadata fromscijava-index; instantiation viaDiscoverer; ordering viascijava-priority. Plus the core services: object registry, prefs, thread, app/status.- The container core is done:
Service,Context, lazy creation, priority selection, lifecycle, disposal, and oneEventBusper context.scijava-context-testis a sibling module — the only way to test the claims that matter, since a module must really declareprovides, and its implementation package must really be unexported, for the test to mean anything. It verifies that a service in a package that is neither exported nor opened is still discovered and constructed. - Services are discovered as
Service, never as their own interface.ServiceLoaderresolvesusesagainst its caller's module, so a container cannot look up an arbitrary third-party interface on that module's behalf. Declaring one base type that this moduleusesis what makes discovery work under JPMS at all; the container then sorts implementations by the interfaces they implement.Provider.type()keeps that cheap, since implementations of other types are never constructed. - Two services may depend on each other, because dependencies are
acquired in
initializerather than in the constructor — a cycle that constructor injection could not resolve at all. The cost is that a service in a cycle may briefly see a peer that has not finished initializing. - Disposal reverses the order in which services finished initializing, not the order they were requested, so a service is always torn down before the ones it depends on.
- The plugin tier is done:
@Plugin(indexable, with@Attr) andContext.plugins(Class), which returnsDiscoverydescriptors from the annotation index — class name, metadata and priority, with nothing loaded until asked. Tested through a real build inscijava-context-test: annotated classes in an unexported package, indexed by the annotation processor at compile time, discovered with their metadata, and constructed only on demand. - A downstream project must put the processor on the annotation processor
path (as the Ops modules do for
scijava-ops-indexer). javac will not find it on the module path, and says nothing when it finds no processor at all: the build simply produces no index and the plugins silently fail to appear. This is the hazard noted above, met first-hand.pom-scijavaconfiguring this for SciJava components would remove the trap for the people most likely to fall into it. - Field injection is done:
@Dependencyfills in services, theContextand theEventBus, after construction and beforeService.initialize. It is deliberately not called@Parameteras in SciJava Common, where that annotation meant two unrelated things — a dependency to inject, and an input to a module — the second of which is noworg.scijava.struct's business.scijava-context-testinjects private fields of a plugin across a real module boundary, proving both halves of the earlier claim at once: the qualifiedopensgrants the container deep reflection, and the package is still exported to nobody. @EventHandlerscanning is done, and it is what the two-tier design was protecting: the event bus itself stays reflection-free, while the container — which already reflects — turns annotated methods into subscriptions. A service's handlers are subscribed when the context creates it and dropped when the context is disposed, so a service author writes no subscription or cleanup code at all.- Objects the context did not create are not subscribed automatically:
a plugin may be created and discarded many times in a session, and
handlers outliving their objects would pile up.
Context.subscribe(Object)returns the subscriptions for the caller to close. - What a handler throws reaches the publisher unwrapped, rather than as an
InvocationTargetException. - Still to do here: the core services themselves. The one-way legacy
bridge is built, as
scijava-compat; see below. - Dependencies are not constructor arguments. Constructor injection
would publish every dependency in a signature, so changing an internal
dependency would be an API change and a binary compatibility break unless
old constructors were kept forever. It also cannot work for the
ServiceLoadertier, which requires a public no-arg constructor or a staticprovider()factory. Dependencies are instead acquired after construction — declaratively, by annotated field, as SciJava Common does — which keeps them an implementation detail. - Services may therefore have a private constructor and a
public static provider()factory, exposing no construction API at all. - Deliberately a much smaller surface than SJC's
Context+PluginService+PluginInfo+ the handler/wrapper/typed-service hierarchy. Keep what is used; drop the rest. - Keep the class name
Context. The scripting layer controls the parameter alias table, so#@ Context ctxcan resolve to whichever class we choose; script compatibility does not force a rename, and the decision can be made late.
- The container core is done:
scijava-convert3(name TBD): ported, not replaced by Ops. Implicit parameter conversion andgetCompatibleInputsare foundational to the execution layer and the input harvester —imagej-legacy'sDatasetToImagePlusConverterand friends are the proof. AConverterSPI plus a convert service discovered viaDiscoverer, with one adapter exposing Ops conversions as converters. Ops matching-based conversion stays a distinct mechanism joined by that adapter, not merged.scijava-cachemoves into this repository, keeping theorg.scijava.cachepackage, with its SJC dependency repointed toscijava-context. It never reached 1.0.0, so there is no SemVer concern.- One-way bridge only: built as
scijava-compat, which presents an SJC context's modules as SJ3 commands (see The real risk is migration, below). Still to do: preprocessors that inject legacy objects into existing scripts. Nothing is added to SJC. - Fiji startup can then construct the SJ3
Contextinstead of the SJC one.
-
Factoring the member parsing out of
scijava-ops-engineis wanted, but the coupling is deeper than the file names suggest. Inspecting the nineteen classes inops.engine.struct, only a handful are framework-neutral (FieldInstance,ParameterData,FunctionalMethodType,SynthesizedParameterMember,RetypingRequest). The parsers themselves reach into Op-specific exceptions (FunctionalTypeOpException,NullablesOnMultipleMethodsException), Op-specific annotations (@Nullable,@OpDependencyinscijava-ops-spi), andops.engine.utilhelpers. Lifting them means first deciding where an "optional parameter" annotation lives, andscijava-ops-spiis already released.- So: build the execution layer first and let a second real consumer
show which abstractions are genuinely shared, rather than guessing from
the Ops side alone. That is the same discipline applied to
ObjectServiceand the settings store. - The execution layer must not depend on
ops-engine; if a dependency is useful it runs the other way.
- So: build the execution layer first and let a second real consumer
show which abstractions are genuinely shared, rather than guessing from
the Ops side alone. That is the same discipline applied to
-
scijava-execute(org.scijava.execute): pre/postprocessor chains, input resolution, a@Parameterequivalent, and a runner — built onscijava-struct. Cancellation needs nothing of its own: a run is aCallablefor an executor, and cancelling theFutureinterrupts it.- Started:
@Parameteron fields, aMemberParserthat reads them (inherited ones included), andExecutables.run, which binds inputs by name and returns outputs by name. @Parameterhere means only what it meant in SciJava Common's module sense — an input or output of something runnable. Injecting a service is@Dependency, inscijava-context. Conflating those two is what made the original confusing.- A required input must be supplied, not merely non-null. Checking the
field instead would let a missing required
doublerun silently as0.0, since a primitive field is never null. - The processor chain is done:
PreprocessorandPostprocessorplugins, andRunner.run, which is always asynchronous and returnsFuture<ExecutionResult>. One verb covers both cases, since a caller wanting to block writesrun(...).get()— as SciJava Common'sModuleServicehas long demonstrated. - Declining is not cancellation. A preprocessor may stop a run before it
happens — the user closed the dialog, or a precondition is unmet — which
is an ordinary outcome, not an error and not interruption of work under
way. It is reported by
ExecutionResult.isDeclined(), withreason()for the user anddeclinedBy()naming the preprocessor. ExecutionResultis deliberately not aFuture. A future'sisCancelled()andget()are coupled by contract — whenever the former is true the latter must throw — so modelling a declined run as a cancelled future turns it back into an exception, which returning a result was meant to avoid. The asynchrony lives inFuture<ExecutionResult>; what happened lives in the result.declinedBy()returns the preprocessor instance, not its class, since a chain may hold two instances of one class and the useful question is which of them objected.- Declining lives on the execution, not the preprocessor. SciJava Common
put
isCanceled()/getCancelReason()on the plugin, which made preprocessors stateful and unsafe to share across runs. Telling the execution keeps them stateless — which matters here, sinceContextconstructs a fresh plugin instance per call. - Still to do here: factoring the framework-neutral member parsing out of
ops-engine— which is a larger job than it looks, see below.
- Started:
-
Commands: a struct, plus menu metadata, plus
run. Commands and Ops remain separate concepts sharing this layer. -
Scripting:
javax.scriptis not general enough. GraalVM's Truffle languages exposeorg.graalvm.polyglot.Context(aScriptEngineshim loses polyglot bindings, sandboxing and resource limits), and Appose-based Python runs out of process, whichjavax.scriptcannot model at all. So:scijava-scripting-api: a smallScriptLanguage/ScriptEnginefacade with norequires java.scripting;- separate adapter modules for
javax.script, GraalVM polyglot, and Appose.
#@parameters parse into structs. The externalscripting-*repositories migrate onto the facade.
The problem with SciJava Common was never that it had menus. It is that the
core had them: one artifact bundles the plugin framework, the application
container, menus, displays, tools and a UI opinion, so a library wanting only
plugin discovery inherits MenuPath, Display and a transitive AWT flavour.
The remedy is stratification, not deletion. Everything Fiji needs still exists; it moves to a layer that can be depended on separately. Where this document says a subsystem is "dropped", that means dropped from the core — unless it says there is no replacement at all, which it says explicitly.
| Layer | Contents | Depends on |
|---|---|---|
| 0. Foundation (built) | spi, common3, collections, priority, progress, concurrent, discovery, index, struct, io3, events, context, execute |
nothing above |
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 |
| 2. Toolkit bindings | scijava-awt (and the AWT platform layer the others use), scijava-swing, scijava-javafx, headless |
layer 1 |
| 3. Application | Fiji: which menus exist, branding, update sites, defaults | layer 2 |
Only layer 2 imports AWT or Swing. Layer 0 never mentions a user interface, so headless is not a mode — it is what the core does.
The machinery the application shell needs was built in phases 1-3, and in several cases was built because of it:
| Fiji needs | Built |
|---|---|
| Menus over hundreds of commands, without loading their classes | the @Plugin index, and Discovery.implClassName()/attrs() before type()/get() |
| Parameter dialogs | Preprocessor: harvesting is a preprocessing step |
| "The user pressed Cancel" | Execution.decline(reason), reported by ExecutionResult |
| Showing outputs | Postprocessor: the DisplayPostprocessor seam |
| Tool and input events, one handler claiming a keystroke | scijava-events, with Consumable |
| Menu ordering | scijava-priority, plus a weight attribute in the index |
NB: SciJava Common builds its menu from ModuleInfo, whose
getDelegateClassName() names the class without loading it and whose
loadDelegateClass() loads on demand. That is exactly the
implClassName()/type()/get() split of Discovery, so the expensive part
of the menu story is already solved and tested.
All of the presentation metadata survives — menu path, label, icon, accelerator, weight, selection group, visibility, enablement. Fiji's menus are built from it, and hundreds of commands depend on it.
It becomes data rather than an inheritance chain. SciJava Common has
BasicDetails → UIDetails → AbstractUIDetails, which every plugin extends
in order to carry a label. Here it is attributes in the annotation index, read
without loading, with a command-info view over Discovery. The same
information, fewer types, a faster menu build. Expect commands to look like:
@Command(menuPath = "Image>Adjust>Brightness/Contrast...", weight = 12,
accelerator = "^C", iconPath = "/icons/bc.png")
public class BrightnessContrast implements Runnable {
@Parameter private Dataset image;
}@Command as its own @Indexable annotation: IndexDiscoverer is generic
over the annotation type, so a dedicated, self-documenting annotation costs
nothing compared with stuffing this into @Plugin attributes.
Reworked rather than ported: AbstractUIDetails's inheritance, the
display package's DisplayService/Display/DisplayViewer/DisplayPanel
layering, and the Gateway/SciJava convenience object. Those are shape
problems; the capabilities survive.
Hundreds of commands live across dozens of repositories with different maintainers. Per command the change is mechanical, but there is no flag day on which they all update.
So the one-way legacy bridge matters more than its place in the phases
implies: for Fiji to run on SJ3 before every command is ported, an SJ3
application must present SciJava Common ModuleInfos as SJ3 commands —
metadata flowing both ways, dependency flowing one way. That is what makes the migration incremental
rather than a big bang.
scijava-compat is built, and it is the only component that depends on
SciJava Common in this direction. Legacy.commands(context) turns everything
a legacy context can run into CommandInfos, which go into an application's
menus beside its own commands and its scripts; LegacyContext.start() does the
same without the caller naming a SciJava Common type at all.
What it found, which is why bridges are worth building early:
org.scijava.commandwas 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, and on the classpath it is worse — two differentCommandinterfaces with one name, first jar wins. The incarnation rule was applied toio3,convert3andscript3and simply missed here. Hencescijava-command3/org.scijava.command3, and the two can now sit on the module path together. No other package collides: 77 SciJava Common packages against 34 SciJava3 ones, and that was the only one.- SciJava Common's
@Parametermeans two things, "this is an input" and "inject this service", and 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 parameter whose type is aServiceor aContextis the legacy context's business and never reaches a dialog. DynamicCommandneeds no equivalent to be supported. Its parameters live on the module's own description rather than the shared one, so the bridge initializes atcreate()time (as SciJava Common'sInitPreprocessordoes) and reads the module's description. What SciJava3 declines to offer as a way of writing commands, it presents without trouble.- Callbacks and validators translate by name. SciJava3 names a behavior and asks the executable what the name means; for a legacy command it means a method on the delegate object, which SciJava Common knows how to invoke. A legacy dialog therefore behaves in a SciJava3 application exactly as it did in an ImageJ2 one. SciJava Common's two validator protocols — throw, or return a message — collapse into SciJava3's one, and the wrapper exception's unhelpful "Error executing method" is unwrapped so the user sees what the validator actually said.
- Accelerators are translated, not passed through.
Accelerator.toString()renders Swing's format ("control L"), which Swing would parse back and JavaFX would not; written as^L, all three bindings agree. - Menu paths are rebuilt from their entries, because
MenuPath.getMenuString()renders"A > B > C"with spaces that would end up inside the menu labels. - The bridge's own API names no SciJava Common type, which is not tidiness:
a JPMS module would otherwise have to
requires org.scijavamerely to hold the context, and a test-scoped use cannot say that at all.
The compatibility components are named for the foreign thing each adapts to, which settled a name clash and shook out a mixed module:
| component | what it does | depends on |
|---|---|---|
scijava-compat |
SciJava Common's commands, usable from SciJava3 | scijava-common, command3 |
scijava-ops-compat |
SciJava3's ops, usable from a SciJava Common application | scijava-common, ops-api, progress |
scijava-imagej-compat |
teaches scijava-types to read a Dataset's generic type |
imagej-common, imglib2, types |
The first two are the same boundary in opposite directions, and separate
because their dependencies are disjoint: an application wanting Fiji's
existing commands in its menus should not thereby acquire ops. The third was
hiding inside the old scijava-legacy, whose module-info said
requires net.imagej for all of it — so anyone wanting ops inside a
SciJava Common application was acquiring ImageJ2 to get it, on account of one
class that has nothing to do with SciJava Common at all. It is a candidate for
moving into an ImageJ repository entirely.
Splitting it cost five build iterations, every one of them 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. Module boundaries here cannot be drawn by reading
imports, and single-module -pl builds cannot check them - they resolve
released artifacts, some of them a year old, rather than the reactor's own.
The old POM already carried a warning to this effect, which was pruned past
before it was read.
The vocabulary is settled, and deliberately smaller than SciJava Common's:
| word | means |
|---|---|
| command | anything a user can run, with declared parameters: CommandInfo |
| class command | one whose implementation is a class - Java, Kotlin, Groovy, any of them: ClassCommandInfo, read from the annotation index |
| script command | one whose implementation is source in some language, read by scijava-script3 |
| executable | the layer below: something with parameters that runs, knowing nothing of menus or discovery (org.scijava.execute.Executable) |
| module | a JPMS module, and nothing else |
| plugin | anything discovered by @Plugin - a widget factory, a converter, a preprocessor. A command is one kind |
What went away: module in SciJava Common's sense (it is now "command", which is what users already called it); macro, which now means the ImageJ 1.x macro language and nothing here; and extension, which was never a technical term.
The Command interface is not the definition of a command - CommandInfo
is. It is how to write one as a class, and a script implements nothing at all
while being no less a command. Which is why the general type went from
ExecutableInfo to CommandInfo, and the class-based one from CommandInfo
to ClassCommandInfo: naming the general thing after what users actually call
it costs one word, and the alternative was SciJava Common's design with
"executable" substituted for "module".
scijava-convert3 (org.scijava.convert3) is built, and deliberately
sits below the execution layer rather than beside it: binding an input to a
parameter converts, and a script, a command line and a text field all have
only strings to offer. It therefore depends on nothing but scijava-common3
and scijava-priority, and finds its converters through plain
ServiceLoader - no container, no configuration.
- One question, not eight.
Converter.supports(Object, Type)asks whether this value can become that type. SciJava Common had eightcanConvertoverloads acrossObject/Class/Typepairings, plus aConversionRequestto carry the combinations, plus anAbstractConverterto make the overloads bearable. The declaredsourceType()/destType()answer the common case by themselves, soConverter.of(String.class, Foo.class, Foo::parse)is a whole converter. - One converter per concern, rather than one
DefaultConverterholding every special case in sequence: cast, number, string-to-value, to-string, array, collection, file/path, and a wrapping constructor last. Each is discoverable, orderable by priority, and replaceable by a downstream component that disagrees. - Unconvertible is not zero.
tryConvertreturns empty where a value cannot become the type, andconvertthrows. Text that is half-typed converts to nothing, which is what lets a widget leave a parameter alone while the user is still typing - a distinction SciJava Common could not make, since it returned null for both "no" and "null". - Exactness where the type asked for it: a
BigDecimalfrom adoublegoes through the string, so0.1is0.1and not the binary double nearest to it. - It removed duplication rather than adding a layer. The UI's
Widgets.toType- three bindings' worth of text parsing - is now one call into it, so a widget turning text into a value does exactly what a script does.
Still open: an ObjectService equivalent (what values exist that could be
converted into this parameter) is what a chooser widget wants, and is a
separate question from what conversions are possible. It lands with the object
widget.
scijava-script3 (org.scijava.script3) is built, and the shape of it is
one claim: a script is an Executable like any other. It runs through the
same Runner, meets the same preprocessors, harvests its inputs through the
same dialog in whichever toolkit, and can sit in a menu beside a Java command.
Nothing above this layer knows which it is - a claim now tested, in
scijava-swing, by rendering a Groovy script's parameters with the Swing
widgets and watching its callbacks fire.
javax.scriptis the first backend, not the only one.ScriptLanguageandScriptSessionare the SPI;JsrLanguageturns every JSR-223 engine on the classpath into one, so Groovy, Jython, JRuby, Clojure and BeanShell cost nothing and need declare nothing. GraalVM polyglot and Appose are furtherScriptLanguageimplementations when they are wanted, and neither needs this layer to change.- Callbacks work for scripts, which SciJava Common never managed.
ExecutableInstance.behavior(String)resolves a name however that kind of code does, and for a script that means a function the script defined - so#@ double(callback = "celsiusChanged") celsiusbehaves exactly as the Java annotation does. What the function changed is converted back into the parameters afterwards, because a callback exists precisely to change other parameters. Validators andchoicesFromcome along for the same ride. - A session, not an
eval. Keeping the interpreter is what makes the functions callable afterwards, and it is whyScriptSessionexists rather than a one-shot evaluation. - Declarations are blanked, not removed, so the language's own error
messages still point at the line the author is looking at.
#@is a comment in Python and a syntax error in Groovy, so leaving it in was not an option. - Every declared parameter is bound, including the unfilled ones. A language that resolves names at run time fails on an unbound name rather than seeing null, so a callback mentioning a parameter the user has not reached would otherwise blow up instead of behaving.
- Not ported: the
ScriptProcessorchain, which existed to rewrite a script before evaluation and was used for parameters and a shebang, both of which the header reader does directly.ScriptServicehas no equivalent -Scripts.get().of(path)is a line.ScriptREPL,ScriptInterpreter,AutoCompleterandCodeGeneratorbelong with the script editor. - A script declares its presentation the way a command does.
#@script(menu = "Process>Filters>Blur It", accelerator = "^B", label = ..., weight = ..., iconPath = ...)carries the same keys@Menudoes, and where a script says nothing, the directory it sits in speaks for it:scripts/Process/Filters/Blur_It.groovymeans the same thing, underscores read as spaces. That is how the scripts already in the wild are arranged, so it had better keep working. - A script names its own language with
#@script(language = "jython")or a#!line, which is what settles the languages sharing an extension -.pybeing Jython or Python depending on which is meant. Saying nothing means the extension decides, as before. CommandInfois how an application takes more than one source. AClassCommandInfois one;CommandInfo.of(executable, attrs)makes one out of a script and its directives; a SciJava CommonModuleInfowill make one through the bridge. An application gathers what it can run from as many sources as it has, and nothing downstream learns there was more than one. This is theAppLoadershape thefijifxnotes sketched, and it is now load-bearing rather than planned: all three shells build their menus from the annotation index and a directory of Groovy scripts, and nothing below them can tell which came from where.- It is not called
MenuEntry, and the distinction matters: a menu path is optional. A command invoked by name from a script, one reached only through the search bar, one that exists to be called by something else - all are ordinary things to have, and all are perfectly runnable.MenuTreetakes the subset with a path; the type is named for what it is rather than for the one place it is most often shown.
- It is not called
- Open: whether a parameter with declared choices and no value should preselect the first. SciJava Common does; the model here leaves it unset, which is honest but shows an empty chooser. It is a one-line change in either direction and wants a look at real dialogs before being made.
scijava-cli (org.scijava.cli) is built: one component where SciJava
Common had three packages (console, main, run).
scijava "Gaussian Blur" --sigma 2.5 --edges Wrap
scijava blur.groovy --sigma=2.5
scijava --list filters
scijava --help "Gaussian Blur"
- A command is named the way a person would name it - by menu path, by
label, by the tail of its class name - and matching is forgiving about case,
spacing and a trailing ellipsis. An exact label beats a partial one, so
"Brightness" still reaches
Brightness...althoughBrightness/Contrast...exists; where two answer equally, it lists them rather than guessing. --option valuepairs are the inputs, and they arrive as strings thatscijava-convert3turns into whatever the parameters declared. That is the same path a script header and a text field take, which is why the command line needed no conversion code of its own.- There is no
canRunHeadless(). SciJava Common needed it because harvesting was tangled with the UI; here the harvester is one preprocessor among several and this runner simply does not install one. A command that cannot get an input it needs is declined, with a reason, through the mechanism a dismissed dialog already uses. --helpreads the same metadata the menus and dialogs read: labels, types, choices, which inputs are optional. Nothing describes a command twice.- Not ported:
ConsoleServiceandConsoleArgument, the pluggable argument mechanism. It earns its place when a component actually needs to add an argument, and until then a parser of some forty lines does.MainServicehas no equivalent either -mainis a method.
scijava-settings (org.scijava.settings) is built: one TOML file a
person can read, edit, copy between machines and name in a forum post.
- One path on every platform:
~/.config/<app>/settings.toml, honoringXDG_CONFIG_HOME, overridable by a system property. Not what each platform would prefer, and deliberately: what was wrong withjava.util.prefswas that the store was opaque, and the cure for that is one answer to "where is it?" rather than three correct ones. Appose made the same choice. Settingsis an object, not a singleton and not a service. Settings belong to an application, so two applications sharing a JVM get two. This is the line the codebase had been drawing without saying: static facades for stateless capabilities (Converters,Locations,Scripts- converting a string to anintdoes not depend on which application you are), scoped objects for anything with identity or lifetime. Making settings static would have quietly spent the multiple-contexts promise, and the answer to "why have a container at all, then" would have been "no reason".- A table per command, a key per parameter, keyed by the command's identifier - the class name, or the script's path - and not by its component's coordinates: a class moving between artifacts would otherwise lose what the user chose, and that is a refactor nobody should be punished for.
- Values map onto TOML's own types, by a small hardcoded table, with a
string as the fallback for anything else. So a
List<File>is an array of strings rather than one mangled string, and reading it back converts element-wise throughscijava-convert3. Widgets need no serialization API for this, which is just as well: serialization is a property of the type, and a widget is a view. That is also why it needs no answer per toolkit. - Comments survive a save. The file is one people edit; a store that ate
the
# 0.7 because the detector is noisysomebody left beside a value is a store they would stop editing. - The TOML is parsed here, covering what settings need - tables, all four
string forms, integers in four bases, floats, booleans, all four
date-and-time types, arrays - and refusing inline tables and arrays of
tables by line number rather than misunderstanding them. Neither candidate
library is modular, and an automatic module in a foundation component is the
same trade that dropped MigLayout; the API is small enough that
tomljcan take its place if settings outgrow this. - Persistence is two preprocessors,
LoadInputsandSaveInputs, so that a caller can run a command without persistence interfering - which is what the processor chain is for. Saving is a preprocessor, after the harvester: doing it after the run would lose the values whenever the run threw, which is exactly when the user is about to try again and exactly when retyping everything is most infuriating.
It also turned up two things below it:
Execution.isSupplied(key)is new, because "did the caller pass this?" is not the same question as "is this parameter empty?" - adoubleis never empty, so loading remembered values by looking for nulls would never fill a primitive, and overwriting regardless would make a remembered value beat an explicit one. SciJava Common answered this with a mutableresolvedflag on each parameter; the run knows what it was given, so it is asked instead.- A bug in
scijava-convert3:CastConvertersaw aListgoing to aList<File>, said "already the right type", and handed back aList<String>unchanged - the right container full of the wrong things, which surfaces much later as aClassCastExceptionsomewhere else. It now declines a parameterized collection and lets the element-wise converter have it.
-
scijava-harvest(org.scijava.harvest): the model behind a parameter dialog — groups, dependencies between parameters, validation — with no toolkit anywhere, so it is testable headless and a Swing or JavaFX binding renders it. Prototyped, against the four dialog behaviours actually asked for, and each taught something:- A chosen implementation brings its own parameters. Expansion is driven
by the value's class, not the declared type: the field says
Joke, the value is a knock-knock joke, and it is the joke's parameters that appear. Expanding the declared type finds nothing, an interface having no fields — soStructs.expand, which uses the staticchildStruct(), is not enough. - Static nesting is then the degenerate case where the value's class
never varies. One concept covers both, and the reason is the value-driven
expansion rather than anything about
isStruct(). - A group whose size depends on a value cannot be fields at all, since a
class's fields are fixed when it is compiled. It needs parameters built at
runtime — which is exactly what a script header needs, so both are served
by
Parameters.builder(), members over a map. Two requirements that looked unrelated turned out to be one primitive. - An "advanced" toggle is a group with a
visibleWhenbehavior; a hidden group disappears rather than showing as an empty box. - Callbacks work for scripts, which SciJava Common never managed: it
resolved
callback = "foo"by Java reflection, leaving a script nothing to name.ExecutableInstance.behavior(String)resolves a name however that kind of code does — Java reflects a method, a script asks its engine for a function. - Cascading callbacks terminate. A callback may change any parameter, so
changes cascade, and two that set each other — Celsius and Fahrenheit, a
real case — would never stop. Each parameter's callback runs at most once
per
set. - Validation has one protocol: return a message, or do not. SciJava
Common allows either throwing or returning a non-empty string, which is
why it needs both
validateandvalidateMessage; with one protocol a thrown exception means the validator is broken, rather than being a second way to report a bad value. ObjectServiceis not the mechanism after all. A subgroup's parameters come from whatever object the parameter holds; where that object came from is a separate question, for a chooser widget's candidate list. It is one source among several, so the harvester is not blocked on it.DynamicCommandis supported in use, not in form. Counting its uses across the scijava and imagej repositories shows two different needs wearing one coat: about 39 files mutate the metadata of a declared parameter (setChoices,setMinimumValue), and about 31 add parameters that do not exist statically (addInput). SciJava Common serves both by makingModuleInfomutable and per-instance, which is precisely what makes harvesting hard: a platform cannot know a command's parameters without constructing it.- Adding parameters is the generated group above — and better, because it
is declared:
@Group(membersFrom = ...)tells a platform exactly where the dynamic part is and that everything else is fixed. - Computing metadata is
@Parameter(choicesFrom = "behavior"), which leaves the parameter statically visible while its values follow the state.@Parameter(choices = {...})covers the static case, andParameterNode.choices()hands a UI the resolved list either way. Being a behavior, it works for scripts too. - So there is no
DynamicCommandbase class and no mutable description. Ifminandmaxwant the same treatment,minFrom/maxFromfollow the identical pattern — worth adding when a widget needs it, not before.
- Adding parameters is the generated group above — and better, because it
is declared:
- Known rough edges: group placement is provisional (a group appears
where its first member would, and a generated group needs an explicit
afteranchor);ParameterModeldecides the tree changed by comparingtoString(), which is right for correctness and wrong for a UI that should patch rather than rebuild — the Swing dialog rebuilds its widgets whenever the tree changes, which is correct and loses focus on a parameter whose callback reshapes the dialog.
- A chosen implementation brings its own parameters. Expansion is driven
by the value's class, not the declared type: the field says
-
scijava-ui3(org.scijava.ui3) andscijava-swing(org.scijava.swing): the contracts, and the first toolkit to meet them. Built, and the shape of the split is the point:Widgetis a view of aParameterNode, and that is all it is. There is noWidgetModel: SciJava Common needed one because a widget could not see the module, whereas a widget here reads the node for label, description, bounds, style and resolved choices, and writes throughParameterModel. Writing through the model is what makes callbacks run and the dialog reshape itself, so a widget gets the dynamic behavior by not doing anything clever.WidgetPanelis aWidget, so a group nests in its parent's list with no special case, however deep.WidgetPanelswalks the tree the same way for every toolkit; a binding supplies factories and a panel factory, some 150 lines of tree-walking it no longer writes.InputHarvesteris aPreprocessor. Dismissing the dialog isExecution.decline, an ordinary outcome that theExecutionResultreports, rather than acanceledflag on a stateful preprocessor.- MigLayout is gone, replaced by
GridBagLayout: two-column label-field layout is not worth a third-party dependency, still less an automatic module in a JPMS build. - Seven widgets so far — number (spinner, with an optional slider or scroll bar, and labelled tick marks), text (field, password, area, and the arbitrary-precision numbers a spinner cannot step), toggle, choice, file, message, and the panel itself. The button, color, date, file-list and radio-choice widgets are not ported; each earns its place when something asks for it.
- An enum needs no annotation: its constants are its choices, resolved
in
ParameterTreeso every toolkit gets it.softMin/softMaxbound the slider where the permitted range is far wider than the useful one, while the spinner still enforces the hardmin/max. - A widget reads its node out of the current tree, not the one it was
built from. The tree is rebuilt on every
set, so a captured node goes stale — and sinceParameterModelrebuilds the widgets only when the tree's shape changes, a parameter whose computed choices changed while its shape did not would otherwise keep offering the old values. - The dialog never moves and never shrinks. After the first build it may grow, to make room for parameters that have just appeared, but a dialog that re-centred itself, or closed up around a group the user had just collapsed, would move the controls out from under the pointer.
- An empty dialog says why. A missing annotation index — javac produces one only when scijava-index is on the annotation processor path, and says nothing when it is not — means no widget factories are discovered, and the dialog comes up with nothing but OK and Cancel. That is now a warning naming the missing index, as is a parameter no factory accepted.
- Style hints are advisory strings (
@Parameter(style = "slider"),"format:0.00"), which a toolkit is free to ignore, so a parameter styled for Swing still renders elsewhere.min,maxandstepSizeare strings too, read back in the parameter's own type — because metadata has to survive a script header. - Demos with
main()(Demosin the test sources) put each tricky behavior on screen: the kitchen sink, the advanced toggle, the generated group, computed choices, live validation, and two values that keep each other in step.
-
Input harvesting is a headline deliverable, not a port. It is the workhorse that lets Fiji users write scripts without UI-specific concerns. Build it on
scijava-struct, and complete the long-requested dynamic subgroups (widgets appearing based on another widget's value) — see scijava-common#42 and the prototype preserved on thehistorical/scijava-ops-prototypebranch (widget/,swing-widget/), which is the design starting point rather thanorg.scijava.widgetas written. -
A shell exists, as a demo:
Shellinscijava-swing's test sources is a window with menus, a search bar and a status line. It is the first thing to put the whole stack together - commands found through the annotation index, arranged byMenuTree, rendered bySwingMenus, run byRunner, filled in bySwingInputHarvester- and starting it loads no command class.MenuCreator/Menus(inscijava-command3, beside the tree they walk) hold the toolkit-free part of the walk, so a second toolkit implements four methods and inherits the rest. -
From the
fijifxexperiment (unpublished, since retired), which asked the right questions before this design existed:- "Is there any way we can build the menus before loading the command
classes? Not if we use
@Pluginannotations on the commands themselves -- we can do it if all menu items are scripts." That conclusion is now wrong, and usefully so: the annotation index is read as data, and@Menuis indexed separately from@Pluginand joined on the class name, so a menu of ten thousand commands costs no class loading at all. The experiment's own class-loading test - a static initializer that sleeps a second - is the measurement that made the question urgent. AppLoaderis the legacy bridge's shape. The experiment sketched one loader per source of commands - SciJava's plugin index, ImageJ 1.x'splugins.config, a Fiji.toml, a directory of scripts - each contributing menu entries into one application model, and each able to report progress for a splash screen. That is what the bridge needs: several discovery sources feeding oneMenuTree, with SciJava Common'sModuleInfos as one source among them rather than a special case.- The main window is menu bar, tool bar, progress bar, status bar and a search field, and the search field is not an afterthought: a command that is in no menu is still reachable, which the demo shell shows.
- "Is there any way we can build the menus before loading the command
classes? Not if we use
-
A second binding,
scijava-javafx, is what turns "toolkit-agnostic" from an assertion into a measurement. The whole ofscijava-ui3survived it with two changes, both of which were Swing keeping something that was never Swing's:Widget.isLabeled()- whether a parameter wants a label beside it is a statement about the parameter, and every toolkit would have answered it identically.WidgetPanel.showProblems(Map)- how a problem looks is a toolkit's business, but that there is one, shown per parameter and cleared when fixed, is not. Everything else -Widget,WidgetFactory,WidgetPanelFactory,WidgetPanels,Widgets,InputHarvester,MenuCreator,Menus- was untouched, andParameterModelandParameterTreenever came into question.
-
What the second binding had to do differently is worth recording, because it is what a third will face too:
- The toolkit must be started, once, and JavaFX has no
invokeAndWait.FxThreadis that plumbing, and it deliberately does not useApplication.launch, which takes over the process and returns only when the last window closes - wrong for a binding that an application, a script or a test may use. showAndWaitruns a nested event loop, so the dialog must be built and shown in one visit to the JavaFX thread, where Swing wanted two.- JavaFX spinners do not preserve a parameter's type - their value
factories are
IntegerorDoubleand nothing else - so the widget converts on the way out, and an editable spinner needs its editor watched or a typed value is silently lost when focus moves. - Some things are simply easier: a collapsible group is a
TitledPane, where Swing needs a hand-rolled header button;KeyCombination.SHORTCUT_DOWNsays what Swing needs aToolkitcall to compute.
- The toolkit must be started, once, and JavaFX has no
-
A third binding,
scijava-awt, is where "toolkit-agnostic" stops being a claim about two similar toolkits. It changed nothing in the contracts. What it did change is where the shared code lives:AbstractWidgetmoved intoscijava-ui3, because three bindings had written the same bookkeeping - find the node in the current tree, write through the model, do not mistake a refresh for the user typing. Two would have been a coincidence.Acceleratormoved intoscijava-command3, because Swing wants aKeyStroke, JavaFX aKeyCombinationand AWT aMenuShortcut: three ways of saying a shortcut, one thing being said. A binding that parses^+Citself is a binding that can disagree about what it means.- AWT is the harshest case so far, and instructive for it: no spinner, no
slider, no titled border, no collapsible pane, no icons in menus, and a
MenuShortcutthat cannot express alt. The number widget is a text field and a scroll bar honoringmin,max,stepSizeand the soft bounds; the collapsible group is a button that hides a panel; an accelerator AWT cannot say is dropped rather than approximated into some other key. None of it asked the model or the contracts for anything. - It also found a difference worth knowing: AWT's
TextComponent.setTextdoes not notify text listeners, where a Swing document would. Harmless here - the refresh guard covers it either way - but it is the kind of thing only a third toolkit tells you.
-
On the structure of
scijava-awtandscijava-swing, which SciJava Common got into four components (scijava-ui-awt,scijava-ui-swing,imagej-ui-awt,imagej-ui-swing): the evidence says the toolkit axis is not where the duplication was.scijava-ui-swingimported exactly six things fromscijava-ui-awt-AWTInputEventDispatcher,AWTDropTargetEventDispatcher,AWTColors,AWTWindowEventDispatcher,AWTWindows,AWTClipboard- and not one widget, becausejava.awt.ChoiceandJComboBoxhave nothing whatever in common. So:- Swing depends on AWT for the platform, never for widgets.
Edtis the first instance: the dispatch thread belongs tojava.awt.EventQueue, andSwingUtilitiesmerely forwards to it, so code that needs to reach the EDT need not drag in Swing. Colors, cursors, clipboard, drag-and-drop, window placement and screen geometry follow the same way. - The widget types stay siblings.
SwingWidgetcould extendAwtWidget-JComponentis aComponent- but discovery filters onWidgetFactory.widgetType(), so that would mean a pure-AWT application silently filling its dialogs with Swing controls the moment scijava-swing appeared on the classpath. Mixing the two is then an explicit adapter, which is what embedding an ImageJ 1.x canvas in a Swing frame will want anyway. - The image-processing layer should not repeat the matrix. What made
four components was (generic | ImageJ) x (AWT | Swing), and the ImageJ
half of that is mostly one thing: a canvas that paints a
BufferedImageand handles a tool's events. That is AWT code, and it works unchanged inside a Swing frame - which is precisely what ImageJ 1.x has always done. So the image layer wants an AWT canvas plus per-toolkit frames, not two parallel implementations.
- Swing depends on AWT for the platform, never for widgets.
-
scijava-ui3-testis the anti-drift mechanism: the sample commands and a conformance suite that every binding extends - eight assertions about widgets, three about menus. Swing and JavaFX render the same declarations and are held to the same behavior, and a third binding starts by making the suite pass. A binding's own tests then cover only what is genuinely its own: which control it chose, how it parses an accelerator. -
The application shell moves to layers 1 and 2, it is not discarded:
ApplicationFrame,Desktop,StatusBarandToolBarare contracts inscijava-ui3and implementations in the toolkit bindings. What the core drops is any knowledge that they exist. -
inputandtoolare re-framed, not frozen: UI-agnostic facades over GUI concepts, layered onscijava-events, letting code listen for GUI events or implement interactive behavior (e.g. a pencil tool) without binding to Swing or JavaFX. -
displaygets an overhaul, not a port. The role — matching a module's outputs to a way of presenting them, asDisplayPostprocessordoes — is worth keeping; the current design is overengineered. -
platformandui.dndfeed ascijava-desktopmodernization track: desktop integration, drag-and-drop andfiji://links matter to the community and must keep working. -
CLI module:
console,main,run.startupstands alone — it is relevant whether the application starts from the CLI or a GUI. -
Likely dropped:
welcome,download,text,options.
| SJC package | Disposition |
|---|---|
util |
Split across common3, collections, meta, spi; remainder dropped |
annotations |
→ scijava-index (Phase 1) |
io.location, io.handle, io.nio |
→ scijava-io3 (Phase 1) |
event |
→ scijava-events, clean-room rewrite (Phase 1) |
parse |
→ Parsington (Phase 1) |
log |
Dropped — use SLF4J |
cache |
External scijava-cache moves in (Phase 2) |
thread |
→ scijava-concurrent |
task |
→ scijava-progress |
Context, plugin, service, object, prefs, app |
→ scijava-context (Phase 2) |
convert |
→ scijava-convert3 (Phase 2) |
module, command |
→ execution layer (Phase 3) |
script |
→ scripting facade + adapters (Phase 3) |
widget |
→ input harvesting, redesigned (Phase 4) |
ui, menu |
scijava-ui3 contracts and scijava-menu (layer 1), with toolkit bindings in layer 2 (Phase 4) |
input, tool |
Re-framed as UI-agnostic facades (Phase 4) |
display |
Overhauled, not ported (Phase 4) |
platform, ui.dnd |
scijava-desktop modernization (Phase 4) |
console, main, run |
Single CLI module (Phase 4) |
startup |
Standalone module (Phase 4) |
welcome, download, text, options |
Likely dropped |
minimaven, test |
Out of scope |
- Port the code and tests (JUnit 4 → JUnit 5) with a
module-info.java, no SJC dependency, and no split packages. - Add an adapter in
scijava-compat(orscijava-ops-compat, for the opposite direction) only if a concrete need exists. - Mark the SJC counterpart
@deprecatedwith a pointer, and add rows to migration.md. - Update the downstream components that were using it.
The end state is that this repository contains all core SciJava3
subsystems, with no dependency on external scijava-<foo> components.
scijava-cache, scijava-listeners, scijava-optional, scijava-table,
scijava-search and scijava-log-slf4j all move in over time. Components
intended to work standalone — Parsington, for instance — keep their
independence and should not carry the scijava- prefix.
The plan once said Phase 2 would bring over "the core services: object registry, prefs, thread, app/status". Measured against usage and against what has since been built, most of that does not survive:
| SJC service | Files outside SJC | Disposition |
|---|---|---|
StatusService |
57 | Superseded by scijava-progress. Porting it would re-create what was just replaced. |
ThreadService |
76 | Mostly EDT dispatch, which is a UI concern: scijava-concurrent covers parallelism, and the rest belongs with the UI layer (Phase 4). |
ObjectService |
52 | Real, but its consumers are the widgets and the conversion layer. It should land with them, so its shape is driven by a consumer rather than guessed (Phase 3/4). |
AppService |
52 | Largely version and title metadata, which scijava-meta covers; the rest is app-shell material already dropped. |
PrefService |
31 | Split in two — see below. |
PrefService is really two things, and only one of them is core.
Widget value persistence — remembering what a user last typed into a given parameter of a given module — is policy. It needs module identity, parameter names, and a rule for when to save, none of which mean anything without the input harvester. It belongs with the harvester, in Phase 4.
A settings store — durable key/value state in a file — is a general capability whose API needs no consumer to get right. Deferred, but with the design settled now, so that Phase 4 inherits decisions rather than a debate:
- Not
java.util.prefs. Its opacity is the actual complaint: the registry on Windows, plists on macOS,~/.java/.userPrefson Linux; values over 8KB silently truncated; nothing a user can inspect or diff. - TOML. It reads like the INI files everyone already understands
(
key = value), supports comments, and — unlike YAML — is not whitespace-fragile and has no implicit typing, sonostays the stringnoand1.10stays1.10. Those YAML traps bite exactly the values a config file holds. Jaunch already uses TOML, so the format is familiar across the stack. The cost is a dependency: the JDK has no TOML parser, wheresnakeyamlwas already present — worth choosing the library when this is built. $XDG_CONFIG_HOME/fiji, else~/.config/fiji— what users asked for — on every platform rather than%APPDATA%and~/Library. The complaint was opacity, and a path users can find, back up and quote in a bug report beats platform convention here. Overridable by system property, and the effective path should be printable at runtime.- Namespaced by class, as SJC does, mapping onto sections in the file.
- No migration from the old store: SJC keeps working for SJC, and a one-time import is a feature to add if asked for, not a reason to couple the two.
- Open, and genuinely blocked on the harvester: what to do about stale keys. Remembered values accumulate for modules that no longer exist, and neither SJC nor a plain file store has an answer. The harvester is what knows which keys are still live.
scijava-persist: polymorphic serialization where the implementations live in other people's repositories, resolved by discovery — a real and recurring need, and the discovery half is exactly SciJava-shaped. Worth rebuilding when a consumer appears, but not worth lifting: it hard-wires Gson into its SPI (IClassAdapter extends JsonSerializer), vendors a copy of Gson'sRuntimeTypeAdapterFactory, and is built onContext+@Plugin. A rewrite would be much smaller, since Jackson has first-class polymorphic support and only the discovery-driven subtype registration would be ours. Its author ended up inlining equivalent logic downstream, and there is no concrete core consumer today. It was never released, and its code stays in the archived incubator, at99712e0, as a reference for that rewrite.
- Names: the execution-layer module, and
scijava-convert3. util.Timingandutil.TreeNode: port or drop, pending evidence of downstream usage.- A build-time check that every consumed SciJava artifact is version-pinned in the consuming POM — see hard constraint 4. Today this is caught only by a full clean build after an API change.
display: what the redesigned output-presentation mechanism looks like.