Skip to content

Commit 2e01213

Browse files
ctruedenclaude
andcommitted
docs: scrutinize the core services, and settle the preferences design
The plan 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: StatusService is superseded by scijava-progress, ThreadService is mostly EDT dispatch and so belongs with the UI layer, AppService is largely metadata that scijava-meta already covers, and ObjectService should land with the widgets and conversion layer that use it, so that a consumer shapes it. PrefService is two things. Remembering what a user last typed into a given parameter of a given module is policy, and means nothing without the input harvester, so it goes to Phase 4. A settings store is a general capability whose API needs no consumer to get right, so it is deferred but its design is settled now, and recorded: not java.util.prefs, whose opacity is the actual complaint; YAML, since snakeyaml is already here and unlike JSON supports comments; $XDG_CONFIG_HOME/fiji or ~/.config/fiji on every platform, printable at runtime; namespaced by class; no migration from the old store. One question is genuinely blocked on the harvester and is recorded as open: stale keys accumulate for modules that no longer exist, and the harvester is what knows which are still live. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent de2e89f commit 2e01213

2 files changed

Lines changed: 53 additions & 1 deletion

File tree

‎docs/migration-plan.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -700,6 +700,55 @@ subsystems, with no dependency on external `scijava-<foo>` components.
700700
intended to work standalone — Parsington, for instance — keep their
701701
independence and should not carry the `scijava-` prefix.
702702

703+
### The core services are not a block to port
704+
705+
The plan once said Phase 2 would bring over "the core services: object
706+
registry, prefs, thread, app/status". Measured against usage and against what
707+
has since been built, most of that does not survive:
708+
709+
| SJC service | Files outside SJC | Disposition |
710+
| --- | --- | --- |
711+
| `StatusService` | 57 | **Superseded** by `scijava-progress`. Porting it would re-create what was just replaced. |
712+
| `ThreadService` | 76 | Mostly EDT dispatch, which is a **UI** concern: `scijava-concurrent` covers parallelism, and the rest belongs with the UI layer (Phase 4). |
713+
| `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). |
714+
| `AppService` | 52 | Largely version and title metadata, which `scijava-meta` covers; the rest is app-shell material already dropped. |
715+
| `PrefService` | 31 | Split in two — see below. |
716+
717+
#### Preferences: a store, and a policy
718+
719+
`PrefService` is really two things, and only one of them is core.
720+
721+
**Widget value persistence** — remembering what a user last typed into a given
722+
parameter of a given module — is *policy*. It needs module identity, parameter
723+
names, and a rule for when to save, none of which mean anything without the
724+
input harvester. It belongs with the harvester, in Phase 4.
725+
726+
**A settings store** — durable key/value state in a file — is a general
727+
capability whose API needs no consumer to get right. Deferred, but with the
728+
design settled now, so that Phase 4 inherits decisions rather than a debate:
729+
730+
- **Not `java.util.prefs`.** Its opacity is the actual complaint: the registry
731+
on Windows, plists on macOS, `~/.java/.userPrefs` on Linux; values over 8KB
732+
silently truncated; nothing a user can inspect or diff.
733+
- **YAML.** `snakeyaml` is already in this stack for op declarations, so it is
734+
no new dependency, and unlike JSON it supports **comments**, which a
735+
hand-editable file wants. Load with the safe constructor and quote scalars
736+
on write, to avoid implicit typing turning `no` into `false` and version
737+
strings into numbers.
738+
- **`$XDG_CONFIG_HOME/fiji`, else `~/.config/fiji`** — what users asked for —
739+
on every platform rather than `%APPDATA%` and `~/Library`. The complaint was
740+
opacity, and a path users can find, back up and quote in a bug report beats
741+
platform convention here. Overridable by system property, and the effective
742+
path should be printable at runtime.
743+
- **Namespaced by class**, as SJC does, mapping onto sections in the file.
744+
- **No migration** from the old store: SJC keeps working for SJC, and a
745+
one-time import is a feature to add if asked for, not a reason to couple the
746+
two.
747+
- **Open, and genuinely blocked on the harvester:** what to do about stale
748+
keys. Remembered values accumulate for modules that no longer exist, and
749+
neither SJC nor a plain file store has an answer. The harvester is what
750+
knows which keys are still live.
751+
703752
## Later, not now
704753

705754
- **`scijava-persist`** (in the incubator): polymorphic serialization where

‎docs/migration.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,10 @@ A **dropped** row is a successful outcome, not a gap.
116116
| `plugin` (`Plugin`, `Attr`, `PluginService`, `PluginInfo`, `PluginIndex`) | `org.scijava.context.Plugin` and `Attr`, discovered via `Context.plugins(Class)`. `PluginInfo` becomes `org.scijava.discovery.Discovery`, which reports class name, metadata and priority without loading the class; `PluginService` and `PluginIndex` are subsumed by `Context.plugins` | ported |
117117
| `plugin` (the `HandlerPlugin`/`WrapperPlugin`/`TypedPlugin`/`SingletonPlugin` hierarchy and their services) | not ported — each user of these inlines the small contract it needs, as `DataHandle` did | dropped |
118118
| `service` | `org.scijava.context`: `Service` (no longer a plugin, and discovered via `ServiceLoader`), with `Context` holding them. `SciJavaService` has no equivalent — a marker is not needed. `ServiceHelper` and `ServiceIndex` are internal to `Context` | ported |
119-
| `object`, `prefs`, `app` | `org.scijava.context` core services (Phase 2) | planned |
119+
| `object` | with the widgets and conversion layer that use it (Phase 3/4), so a consumer shapes it | planned |
120+
| `prefs` | split: a YAML settings store under `~/.config/fiji` (design settled in [migration-plan.md](migration-plan.md)), and widget value persistence, which belongs with the input harvester (Phase 4). Explicitly **not** `java.util.prefs` | planned |
121+
| `app` | mostly `org.scijava.meta` for version and title metadata; the rest is app-shell material, dropped | planned |
122+
| `thread` | EDT dispatch belongs with the UI layer (Phase 4); parallelism is `org.scijava.concurrent` | planned |
120123
| `convert` | `scijava-convert3` (Phase 2) | planned |
121124
| `module`, `module.process`, `command` | execution layer on `scijava-struct` (Phase 3) | planned |
122125
| `script`, `script.process` | scripting facade + `javax.script` / GraalVM polyglot / Appose adapters (Phase 3) | planned |

0 commit comments

Comments
 (0)