Netbinox

From APIDesign

Revision as of 07:32, 1 September 2011

Interested in Swing and Equinox? Then welcome to the world where these systems co-exist in peace! Netbinox is a synergy between NetBeans Platform and Equinox. With recent improvements to NetbinoxPerformance, this project now represents the fastest OSGi container on the planet. Even faster than plain Equinox.

Since NetBeans 7.1 the Netbinox is used by the NetBeans IDE to host parts of Mylyn (especially bugzilla and JIRA connectors).

Can Netbinox be Better than Equinox?

How can something bigger be faster than something smaller? That is one question that I was asked recently. Yeah, sounds a little unnatural. However it is still a real question. Still in doubt? Well, in the 18th century, people believed that things heavier than air can't fly too.

The beauty of the Netbinox solution lies in the joining of efforts. The NetBeans team is a long term expert in improving Startup performance. We managed to reduce startup time of NetBeans by 60% since release 6.1. We have the know-how modular desktop applications need to start as quickly as possible. The Netbinox project transfers that knowledge to the Equinox world. As a result, by joining our forces, we managed to significantly improve the cold startup time of JDeveloper (e.g. large OSGi packaged Swing based application) without changing a line of its code, as the following table shows:

Despite Netbinox being bigger than Equinox (naturally), it delivers a faster daily morning startup. This is the result of applying the best practices we learned while developing NetBeans and bridging them for OSGi users. Netbinox is now the fastest desktop application OSGi container on the Earth.

The Differences

The goal of the Netbinox project is to make sure that bundles running inside of the OSGi container see the exact execution environment as they are used to. In case you have a bundle and you are calling into the OSGi APIs and you see some difference, don't hesitate to report a bug.

The Netbinox system reconfigures classical Equinox container and replaces its bundle content access system. Instead of classical (and slow) ZipBundleFile, there is enhanced JarBundleFile which knows how to communicate with NetBeans Runtime Container start caches. This is the heart of the whole system that brings the performance improvements and makes the difference. I write difference in both, positive and negative meaning. As the whole bundle access system is rewritten, there is non zero probability its behaviour is not completely same as the original one (see the previous paragraph what to do if you find a difference).

The deviations observable from within the OSGi specification shall be limited to those related to bundle content access. However, they may be other type of deviations, as the OSGi specification does not prescribe the installation layout neither specific OSGi container extensions, nor it defines behavior of ThreadContextClassLoader. Equinox also provides its own extension hooks, not part of OSGi specification. NetbinoxHooks are as similar as possible, but are registered in slightly different way.

The Netbinox system wraps the Equinox container and takes care of loading its classes. In order to support not just Equinox, but also Felix (as part of Netigso project), we had to separate the OSGi API classes from the JARs of those OSGi containers. Since version 1.16.8 the the modules/ext/equinox.jar used by Netbinox is identical to up stream org.eclipse.osgi_VERSION.vDATE.jar (it used to contain only Equinox specific classes before 195305 was fixed). The common OSGi APIs are in modules/ext/osgi.cmpn-4.2.jar and modules/ext/osgi.core-4.2.jar. No problems related to this separation were reported so far.

While using Equinox in the Eclipse way, one gets not only the OSGi container, but often also reuses the launcher. This launcher has some assumptions about configuration files, command line options, etc. None of this is reused by Netbinox. Rather the configuration files are standard NetBeans ones (although there are ways to read Eclipse like ones too). The Eclipse like command line options are not recognized, however most of the functionality remains accessible via system properties. For example, one cannot use -console to start the Equinox's OSGi console, but one can still specify -J-Dosgi.console= property to turn the same functionality on. There are ways to enhance the NetBeans and thus Netbinox launcher to understand new options, however that is a topic for another document.

The goal of Netbinox is to be fully compatible with Equinox from inside the OSGi container. The goal is not to mimic how the container looks and is accessed from outside. By default the standard NetBeans like access is supported, although there are ways to mimic the Eclipse like approach too.

The NetbinoxTutorial

Before NetBeans 7.1 and After

