Skip to content

Commit eccf33e

Browse files
ctruedenclaude
andcommitted
scijava-settings: one TOML file a person can read and edit
Settings live at ~/.config/<app>/settings.toml on every platform, honoring XDG_CONFIG_HOME, overridable by a system property. Not what each platform would prefer, and deliberately: what was wrong with java.util.prefs was 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. `Settings` is an object, not a singleton and not a service. Settings belong to an application, and two applications sharing a JVM want two of them. That is the line this codebase had been drawing without saying it: static facades for stateless capabilities -- Converters, Locations, Scripts, since converting a string to an int does not depend on which application you are -- and scoped objects for anything with identity or lifetime. A static settings store would have quietly spent the multiple-contexts promise, and then the honest question would be why there is a container at all. A table per command, keyed by its identifier rather than by its component's coordinates: a class moving between artifacts would otherwise lose what the user chose, which is a refactor nobody should be punished for. Values map onto TOML's own types by a small hardcoded table with string as the fallback, so a List<File> is an array of strings rather than one mangled string, and reading converts element-wise through convert3. Widgets need no serialization API for this: serialization is a property of the type, and a widget is a view -- which is also why it needs no answer per toolkit. Comments survive a save. The file is one people edit, and a store that ate the "# 0.7 because the detector is noisy" beside a value is one they would stop editing. The TOML is parsed here: tables, all four string forms, integers in four bases, floats, booleans, all four date-and-time types, arrays -- with inline tables and arrays of tables refused by line number rather than misunderstood. Neither candidate library is modular, and an automatic module in a foundation component is the trade that dropped MigLayout; the API is small enough that tomlj can take its place later. Persistence is LoadInputs and SaveInputs, both preprocessors, so a caller can run a command without persistence interfering. Saving before the run rather than after is Curtis's call and a good one: saving afterwards loses the values whenever the run threw, which is exactly when the user is about to try again. There is a test that fails under the other design. Two things fell out below it: - Execution.isSupplied(key), because "did the caller pass this?" is not "is this parameter empty?" -- a double is never empty, so loading by null-check would never fill a primitive, and overwriting regardless would make a remembered value beat an explicit one. SciJava Common used a mutable `resolved` flag per parameter; the run knows what it was given, so it is asked instead. - A convert3 bug: CastConverter saw a List bound for List<File>, called it already the right type, and returned a List<String> untouched -- the right container full of the wrong things. It now declines a parameterized collection and lets the element-wise converter have it. The earlier tests missed this because they all converted arrays to lists, where the raw types differ. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NShAz21gbEHnGzhVnC47cb
1 parent 3a2aa7e commit eccf33e

21 files changed

Lines changed: 2303 additions & 5 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1004,6 +1004,67 @@ scijava --help "Gaussian Blur"
10041004
add an argument, and until then a parser of some forty lines does. `MainService`
10051005
has no equivalent either - `main` is a method.
10061006

