Skip to content

Commit 9a5b15e

Browse files
ctruedenclaude
andcommitted
scijava-common3: absorb general utilities from SciJava Common
Adds four classes, porting only what earns its place and recording the rest as dropped in docs/migration.md: - Numbers (from NumberUtils, plus ArrayUtils.safeMultiply32/64) - Strings (from StringUtils: padStart, padEnd, isNullOrEmpty, splitUnquoted) - Digests (from DigestUtils) - Processes (from ProcessUtils, reimplemented on ProcessBuilder) Decisions were driven by counting real usages across the scijava and imagej repositories: - ArrayUtils is dropped apart from safeMultiply32/64 (11 usages, and worth keeping as a readable wrapper for Math.multiplyExact). Its 18 contains/indexOf methods have 3 usages between them and are a loop or a stream in the standard library. - ListUtils (first: one line; string: StringJoiner) and UnitUtils (one usage ecosystem-wide) are dropped. - Bytes is deferred to scijava-io3, its natural consumer. - StringUtils.sanitize, sanitizeDouble, stripNulls and samePrefix have no usages anywhere and are dropped. Behavioral changes worth noting, both recorded in the migration table: - Numbers.toNumber no longer consults a conversion framework, since scijava-common3 must stay dependency-free; it handles numbers and strings only. - Digests.digest throws IllegalArgumentException for an unknown algorithm rather than returning null, which in SciJava Common surfaced as a NullPointerException somewhere else entirely. The best* family is therefore plain SHA-1, which every Java platform guarantees. Tests are ported from SciJava Common to JUnit 5 and extended. The Processes tests cover what its reimplementation could plausibly break: closing the process's stdin once input is exhausted, not closing the caller's streams, a multi-byte character split across two reads, a non-zero exit status, and interruption. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 9084574 commit 9a5b15e

9 files changed

Lines changed: 1149 additions & 8 deletions

File tree

