Skip to content

Commit 313843f

Browse files
ctruedenclaude
andcommitted
docs: correct the Phase 2 injection design
Constructor injection was the wrong call, for the reasons raised in review: it publishes every dependency in a signature, so changing an internal dependency becomes an API change and a binary compatibility break unless old constructors are kept forever. It also cannot serve the ServiceLoader tier, which requires a public no-arg constructor or a static provider() factory. The premise behind it was also wrong. I had assumed that letting the container instantiate a plugin means exporting its package, which would indeed break encapsulation -- callers could cast to implementations and call non-API methods. But `opens` is not `exports`: a qualified `opens <pkg> to <container>` grants deep reflective access at runtime while leaving the package invisible at compile time. Measured with a three-module test project on JDK 21, rather than assumed: - ServiceLoader finds a provider declared with `provides` in a package that is neither exported nor opened. - Reflective newInstance on such a package fails with IllegalAccessException; with a qualified `opens` it succeeds. - setAccessible injection into a private field works with that opens. - An ordinary module importing a class from the opened but unexported package fails to compile: "package ... is declared in module ..., which does not export it". - A service with a private constructor and a public static provider() factory works; ServiceLoader prefers the factory. So declarative field injection survives JPMS intact, encapsulation is preserved, and the cost to a plugin module is one `opens` line. The claim that we must give up private-field injection is removed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 7d73482 commit 313843f

1 file changed

Lines changed: 43 additions & 17 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 43 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,11 @@ The deliverable is not a reimplementation of SJC. It is:
3030
- **Classpath-first, module-path-clean.** Fiji runs on the classpath, so JPMS
3131
strictness binds only those who deliberately modularize. Design so that
3232
modularization is *possible* without contorting for it: no split packages,
33-
plugin classes public in exported packages, constructor injection rather
34-
than private-field reflection, resources under `META-INF/`. The one thing we
35-
give up is `setAccessible`-based injection into private fields.
33+
resources under `META-INF/`, and a qualified `opens` to the container where
34+
a module wants its implementations injected. Notably we give up **nothing**
35+
here: implementation packages stay unexported and encapsulated, and
36+
declarative field injection keeps working. See the JPMS section below for
37+
the measurements behind this.
3638
- **Leave SJC alone.** No functional changes, no Java version bump, no
3739
delegation layer. Only `@deprecated` javadoc.
3840
- **One-way migration.** Downstream components migrate by swapping the
@@ -188,17 +190,32 @@ elsewhere too).
188190

189191
### JPMS specifics
190192

191-
- Index resources are safe: `META-INF/json/...` is not a valid package name,
192-
so it stays readable via `ClassLoader.getResources` from named modules.
193-
- Instantiating a public class with a public no-arg constructor in an
194-
**exported** package needs no `opens`.
195-
- `setAccessible` on private fields — how SJC injects `@Parameter`
196-
(`Context.java:510`, `ServiceHelper.java:317`) — **does** require `opens`.
197-
This is the one thing forcing every plugin module to open itself.
193+
These were measured, not reasoned about, with a three-module test project
194+
(`javac --module-source-path`, run on the module path, JDK 21):
198195

199-
Therefore the SJ3 context uses **constructor injection** (or an explicit
200-
`initialize(Context)`), so that `exports` suffices and `@Plugin` coexists with
201-
JPMS.
196+
| Situation | Result |
197+
| --- | --- |
198+
| Index resources (`META-INF/json/...`) read via `ClassLoader.getResources` | **works** — `META-INF` is not a valid package name, so it is never encapsulated |
199+
| `ServiceLoader` finding a provider declared with `provides`, in a package that is neither exported nor opened | **works** — the `provides` declaration itself grants the access |
200+
| Reflective `newInstance` on a public class in a package that is neither exported nor opened | **fails**: `IllegalAccessException` |
201+
| The same, with a qualified `opens <pkg> to <container>` | **works** |
202+
| `setAccessible` injection into a **private** field, with that qualified `opens` | **works** |
203+
| An ordinary module importing a class from that opened-but-unexported package | **compile error**: "package ... is declared in module ..., which does not export it" |
204+
| A service with a **private** constructor plus a `public static provider()` factory | **works** — `ServiceLoader` prefers the factory |
205+
206+
The load-bearing conclusion is the second-to-last row: **`opens` is not
207+
`exports`.** A qualified `opens` grants the container deep reflective access at
208+
runtime while leaving the package invisible to ordinary callers at compile
209+
time. Implementations therefore stay encapsulated — callers cannot import
210+
them, cannot cast to them, and cannot call their non-API methods — and the
211+
container can still construct and inject them.
212+
213+
So the SJ3 context keeps **declarative field injection**, as SciJava Common
214+
has always had. The cost to a plugin module is one line:
215+
216+
```java
217+
opens my.plugins.impl to org.scijava.context;
218+
```
202219

203220
### Logging
204221

@@ -296,10 +313,19 @@ No application context required by anything in this phase.
296313
### Phase 2 — The application context
297314

298315
- **`scijava-context`** (new, `org.scijava.context`): services with a
299-
lifecycle and **constructor-based** dependency injection; plugin metadata
300-
from `scijava-index`; instantiation via `Discoverer`; ordering via
301-
`scijava-priority`. Plus the core services: object registry, prefs, thread,
302-
app/status.
316+
lifecycle and dependency injection; plugin metadata from `scijava-index`;
317+
instantiation via `Discoverer`; ordering via `scijava-priority`. Plus the
318+
core services: object registry, prefs, thread, app/status.
319+
- **Dependencies are not constructor arguments.** Constructor injection
320+
would publish every dependency in a signature, so changing an internal
321+
dependency would be an API change and a binary compatibility break unless
322+
old constructors were kept forever. It also cannot work for the
323+
`ServiceLoader` tier, which requires a public no-arg constructor or a
324+
static `provider()` factory. Dependencies are instead acquired after
325+
construction — declaratively, by annotated field, as SciJava Common does —
326+
which keeps them an implementation detail.
327+
- Services may therefore have a **private** constructor and a
328+
`public static provider()` factory, exposing no construction API at all.
303329
- Deliberately a much smaller surface than SJC's `Context` +
304330
`PluginService` + `PluginInfo` + the handler/wrapper/typed-service
305331
hierarchy. Keep what is used; drop the rest.

0 commit comments

Comments
 (0)