FELIX-6759 - PROTOTYPE: use plurl for URL handler factory multiplexing

[paulrutter]

Warning

Draft / prototype — not for merge. There is an unresolved licensing question below that blocks this as it stands.

Prototype exploring @tjwatson's suggestion in #433 (comment) that Felix and Equinox should share a cooperative mechanism for the java.net.URL factory singletons. Branches off, and targets, #433.

The problem

URLHandlers claims the JVM-wide URLStreamHandlerFactory by reflectively swapping a private static field on java.net.URL, via SecureAction.swapStaticFieldIfNotClass. Obtaining a MethodHandles.Lookup trusted enough to do that is the only remaining reason the framework uses sun.misc.Unsafe — the staticFieldOffset/getObject steal of IMPL_LOOKUP. It also means whichever framework installs itself last wins the singleton, so Felix and Equinox cannot coexist in one JVM without clobbering each other.

To be clear about urgency: this is not a JDK 25 blocker. That Unsafe block is guarded by catch (Throwable) and falls back to AccessibleObject.setAccessible, so on JDK 25 it only produces the familiar warning. This is about JDK 26+ and about framework interop.

What this does

• Vendors the 11 plurl sources from eclipse-osgi-technology/plurl (commit 6581777) into org.apache.felix.framework.plurl. The only change is the package rename; every license header and copyright notice is preserved verbatim. This mirrors what Equinox did in Plurl API for managing Java singleton factories in URL eclipse-equinox/equinox#848.
• Adds PlurlURLHandlers, adapting URLHandlers to PlurlStreamHandlerFactory / PlurlContentHandlerFactory. Plurl installs one cooperative router through the supported URL.setURLStreamHandlerFactory API and routes by asking each registered factory shouldHandle(Class) — which maps directly onto what URLHandlers.getFrameworkFromContext() already does by hand, and needs no Unsafe.

Verified on JDK 25: the framework compiles and its test results are unchanged.

⚠️ Licensing — @tjwatson could you confirm?

Every vendored source file declares:

SPDX-License-Identifier: EPL-2.0
Copyright (c) 2025 IBM Corporation

but plurl's own LICENSE file and its pom.xml both declare Apache-2.0. (Its NOTICE also still refers to "slf4j-osgi", which looks like a copy-paste leftover.)

This matters because of where it is being copied to. EPL-2.0 is Category B at the ASF and must not be included in an Apache source release. Equinox was free to vendor these files because Eclipse projects are EPL-2.0 natively; Felix is not.

Given the repo's LICENSE and pom say Apache-2.0, my guess is the EPL headers are carried over from the original Equinox code rather than intended. Could you confirm the intended license and, if it is Apache-2.0, correct the source headers upstream? That would unblock the vendoring approach for Felix and anyone else.

If the headers are intentionally EPL-2.0, then Felix cannot vendor the sources and the options become:

1. consume plurl as a released binary dependency under the Category B rules — which additionally needs plurl published to Maven Central, as it currently has no release or tag; or
2. write an Apache-2.0 implementation of the same design in Felix, which works but forks the effort rather than converging on the shared library.

cc @stbischof @laeubi @mattrpav

🤖 Generated with Claude Code

[paulrutter]

CI is red on purpose — Apache RAT rejects the vendored sources

Now that stacked PRs get CI (the pull_request trigger only accepted master as a base, so this PR was getting no build at all until that was fixed on the base branch), the build runs — and fails on all four JDKs in exactly the way that matters:

[INFO] Rat check: Summary over all files. Unapproved: 12, unknown: 12, generated: 0, approved: 243 licenses.
[ERROR] Failed to execute goal org.apache.rat:apache-rat-plugin:0.15:check (default)
        on project org.apache.felix.framework: Too many files with unapproved license: 12

All 12 flagged files are the vendored plurl sources — the 11 .java files plus the README.md. Nothing else in the framework is flagged.

This is the licensing question answering itself. apache-rat-plugin is the ASF's own compliance gate, and it will not accept SPDX-License-Identifier: EPL-2.0 headers in an Apache source tree. It is enforcing the Category B rule automatically. Equinox could vendor these files because Eclipse projects are EPL-2.0 natively; Felix cannot.

