Skip to content

feat(services): add native karaf.url service (mvn: and wrap:) and use it in karaf-light - #2333

Open
jbonofre wants to merge 4 commits into
apache:mainfrom
jbonofre:gh-2332
Open

jbonofre wants to merge 4 commits into
apache:mainfrom
jbonofre:gh-2332

Conversation

@jbonofre

@jbonofre jbonofre commented Mar 14, 2026 •

Copy link
Copy Markdown
Member

Part of #2212, closes #2332.

Add a native Karaf URL service as an alternative to Pax URL, and use it in the apache-karaf-light distribution.

Karaf URL service (services/url)

  • mvn: protocol handler and MavenResolver service, resolving artifacts from the default (local, file-based) repositories, the local repository and remote repositories, without Aether. Configuration PID: org.apache.karaf.url.mvn (property names compatible with org.ops4j.pax.url.mvn).
  • wrap: protocol handler, equivalent to pax-url-wrap: same syntax (wrap:jar-url[,instructions-url][$instructions]), overwrite modes (keep, merge, full) and defaults. The manifest is generated with bnd (7.4.0), embedded privately in the bundle (only the used packages), so all bnd instructions are supported. The bundle is about 2.5 MB because of bnd.
  • Supports the @multi repositories (KAR repositories), declares the URL handler capabilities, and waits for the ConfigAdmin configuration when org.apache.karaf.url.mvn.requireConfigAdminConfig is set.

karaf-light distribution

  • New url feature in the standard features (Karaf URL service at start level 5 with its etc/org.apache.karaf.url.mvn.cfg), used as startup feature by karaf-light.
  • karaf-light blacklists the pax-url-aether and pax-url-wrap bundles (the wrap feature stays as marker for the wrap deployer and the wrap prerequisites), and the unused pax-url files are removed from the assembly.
  • features.core resolves the artifacts through a resolver abstraction: the Karaf URL service MavenResolver when available, pax-url-aether otherwise. The org.ops4j.pax.url.mvn import is now optional, so the default distribution is unchanged.
  • feature:export-bundles relies on the URL handlers instead of the pax-url-aether MavenResolver service.
  • Child instances get the Karaf URL service configuration and the features processing file of the root instance.

Testing

  • Unit tests for the new handlers, the resolver changes and the instance alignment.
  • Booted karaf-light: no Pax URL bundle, all boot features started, restart, wrap:mvn: installs, deploy folder wrapping, feature:install with wrap: bundles, feature:export-bundles, kar:install, child instance create/start.
  • Booted the default distribution: still uses Pax URL, boot features, feature:export-bundles and wrap: installs work.

Known limitations

  • The Karaf Maven resolver doesn't read maven-metadata.xml: remote snapshots, LATEST and version ranges are not resolved.
  • The maven:* commands still target the org.ops4j.pax.url.mvn configuration.

@jbonofre jbonofre linked an issue Mar 18, 2026 that may be closed by this pull request
Add a new URL handler service under services/url that provides a native
replacement for pax-url-mvn. The service registers a URLStreamHandlerService
for the mvn: protocol and exposes a MavenResolver API for programmatic
artifact resolution from local and remote Maven repositories.
Remove the redundant explicit Bundle-Activator instruction, which
collided with the activator class already detected by
karaf-services-maven-plugin and produced an invalid duplicate-type
manifest header, failing the bundle build. Also embed
org.apache.karaf.util.maven and org.apache.karaf.util.tracker(.annotation),
which are provided-scope dependencies that were not packaged into the
bundle, leaving Parser and BaseActivator unresolved at runtime.
@github-actions

github-actions Bot commented Sep 8, 2026 •

Copy link
Copy Markdown

Test Results

  744 files  + 39    744 suites  +39   1h 17m 24s ⏱️ - 5m 36s
1 141 tests +195  1 007 ✅ +109  134 💤 + 86  0 ❌ ±0 
3 423 runs  +585  3 021 ✅ +327  402 💤 +258  0 ❌ ±0 

Results for commit 9e419dc. ± Comparison against base commit 681f0cc.