1007+
### Settings
1008+
1009+
**`scijava-settings`** (`org.scijava.settings`) is built: one TOML file a
1010+
person can read, edit, copy between machines and name in a forum post.
1011+
1012+
- **One path on every platform**: `~/.config/<app>/settings.toml`, honoring
1013+
`XDG_CONFIG_HOME`, overridable by a system property. Not what each platform
1014+
would prefer, and deliberately: what was wrong with `java.util.prefs` was
1015+
that the store was *opaque*, and the cure for that is one answer to "where
1016+
is it?" rather than three correct ones. Appose made the same choice.
1017+
- **`Settings` is an object, not a singleton and not a service.** Settings
1018+
belong to an application, so two applications sharing a JVM get two. This is
1019+
the line the codebase had been drawing without saying: *static facades for
1020+
stateless capabilities* (`Converters`, `Locations`, `Scripts` - converting a
1021+
string to an `int` does not depend on which application you are), *scoped
1022+
objects for anything with identity or lifetime*. Making settings static
1023+
would have quietly spent the multiple-contexts promise, and the answer to
1024+
"why have a container at all, then" would have been "no reason".
1025+
- **A table per command, a key per parameter**, keyed by the command's
1026+
identifier - the class name, or the script's path - and not by its
1027+
component's coordinates: a class moving between artifacts would otherwise
1028+
lose what the user chose, and that is a refactor nobody should be punished
1029+
for.
1030+
- **Values map onto TOML's own types**, by a small hardcoded table, with a
1031+
string as the fallback for anything else. So a `List<File>` is an array of
1032+
strings rather than one mangled string, and reading it back converts
1033+
element-wise through `scijava-convert3`. Widgets need no serialization API
1034+
for this, which is just as well: serialization is a property of the *type*,
1035+
and a widget is a view. That is also why it needs no answer per toolkit.
1036+
- **Comments survive a save.** The file is one people edit; a store that ate
1037+
the `# 0.7 because the detector is noisy` somebody left beside a value is a
1038+
store they would stop editing.
1039+
- **The TOML is parsed here**, covering what settings need - tables, all four
1040+
string forms, integers in four bases, floats, booleans, all four
1041+
date-and-time types, arrays - and refusing inline tables and arrays of
1042+
tables by line number rather than misunderstanding them. Neither candidate
1043+
library is modular, and an automatic module in a foundation component is the
1044+
same trade that dropped MigLayout; the API is small enough that `tomlj` can
1045+
take its place if settings outgrow this.
1046+
- **Persistence is two preprocessors**, `LoadInputs` and `SaveInputs`, so that
1047+
a caller can run a command without persistence interfering - which is what
1048+
the processor chain is for. Saving is a *pre*processor, after the harvester:
1049+
doing it after the run would lose the values whenever the run threw, which
1050+
is exactly when the user is about to try again and exactly when retyping
1051+
everything is most infuriating.
1052+
1053+
It also turned up two things below it:
1054+
1055+
- **`Execution.isSupplied(key)`** is new, because "did the caller pass this?"
1056+
is not the same question as "is this parameter empty?" - a `double` is never
1057+
empty, so loading remembered values by looking for nulls would never fill a
1058+
primitive, and overwriting regardless would make a remembered value beat an
1059+
explicit one. SciJava Common answered this with a mutable `resolved` flag on
1060+
each parameter; the run knows what it was given, so it is asked instead.
1061+
- **A bug in `scijava-convert3`**: `CastConverter` saw a `List` going to a
1062+
`List<File>`, said "already the right type", and handed back a
1063+
`List<String>` unchanged - the right container full of the wrong things,
1064+
which surfaces much later as a `ClassCastException` somewhere else. It now
1065+
declines a parameterized collection and lets the element-wise converter have
1066+
it.
1067+
10071068
### Phase 4 — UI and desktop
10081069

10091070
- **`scijava-harvest`** (`org.scijava.harvest`): the model behind a parameter

‎docs/migration.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ A **dropped** row is a successful outcome, not a gap.
4747
| `NumberUtils` | `org.scijava.common3.Numbers`. `getMinimumNumber`/`getMaximumNumber` → `minimum`/`maximum`; `asBigDecimal`/`asBigInteger` → `bigDecimal`/`bigInteger`; `clampToRange` → `clamp`. **`toNumber` no longer consults a conversion framework** — it handles numbers and strings only, so `common3` stays dependency-free | ported |
4848
| `PlatformUtils` | `org.scijava.common3.Platforms` | ported |
4949
| `POM` | `org.scijava.meta.POM` | ported |
50-
| `Prefs` | `scijava-context` prefs service (Phase 2); already deprecated in SJC | planned |
50+
| `Prefs` | `org.scijava.settings.Settings`; already deprecated in SJC | ported |
5151
| `ProcessUtils` | `org.scijava.common3.Processes`, reimplemented on `ProcessBuilder`; no longer needs `ReadInto` | ported |
5252
| `PropertiesHelper` | none — inline | dropped |
5353
| `Sizable`, `SizableArrayList` | none — the reflective-resizing rationale died with Java 17 | dropped |
@@ -117,7 +117,7 @@ A **dropped** row is a successful outcome, not a gap.
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 |
119119
| `object` | with the widgets and conversion layer that use it (Phase 3/4), so a consumer shapes it | planned |
120-
| `prefs` | split: a TOML 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 |
120+
| `prefs` | `org.scijava.settings`: one TOML file a person can read, edit and copy, at `~/.config/<app>/settings.toml` on every platform. `PrefService` becomes `Settings`, an ordinary object rather than a service or a singleton - settings belong to an application, and two applications in one JVM want two of them. A table per command (its identifier), a key per parameter; values map onto TOML's own types, so a `List<File>` is an array of strings rather than one mangled string, and reading converts through `scijava-convert3`. Widget value persistence is `LoadInputs` and `SaveInputs`, both **preprocessors**: saving after the run would lose the values exactly when a run failed and the user is about to try again | ported |
121121
| `app` | mostly `org.scijava.meta` for version and title metadata; the rest is app-shell material, dropped | planned |
122122
| `thread` | EDT dispatch belongs with the UI layer (Phase 4); parallelism is `org.scijava.concurrent` | planned |
123123
| `convert` | `org.scijava.convert3`: `Converter` asks one question - can you turn *this value* into *that type* - where SciJava Common had eight `canConvert` overloads and a `ConversionRequest` to carry the combinations. `ConvertService` becomes `Converters`, backed by plain `ServiceLoader` so that conversion sits *below* the container: parameter binding converts, and a script or command line supplies strings for everything. `DefaultConverter`'s pile of special cases becomes one converter per concern (cast, number, string, to-string, array, collection, constructor, file/path), each contributable and orderable by priority. `Converter.of(String.class, Foo.class, Foo::parse)` covers the common case in a line | ported |