‎docs/migration.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -21,39 +21,39 @@ A **dropped** row is a successful outcome, not a gap.
2121
| --- | --- | --- |
2222
| `AbstractPrimitiveArray` | `org.scijava.collections.AbstractPrimitiveArray` | ported |
2323
| `AppUtils` | `org.scijava.common3.Apps` | ported |
24-
| `ArrayUtils` | `org.scijava.common3` (Phase 1) | planned |
24+
| `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` | `org.scijava.common3` (Phase 1) | planned |
26+
| `Bytes` | deferred to `scijava-io3`, its natural consumer; `java.nio.ByteBuffer` covers casual use | open |
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 |
3030
| `CombineAnnotations`, `Combiner`, `MetaInfCombiner`, `ServiceCombiner` | build-time tooling; `scijava-maven-plugin` | dropped |
3131
| `ConversionUtils` | `scijava-convert3` (Phase 2); already deprecated in SJC | planned |
3232
| `DebugUtils` | `org.scijava.common3.Threads` | ported |
3333
| `DefaultTreeNode`, `TreeNode` | on hold — only `imagej-common` uses it; may move there | open |
34-
| `DigestUtils` | `org.scijava.common3` (Phase 1) | planned |
34+
| `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 |
3535
| `FileUtils` | `org.scijava.common3` (non-URL parts, Phase 1); URL parts in `common3.URLs` | planned |
3636
| `GenericUtils` | `org.scijava.common3.Types` (already deprecated in SJC) | ported |
3737
| `IntCoords`, `IntRect`, `RealCoords`, `RealRect` | UI layer (Phase 4) | open |
3838
| `IteratorPlus` | none — use the standard `Iterator`/`Iterable` API | dropped |
3939
| `LastRecentlyUsed` | `java.util.LinkedHashMap` with `accessOrder=true` + `removeEldestEntry` | dropped |
40-
| `ListUtils` | `org.scijava.common3` (Phase 1); `first` is one line, inline it | planned |
40+
| `ListUtils` | dropped: `first` is one line, inline it; `string` → `StringJoiner` or `String.join` | dropped |
4141
| `LineOutputStream`, `ReadInto`, `StringMaker`, `Query` | none — inline as needed | dropped |
4242
| `Manifest` | `org.scijava.meta.Manifest` | ported |
4343
| `MersenneTwisterFast` | `org.scijava.common3.MersenneTwisterFast` | ported |
4444
| `MirrorWebsite`, `TunePlayer`, `ReflectedUniverse`, `ReflectException` | none | dropped |
4545
| `MiscUtils` | `org.scijava.common3.Comparisons` | ported |
46-
| `NumberUtils` | `org.scijava.common3` (Phase 1) | planned |
46+
| `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 |
4747
| `PlatformUtils` | `org.scijava.common3.Platforms` | ported |
4848
| `POM` | `org.scijava.meta.POM` | ported |
4949
| `Prefs` | `scijava-context` prefs service (Phase 2); already deprecated in SJC | planned |
50-
| `ProcessUtils` | `org.scijava.common3` (Phase 1) | planned |
50+
| `ProcessUtils` | `org.scijava.common3.Processes`, reimplemented on `ProcessBuilder`; no longer needs `ReadInto` | ported |
5151
| `PropertiesHelper` | none — inline | dropped |
5252
| `Sizable`, `SizableArrayList` | none — the reflective-resizing rationale died with Java 17 | dropped |
53-
| `StringUtils` | `org.scijava.common3` (Phase 1) | planned |
53+
| `StringUtils` | `org.scijava.common3.Strings`: `padStart`, `padEnd`, `isNullOrEmpty`, `splitUnquoted`. `sanitize`, `sanitizeDouble`, `stripNulls` and `samePrefix` are dropped — no usages anywhere | ported |
5454
| `Timing` | on hold — pending evidence of downstream usage | open |
5555
| `Types` | `org.scijava.common3.Types` + `org.scijava.common3.Classes` — **not** a drop-in superset, see below | ported |
56-
| `UnitUtils` | `org.scijava.common3` (Phase 1) | planned |
56+
| `UnitUtils` | dropped — one usage ecosystem-wide; add it back on demand | dropped |
5757
| `VersionUtils` | `org.scijava.meta.Versions` | ported |
5858
| `XML` | `org.scijava.meta.XML` | ported |
5959

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
/*
2+
* #%L
3+
* Common functionality widely used across SciJava modules.
4+
* %%
5+
* Copyright (C) 2021 - 2025 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.common3;
31+
32+
import java.nio.charset.StandardCharsets;
33+
import java.security.MessageDigest;
34+
import java.security.NoSuchAlgorithmException;
35+
import java.util.Base64;
36+
37+
/**
38+
* Useful methods for computing digests, and for rendering bytes as text.
39+
*
40+
* @author Curtis Rueden
41+
* @author Johannes Schindelin
42+
*/
43+
public final class Digests {
44+
45+
private static final char[] HEX = "0123456789abcdef".toCharArray();
46+
47+
private Digests() {
48+
// NB: prevent instantiation of utility class.
49+
}
50+
51+
/** Converts the given bytes to a string, assuming UTF-8 encoding. */
52+
public static String string(final byte[] bytes) {
53+
return new String(bytes, StandardCharsets.UTF_8);
54+
}
55+
56+
/** Converts the given string to bytes, using UTF-8 encoding. */
57+
public static byte[] bytes(final String s) {
58+
return s.getBytes(StandardCharsets.UTF_8);
59+
}
60+
61+
/** Converts the given int to bytes, most significant byte first. */
62+
public static byte[] bytes(final int i) {
63+
return new byte[] { //
64+
(byte) (0xff & (i >>> 24)), //
65+
(byte) (0xff & (i >>> 16)), //
66+
(byte) (0xff & (i >>> 8)), //
67+
(byte) (0xff & i) //
68+
};
69+
}
70+
71+
/** Renders the given bytes as a lowercase hexadecimal string. */
72+
public static String hex(final byte[] bytes) {
73+
final char[] buffer = new char[bytes.length * 2];
74+
for (int i = 0; i < bytes.length; i++) {
75+
buffer[i * 2] = HEX[(bytes[i] & 0xf0) >> 4];
76+
buffer[i * 2 + 1] = HEX[bytes[i] & 0xf];
77+
}
78+
return new String(buffer);
79+
}
80+
81+
/** Renders the given bytes as a base64 string. */
82+
public static String base64(final byte[] bytes) {
83+
return Base64.getEncoder().encodeToString(bytes);
84+
}
85+
86+
/** Computes a weak but deterministic hash of the given string. */
87+
public static byte[] hash(final String s) {
88+
return bytes(s.hashCode());
89+
}
90+
91+
/**
92+
* Computes a weak but deterministic hash of the given bytes.
93+
* <p>
94+
* NB: the hash code of the byte array cannot be used directly, because
95+
* primitive arrays inherit {@link Object#hashCode}, which differs per
96+
* instance. Converting to a string first yields a consistent result.
97+
* </p>
98+
*/
99+
public static byte[] hash(final byte[] bytes) {
100+
return hash(string(bytes));
101+
}
102+
103+
/** Computes the SHA-1 digest of the given bytes. */
104+
public static byte[] sha1(final byte[] bytes) {
105+
return digest("SHA-1", bytes);
106+
}
107+
108+
/** Computes the MD5 digest of the given bytes. */
109+
public static byte[] md5(final byte[] bytes) {
110+
return digest("MD5", bytes);
111+
}
112+
113+
/**
114+
* Computes the digest of the given bytes using the given algorithm.
115+
*
116+
* @param algorithm the digest algorithm; every Java platform is required to
117+
* support {@code MD5}, {@code SHA-1} and {@code SHA-256}
118+
* @param bytes the bytes to digest
119+
* @return the digest
120+
* @throws IllegalArgumentException if the algorithm is not available
121+
*/
122+
public static byte[] digest(final String algorithm, final byte[] bytes) {
123+
try {
124+
final MessageDigest digest = MessageDigest.getInstance(algorithm);
125+
digest.update(bytes);
126+
return digest.digest();
127+
}
128+
catch (final NoSuchAlgorithmException exc) {
129+
throw new IllegalArgumentException("No such digest algorithm: " +
130+
algorithm, exc);
131+
}
132+
}
133+
134+
/** Computes the strongest available digest of the given string. */
135+
public static byte[] best(final String s) {
136+
return best(bytes(s));
137+
}
138+
139+
/** Computes the strongest available digest of the given bytes. */
140+
public static byte[] best(final byte[] bytes) {
141+
return sha1(bytes);
142+
}
143+
144+
/** Computes {@link #best(String)}, rendered as hexadecimal. */
145+
public static String bestHex(final String text) {
146+
return hex(best(text));
147+
}
148+
149+
/** Computes {@link #best(byte[])}, rendered as hexadecimal. */
150+
public static String bestHex(final byte[] bytes) {
151+
return hex(best(bytes));
152+
}
153+
154+
/** Computes {@link #best(String)}, rendered as base64. */
155+
public static String bestBase64(final String text) {
156+
return base64(best(text));
157+
}
158+
159+
/** Computes {@link #best(byte[])}, rendered as base64. */
160+
public static String bestBase64(final byte[] bytes) {
161+
return base64(best(bytes));
162+
}
163+
}

0 commit comments

Comments
 (0)