NetBeansInOSGi

Contents

Overview

This feature is the ability to run NetBeans module code natively as OSGi bundles, rather than using the NetBeans module system.

Tracking: #179473

What This Is Not

Running NetBeans code in this mode is not a full replacement for the NetBeans Platform. For example, you do not get:

  • Advanced features of the NetBeans module system, such as friend APIs, implementation dependencies, eager & autoload status, or provide-require coupling.
  • CLI handling.
  • Pretty logging and exception reporting.
  • Plugin Manager (also known as "auto update").
  • Launcher logic such as cluster management or settings import.
  • Full integration with the NetBeans module development system.
  • Sophisticated caching of module resources and associated startup optimizations.

Additionally, this mode is experimental for now and likely to have serious bugs or limitations that could block usage in production environments.

If you rely on these kinds of features in the NetBeans Platform and want the best support, you are encouraged to continue to run the Platform in the traditional mode.

If you simply want to use a few existing OSGi bundles in your Platform-based application without repackaging them, this is already supported as of NetBeans 6.9: OSGiAndNetBeans. Just include these bundles in your application's cluster path (an import tool is available in the module suite GUI for this purpose); Apache Felix will automatically start inside the NetBeans Platform runtime and load those bundles. It is also possible to use the NetBeans module project type to build OSGi bundles from source if your needs are very basic.

What This Is

If, on the other hand, your application is essentially built on OSGi, you already have an OSGi-compliant container you are happy with, you have OSGi-oriented development tools (whether based in the NetBeans IDE or not), and you simply want to take advantage of pieces of the NetBeans Platform in your application, then this alternate mode may be useful.

