Skip to content

Commit 6c4337f

Browse files
ctruedenclaude
andcommitted
scijava-context: the plugin tier
@plugin (indexable, with @attr) and Context.plugins(Class), which returns Discovery descriptors straight from the annotation index: class name, metadata and priority readable with nothing loaded, and construction only on demand. That is what keeps a menu of a thousand commands cheap to build, and it is the payoff for the Discovery refactor. scijava-context-test exercises the whole path through a real build: annotated classes in a package that is opened to the container but exported to nobody, indexed by the annotation processor at compile time, discovered with their metadata, constructed only when asked. Two JPMS findings, neither of which survives reasoning alone: - An `opens` must name the module that actually performs the reflection. The first attempt failed with IllegalAccessException because the package was opened to org.scijava.context while newInstance was being called inside org.scijava.discovery. Generic discovery code therefore cannot construct a plugin on a container's behalf: Discovery.of and IndexDiscoverer now take an optional instantiator, and the context supplies one defined in its own module, so users open their packages to org.scijava.context exactly as @plugin's javadoc says. - The annotation processor must be on the annotation processor path, and its absence is silent. The first build produced no index and reported nothing: javac does not find processors on the module path, and says nothing when it finds none at all. This is the hazard recorded in the plan, met first-hand. Whether pom-scijava should configure this for SciJava components is worth deciding, since the people most likely to fall into it are the hobbyists @plugin exists to serve. SciJava Common's HandlerPlugin/WrapperPlugin/TypedPlugin/SingletonPlugin hierarchy is not ported: each user inlines the small contract it needs, as DataHandle already did. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent e598ea3 commit 6c4337f

15 files changed

Lines changed: 655 additions & 7 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,7 @@ These were measured, not reasoned about, with a three-module test project
224224
| `setAccessible` injection into a **private** field, with that qualified `opens` | **works** |
225225
| An ordinary module importing a class from that opened-but-unexported package | **compile error**: "package ... is declared in module ..., which does not export it" |
226226
| A service with a **private** constructor plus a `public static provider()` factory | **works** — `ServiceLoader` prefers the factory |
227+
| Reflective construction of a class in a package opened **to the container**, performed by a *different* module (e.g. a shared discovery library) | **fails**: `IllegalAccessException` — the check is against the module that performs it |
227228

228229
The load-bearing conclusion is the second-to-last row: **`opens` is not
229230
`exports`.** A qualified `opens` grants the container deep reflective access at
@@ -232,6 +233,13 @@ time. Implementations therefore stay encapsulated — callers cannot import
232233
them, cannot cast to them, and cannot call their non-API methods — and the
233234
container can still construct and inject them.
234235

236+
That last row is easy to design past and costly to discover late: it is not
237+
enough to know *that* reflection needs an `opens`, one must know **which
238+
module the `opens` names**. Generic discovery code cannot construct a plugin on
239+
a container's behalf, so the container passes an instantiator defined in its
240+
own module, and users open their packages to the container. `Discovery.of` and
241+
`IndexDiscoverer` therefore take an optional instantiator.
242+
235243
So the SJ3 context keeps **declarative field injection**, as SciJava Common
236244
has always had. The cost to a plugin module is one line:
237245

@@ -527,9 +535,23 @@ No application context required by anything in this phase.
527535
- **Disposal reverses the order in which services finished initializing**,
528536
not the order they were requested, so a service is always torn down before
529537
the ones it depends on.
530-
- Still to do here: the `@Plugin` tier via `scijava-index`, declarative
531-
field injection through a qualified `opens`, `@EventHandler` scanning, the
532-
one-way legacy bridge, and the core services themselves.
538+
- **The plugin tier is done**: `@Plugin` (indexable, with `@Attr`) and
539+
`Context.plugins(Class)`, which returns `Discovery` descriptors from the
540+
annotation index — class name, metadata and priority, with nothing loaded
541+
until asked. Tested through a real build in `scijava-context-test`:
542+
annotated classes in an unexported package, indexed by the annotation
543+
processor at compile time, discovered with their metadata, and constructed
544+
only on demand.
545+
- **A downstream project must put the processor on the annotation processor
546+
path** (as the Ops modules do for `scijava-ops-indexer`). javac will not
547+
find it on the module path, and says nothing when it finds no processor at
548+
all: the build simply produces no index and the plugins silently fail to
549+
appear. This is the hazard noted above, met first-hand. `pom-scijava`
550+
configuring this for SciJava components would remove the trap for the
551+
people most likely to fall into it.
552+
- Still to do here: declarative field injection through a qualified `opens`,
553+
`@EventHandler` scanning, the one-way legacy bridge, and the core services
554+
themselves.
533555
- **Dependencies are not constructor arguments.** Constructor injection
534556
would publish every dependency in a signature, so changing an internal
535557
dependency would be an API change and a binary compatibility break unless