Prior to NetBeans 7.1 the Netbinox was a separate component hosted in the apidesign Hg repository (under GPL license), but since NetBeans 7.1 the Netbinox is integral part of NetBeans (under more liberal NetBeans licenses).

It is easy to start!

Here is an old (but working) tutorial to use the standalone GPL licensed Netbinox. You can either build the GPL sources of the bridge between NetBeans and Equinox yourself or download the binaries.

To build from the sources you need JDK6:

$ hg clone http://source.apidesign.org/hg/netbinox
$ cd netbinox
$ ant

This script will download all the necessary binaries, build Netbinox bits and create an NBM file and update center that can be installed into any NetBeans IDE or application. Alternatively you can download the NBM binary and archive with sources directly from the daily builder or you can even build ZIP file with whole application:

$ ant build-zip

Execute!

Now it is time to start the system. You can do it via Ant by running

$ ant run

This will start the NetBeans Platform together with Equinox OSGi container.

Empower Mylyn

Download our sample application that uses Mylyn (written as set of OSGi bundles) to connect to Bugzilla.

$ hg clone http://source.apidesign.org/hg/netbinox-mylyn-sample

The root of the sources contains folder eclipse which contains some OSGi JAR libraries in raw form - e.g. just copied from Eclipse installation. The first thing to help Netbinox to use them is is to clusterize them. This can be done manually using

Code from platform.xml:

<target name="convert">
    <ant antfile="${harness.dir}/suite.xml" target="clusterize">
        <property name="cluster" location="../eclipse"/>
        <property name="includes" value="modules/*.jar"/>
    </ant>
</target>
 

which produces bunch of XML configuration files in the config/Modules directory. These help Netbinox recognize bundles present in each cluster. This is common output of that Ant target:

clusterize:
    [mkdir] Created dir: /netbinox-mylyn-sample/eclipse/config/Modules
[createmodulexml] Autoload modules: [org.apache.commons.codec, org.apache.commons.httpclient, org.apache.commons.lang, org.apache.commons.logging, org.eclipse.core.contenttype, org.eclipse.core.jobs, org.eclipse.core.net, org.eclipse.core.runtime, 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.tasks.core]

However due to intricate build script setup this shall not be necessary. Just open the suite in your new unzipped the Netbinox IDE and run it.

Listen to ScreenCast

You can either follow the instructions written on this page, or if you wish, you can also listen and watch me and Geertjan demonstrating and discussing the power of Mylyn, NetBeans and the common ground in the following screen cast:

Develop with Mylyn

The next step is to use the Netbinox IDE and open mylyn-suite project (which is the next directory in the sample along the eclipse one). If you open the project customizer you can verify that there is a cluster called eclipse which enlists all the modules prepared in the previous step.

The application consists of two subprojects. One produces a NetBeans module that depends on OSGi bundles. Here is a dependency excerpt from the project.xml configuration file:

Code from project.xml:

<module-dependencies>
    <dependency>
        <code-name-base>org.eclipse.core.runtime</code-name-base>
        <build-prerequisite/>
        <compile-dependency/>
        <run-dependency>
            <specification-version>3.5.0</specification-version>
        </run-dependency>
    </dependency>
    <dependency>
        <code-name-base>org.eclipse.equinox.common</code-name-base>
        <build-prerequisite/>
        <compile-dependency/>
        <run-dependency>
            <specification-version>3.5.1</specification-version>
        </run-dependency>
    </dependency>
    <dependency>
        <code-name-base>org.eclipse.mylyn.bugzilla.core</code-name-base>
        <build-prerequisite/>
        <compile-dependency/>
        <run-dependency>
            <specification-version>3.2.2</specification-version>
        </run-dependency>
    </dependency>
    <dependency>
        <code-name-base>org.eclipse.mylyn.commons.net</code-name-base>
        <build-prerequisite/>
        <compile-dependency/>
        <run-dependency>
            <specification-version>3.2.0</specification-version>
        </run-dependency>
    </dependency>
    <dependency>
        <code-name-base>org.eclipse.mylyn.tasks.core</code-name-base>
        <build-prerequisite/>
        <compile-dependency/>
        <run-dependency>
            <specification-version>3.2.2</specification-version>
        </run-dependency>
    </dependency>
    <dependency>
        <code-name-base>org.openide.util</code-name-base>
        <build-prerequisite/>
        <compile-dependency/>
        <run-dependency>
            <specification-version>8.0</specification-version>
        </run-dependency>
    </dependency>
