Skip to content

Commit 758e94a

Browse files
ctruedenclaude
andcommitted
scijava-convert3: one question, and it sits below the container
Binding an input to a parameter converts, and a script, a command line and a text field all have only strings to offer -- so conversion cannot be something only a container has. scijava-convert3 depends on nothing but scijava-common3 and scijava-priority, and finds its converters through plain ServiceLoader. `Converter.supports(Object, Type)` asks whether *this value* can become *that type*. SciJava Common had eight `canConvert` overloads across Object/Class/Type pairings, a ConversionRequest to carry the combinations, and an AbstractConverter to make that bearable. Declaring sourceType() and destType() answers the common case by itself, so Converter.of(String.class, Foo.class, Foo::parse) is a whole converter. DefaultConverter's sequence of special cases becomes one converter per concern -- cast, number, string-to-value, to-string, array, collection, file/path, and a wrapping constructor last -- each separately discoverable, orderable by priority, and replaceable by a component that disagrees, which a monolith never allowed. Unconvertible is not zero: tryConvert returns empty and convert throws, where SciJava Common returned null for both "cannot" and "converted to null". That distinction is what a widget needs to leave a parameter alone while the user is still typing -- and with it available, `Widgets.toType` is now one call into convert3 rather than a third copy of text parsing. A BigDecimal from a double goes through the string, so 0.1 stays 0.1 rather than the binary double nearest it. Wired in where it earns its keep: `Executables.bind` converts supplied inputs, so run(cmd, Map.of("a", "1.5")) reaches a `double a`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 484cd71 commit 758e94a

24 files changed

Lines changed: 1761 additions & 26 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -762,6 +762,45 @@ ways, dependency flowing one way. That is what makes the migration incremental
762762
rather than a big bang, and it should be sequenced *with* layer 1 rather than
763763
after it.
764764

765+
### Conversion
766+
767+
**`scijava-convert3`** (`org.scijava.convert3`) is built, and deliberately
768+
sits *below* the execution layer rather than beside it: binding an input to a
769+
parameter converts, and a script, a command line and a text field all have
770+
only strings to offer. It therefore depends on nothing but `scijava-common3`
771+
and `scijava-priority`, and finds its converters through plain
772+
`ServiceLoader` - no container, no configuration.
773+
774+
- **One question, not eight.** `Converter.supports(Object, Type)` asks whether
775+
*this value* can become *that type*. SciJava Common had eight `canConvert`
776+
overloads across `Object`/`Class`/`Type` pairings, plus a
777+
`ConversionRequest` to carry the combinations, plus an `AbstractConverter`
778+
to make the overloads bearable. The declared `sourceType()`/`destType()`
779+
answer the common case by themselves, so
780+
`Converter.of(String.class, Foo.class, Foo::parse)` is a whole converter.
781+
- **One converter per concern**, rather than one `DefaultConverter` holding
782+
every special case in sequence: cast, number, string-to-value, to-string,
783+
array, collection, file/path, and a wrapping constructor last. Each is
784+
discoverable, orderable by priority, and replaceable by a downstream
785+
component that disagrees.
786+
- **Unconvertible is not zero.** `tryConvert` returns empty where a value
787+
cannot become the type, and `convert` throws. Text that is half-typed
788+
converts to nothing, which is what lets a widget leave a parameter alone
789+
while the user is still typing - a distinction SciJava Common could not
790+
make, since it returned null for both "no" and "null".
791+
- **Exactness where the type asked for it**: a `BigDecimal` from a `double`
792+
goes through the string, so `0.1` is `0.1` and not the binary double nearest
793+
to it.
794+
- **It removed duplication rather than adding a layer.** The UI's
795+
`Widgets.toType` - three bindings' worth of text parsing - is now one call
796+
into it, so a widget turning text into a value does exactly what a script
797+
does.
798+
799+
Still open: an `ObjectService` equivalent (what values *exist* that could be
800+
converted into this parameter) is what a chooser widget wants, and is a
801+
separate question from what conversions are possible. It lands with the object
802+
widget.
803+
765804
### Phase 4 — UI and desktop
766805