‎docs/migration.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,8 @@ A **dropped** row is a successful outcome, not a gap.
111111
| `cache` | `scijava-cache` moves in, keeping `org.scijava.cache` (Phase 2) | planned |
112112
| `thread` | `org.scijava.concurrent` | ported |
113113
| `task` | `org.scijava.progress` | ported |
114-
| `plugin` | `org.scijava.context` + `org.scijava.index` + `Discoverer` (Phase 2) | planned |
114+
| `plugin` (`Plugin`, `Attr`, `PluginService`, `PluginInfo`, `PluginIndex`) | `org.scijava.context.Plugin` and `Attr`, discovered via `Context.plugins(Class)`. `PluginInfo` becomes `org.scijava.discovery.Discovery`, which reports class name, metadata and priority without loading the class; `PluginService` and `PluginIndex` are subsumed by `Context.plugins` | ported |
115+
| `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 |
115116
| `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 |
116117
| `object`, `prefs`, `app` | `org.scijava.context` core services (Phase 2) | planned |
117118
| `convert` | `scijava-convert3` (Phase 2) | planned |

‎scijava-context-test/pom.xml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,9 @@
9595

9696
<!-- Note: These versions must match across all component POMs! -->
9797
<scijava-context.version>1.0.0-SNAPSHOT</scijava-context.version>
98+
<scijava-discovery.version>1.0.1-SNAPSHOT</scijava-discovery.version>
99+
<scijava-index.version>1.0.0-SNAPSHOT</scijava-index.version>
100+
<scijava-priority.version>1.0.1-SNAPSHOT</scijava-priority.version>
98101
</properties>
99102

100103
<dependencies>
@@ -103,6 +106,16 @@
103106
<artifactId>scijava-context</artifactId>
104107
<version>${scijava-context.version}</version>
105108
</dependency>
109+
<dependency>
110+
<groupId>org.scijava</groupId>
111+
<artifactId>scijava-discovery</artifactId>
112+
<version>${scijava-discovery.version}</version>
113+
</dependency>
114+
<dependency>
115+
<groupId>org.scijava</groupId>
116+
<artifactId>scijava-priority</artifactId>
117+
<version>${scijava-priority.version}</version>
118+
</dependency>
106119
<!-- SciJava dependencies -->
107120

108121
<!-- Test scope dependencies -->
@@ -115,6 +128,25 @@
115128

116129
<build>
117130
<plugins>
131+
<!--
132+
NB: the annotation index is generated by scijava-index's annotation
133+
processor, which must be on the processor path. Note that javac will
134+
not find it on the module path, and says nothing when it finds no
135+
processor at all: the build simply produces no index, and the plugins
136+
silently fail to be discovered.
137+
-->
138+
<plugin>
139+
<artifactId>maven-compiler-plugin</artifactId>
140+
<configuration>
141+
<annotationProcessorPaths>
142+
<path>
143+
<groupId>org.scijava</groupId>
144+
<artifactId>scijava-index</artifactId>
145+
<version>${scijava-index.version}</version>
146+
</path>
147+
</annotationProcessorPaths>
148+
</configuration>
149+
</plugin>
118150
<plugin>
119151
<artifactId>maven-enforcer-plugin</artifactId>
120152
<executions>

‎scijava-context-test/src/main/java/module-info.java‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,14 @@
2929