‎pom.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@
9191
<module>scijava-priority</module>
9292
<module>scijava-progress</module>
9393
<module>scijava-script3</module>
94+
<module>scijava-settings</module>
9495
<module>scijava-spi</module>
9596
<module>scijava-struct</module>
9697
<module>scijava-swing</module>

‎scijava-convert3/src/main/java/org/scijava/convert3/CastConverter.java‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,9 @@
2929

3030
package org.scijava.convert3;
3131

32+
import java.lang.reflect.ParameterizedType;
3233
import java.lang.reflect.Type;
34+
import java.util.Collection;
3335

3436
import org.scijava.common3.Classes;
3537
import org.scijava.common3.Types;
@@ -62,7 +64,25 @@ public boolean supports(final Object source, final Type dest) {
6264
if (source == null || dest == null) return false;
6365
final Class<?> raw = Types.raw(dest);
6466
if (raw == null) return false;
65-
return Classes.box(raw).isInstance(source);
67+
if (!Classes.box(raw).isInstance(source)) return false;
68+
// NB: a collection is only "already the right type" if what it holds is
69+
// too, and erasure means we cannot tell by looking at the type. A
70+
// List<String> handed to a List<File> would otherwise be returned
71+
// unchanged -- the right raw type full of the wrong things -- so the
72+
// element-wise converter gets it instead, and returns it untouched when
73+
// the elements do match.
74+
return !(source instanceof Collection && isParameterized(dest));
75+
}
76+
77+
/** Gets whether the type says anything about what it contains. */
78+
private static boolean isParameterized(final Type dest) {
79+
if (!(dest instanceof ParameterizedType)) return false;
80+
for (final Type argument : ((ParameterizedType) dest)
81+
.getActualTypeArguments())
82+
{
83+
if (argument != Object.class) return true;
84+
}
85+
return false;
6686
}
6787

6888
@Override

‎scijava-convert3/src/test/java/org/scijava/convert3/ConvertersTest.java‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,27 @@ public void testCollections() {
141141
assertEquals(Set.of(1, 2), set);
142142
}
143143