This pull request removes 10 and adds 205 tests. Note that renamed tests count towards both.
org.apache.karaf.audit.TestPerf ‑ Unknown test
org.apache.karaf.itests.XATest ‑ Unknown test
org.apache.karaf.itests.examples.RestExampleTest ‑ Unknown test
org.apache.karaf.itests.examples.SoapExampleTest ‑ Unknown test
org.apache.karaf.itests.features.Spring61FeaturesTest ‑ Unknown test
org.apache.karaf.main.lock.DefaultJDBCLockIntegrationTest ‑ Unknown test
org.apache.karaf.main.lock.H2JDBCLockIntegrationTest ‑ Unknown test
org.apache.karaf.main.lock.MySQLJDBCLockIntegrationTest ‑ Unknown test
org.apache.karaf.main.lock.OracleJDBCLockIntegrationTest ‑ Unknown test
org.apache.karaf.main.lock.PostgreSQLJDBCLockIntegrationTest ‑ Unknown test
org.apache.karaf.audit.TestPerf ‑ testFormatString
org.apache.karaf.audit.TestPerf ‑ testGelfTimestamp
org.apache.karaf.audit.TestPerf ‑ testSerialize
org.apache.karaf.config.core.impl.ConfigRepositoryImplContainmentTest ‑ factoryAliasTraversalIsRejected
org.apache.karaf.config.core.impl.ConfigRepositoryImplContainmentTest ‑ fileinstallFilenameOutsideEtcIsRejected
org.apache.karaf.config.core.impl.ConfigRepositoryImplContainmentTest ‑ regularUpdateStillWritesInsideEtc
org.apache.karaf.config.core.impl.ConfigRepositoryImplContainmentTest ‑ traversalPidIsRejected
org.apache.karaf.features.ConditionalTest ‑ testLoadJson
org.apache.karaf.features.internal.download.impl.SimpleDownloadTaskTest ‑ concurrentDownloadsOfSameUrlNeverExposeATransientlyMissingFile
org.apache.karaf.features.internal.service.FeatureConfigInstallerTest ‑ testUpdateExistingConfigWritesAtomically
…
This pull request removes 10 skipped tests and adds 96 skipped tests. Note that renamed tests count towards both.
org.apache.karaf.audit.TestPerf ‑ Unknown test
org.apache.karaf.itests.XATest ‑ Unknown test
org.apache.karaf.itests.examples.RestExampleTest ‑ Unknown test
org.apache.karaf.itests.examples.SoapExampleTest ‑ Unknown test
org.apache.karaf.itests.features.Spring61FeaturesTest ‑ Unknown test
org.apache.karaf.main.lock.DefaultJDBCLockIntegrationTest ‑ Unknown test
org.apache.karaf.main.lock.H2JDBCLockIntegrationTest ‑ Unknown test
org.apache.karaf.main.lock.MySQLJDBCLockIntegrationTest ‑ Unknown test
org.apache.karaf.main.lock.OracleJDBCLockIntegrationTest ‑ Unknown test
org.apache.karaf.main.lock.PostgreSQLJDBCLockIntegrationTest ‑ Unknown test
org.apache.karaf.audit.TestPerf ‑ testFormatString
org.apache.karaf.audit.TestPerf ‑ testGelfTimestamp
org.apache.karaf.audit.TestPerf ‑ testSerialize
org.apache.karaf.itests.XATest ‑ test
org.apache.karaf.itests.examples.RestExampleTest ‑ testBlueprintWithCxfClient
org.apache.karaf.itests.examples.RestExampleTest ‑ testBlueprintWithHttpClient
org.apache.karaf.itests.examples.RestExampleTest ‑ testScrWithCxfClient
org.apache.karaf.itests.examples.RestExampleTest ‑ testScrWithHttpClient
org.apache.karaf.itests.examples.RestExampleTest ‑ testScrWithJerseyClient
org.apache.karaf.itests.examples.RestExampleTest ‑ testWhiteboard
…

♻️ This comment has been updated with latest results.

Add a wrap: URL handler to the native Karaf URL service, equivalent to
pax-url-wrap. The handler supports the same syntax
(wrap:jar-url[,instructions-url][$instructions]), the overwrite modes
(keep, merge, full) and the same defaults (optional Import-Package,
Export-Package: *, symbolic name derived from the URL).

The OSGi manifest is generated with bnd, embedded privately in the bundle
(only the used packages, with the OSGi API not provided by the framework),
so all bnd instructions are supported.
…bution

The karaf-light distribution now provides the mvn: and wrap: protocols with
the native Karaf URL service instead of pax-url-aether and pax-url-wrap.

- features.core resolves the Maven artifacts through a resolver abstraction,
  using the Karaf URL service MavenResolver when available and pax-url-aether
  otherwise. The org.ops4j.pax.url.mvn import is now optional.
- feature:export-bundles relies on the URL handlers instead of the
  pax-url-aether MavenResolver service.
- Add the url feature (Karaf URL service at start level 5 and its
  etc/org.apache.karaf.url.mvn.cfg configuration) to the standard features.
- karaf-light uses url as startup feature and blacklists the pax-url-aether
  and pax-url-wrap bundles (the wrap feature stays as marker for the wrap
  deployer and the wrap prerequisites). The unused pax-url files are removed
  from the assembly.
- The Karaf URL service declares its URL handler capabilities, supports the
  @multi repositories (KAR repositories), and waits for the ConfigAdmin
  configuration when org.apache.karaf.url.mvn.requireConfigAdminConfig is
  set (as in etc/config.properties).
- Child instances get the Karaf URL service configuration and the features
  processing file of the root instance.
@jbonofre jbonofre changed the title feat(services): add native karaf.url service as mvn: protocol handler feat(services): add native karaf.url service (mvn: and wrap:) and use it in karaf-light Oct 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Create Karaf URL service

1 participant