3030
module org.scijava.context.test {
3131

32-
// NB: the implementation package is deliberately NOT exported.
32+
// NB: the implementation package is deliberately NOT exported. It is
33+
// opened to the container only, which is what plugin construction needs --
34+
// and opens is not exports, so callers still cannot reach these classes.
3335
exports org.scijava.context.test;
36+
opens org.scijava.context.test.impl to org.scijava.context;
3437

3538
requires org.scijava.context;
39+
requires org.scijava.discovery;
3640

3741
provides org.scijava.context.Service with
3842
org.scijava.context.test.impl.HiddenGreeter;
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/*-
2+
* #%L
3+
* Integration tests for the scijava-context library.
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.context.test;
31+
32+
/** An extension type that plugins provide. */
33+
public interface Shouter {
34+
35+
String shout();
36+
}
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
/*-
2+
* #%L
3+
* Integration tests for the scijava-context library.
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.context.test.impl;
31+
32+
import org.scijava.context.Attr;
33+
import org.scijava.context.Plugin;
34+
import org.scijava.context.test.Shouter;
35+
import org.scijava.priority.Priority;
36+
37+
/** A high-priority {@link Shouter}, in an unexported package. */
38+
@Plugin(type = Shouter.class, name = "loud", label = "Loud shouter",
39+
priority = Priority.HIGH, attrs = { @Attr(name = "volume", value = "11") })
40+
public class LoudShouter implements Shouter {
41+
42+
/** Records whether this class has ever been constructed. */
43+
public static volatile boolean constructed = false;
44+
45+
public LoudShouter() {
46+
constructed = true;
47+
}
48+
49+
@Override
50+
public String shout() {
51+
return "HELLO";
52+
}
53+
}
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
/*-
2+
* #%L
3+
* Integration tests for the scijava-context library.
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.context.test.impl;
31+
32+
import org.scijava.context.Plugin;
33+
import org.scijava.context.test.Shouter;
34+
import org.scijava.priority.Priority;
35+
36+
/** A low-priority {@link Shouter}. */
37+
@Plugin(type = Shouter.class, name = "quiet", priority = Priority.LOW)
38+
public class QuietShouter implements Shouter {
39+
40+
@Override
41+
public String shout() {
42+
return "hello";
43+
}
44+
}
Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
/*-
2+
* #%L
3+
* Integration tests for the scijava-context library.
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.context.test;
31+
32+
import static org.junit.jupiter.api.Assertions.assertEquals;
33+
import static org.junit.jupiter.api.Assertions.assertFalse;
34+
import static org.junit.jupiter.api.Assertions.assertTrue;
35+
36+
import java.util.List;
37+
import java.util.stream.Collectors;
38+
39+
import org.junit.jupiter.api.Test;
40+
import org.scijava.context.Context;
41+
import org.scijava.discovery.Discovery;
42+
43+
/**
44+
* Tests plugin discovery: the {@code @Plugin} annotation, the index the
45+
* annotation processor writes at build time, and {@link Context#plugins}.
46+
* <p>
47+
* This lives in its own module so the whole path is real - the annotation is
48+
* processed by an actual build, and the implementations sit in a package that
49+
* is opened to the container but exported to nobody.
50+
* </p>
51+
*
52+
* @author Curtis Rueden
53+
*/
54+
public class PluginDiscoveryTest {
55+
56+
private static final String LOUD = "org.scijava.context.test.impl.LoudShouter";
57+
private static final String QUIET =
58+
"org.scijava.context.test.impl.QuietShouter";
59+
60+
/** Annotate a class, and it is found. No configuration file to write. */
61+
@Test
62+
public void testPluginsAreDiscovered() {
63+
try (final Context context = Context.create()) {
64+
final List<String> names = context.plugins(Shouter.class).stream() //
65+
.map(Discovery::implClassName) //
66+
.collect(Collectors.toList());
67+
// NB: highest priority first.
68+
assertEquals(List.of(LOUD, QUIET), names);
69+
}
70+
}
71+
72+
/**
73+
* The point of an index: metadata is readable without loading the plugin
74+
* class, which is what makes building a large menu cheap.
75+
*/
76+
@Test
77+
public void testMetadataWithoutLoadingTheClass() {
78+
try (final Context context = Context.create()) {
79+
final Discovery<Shouter> loud = context.plugins(Shouter.class).get(0);
80+
81+
assertEquals(LOUD, loud.implClassName());
82+
assertEquals("loud", loud.attr("name").orElse(null));
83+
assertEquals("Loud shouter", loud.attr("label").orElse(null));
84+
assertEquals("11", loud.attr("volume").orElse(null));
85+
assertEquals(100.0, loud.priority());
86+
87+
// None of that constructed anything.
88+
assertFalse(constructedLoudShouter(),
89+
"reading metadata constructed the plugin");
90+
91+
// Asking for the object is what constructs it.
92+
assertEquals("HELLO", loud.get().shout());
93+
assertTrue(constructedLoudShouter());
94+
}
95+
}
96+
97+
/** The implementations stay encapsulated: opened to the container only. */
98+
@Test
99+
public void testImplementationsAreNotExported() {
100+
final Module module = Shouter.class.getModule();
101+
assertTrue(module.isNamed(), "not running on the module path");
102+
assertFalse(module.isExported("org.scijava.context.test.impl"),
103+
"the implementation package must not be exported");
104+
assertTrue(module.isOpen("org.scijava.context.test.impl",
105+
Context.class.getModule()), "the container needs reflective access");
106+
}
107+
108+
/** An unindexed type yields nothing rather than failing. */
109+
@Test
110+
public void testUnknownPluginType() {
111+
try (final Context context = Context.create()) {
112+
assertTrue(context.plugins(Runnable.class).isEmpty());
113+
}
114+
}
115+
116+
/**
117+
* NB: read through the module system rather than touching the class, since
118+
* referring to the static field would itself load it.
119+
*/
120+
private static boolean constructedLoudShouter() {
121+
try {
122+
final Class<?> c = Class.forName(LOUD);
123+
return c.getField("constructed").getBoolean(null);
124+
}
125+
catch (final ReflectiveOperationException exc) {
126+
throw new AssertionError(exc);
127+
}
128+
}
129+
}

0 commit comments

Comments
 (0)