A small tool (currently available as an Ant task) accepts some NetBeans modules as input - normally a collection of clusters (directories containing modules/*.jar) - and as output produces a collection of OSGi bundles. The module JARs are mostly untouched, the differences being that

  • (Most) NetBeans-specific manifest keys are translated to their closest OSGi equivalents.
  • Extra files associated with the module, including Class-Path extensions, are packaged inside the bundle.

(Any OSGi bundles found in the input are copied unmodified to the output.)

The bundles thus processed should include org.netbeans.core.osgi (part of the NetBeans Platform in 6.9+) and its transitive dependencies; this contains runtime support that other modules will rely on. You can then load these bundles inside a compliant OSGi container (currently tested on Apache Felix), and they should function more or less as the original NetBeans modules did; see below for details, but as one example, FileUtil.getConfigRoot() will load a "system file system" composed of module XML layers.

These basic services should be enough to run most NetBeans Platform modules that you might want to pick up in your application. Infrastructure such as modular class loading, startup sequence, logging, updates and deployment, etc. are assumed to be handled by your OSGi container or associated software - NetBeans code is not involved.

As a convenience, from a NetBeans module suite project you can run a single Ant target to create bundles for all modules present either as binaries in the cluster path (often just the NetBeans platform cluster) or as sources in the suite itself. There is also a target to start Apache Felix with bundle autodeploy set to this directory. This feature is mainly intended as a way to quickly demonstrate that some modules can be run in pure OSGi mode; a realistic development scenario would probably involve converting a NetBeans release into OSGi format once and then using OSGi-oriented tools for all further development.

What Works Already

Much of the Java IDE can now run in OSGi mode. (see #Demo)

  • Can build, run, debug, and profile OSGi bundles using context menu actions on NetBeans module suite.
  • Can build an OSGi Bundle Repository rather than a simple directory full of JARs.
  • NetBeans module code name base, major release version, specification version, and implementation version are encoded in OSGi bundle symbolic name and version with qualifier.
  • Versioned module dependencies are translated to OSGi Require-Bundle directives, including major release versions and their ranges.
  • JRE dependencies outside the java.* namespace are imported.
  • Module display name, category, and (short) description are translated to OSGi localized metadata.
  • Class-Path extensions are translated. (The extension JARs will be packaged inside the bundle so it is self-contained, more like a NetBeans NBM file than a module JAR.)
  • Public packages (including wildcards matching Class-Path extensions) are translated to OSGi package exports.
  • Lookup.getDefault() will include various items that would normally be present in a NetBeans runtime:
    • META-INF/services declaratively registered in modules (e.g. using @ServiceProvider)
    • the Services folder
    • ModuleInfo instances for each loaded bundle
    • a ClassLoader which can load classes and resources from all enabled (i.e. "resolved") bundles
  • ModuleInstall implementations will be run when bundles are started or stopped.
  • XML layers (both explicit and generated by annotation) will be loaded into the system filesystem, including _hidden masks.
  • FileSystem implementations in default lookup will be injected into the system filesystem, including honoring the fallback attribute.
  • ${netbeans.user} is set to the OSGi cache directory.
  • ${netbeans.user}/config is used as a writable layer for persisting customizations, including storage of NbPreferences.
  • LifecycleManager.getDefault().exit() shuts down the OSGi framework cleanly. (A container may block System.exit(0).)
  • Custom URL protocol handlers (such as nbresloc) are registered.
  • InstalledFileLocator (and nbinst URL protocol) work.
  • *.settings files may be used, e.g. with @ConvertAsJavaBean.
  • The NetBeans main window GUI will be run if you include org.netbeans.core.windows. Standard L&F customizations are applied and a splash screen is shown with your branding.
  • Modules are loaded in dependency order, taking into account also OpenIDE-Module-Provides, OpenIDE-Module-Requires, and OpenIDE-Module-Needs. OS-specific modules such as applemenu are loaded only when appropriate.

What Does Not Yet Work

This list does not include fundamental limitations as listed above, such as the lack of support for CLI options. The following are items which could be expected to be fixed to make for a production-quality feature.

  • There is no support for running the module -> bundle conversion using Maven.
  • Bundled JNI libraries are not packaged so that OSGi can find them. (JNA should not be affected.)
  • Some special file attributes of the system filesystem are not supported:
    • removeWritables to revert modifications to $cachedir/config
    • class:* to inspect type of newvalue/methodvalue
    • layers to determine owning module

What Probably Cannot be Made to Work

  • Friend and implementation dependencies should be translated somehow using import constraints. Currently such APIs are just exposed as public. It is not clear it is even possible to fix this issue, since Import-Package does not support packages split across modules, which are very commonplace in the NetBeans APIs; Require-Bundle is needed to support these cases, but that does not support either the constraints needed for friend dependencies, or the importer-controlled package list needed for implementation dependencies.
  • If Plugin Manager is included in the module set, its GUI will simply be suppressed. The API is still active if other modules try to use it, but attempts to do so will just produce errors since the NB module system cannot be started. Would be nice for an alternate module provider to be injected in OSGi mode which can at least display a read-only list of installed bundles.
  • Some modules assume that Thread.currentThread().getContextClassLoader() == Lookup.getDefault().lookup(ClassLoader.class), which is always a risky assumption and will not be true in an OSGi environment. (Setting the CCL might adversely affect non-NetBeans bundles.)
  • Some modules assume that Class.forName(String) will work to load JRE classes even in sun.* or other private packages. This does not work from an OSGi bundle unless the module has used DynamicImport-Package, which the translator does not generate unless it sees a static (non-reflective) reference. The fix is to use ClassLoader.getSystemClassLoader().loadClass(String) instead.
  • NetBeans code sometimes runs some cleanup processes (e.g. related to finalization) asynchronously; if this happens after/during framework shutdown, Felix throws errors. FELIX-2128 OSGi bundles are forbidden to run any code (even finalizers!) after the bundle has been stopped, but this is very hard to enforce. Equinox is said to be more forgiving.
  • Branding only works with a clean bundle cache directory. FELIX-2177 (fixed for Felix 3)
  • The bundle repository index has invalid category fields. OBR-71

Demo

Create an empty suite with nbproject/platform.properties:

cluster.path=\
    ${nbplatform.active.dir}/harness:\
    ${nbplatform.active.dir}/ide:\
    ${nbplatform.active.dir}/java:\
    ${nbplatform.active.dir}/nb:\
    ${nbplatform.active.dir}/platform:\
    ${nbplatform.active.dir}/websvccommon
disabled.modules=\
    org.eclipse.core.contenttype,\
    org.eclipse.core.jobs,\
    org.eclipse.core.net,\
    org.eclipse.core.runtime,\
    org.eclipse.core.runtime.compatibility.auth,\
    org.eclipse.equinox.app,\
    org.eclipse.equinox.common,\
    org.eclipse.equinox.preferences,\
    org.eclipse.equinox.registry,\
    org.eclipse.equinox.security,\
    org.eclipse.mylyn.bugzilla.core,\
    org.eclipse.mylyn.commons.core,\
    org.eclipse.mylyn.commons.net,\
    org.eclipse.mylyn.commons.xmlrpc,\
    org.eclipse.mylyn.tasks.core,\
    org.netbeans.modules.bugzilla,\
    org.netbeans.modules.bugzilla.exceptionreporter

(see bug #211809 for why Equinox/Mylyn bundles are excluded) and nbproject/project.properties:

modules=
branding.token=nb
felix-sys-prop.org.osgi.framework.system.packages.extra=\
    com.sun.jdi,com.sun.jdi.connect,com.sun.jdi.connect.spi,com.sun.jdi.event,\
    com.sun.jdi.request,sun.awt,sun.misc,com.sun.java.swing.plaf.windows,\
    org.w3c.dom.html,org.w3c.dom.ranges,org.w3c.dom.traversal
osgi.run.cp.extra=\
    ${java.home}/../lib/tools.jar:\
    ${java.home}/../lib/sa-jdi.jar:\
    ${java.home}/../lib/dt.jar
osgi.run.args=-ea -client -Xss2m -Xms32m -XX:PermSize=32m -XX:MaxPermSize=200m -Dnetbeans.full.hack=true

If you Run in Felix, you should get most of the NetBeans Java IDE, though startup time is much slower than in regular mode. Most things work (edit, compile, run, debug).

To be Documented

  • What properties you can usefully set. Some examples shown in demo above.
  • What to do with a bundle repository once created.
  • How to run apps in other OSGi containers. Generally easy to get started with Pax Runner:
 .../pax-runner-1.4.0/bin/pax-run.sh --platform=equinox .../PaintApp/build/osgi

but less clear how to pass a cache directory (~ NetBeans user directory), branding, etc.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo