Skip to content

Commit d56ec5e

Browse files
ctruedenclaude
andcommitted
scijava-index: port annotation indexing, with a lazy Discoverer
Ports SciJava Common's org.scijava.annotations as org.scijava.index, and adds IndexDiscoverer, which is what the Discovery refactor was for: an index records each implementation's class name and annotation values, so filtering, sorting and display happen on metadata alone, and only type() or get() touches a class. The index format (META-INF/json/<annotation>) is deliberately unchanged, so an index written by either SciJava Common or SciJava3 is readable by the other. That keeps a jar built against one usable with the other during the migration. IndexDiscoverer stays annotation-agnostic: which type an indexed item provides is supplied as a function, since it must be answerable from metadata alone. For an annotation shaped like @plugin(type = Service.class) that is item -> item.annotation().type().getName(), which loads the declared type but never the implementation. Two tests cover the properties that matter: - Discovery never asks the class loader for the implementation class. This needs a class loader that records what it is asked for; a static flag on the implementation cannot show it, because reading the flag would itself load the class. The flag test remains, but proves only that nothing was constructed, and is named accordingly. - The annotation processor works through javac, with this component on the processor path and nothing else configured -- the path a downstream project actually takes. The test asserts the index is written with its metadata and is then discoverable lazily. Not ported: EclipseHelper (m2e's .factorypath generation covers it), AnnotationCombiner (build tooling, belongs in scijava-maven-plugin), and the legacy reader for the pre-2013 META-INF/annotations format. DirectoryIndexer and ByteCodeAnalyzer are kept: this component needs them to index its own test classes, and a Maven plugin needs them for the fallback indexing path. This component sets maven.compiler.proc to none for itself, because javac reads META-INF/services before the processor class it names exists. SciJava Common has the same constraint and solves it the same way. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent ca03cfd commit d56ec5e

23 files changed

Lines changed: 2809 additions & 4 deletions

‎docs/migration-plan.md‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -255,8 +255,25 @@ No application context required by anything in this phase.
255255
`ListUtils`, `UnitUtils`, and the non-URL parts of `FileUtils`. It stays
256256
dependency-free. (`Timing` is on hold — unclear downstream usage.)
257257
- **`scijava-index`** (new, `org.scijava.index`): ports `annotations` — the
258-
annotation processor and index reader — plus a `Discoverer` backed by the
259-
index. This is what supplies plugin metadata without loading classes.
258+
annotation processor and index reader — plus `IndexDiscoverer`, a
259+
`Discoverer` backed by the index. **Done.** This is what supplies plugin
260+
metadata without loading classes, and it is what the `Discovery` refactor
261+
was for: a test proves that discovery never asks the class loader for an
262+
implementation class, using a recording class loader rather than a static
263+
flag, since reading such a flag would itself load the class.
264+
- The index format (`META-INF/json/<annotation>`) is deliberately unchanged
265+
from SJC, so an index written by either side is readable by the other.
266+
- Which type an indexed item provides must be answerable from metadata,
267+
so `IndexDiscoverer` takes a function for it; for an annotation shaped
268+
like `@Plugin(type = Service.class)` that is
269+
`item -> item.annotation().type().getName()`, which loads the *declared*
270+
type but never the implementation.
271+
- The component sets `maven.compiler.proc` to `none` for itself: javac
272+
reads `META-INF/services` before the processor class it names exists.
273+
SJC has the same constraint, and solves it the same way.
274+
- Still to do: the loud runtime diagnostic for an annotated class missing
275+
from the index. It belongs with whichever component defines the
276+
annotation, so it lands in Phase 2.
260277
- **`scijava-io3`** (new, `org.scijava.io3.{location, handle, nio}`): ports
261278
`io.location`, `io.handle`, `io.nio` and `ByteBank`. Handles and resolvers
262279
are found via `Discoverer` + `Priority`. The external `scijava-io-http`

‎docs/migration.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -93,8 +93,10 @@ A **dropped** row is a successful outcome, not a gap.
9393

9494
| SJC package | Replacement | Status |
9595
| --- | --- | --- |
96-
| `annotations` | `org.scijava.index` (Phase 1) | planned |
97-
| `annotations.EclipseHelper` | none — m2e `.factorypath` covers it; directory indexing belongs in `scijava-maven-plugin` | dropped |
96+
| `annotations` | `org.scijava.index`: `Indexable`, `Index`, `IndexItem`, `IndexReader`, `AbstractIndexWriter`, `AnnotationProcessor`, `ByteCodeAnalyzer`, `DirectoryIndexer`, plus the new `IndexDiscoverer`. The index format (`META-INF/json/<annotation>`) is unchanged, so indexes stay readable by both | ported |
97+
| `annotations.EclipseHelper` | none — m2e `.factorypath` covers it; `DirectoryIndexer` is ported, so a Maven plugin can still index a directory | dropped |
98+
| `annotations.AnnotationCombiner` | `scijava-maven-plugin` — it merges indexes for shaded JARs, which is build tooling | dropped |
99+
| `annotations.legacy` | none — reads the pre-2013 `META-INF/annotations/` format | dropped |
98100
| `io.location`, `io.handle`, `io.nio`, `ByteBank` | `org.scijava.io3.*` (Phase 1) | planned |
99101
| `io` (`IOPlugin`, `IOService`, `RecentFileService`) | `scijava-io3` (Phase 1), pending review of what is still used | open |
100102
| `event`, `event.bushe` | `org.scijava.events` — clean-room rewrite, not a port (Phase 1) | 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</module>
6565
<module>scijava-discovery-test</module>
6666
<module>scijava-function</module>
67+
<module>scijava-index</module>
6768
<module>scijava-legacy</module>
6869
<module>scijava-meta</module>
6970
<module>scijava-ops-api</module>

‎scijava-index/pom.xml‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
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-index</artifactId>
13+
<version>1.0.0-SNAPSHOT</version>
14+
15+
<name>SciJava Index</name>
16+
<description>Annotation indexing, for discovery without class loading.</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.index</package-name>
84+
85+
<!--
86+
This component provides an annotation processor, and so cannot run one
87+
while compiling itself: javac reads META-INF/services before the class
88+
it names exists. SciJava Common has the same constraint. Note that this
89+
means this component's own classes are never indexed, which is fine:
90+
it declares no indexable annotations of its own.
91+
-->
92+
<maven.compiler.proc>none</maven.compiler.proc>
93+
94+
<license.licenseName>bsd_2</license.licenseName>
95+
<license.copyrightOwners>SciJava developers.</license.copyrightOwners>
96+
97+
<!-- Note: These versions must match across all component POMs! -->
98+
<scijava-common3.version>1.0.1-SNAPSHOT</scijava-common3.version>
99+
<scijava-discovery.version>1.0.1-SNAPSHOT</scijava-discovery.version>
100+
<scijava-priority.version>1.0.1-SNAPSHOT</scijava-priority.version>
101+
</properties>
102+
103+
<dependencies>
104+
<dependency>
105+
<groupId>org.scijava</groupId>
106+
<artifactId>scijava-common3</artifactId>
107+
<version>${scijava-common3.version}</version>
108+
</dependency>
109+
<dependency>
110+
<groupId>org.scijava</groupId>
111+
<artifactId>scijava-discovery</artifactId>
112+
<version>${scijava-discovery.version}</version>
113+
</dependency>
114+
115+
<!-- Test scope dependencies -->
116+
<dependency>
117+
<groupId>org.junit.jupiter</groupId>
118+
<artifactId>junit-jupiter-api</artifactId>
119+
<scope>test</scope>
120+
</dependency>
121+
</dependencies>
122+
123+
<build>
124+
<plugins>
125+
<plugin>
126+
<artifactId>maven-enforcer-plugin</artifactId>
127+
<executions>
128+
<execution>
129+
<id>enforce-package-rules</id>
130+
<goals>
131+
<goal>enforce</goal>
132+
</goals>
133+
<phase>test</phase>
134+
<configuration>
135+
<rules>
136+
<NoPackageCyclesRule implementation="org.scijava.maven.plugin.enforcer.NoPackageCyclesRule" />
137+
<NoSubpackageDependenceRule implementation="org.scijava.maven.plugin.enforcer.NoSubpackageDependenceRule" />
138+
</rules>
139+
</configuration>
140+
</execution>
141+
</executions>
142+
</plugin>
143+
<plugin>
144+
<artifactId>maven-javadoc-plugin</artifactId>
145+
<configuration>
146+
<links>
147+
<link>https://javadoc.scijava.org/Java11/</link>
148+
</links>
149+
</configuration>
150+
</plugin>
151+
</plugins>
152+
</build>
153+
</project>
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
/*
2+
* #%L
3+
* Annotation indexing, for discovery without class loading.
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.index {
31+
32+
exports org.scijava.index;
33+
34+
requires java.compiler;
35+
requires transitive org.scijava.discovery;
36+
requires org.scijava.priority;
37+
38+
provides javax.annotation.processing.Processor with
39+
org.scijava.index.AnnotationProcessor;
40+
41+
}

0 commit comments

Comments
 (0)