144+
/**
145+
* A collection of the wrong element type is converted, not waved through.
146+
* <p>
147+
* NB: erasure makes {@code List<String>} and {@code List<File>} the same
148+
* raw type, so a cast would return the right kind of container full of the
149+
* wrong things - which is the sort of bug that surfaces much later, as a
150+
* ClassCastException somewhere else entirely.
151+
* </p>
152+
*/
153+
@Test
154+
public void testCollectionElementsAreConverted() {
155+
final List<?> converted = (List<?>) converters.convert(List.of("1", "2"),
156+
Types.parameterize(List.class, Integer.class));
157+
158+
assertEquals(List.of(1, 2), converted);
159+
160+
// and a list that is already right comes back equal
161+
assertEquals(List.of(1, 2), converters.convert(List.of(1, 2), Types
162+
.parameterize(List.class, Integer.class)));
163+
}
164+
144165
/** The three ways of naming a file all convert to one another. */
145166
@Test
146167
public void testFilesAndPaths() {

‎scijava-execute/src/main/java/org/scijava/execute/Execution.java‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,22 @@ public interface Execution {
7575
/** Gets why this run was declined, if it was. */
7676
Optional<String> reason();
7777

78+
/**
79+
* Gets whether the caller supplied this input.
80+
* <p>
81+
* NB: not the same question as whether the parameter holds a value, and the
82+
* difference matters. A {@code double} always holds one, so a preprocessor
83+
* filling in "empty" parameters by looking for nulls would never fill a
84+
* primitive - and one that overwrote them regardless would throw away what
85+
* the caller passed. SciJava Common answered this with a mutable
86+
* {@code resolved} flag on each parameter; here the run knows what it was
87+
* given, so it is asked instead.
88+
* </p>
89+
*
90+
* @param key the parameter's name
91+
*/
92+
boolean isSupplied(String key);
93+
7894
/**
7995
* Gets the outputs produced so far. Empty until the object has run, so this
8096
* is for postprocessors.

‎scijava-execute/src/main/java/org/scijava/execute/FieldParameterMember.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,8 @@ public Map<String, String> attrs() {
139139
put(attrs, SOFT_MIN, parameter.softMin());
140140
put(attrs, SOFT_MAX, parameter.softMax());
141141
put(attrs, STYLE, parameter.style());
142+
if (!parameter.persist()) attrs.put(PERSIST, "false");
143+
put(attrs, PERSIST_KEY, parameter.persistKey());
142144
return attrs;
143145
}
144146

‎scijava-execute/src/main/java/org/scijava/execute/Parameter.java‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,26 @@
7474
/** Whether a value must be supplied. */
7575
boolean required() default true;
7676

77+
/**
78+
* Whether to remember this value between runs.
79+
* <p>
80+
* A dialog opens showing what the user chose last time, which is what makes
81+
* one feel like it remembers them. Say no for a value that should not carry
82+
* over - a file to overwrite, a one-off seed, anything whose staleness
83+
* would be a nasty surprise.
84+
* </p>
85+
*/
86+
boolean persist() default true;
87+
88+
/**
89+
* The name this value is remembered under, where its own would be wrong.
90+
* <p>
91+
* Renaming a field would otherwise lose what the user chose; naming it here
92+
* keeps the two apart.
93+
* </p>
94+
*/
95+
String persistKey() default "";
96+
7797
/** A human-readable label, for display. */
7898
String label() default "";
7999

‎scijava-execute/src/main/java/org/scijava/execute/ParameterMember.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,12 @@ public interface ParameterMember<T> extends Member<T> {
8787
/** Metadata key: the largest value a slider should span. */
8888
String SOFT_MAX = "softMax";
8989

90+
/** Metadata key: whether to remember this value between runs. */
91+
String PERSIST = "persist";
92+
93+
/** Metadata key: the name to remember this value under. */
94+
String PERSIST_KEY = "persistKey";
95+
9096
/** Metadata key: a hint about how to display this parameter. */
9197
String STYLE = "style";
9298

‎scijava-execute/src/main/java/org/scijava/execute/Runner.java‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
import java.util.Comparator;
3434
import java.util.List;
3535
import java.util.Map;
36+
import java.util.Set;
3637
import java.util.Optional;
3738
import java.util.concurrent.ExecutorService;
3839
import java.util.concurrent.Executors;
@@ -137,7 +138,7 @@ private ExecutionResult execute(final Executable executable,
137138
{
138139
final ExecutableInstance instance = executable.create();
139140
final DefaultExecution execution = new DefaultExecution(instance, //
140-
Executables.bind(instance.parameters(), inputs, false));
141+
Executables.bind(instance.parameters(), inputs, false), inputs.keySet());
141142

142143
for (final Preprocessor preprocessor : preprocessors) {
143144
Executables.checkCancellation();
@@ -203,11 +204,20 @@ private static class DefaultExecution implements Execution {
203204
private boolean declined;
204205
private Map<String, Object> outputs = Map.of();
205206

207+
/** The names the caller passed, as opposed to what a field holds. */
208+
private final Set<String> supplied;
209+
206210
DefaultExecution(final ExecutableInstance instance,
207-
final StructInstance<?> parameters)
211+
final StructInstance<?> parameters, final Set<String> supplied)
208212
{
209213
this.instance = instance;
210214
this.parameters = parameters;
215+
this.supplied = Set.copyOf(supplied);
216+
}
217+
218+
@Override
219+
public boolean isSupplied(final String key) {
220+
return supplied.contains(key);
211221
}
212222

213223
void complete(final Map<String, Object> outputs) {

0 commit comments

Comments
 (0)