The failure is being left in place deliberately. It could be silenced with a RAT exclusion for plurl/**, but that would suppress a genuine compliance violation rather than resolve it, and would leave a green tick implying the licensing was settled when it is not. Red is the accurate state: this branch cannot merge as it stands.

So the technical side is done and the remaining blocker is purely licensing:

• the framework compiles and its tests are unchanged with plurl vendored and PlurlURLHandlers wired in;
• the only thing standing in the way is the header discrepancy — plurl's LICENSE and pom.xml say Apache-2.0, while every source file says EPL-2.0 with Copyright (c) 2025 IBM Corporation.

@tjwatson — if the EPL headers are carried over from the original Equinox code rather than intended, correcting them upstream to match plurl's own Apache-2.0 LICENSE and pom would turn this red build green and unblock the approach for Felix and anyone else wanting to adopt the library. If they are intentionally EPL-2.0, then Felix needs one of the alternatives listed in the PR description instead.

🤖 Generated with Claude Code

[tjwatson]

The intention when I moved the source to osgi-technology was that I would use the apache header like this:

https://github.com/eclipse-osgi-technology/osgi-test/blob/696b03cd2eaf4e91f7ad0e3d424e4bebb28525ce/org.osgi.test.assertj.feature/src/test/java/org/osgi/test/assertj/feature/AssertionsTest.java#L1-L17

Somehow that was overlooked when setting up the source in https://github.com/eclipse-osgi-technology/plurl

It should be a non-issue to get the headers updated. But what I ultimately wanted to do was have a release out of the osgi-technology project for plurl that would be used by both Equinox and Felix unchanged, in the original package there.

[paulrutter]

The intention when I moved the source to osgi-technology was that I would use the apache header like this:

https://github.com/eclipse-osgi-technology/osgi-test/blob/696b03cd2eaf4e91f7ad0e3d424e4bebb28525ce/org.osgi.test.assertj.feature/src/test/java/org/osgi/test/assertj/feature/AssertionsTest.java#L1-L17

Somehow that was overlooked when setting up the source in https://github.com/eclipse-osgi-technology/plurl

It should be a non-issue to get the headers updated. But what I ultimately wanted to do was have a release out of the osgi-technology project for plurl that would be used by both Equinox and Felix unchanged, in the original package there.

Thanks for your quick reply! Let's first see if we can get consensus on the JDK 25 PR, then we can revisit this one.

Would it be possible to get plurl released as a separate artifact, with the right headers, so we can use it without copying the code into Felix?

Apart from that, does this PR make sense to you?

[tjwatson]

Would it be possible to get plurl released as a separate artifact, with the right headers, so we can use it without copying the code into Felix?

I've updated the source headers to use Apache-2.0 with: eclipse-osgi-technology/plurl#45

Note that the source also needed an upstream fix I had put in Equinox with PR: eclipse-osgi-technology/plurl#55

I am not sure how long it will take to get a release out of the osgi-technology project because I have not done a release out of this particular project yet. I'll ask existing members of the project about what steps are needed to get a release done. But I don't want that to block you on progress. With the current state of the source I think it should be fine for you to proceed with copying in the source now.

[paulrutter]

Thanks, that's great! I will pull in the latest version and use it verbatim except the package names. Once the JDK 25 PR lands, this one is next on the list.

Once a proper release is out, we can then switch to that artifact instead and remove the vendored sources.

[tjwatson]

I don't see where you are calling org.eclipse.osgitech.plurl.Plurl.install(String...) to get the singleton factories registered with the JVM.

[tjwatson]

For Equinox I do an additional check to make sure the class loader is for a bundle that is actually installed in this framework instance. I assume you would want the same thing here. Otherwise one felix framework may handle lookups for a bundle resolved in another felix framework instance.

[paulrutter]

I don't see where you are calling org.eclipse.osgitech.plurl.Plurl.install(String...) to get the singleton factories registered with the JVM.

Looking into this, i stopped working on the draft when i noticed the license. Will continue with it now that's resolved 👍🏻

[tjwatson]

I don't see where you are calling org.eclipse.osgitech.plurl.Plurl.install(String...) to get the singleton factories registered with the JVM.

Looking into this, i stopped working on the draft when i noticed the license. Will continue with it now that's resolved 👍🏻

I should mention that the intention was to use a ServiceLoader call to lookup the implementation instance of Plurl. But I found just doing a new PlurlImpl() is easier as long as you don't care to replace the impl with some other META-INF/services implementation.

[paulrutter]

Thanks for sorting the headers — apache-rat is satisfied now, which was blocking the build entirely. I've pushed a substantial rework; summary below, with one design question at the end.

I refreshed the vendored sources from upstream, so they include the Apache-2.0 headers from eclipse-osgi-technology/plurl#45 and the fix from eclipse-osgi-technology/plurl#55. Only the package rename is applied. And new PlurlImpl() rather than the ServiceLoader, as you suggested.

Both of your review points were real defects

• Plurl.install(..) was never called. Since the static Plurl.add(..) helpers operate through a plurl: URL, without installing the router first they fail with unknown protocol: plurl. Nothing in the draft exercised the adapter, so it compiled and the tests passed while being dead code.
• shouldHandle was too loose. It only checked that a class came from some Felix bundle class loader, so with two frameworks in one JVM either could answer for the other's bundles. It now also requires the owning framework to match, as your EquinoxBundle/container check does.

Plurl is now the mechanism, not an addition alongside it

• URLHandlers no longer swaps the java.net.URL/URLConnection static fields, and its singleton is not constructed. I had planned to keep that as a fallback, but the catch in your SystemBundleActivator changed my mind: a fallback keeps the sun.misc.Unsafe path alive, which is the thing we're trying to delete. Felix now behaves as Equinox does — if registration fails it logs and that framework contributes no URL handlers.
• Removing the swap turned out to be necessary, not just tidy. With URLHandlers taking the singletons first, plurl found them occupied and required --add-opens java.base/java.net=ALL-UNNAMED. Installing into a clean JVM uses the supported API and needs no flag.
• URLHandlersBundleStreamHandler and URLHandlersStreamHandlerProxy now extend PlurlStreamHandlerBase, mirroring your changes to BundleResourceHandler and URLStreamHandlerProxy.
• The router is installed once per JVM and reference counted. Uninstalling per framework tore it down while another framework was still registered.
• Added a test that starts a framework and asserts registration actually happened, that the plurl: protocol resolves, and that shouldHandle doesn't claim classes outside the framework.

On Linux the framework suite is 121 tests with a single error, which is the question below.

Routing a URL re-parsed outside any bundle

URLHandlersTest.urlHandlersWithClassLoaderIsolation loads a second copy of the whole framework — and therefore of the vendored plurl classes — in a separate class loader, each with its own framework. It then does the equivalent of:

URL url = bundle.getEntry("...");
new URL(url.toExternalForm()).openStream();   // called from a plain test class

That second new URL(..) is re-parsed without an explicit handler, from a class not loaded by any bundle. There is no bundle frame anywhere on the stack, so shouldHandle cannot attribute it and plurl has nothing to route on.

Note I deliberately do not bind the bundle: handler to one framework the way you bind yours to the container. The JVM caches one handler per protocol, so a pinned handler also gets used for another framework's bundle: URLs. Instead the framework is resolved per call from the UUID in the URL host, via URLHandlers.getFrameworkFromContext(uuid) — which only sees its own copy's frameworks. Previously a second copy reflectively called registerFrameworkListsForContextSearch on whichever copy owned the JVM factory, so UUIDs resolved across class loaders. With plurl there is no "root URLHandlers" to find, so that rendezvous is gone.

I initially assumed Equinox must solve this and Felix was missing something. Reading BundleResourceHandler properly, it's the other way round:

String host = url.getHost();               // "<bundleId>.<container.hashCode()>"
bundleID = parseBundleIDFromURLHost(host); // parses ONLY the bundle id
Module module = getModule(bundleID);       // -> container.getModule(id), the BOUND container

The container is encoded in the host by createURLHostForBundleID, but openConnection parses only the bundle id and resolves it against whichever container the handler was constructed with; the container part is used for equals/hashCode/hostsEqual/sameFile, never to locate the owner. So in this scenario Equinox would either return the resource with that id from the wrong container, or fail with URL_NO_BUNDLE_FOUND. It relies on shouldHandle having routed correctly, with no fallback when attribution is impossible.

Felix's UUID lookup is a stronger guarantee, which is why there's a test for it here and no equivalent upstream. So the question isn't how Equinox does it, but:

Would plurl consider routing a URL to its owning factory, not only a calling Class?

A boolean shouldHandle(URL) on PlurlStreamHandlerFactory, consulted when call stack attribution yields nothing, would let each framework claim its own URLs by inspecting the host. Both frameworks would then be correct for URLs re-parsed outside a bundle, and Equinox could tighten its behaviour if it wanted to.

Without that, the Felix-side options are:

1. Match Equinox — bind the handler to one framework and accept that cross-framework re-parsing resolves against the wrong one. Converges with upstream, but drops behaviour Felix has today and means weakening or removing that test.
2. Keep the guarantee with a Felix-side cross-copy UUID registry — which reintroduces reflection into exactly the mechanism plurl is meant to replace, since each class loader has its own copy of both URLHandlers and the plurl classes and there's no shared rendezvous to publish to.

I'd rather not do 1 silently. Happy to raise the API idea as a plurl issue with a concrete proposal if you think it's reasonable.

[tjwatson]

Keep the guarantee with a Felix-side cross-copy UUID registry — which reintroduces reflection into exactly the mechanism plurl is meant to replace, since each class loader has its own copy of both URLHandlers and the plurl classes and there's no shared rendezvous to publish to.

I am a bit confused by this because there is a unit test in plurl that mimics a copy scenario and a separate class loader (proxy) scenario. The intent of Plurl is not only can the users have their own copy loaded by a difference class loader, but their own copy could live in a completely different package name. For example. see the test that has a copy of Plurl APIs at

https://github.com/eclipse-osgi-technology/plurl/tree/main/src/test/java/org/eclipse/osgitech/plurl/test/copy

In this case it reflects on agreed upon method names from the Plurl APIs. This way, as long as the copies mirror the upstream Plurl APIs then they can intermix in the same JVM. This way Felix and Equinox can both run in the same JVM and still multiplex on the protocols even if they copied the plurl API/impl into their own felix and equinox packages.

Can you go into more details on what plurl changes you need to get the bundle protocol to work in Felix. Do you need some alternative way to tell plurl about your protocols so that we delegate to the factory for the protocol differently than the default?

[paulrutter]

You're right, my earlier statement was wrong — install() returns early when checkPlurlProtocol() finds an installed plurl, so a second copy registers with the live router rather than replacing it. Nothing in the Felix registration needed changing.

To answer your question: protocol-level delegation wouldn't help, because every Felix framework instance uses the same bundle: protocol. The owner is identified by the framework UUID in the URL host, so selection needs to see the URL. Implemented and split so the plurl part can be lifted on its own:

• 7f9938c — PlurlFactory gains default boolean shouldHandle(URL) returning false; consulted during selection and delegated through PlurlFactoryHolder
• 5952c24 — narrows it so only a factory that claims a URL can act, keeping the per-URL pinning
• 392c522 — Felix side: claim bundle: URLs by framework UUID

URLHandlersTest.urlHandlersWithClassLoaderIsolation now passes.

Three things worth knowing, all found by implementing it:

1. The interface method alone is inert. Selection happens in parseURL, where the JDK has set only protocol — host is populated by parseURL — so there's nothing to inspect, and that choice is then cached for the URL's lifetime. PlurlFactoryHolder also had to delegate the new method, or the default answers for every holder and never reaches a factory.
2. Nothing changes unless a factory opts in. My first attempt skipped the urlToHandler record while the URL was unparsed, which would have broken Equinox: BundleResourceHandler keeps mutable per-URL state (bundleEntry, cleared in parseURL, used as a fast path in openConnection) that assumes one handler per URL. 5952c24 instead records as before and lets only a claiming factory correct it once. Both Equinox factories declare only shouldHandle(Class), so they never claim and behave identically.
3. shouldHandle(URL) overloads shouldHandle(Class), making shouldHandle(null) ambiguous — it broke my own test compile. A distinct name would avoid that upstream.

Separately: when no factory claims a URL, declining may be safer than selecting the first factory added, since framework A can be handed a URL naming framework B. Felix's UUID check makes that a clean failure; Equinox resolves only the bundle id against its bound container, so it would answer with its own resource. Happy to leave the fallback as-is if you'd rather.

Glad to raise this as a plurl issue/PR, squashed however you prefer.

---

Ready-to-apply patch against eclipse-osgi-technology/plurl main, with the package and paths rewritten to the upstream layout. Verified with git apply --check on a fresh clone. Covers both plurl commits above; the Felix side is not included.

plurl-url-selection.patch

diff --git a/src/main/java/org/eclipse/osgitech/plurl/PlurlFactory.java b/src/main/java/org/eclipse/osgitech/plurl/PlurlFactory.java
index 520bf92d97..24aacb75d1 100644
--- a/src/main/java/org/eclipse/osgitech/plurl/PlurlFactory.java
+++ b/src/main/java/org/eclipse/osgitech/plurl/PlurlFactory.java
@@ -26,6 +26,24 @@ package org.eclipse.osgitech.plurl;
  * @see Plurl#add(PlurlStreamHandlerFactory)
  */
 public interface PlurlFactory {
+	/**
+	 * Returns true if this factory should handle the given URL. This is consulted
+	 * before the call stack is examined, and lets a factory claim a URL that only it
+	 * can own, for cases where no class on the call stack identifies the owner. For
+	 * example several instances of the same framework may share a protocol and be
+	 * distinguished only by information in the URL itself.
+	 * <p>
+	 * This is only consulted for URLs that carry enough information to decide, that
+	 * is once the URL has been parsed. A factory that cannot tell from the URL alone
+	 * must return false so that call stack selection is used instead.
+	 *
+	 * @param url the URL a handler is required for
+	 * @return true if this factory should handle the URL
+	 */
+	default boolean shouldHandle(java.net.URL url) {
+		return false;
+	}
+
 	/**
 	 * A plurl implementation will call this method with the classes in the call
 	 * stack which are using the java.net APIs to create URL objects for a specific
diff --git a/src/main/java/org/eclipse/osgitech/plurl/impl/PlurlImpl.java b/src/main/java/org/eclipse/osgitech/plurl/impl/PlurlImpl.java
index 7cbcac6ca2..72e016c8cb 100644
--- a/src/main/java/org/eclipse/osgitech/plurl/impl/PlurlImpl.java
+++ b/src/main/java/org/eclipse/osgitech/plurl/impl/PlurlImpl.java
@@ -820,6 +820,29 @@ public final class PlurlImpl implements Plurl {
 		return null;
 	}
 
+	/**
+	 * Returns the handler of the factory that claims this specific URL, or null when
+	 * no factory claims it. Unlike {@link #findFactory(List)} there is no call stack
+	 * inspection and no fallback to the first factory: this only answers when a
+	 * factory positively identifies the URL as its own.
+	 */
+	PlurlStreamHandler findClaimedPlurlStreamHandler(String protocol, URL url) {
+		if (!isUsableForSelection(url)) {
+			return null;
+		}
+		List<URLStreamHandlerFactoryHolder> factories = getURLStreamHandlerFactories();
+		if (factories.size() < 2) {
+			// nothing to disambiguate
+			return null;
+		}
+		for (URLStreamHandlerFactoryHolder f : factories) {
+			if (shouldHandleURL(f, url)) {
+				return f.getHandler(protocol);
+			}
+		}
+		return null;
+	}
+
 	private <F> F findFactory(List<F> factories) {
 		int numFactories = factories.size();
 		if (numFactories == 1) {
@@ -855,6 +878,43 @@ public final class PlurlImpl implements Plurl {
 		return numFactories > 0 ? factories.get(0) : null;
 	}
 
+	/**
+	 * A URL can only be used for selection once it has been parsed. During
+	 * {@code parseURL} the URL is still being populated, so there is nothing to
+	 * decide on yet.
+	 */
+	private static boolean isUsableForSelection(URL url) {
+		if (url == null) {
+			return false;
+		}
+		String host = url.getHost();
+		return (host != null) && !host.isEmpty();
+	}
+
+	private <F> boolean shouldHandleURL(F f, URL url) {
+		if (f instanceof PlurlFactory) {
+			return ((PlurlFactory) f).shouldHandle(url);
+		}
+		// use reflection in case this Plurl package isn't visible to the factory impl,
+		// and tolerate copies that predate this method
+		try {
+			Method m = findShouldHandleURL(f.getClass());
+			return (m == null) ? false : (boolean) m.invoke(f, url);
+		} catch (Exception e) {
+			return false;
+		}
+	}
+
+	Method findShouldHandleURL(Class<?> clazz) {
+		try {
+			Method shouldHandle = clazz.getMethod("shouldHandle", URL.class); //$NON-NLS-1$
+			shouldHandle.setAccessible(true);
+			return shouldHandle;
+		} catch (NoSuchMethodException e) {
+			return null;
+		}
+	}
+
 	Method findShouldHandle(Class<?> clazz) throws NoSuchMethodException {
 		Method shouldHandle = null;
 		try {
@@ -944,6 +1004,18 @@ public final class PlurlImpl implements Plurl {
 			return ((PlurlFactory) f).shouldHandle(clazz);
 		}
 
+		@Override
+		public boolean shouldHandle(URL url) {
+			F f = factory.get();
+			if (f == null) {
+				return false;
+			}
+			// Delegate to the wrapped factory, reflectively when this plurl package is
+			// not the one the factory was compiled against, and tolerate factories
+			// that predate this method.
+			return shouldHandleURL(f, url);
+		}
+
 		H getHandler(String type) {
 			final F f = factory.get();
 			if (f == null) {
@@ -1419,7 +1491,18 @@ public final class PlurlImpl implements Plurl {
 				// Record the handler found for the URL;
 				// This allows to consistently use the same handler for the
 				// life of the URL object when we are multiplexing.
-				return urlToHandler.get(u, this::findPlurlStreamHandlerImpl);
+				PlurlStreamHandler recorded = urlToHandler.get(u, this::findPlurlStreamHandlerImpl);
+				// The recorded handler may have been chosen during parseURL, before the
+				// URL was populated and therefore before any factory could claim it.
+				// Once the URL can be claimed, let its owner correct the record; from
+				// then on it stays pinned as before. Factories that do not implement
+				// shouldHandle(URL) never claim, so nothing changes for them.
+				PlurlStreamHandler claimed = findClaimedPlurlStreamHandler(protocol, u);
+				if (claimed != null && claimed != recorded) {
+					urlToHandler.replace(u, claimed);
+					return claimed;
+				}
+				return recorded;
 			}
 			return findPlurlStreamHandlerImpl();
 		}
diff --git a/src/main/java/org/eclipse/osgitech/plurl/impl/URLToHandler.java b/src/main/java/org/eclipse/osgitech/plurl/impl/URLToHandler.java
index d17b2b40f7..da5016654d 100644
--- a/src/main/java/org/eclipse/osgitech/plurl/impl/URLToHandler.java
+++ b/src/main/java/org/eclipse/osgitech/plurl/impl/URLToHandler.java
@@ -52,6 +52,21 @@ public class URLToHandler {
 
 	Map<WeakURL, PlurlStreamHandler> entries = Collections.synchronizedMap(new HashMap<>());
 
+	/**
+	 * Replaces the handler recorded for the given URL. Used when the handler first
+	 * recorded was chosen before the URL was populated, and its owner has since
+	 * claimed it.
+	 */
+	void replace(URL u, PlurlStreamHandler handler) {
+		synchronized (entries) {
+			entries.put(new WeakURL(u, queue), handler);
+			Object x;
+			while ((x = queue.poll()) != null) {
+				entries.remove(x);
+			}
+		}
+	}
+
 	PlurlStreamHandler get(URL u, Supplier<PlurlStreamHandler> h) {
 		WeakURL lookup = new WeakURL(u, null);
 		PlurlStreamHandler existing = entries.get(lookup);

[tjwatson]

Open an issue against eclipse-osgi-technology/plurl and you can attach your PR there also. That way we can discuss possible API additions there. Thanks for looking at this.

[paulrutter]

Open an issue against eclipse-osgi-technology/plurl and you can attach your PR there also. That way we can discuss possible API additions there. Thanks for looking at this.

Thanks! Will do and continue the discussion there.
With the proposed patch applied, all unit tests on the Felix side now succeed.
I just have some remaining cleanup todo for Unsafe usage in the meantime.

[tjwatson]

Because I've already released a version of Equinox with the current Plurl signatures I will need to attempt to make any new implementation with the new APIs still be able to handle when copies of the old APIs are still in use in the same JVM instance. That may become impossible over time, but I want to at least try to provide some compatibility between versions of plurl.

Otherwise it will become increasingly difficult to be able to update a core framework implementation which hosts other applications which may embed their own version of a framework implementation (Equinox or Felix). Think of a WAR that uses osgi connect to compose their application components using felix or equinox in their WEB-INF/lib folder. And then that WAR being deployed to a server which is implemented with OSGi, such as glassfish(using felix) or liberty(using equinox).

[paulrutter]

One correction before I open the plurl issue: the shouldHandle(URL) shape I proposed doesn't work, and it took running plurl's own test suite to see why.

PlurlRootURLStreamHandler.parseURL pins the selected handler onto the URL through the private java.net.URL.handler field. Wherever that field is writable — plurl's own test build passes --add-opens java.base/java.net, and the Felix framework bundle declares Add-opens: java.base/java.net — the swap succeeds, plurl steps aside, and openConnection never comes back through it. So a URL-based hook is unreachable in exactly the deployments that need it. My Felix test passed only because that JVM had no add-opens, which is the opposite of reassuring.

Selection has to be decidable at the moment plurl chooses, i.e. mid-parse, when the URL has no host yet. The spec does exist then:

default boolean shouldHandle(String protocol, String spec) { return false; }

consulted in findFactory before the call stack is walked, with PlurlFactoryHolder delegating it the way it already delegates shouldHandle(Class) — without that, findFactory only ever asks the holders, which answer with the interface default.

On your compatibility point: the signature uses only java.lang types, so the reflective path finds it on a factory compiled against a different copy of the package, and a factory that predates the method is tolerated rather than throwing — the lookup is cached, since it sits on the URL parsing path. Existing factories are unaffected either way. To be straight about the limit though: this only helps when the installed router is new enough to consult it. If an older plurl wins the install, Felix falls back to today's behaviour, and nothing on the factory side can change that.

• 81442bc — the plurl change, vendored copy only
• 07d572a — the Felix side, now claiming by UUID read from the spec

51/51 in the plurl repo, including a new PlurlURLSelectionTest that fails without the patch (both URLs served by the first-added factory) and passes with it. Felix's suite is unchanged. I'll raise the issue and PR upstream with that test included.

plurlselectfactorybyspec.patch

[paulrutter]

Raised upstream: plurl#62 with plurl#63 attached, including the test.

[paulrutter]

Added the silent-degradation warning, and the upstream half that makes it possible — plurl#63 now has a second commit.

The problem: the plurl copy that wins the install in a JVM is the one that routes, and it may be older than the copy this framework brought. We register successfully and are then silently misrouted, with no way to tell — bundle: URLs can only be attributed by the UUID they carry, so without shouldHandle(protocol, spec) they go to whichever factory registered first.

Upstream now answers a plurlCapabilities query. An implementation predating it rejects the operation with IOException, so absence of an answer is the answer and needs no cooperation from already-released plurl.

• 1947fc4 — vendored plurl change
• 45b65b6 — Felix warns at startup when the installed router can't route bundle: URLs, instead of leaving it to surface later as a failed resource lookup. The test pins the vendored copy's capability, so re-vendoring an older plurl fails there rather than quietly turning the warning on for everyone.

Also cdd41d1: the vendored plurl sources carry Copyright (c) Contributors to the Eclipse Foundation and were credited in no legal file — not NOTICE, not LICENSE, not DEPENDENCIES. Added the NOTICE entry alongside the existing OSGi Alliance one, which is the same case; no LICENSE change needed since plurl is ALv2 too. RAT doesn't catch this, it only checks source headers.

Framework suite at the pre-existing baseline. @tjwatson no action needed on the Felix commits, but the capability commit upstream is take-it-or-leave-it — the selection commit stands on its own without it.