767806
- **`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
@@ -28,7 +28,7 @@ A **dropped** row is a successful outcome, not a gap.
2828
| `ClassUtils` | `org.scijava.common3.Classes` (mostly already deprecated in SJC) | ported |
2929
| `ColorRGB`, `ColorRGBA`, `Colors` | UI layer (Phase 4) | open |
3030
| `CombineAnnotations`, `Combiner`, `MetaInfCombiner`, `ServiceCombiner` | build-time tooling; `scijava-maven-plugin` | dropped |
31-
| `ConversionUtils` | `scijava-convert3` (Phase 2); already deprecated in SJC | planned |
31+
| `ConversionUtils` | `org.scijava.convert3.Converters`; already deprecated in SJC | ported |
3232
| `DebugUtils` | `org.scijava.common3.Threads` | ported |
3333
| `DefaultTreeNode`, `TreeNode` | on hold — only `imagej-common` uses it; may move there | open |
3434
| `DigestUtils` | `org.scijava.common3.Digests`. `digest` now throws `IllegalArgumentException` for an unknown algorithm rather than returning `null`; `best*` is SHA-1, since every Java platform guarantees it | ported |
@@ -120,7 +120,7 @@ A **dropped** row is a successful outcome, not a gap.
120120
| `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 |
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 |
123-
| `convert` | `scijava-convert3` (Phase 2) | planned |
123+
| `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 |
124124
| `module`, `module.process` | `org.scijava.execute`: `@Parameter` on fields, `Executables` for the plain case, and `Runner` for the processor chain. `ModuleService.run` becomes `Runner.run`, still returning a future, but of an `ExecutionResult` that reports a declined run with its reason and its author rather than through `ModulePreprocessor.isCanceled()` | ported |
125125
| `command` | `org.scijava.command`: `Command` is a `Runnable` whose `@Parameter` fields are its struct; `@Menu` (repeatable) carries the presentation metadata, read from the annotation index without loading the class. `CommandInfo` replaces `ModuleInfo` and needs no `Context`; `MenuTree` replaces `ShadowMenu`. There is no `DynamicCommand`: see `choicesFrom` and `@Group(membersFrom)` | ported |
126126
| `script`, `script.process` | scripting facade + `javax.script` / GraalVM polyglot / Appose adapters (Phase 3) | planned |

‎pom.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@
6363
<module>scijava-command</module>
6464
<module>scijava-common3</module>
6565
<module>scijava-context</module>
66+
<module>scijava-convert3</module>
6667
<module>scijava-context-test</module>
6768
<module>scijava-concurrent</module>
6869
<module>scijava-discovery</module>

‎scijava-convert3/pom.xml‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
5+
<parent>
6+
<groupId>org.scijava</groupId>
7+
<artifactId>pom-scijava</artifactId>
8+
<version>44.0.0</version>
9+
<relativePath />
10+
</parent>
11+
12+
<artifactId>scijava-convert3</artifactId>
13+
<!--
14+
NB: the major version tracks the incarnation, per the incubator README.
15+
The 1.x.y of the other components is a legacy of the first monoversioned
16+
release, not the intended scheme.
17+
-->
18+
<version>3.0.0-SNAPSHOT</version>
19+
20+
<name>SciJava Convert</name>
21+
<description>Converting a value to the type something else wants.</description>
22+
<url>https://github.com/scijava/scijava</url>
23+
<inceptionYear>2026</inceptionYear>
24+
<organization>
25+
<name>SciJava</name>
26+
<url>https://scijava.org/</url>
27+
</organization>
28+
<licenses>
29+
<license>
30+
<name>Simplified BSD License</name>
31+
<distribution>repo</distribution>
32+
</license>
33+
</licenses>
34+
35+
<developers>
36+
<developer>
37+
<id>ctrueden</id>
38+
<name>Curtis Rueden</name>
39+
<roles>
40+
<role>founder</role>
41+
<role>lead</role>
42+
<role>reviewer</role>
43+
<role>support</role>
44+
<role>maintainer</role>
45+
</roles>
46+
</developer>
47+
<developer>
48+
<id>gselzer</id>
49+
<name>Gabriel Selzer</name>
50+
<roles>
51+
<role>founder</role>
52+
<role>debugger</role>
53+
<role>reviewer</role>
54+
<role>support</role>
55+
</roles>
56+
</developer>
57+
</developers>
58+
<contributors>
59+
<contributor>
60+
<name>Johannes Schindelin</name>
61+
<properties><id>dscho</id></properties>
62+
</contributor>
63+
</contributors>
64+
65+
<mailingLists>
66+
<mailingList>
67+
<name>Image.sc Forum</name>
68+
<archive>https://forum.image.sc/tag/scijava</archive>
69+
</mailingList>
70+
</mailingLists>
71+
72+
<scm>
73+
<connection>scm:git:https://github.com/scijava/scijava</connection>
74+
<developerConnection>scm:git:git@github.com:scijava/scijava</developerConnection>
75+
<tag>HEAD</tag>
76+
<url>https://github.com/scijava/scijava</url>
77+
</scm>
78+
<issueManagement>
79+
<system>GitHub Issues</system>
80+
<url>https://github.com/scijava/scijava/issues</url>
81+
</issueManagement>
82+
<ciManagement>
83+
<system>GitHub Actions</system>
84+
<url>https://github.com/scijava/scijava/actions</url>
85+
</ciManagement>
86+
87+
<properties>
88+
<package-name>org.scijava.convert3</package-name>
89+
90+
<license.licenseName>bsd_2</license.licenseName>
91+
<license.copyrightOwners>SciJava developers.</license.copyrightOwners>
92+
93+
<!-- Note: These versions must match across all component POMs! -->
94+
<scijava-common3.version>1.0.1-SNAPSHOT</scijava-common3.version>
95+
<scijava-priority.version>1.0.1-SNAPSHOT</scijava-priority.version>
96+
</properties>
97+
98+
<dependencies>
99+
<!--
100+
NB: Keep this component standalone, and in particular below the
101+
execution layer: parameter binding converts, so convert cannot be
102+
something only a container has. Converters come from plain
103+
ServiceLoader.
104+
-->
105+
<dependency>
106+
<groupId>org.scijava</groupId>
107+
<artifactId>scijava-common3</artifactId>
108+
<version>${scijava-common3.version}</version>
109+
</dependency>
110+
<dependency>
111+
<groupId>org.scijava</groupId>
112+
<artifactId>scijava-priority</artifactId>
113+
<version>${scijava-priority.version}</version>
114+
</dependency>
115+
116+
<!-- Test scope dependencies -->
117+
<dependency>
118+
<groupId>org.junit.jupiter</groupId>
119+
<artifactId>junit-jupiter-api</artifactId>
120+
<scope>test</scope>
121+
</dependency>
122+
</dependencies>
123+
124+
<build>
125+
<plugins>
126+
<plugin>
127+
<artifactId>maven-enforcer-plugin</artifactId>
128+
<executions>
129+
<execution>
130+
<id>enforce-package-rules</id>
131+
<goals>
132+
<goal>enforce</goal>
133+
</goals>
134+
<phase>test</phase>
135+
<configuration>
136+
<rules>
137+
<NoPackageCyclesRule implementation="org.scijava.maven.plugin.enforcer.NoPackageCyclesRule" />
138+
<NoSubpackageDependenceRule implementation="org.scijava.maven.plugin.enforcer.NoSubpackageDependenceRule" />
139+
</rules>
140+
</configuration>
141+
</execution>
142+
</executions>
143+
</plugin>
144+
<plugin>
145+
<artifactId>maven-javadoc-plugin</artifactId>
146+
<configuration>
147+
<links>
148+
<link>https://javadoc.scijava.org/Java11/</link>
149+
</links>
150+
</configuration>
151+
</plugin>
152+
</plugins>
153+
</build>
154+
</project>
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
/*
2+
* #%L
3+
* Converting a value to the type something else wants.
4+
* %%
5+
* Copyright (C) 2026 SciJava developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
module org.scijava.convert3 {
31+
32+
exports org.scijava.convert3;
33+
34+
requires transitive org.scijava.common3;
35+
requires org.scijava.priority;
36+
37+
uses org.scijava.convert3.Converter;
38+
39+
provides org.scijava.convert3.Converter with
40+
org.scijava.convert3.CastConverter,
41+
org.scijava.convert3.NumberConverter,
42+
org.scijava.convert3.StringConverter,
43+
org.scijava.convert3.ToStringConverter,
44+
org.scijava.convert3.ArrayConverter,
45+
org.scijava.convert3.CollectionConverter,
46+
org.scijava.convert3.PathConverters.FileToPath,
47+
org.scijava.convert3.PathConverters.PathToFile,
48+
org.scijava.convert3.PathConverters.StringToPath,
49+
org.scijava.convert3.ConstructorConverter;
50+
51+
}
Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
/*
2+
* #%L
3+
* Converting a value to the type something else wants.
4+
* %%
5+
* Copyright (C) 2026 SciJava developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
package org.scijava.convert3;
31+
32+
import java.lang.reflect.Array;
33+
import java.lang.reflect.Type;
34+
import java.util.Collection;
35+
36+
import org.scijava.common3.Types;
37+
import org.scijava.priority.Priority;
38+
39+
/**
40+
* Converts to an array, converting each element on the way.
41+
* <p>
42+
* A collection becomes an array, an array becomes an array of another
43+
* component type, and a lone value becomes an array of one - which is what
44+
* makes {@code "3"} usable where {@code int[]} is wanted, a thing scripts and
45+
* command lines do constantly.
46+
* </p>
47+
*
48+
* @author Curtis Rueden
49+
*/
50+
public class ArrayConverter implements Converter<Object, Object> {
51+
52+
@Override
53+
public Type sourceType() {
54+
return Object.class;
55+
}
56+
57+
@Override
58+
public Type destType() {
59+
return Object[].class;
60+
}
61+
62+
@Override
63+
public boolean supports(final Object source, final Type dest) {
64+
return source != null && Types.component(dest) != null;
65+
}
66+
67+
@Override
68+
public Object convert(final Object source, final Type dest) {
69+
final Type componentType = Types.component(dest);
70+
final Class<?> component = Types.raw(componentType);
71+
if (component == null) return null;
72+
73+
final Object[] elements = elements(source);
74+
final Object array = Array.newInstance(component, elements.length);
75+
final Converters converters = Converters.get();
76+
for (int i = 0; i < elements.length; i++) {
77+
// NB: each element is converted in turn, so a List<String> reaches an
78+
// int[] without anything knowing about that pair specifically.
79+
final Object element = converters.tryConvert(elements[i], componentType)
80+
.orElse(null);
81+
if (element == null && elements[i] != null) return null;
82+
Array.set(array, i, element);
83+
}
84+
return array;
85+
}
86+
87+
@Override
88+
public double priority() {
89+
return Priority.HIGH;
90+
}
91+
92+
// -- Helper methods --
93+
94+
private static Object[] elements(final Object source) {
95+
if (source instanceof Collection) {
96+
return ((Collection<?>) source).toArray();
97+
}
98+
if (source.getClass().isArray()) {
99+
final int length = Array.getLength(source);
100+
final Object[] elements = new Object[length];
101+
for (int i = 0; i < length; i++)
102+
elements[i] = Array.get(source, i);
103+
return elements;
104+
}
105+
return new Object[] { source };
106+
}
107+
}

0 commit comments

Comments
 (0)