</module-dependencies>
 

And it contains regular Swing action that can use Mylyn APIs to connect to some Bugzilla:

Code from TestBugzilla.java:

TaskRepository repository = new TaskRepository("bugzilla", repoURL);
 
TaskRepositoryManager trm = new TaskRepositoryManager();
BugzillaRepositoryConnector brc = new BugzillaRepositoryConnector();
 
trm.addRepository(repository);
trm.addRepositoryConnector(brc);
 
String url = "/buglist.cgi?" +
            "query_format=advanced" +
            "&short_desc_type=allwordssubstr" +
            "&limit=5";
IRepositoryQuery query = new RepositoryQuery(
    repository.getConnectorKind(), ""
);
query.setUrl(url);
final List<TaskData> collectedData = new ArrayList<TaskData>();
TaskDataCollector collector = new TaskDataCollector() {
    public void accept(TaskData taskData) {
        collectedData.add(taskData);
    }
};
NullProgressMonitor nullProgressMonitor = new NullProgressMonitor();
brc.performQuery(
    repository, query, collector, null, nullProgressMonitor
);
 

This demonstrates how the system launches both the traditional NetBeans Runtime Container as well as Equinox. Both cooperate, start their own modules/bundles and provide them with their usual environment. Moreover there is a bridge (more about that is explained in Netigso article) around helping them mutually communicate with each other.

Develop OSGi!

The previous example shown how to develop a NetBeans module. However sometimes it is preferable to create an OSGi. For example when one needs to deal with BundleContext, it is necessary to create an OSGi bundle.

Nothing is simpler. One just need to change the manifest to contain Bundle-SymbolicName and the the Netbinox IDE generates an OSGi bundle automatically:

Bundle-Activator: org.apidesign.listbundles.Installer
Bundle-SymbolicName: org.apidesign.listbundles
Bundle-Version: 1.0
Import-Package: org.osgi.framework
OpenIDE-Module-Layer: org/apidesign/listbundles/layer.xml
OpenIDE-Module-Localizing-Bundle: org/apidesign/listbundles/Bundle.properties

Then one can create an OSGi activator, remember the context:

Code from Installer.java:

public class Installer implements BundleActivator {
    static BundleContext bc;
 
    public void start(BundleContext c) throws Exception {
        bc = c;
    }
 
    public void stop(BundleContext c) throws Exception {
    }
}
 

And create another Swing action to list all the activated OSGi bundles:

Code from ListBndsl.java:

public final class ListBndsl implements ActionListener {
    public void actionPerformed(ActionEvent e) {
        StringBuilder sb = new StringBuilder();
        for (Bundle b : Installer.bc.getBundles()) {
            if (b.getState() != Bundle.ACTIVE) {
                continue;
            }
            sb.append(b.getSymbolicName());
            sb.append("\n");
        }
        DialogDisplayer.getDefault().notify(
            new NotifyDescriptor.Message(sb)
        );
    }
}
 

The following picture shows the output of such action demonstrating that NetBeans and Equinox really run together:

Join

But nothing is better than real experience. Try the sample yourself. In case you are interested in Netbinox, Netigso and other related technologies, join our mailing list or share your comments.

Resources

• List of bugs - report new bug!
• mailing list - subscribe, view archives, etc.
• Repository with GPLed sources
• Builds made daily
• Everything about OSGi and NetBeans

Why GPL?

The Netbinox project is primarily licensed under GPL. This is for your own good, as it ensures this project is supported by all its users. However you can of course, avoid the GPL viral restrictions. There are two options:

First of all you may find out that you do not need Equinox, that compliant OSGi container is enough. In such case, please use Netigso project which incorporates Apache's Felix and does that without the GPL virality using the standard NetBeans license.

In case you really need Equinox, you have the option is to license the Netbinox project under non-GPL license. Please write to licensing@apidesign.org to learn details.

<comments/>