Skip to content

Commit 790ec74

Browse files
ctruedenclaude
andcommitted
scijava-io3: port locations, standalone on plain ServiceLoader
Ports org.scijava.io.location as org.scijava.io3.location, plus ByteBank and ByteArrayByteBank, which BytesLocation needs. This component is deliberately standalone. It is broadly useful on its own -- to Bio-Formats, for instance -- so its only dependency is scijava-collections, and resolvers are discovered with plain ServiceLoader rather than through Discoverer or a container. Nothing here requires buying into a framework. Plain ServiceLoader is viable precisely here, even though a generic discovery facade cannot use it: the constraint is that ServiceLoader resolves `uses` against its caller's module, which only hurts when discovering arbitrary types on another module's behalf. This component knows its own service type, so it declares `uses` in its own module-info.java and is self-contained. Consequent API changes, recorded in docs/migration.md: - LocationService and DefaultLocationService become Locations, which can also be constructed with an explicit resolver list for embedding and testing. - LocationResolver no longer extends HandlerPlugin, and carries its own priority() as a plain double rather than depending on scijava-priority. The Priority constants remain compatible with it. - URILocation had an injected LogService that nothing used; it is gone, and its query decoding now uses the charset-typed URLDecoder overload instead of catching an impossible UnsupportedEncodingException. Tests cover discovery without a container, priority ordering deciding between two resolvers that support the same scheme, and the reason the string overload exists: a Windows path is not a valid URI, so it must fall back to being read as a file path. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 313843f commit 790ec74

23 files changed

Lines changed: 1906 additions & 5 deletions

‎docs/migration-plan.md‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -290,9 +290,23 @@ No application context required by anything in this phase.
290290
from the index. It belongs with whichever component defines the
291291
annotation, so it lands in Phase 2.
292292
- **`scijava-io3`** (new, `org.scijava.io3.{location, handle, nio}`): ports
293-
`io.location`, `io.handle`, `io.nio` and `ByteBank`. Handles and resolvers
294-
are found via `Discoverer` + `Priority`. The external `scijava-io-http`
295-
folds in later as `org.scijava.io3.http`.
293+
`io.location`, `io.handle`, `io.nio` and `ByteBank`. Locations are **done**;
294+
handles are next. The external `scijava-io-http` folds in later as
295+
`org.scijava.io3.http`.
296+
- **This component stays standalone**: it is broadly useful on its own — to
297+
Bio-Formats, for instance — so it depends on nothing but
298+
`scijava-collections`, and resolvers are discovered with **plain
299+
`ServiceLoader`** rather than `Discoverer` or a container. Nothing here
300+
requires buying into a framework.
301+
- That works because the `uses`-resolves-against-the-caller constraint only
302+
bites a *generic* facade discovering arbitrary types on another module's
303+
behalf. This component knows its own service type, so it declares
304+
`uses org.scijava.io3.location.LocationResolver` in its own
305+
`module-info.java` and is self-contained.
306+
- `LocationResolver` carries its own `priority()` as a plain `double`
307+
rather than depending on `scijava-priority`; the `Priority` constants are
308+
compatible with it. `Locations` can also be constructed with an explicit
309+
resolver list, for embedding and testing.
296310
- **`scijava-events`** (new, `org.scijava.events`): a clean-room event bus,
297311
no context, designed for typed topics and weak-reference subscribers. Not a
298312
port of the bushe fork — rewriting removes the attribution obligation. The

‎docs/migration.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ A **dropped** row is a successful outcome, not a gap.
2323
| `AppUtils` | `org.scijava.common3.Apps` | ported |
2424
| `ArrayUtils` | mostly dropped: `contains`/`indexOf` → `Arrays.asList(a).contains(v)` for object arrays, a loop or stream for primitives; `array` → an array literal; `toCollection` → no replacement. `safeMultiply32`/`safeMultiply64` → `common3.Numbers` (they wrap `Math.multiplyExact`) | ported |
2525
| `BoolArray`, `ByteArray`, `CharArray`, `DoubleArray`, `FloatArray`, `IntArray`, `LongArray`, `ObjectArray`, `ShortArray`, `PrimitiveArray` | `org.scijava.collections.*` | ported |
26-
| `Bytes` | deferred to `scijava-io3`, its natural consumer; `java.nio.ByteBuffer` covers casual use | open |
26+
| `Bytes` | `scijava-io3`, alongside the handles that need it (Phase 1, in progress) | planned |
2727
| `CheckSezpoz` | none | dropped |
2828
| `ClassUtils` | `org.scijava.common3.Classes` (mostly already deprecated in SJC) | ported |
2929
| `ColorRGB`, `ColorRGBA`, `Colors` | UI layer (Phase 4) | open |
@@ -97,7 +97,9 @@ A **dropped** row is a successful outcome, not a gap.
9797
| `annotations.EclipseHelper` | none — m2e `.factorypath` covers it; `DirectoryIndexer` is ported, so a Maven plugin can still index a directory | dropped |
9898
| `annotations.AnnotationCombiner` | `scijava-maven-plugin` — it merges indexes for shaded JARs, which is build tooling | dropped |
9999
| `annotations.legacy` | none — reads the pre-2013 `META-INF/annotations/` format | dropped |
100-
| `io.location`, `io.handle`, `io.nio`, `ByteBank` | `org.scijava.io3.*` (Phase 1) | planned |
100+
| `io.location` | `org.scijava.io3.location`. `LocationService`/`DefaultLocationService` become `Locations`, backed by plain `ServiceLoader`; `LocationResolver` no longer extends `HandlerPlugin` and carries its own `priority()`. `URILocation`'s injected `LogService` was dead code and is gone | ported |
101+
| `ByteBank`, `ByteArrayByteBank` | `org.scijava.io3` | ported |
102+
| `io.handle`, `io.nio` | `org.scijava.io3.handle` (Phase 1, in progress) | planned |
101103
| `io` (`IOPlugin`, `IOService`, `RecentFileService`) | `scijava-io3` (Phase 1), pending review of what is still used | open |
102104
| `event`, `event.bushe` | `org.scijava.events` — clean-room rewrite, not a port (Phase 1) | planned |
103105
| `parse` | Parsington (`org.scijava.parsington`) | planned |

‎pom.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@
6464
<module>scijava-discovery-test</module>
6565
<module>scijava-function</module>
6666
<module>scijava-index</module>
67+
<module>scijava-io3</module>
6768
<module>scijava-legacy</module>
6869
<module>scijava-meta</module>
6970
<module>scijava-ops-api</module>

‎scijava-io3/pom.xml‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
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-io3</artifactId>
13+
<version>1.0.0-SNAPSHOT</version>
14+
15+
<name>SciJava I/O</name>
16+
<description>Locations and data handles: a uniform way to address and read bytes.</description>
17+
<url>https://github.com/scijava/scijava</url>
18+
<inceptionYear>2026</inceptionYear>
19+
<organization>
20+
<name>SciJava</name>
21+
<url>https://scijava.org/</url>
22+
</organization>
23+
<licenses>
24+
<license>
25+
<name>Simplified BSD License</name>
26+
<distribution>repo</distribution>
27+
</license>
28+
</licenses>
29+
30+
<developers>
31+
<developer>
32+
<id>ctrueden</id>
33+
<name>Curtis Rueden</name>
34+
<roles>
35+
<role>founder</role>
36+
<role>lead</role>
37+
<role>reviewer</role>
38+
<role>support</role>
39+
<role>maintainer</role>
40+
</roles>
41+
</developer>
42+
<developer>
43+
<id>gselzer</id>
44+
<name>Gabriel Selzer</name>
45+
<roles>
46+
<role>founder</role>
47+
<role>debugger</role>
48+
<role>reviewer</role>
49+
<role>support</role>
50+
</roles>
51+
</developer>
52+
</developers>
53+
<contributors>
54+
<contributor>
55+
<name>Johannes Schindelin</name>
56+
<properties><id>dscho</id></properties>
57+
</contributor>
58+
</contributors>
59+
60+
<mailingLists>
61+
<mailingList>
62+
<name>Image.sc Forum</name>
63+
<archive>https://forum.image.sc/tag/scijava</archive>
64+
</mailingList>
65+
</mailingLists>
66+
67+
<scm>
68+
<connection>scm:git:https://github.com/scijava/scijava</connection>
69+
<developerConnection>scm:git:git@github.com:scijava/scijava</developerConnection>
70+
<tag>HEAD</tag>
71+
<url>https://github.com/scijava/scijava</url>
72+
</scm>
73+
<issueManagement>
74+
<system>GitHub Issues</system>
75+
<url>https://github.com/scijava/scijava/issues</url>
76+
</issueManagement>
77+
<ciManagement>
78+
<system>GitHub Actions</system>
79+
<url>https://github.com/scijava/scijava/actions</url>
80+
</ciManagement>
81+
82+
<properties>
83+
<package-name>org.scijava.io3</package-name>
84+
85+
<license.licenseName>bsd_2</license.licenseName>
86+
<license.copyrightOwners>SciJava developers.</license.copyrightOwners>
87+
88+
<!-- Note: These versions must match across all component POMs! -->
89+
<scijava-collections.version>1.0.1-SNAPSHOT</scijava-collections.version>
90+
</properties>
91+
92+
<dependencies>
93+
<!--
94+
NB: Keep this component standalone. It is broadly useful on its own (to
95+
Bio-Formats, for instance), and resolvers are discovered with plain
96+
ServiceLoader rather than a SciJava container, so nothing here requires
97+
buying into a framework.
98+
-->
99+
<dependency>
100+
<groupId>org.scijava</groupId>
101+
<artifactId>scijava-collections</artifactId>
102+
<version>${scijava-collections.version}</version>
103+
</dependency>
104+
105+
<!-- Test scope dependencies -->
106+
<dependency>
107+
<groupId>org.junit.jupiter</groupId>
108+
<artifactId>junit-jupiter-api</artifactId>
109+
<scope>test</scope>
110+
</dependency>
111+
</dependencies>
112+
113+
<build>
114+
<plugins>
115+
<plugin>
116+
<artifactId>maven-enforcer-plugin</artifactId>
117+
<executions>
118+
<execution>
119+
<id>enforce-package-rules</id>
120+
<goals>
121+
<goal>enforce</goal>
122+
</goals>
123+
<phase>test</phase>
124+
<configuration>
125+
<rules>
126+
<NoPackageCyclesRule implementation="org.scijava.maven.plugin.enforcer.NoPackageCyclesRule" />
127+
<NoSubpackageDependenceRule implementation="org.scijava.maven.plugin.enforcer.NoSubpackageDependenceRule" />
128+
</rules>
129+
</configuration>
130+
</execution>
131+
</executions>
132+
</plugin>
133+
<plugin>
134+
<artifactId>maven-javadoc-plugin</artifactId>
135+
<configuration>
136+
<links>
137+
<link>https://javadoc.scijava.org/Java11/</link>
138+
</links>
139+
</configuration>
140+
</plugin>
141+
</plugins>
142+
</build>
143+
</project>
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
/*
2+
* #%L
3+
* Locations and data handles: a uniform way to address and read bytes.
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.io3 {
31+
32+
exports org.scijava.io3;
33+
exports org.scijava.io3.location;
34+
35+
requires org.scijava.collections;
36+
37+
uses org.scijava.io3.location.LocationResolver;
38+
39+
provides org.scijava.io3.location.LocationResolver with
40+
org.scijava.io3.location.FileLocationResolver;
41+
42+
}
Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
/*
2+
* #%L
3+
* Locations and data handles: a uniform way to address and read bytes.
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.io3;
31+
32+
import org.scijava.collections.ByteArray;
33+
34+
/**
35+
* {@link ByteBank} implementation backed by a {@link ByteArray}. Self-growing
36+
* up to a maximum capacity of {@link Integer#MAX_VALUE}.
37+
*
38+
* @author Gabriel Einsdorf
39+
*/
40+
public class ByteArrayByteBank implements ByteBank {
41+
42+
private final ByteArray buffer;
43+
private long size;
44+
45+
/**
46+
* Creates a {@link ByteArrayByteBank}.
47+
*/
48+
public ByteArrayByteBank() {
49+
this(new ByteArray());
50+
}
51+
52+
/**
53+
* Creates a {@link ByteArrayByteBank} with the specified initial capacity.
54+
*
55+
* @param initialCapacity the initial capacity of this {@link ByteBank}
56+
*/
57+
public ByteArrayByteBank(final int initialCapacity) {
58+
this(emptyByteArrayOfCapacity(initialCapacity));
59+
}
60+
61+
/**
62+
* Creates a {@link ByteArrayByteBank} that wraps the provided byte array.
63+
*
64+
* @param bytes the bytes to wrap
65+
*/
66+
public ByteArrayByteBank(final byte[] bytes) {
67+
this(new ByteArray(bytes));
68+
}
69+
70+
/**
71+
* Creates a {@link ByteArrayByteBank} that wraps the specified
72+
* {@link ByteArray}.
73+
*
74+
* @param bytes the {@link ByteArray} to wrap
75+
*/
76+
public ByteArrayByteBank(final ByteArray bytes) {
77+
buffer = bytes;
78+
size = bytes.size();
79+
}
80+
81+
@Override
82+
public long getMaxBufferSize() {
83+
return Integer.MAX_VALUE;
84+
}
85+
86+
@Override
87+
public void setBytes(final long startpos, final byte[] bytes,
88+
final int offset, final int length)
89+
{
90+
// ensure we have space
91+
checkWritePos(startpos, startpos + length);
92+
final int neededCapacity = (int) (size + length);
93+
buffer.ensureCapacity(neededCapacity);
94+
95+
// copy the data
96+
System.arraycopy(bytes, offset, buffer.getArray(), (int) startpos, length);
97+
buffer.setSize(neededCapacity);
98+
updateSize(startpos + length);
99+
}
100+
101+
@Override
102+
public void setByte(final long pos, final byte b) {
103+
checkWritePos(pos, pos);
104+
buffer.ensureCapacity((int) pos);
105+
// NB: update the size of the underlying buffer before appending to it
106+
if (pos == buffer.size()) {
107+
buffer.setSize((int) (pos + 1));
108+
}
109+
buffer.setValue((int) pos, b);
110+
updateSize(pos + 1);
111+
}
112+
113+
@Override
114+
public void clear() {
115+
buffer.clear();
116+
size = 0;
117+
}
118+
119+
@Override
120+
public byte getByte(final long pos) {
121+
checkReadPos(pos, pos);
122+
// the buffer might contain bytes with negative value
123+
// we need to flip the sign to positive to satisfy the method contract
124+
return buffer.getValue((int) pos);
125+
}
126+
127+
@Override
128+
public int getBytes(final long startPos, final byte[] b, final int offset,
129+
final int length)
130+
{
131+
checkReadPos(startPos, startPos + length);
132+
// ensure we don't try to read data which is not in the buffer
133+
final int readLength = (int) Math.min(size() - startPos, length);
134+
System.arraycopy(buffer.getArray(), (int) startPos, b, offset, readLength);
135+
return readLength;
136+
}
137+
138+
@Override
139+
public long size() {
140+
return size;
141+
}
142+
143+
// -- Helper methods --
144+
145+
private void updateSize(final long newSize) {
146+
size = newSize > size ? newSize : size;
147+
}
148+
149+
private static ByteArray emptyByteArrayOfCapacity(final int capacity) {
150+
final ByteArray byteArray = new ByteArray(new byte[capacity]);
151+
byteArray.setSize(0);
152+
return byteArray;
153+
}
154+
}

0 commit comments

Comments
 (0)