Netbinox

From APIDesign

Revision as of 10:17, 20 June 2010

Interested in Swing and Equinox? Then welcome to the world where both of these systems co-exist in peace!

The Netbinox is a synergy between NetBeans Platform and Equinox. With recent improvements to NetbinoxPerformance, this is now the fastest OSGi container on the planet. Even faster than plain Equinox.

Why should I want Equinox?

Good question. For worshiping OSGi any standard container shall be fine, including Felix. In such situation feel free to stay with plain Netigso project. However if you rely on non-standard extensions of Equinox or you want to import bundles from Eclipse (like EMF or Mylyn, as they seem to rely on such non-standard extensions and cannot run in regular OSGi container), then Netbinox project shall be your friend and give it a try!

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

• mailing list - subscribe, view archives, etc.
• Repository with GPLed sources
• Builds made daily
• General Overview

Why GPL?

GPL (the General Public License) is viral - software based on any GPL library needs to be licensed as GPL as well. This is good from the global perspective of open source projects. The more GPL open source libraries there is, the more GPL applications there will be.

The virality is also good from the point of view of the library vendor. Every public application based on such library needs to make it sources available publicly. This is good for promotion of the library itself (you would not believe how hard it is to find all users of NetBeans Platform now when we desperately need to show it is useful and used; its licenses -- GPLwithClassPathException and CDDL -- are not viral and thus many usages remain unknown) as it gains more visibility. Publicity makes the developer prouder (obviously I rather use software based on my library than other), and also it increases the possible contributions back to the library (as one can easily take useful pieces of code build upon the library and backport them back to the base).

However not every user of the library wants to release own code under GPL. It may seem that in this case the virality of GPL becomes an unsolvable problem. Surprisingly, the opposite is true. If the author of the library is open to such solution (like me in case of my Netbinox project), it can offer an alternative licensing mechanism. The users can then buy right to remove the virality - e.g. to incorporate the library into own application without releasing own code as GPL. In this case the library author looses some of the benefits discussed in the previous paragraph (visibility, more code with easy backporting), but instead it gets a donation. And donations later help the library to improve more rapidly.

Thus licensing libraries under GPL (with the option to remove virality) seems beneficial for all involved parties. Moreover it is also a clean way to manage sponsoring of an open source project. Instead of emotional attempt to ask for donation: "Do you care about our library? Support us, please!" where the library user needs to do decision about somebody else (about the library maintainer), we have more clearer situation where the library user needs to decide about ownself. The interaction goes like: "Do you want to produce GPL code? OK. No? Then donate!". The library user then makes decision about own business and that is more direct question. As such it cannot be left unanswered (in contrast to "do you want to make a donation?" where the simplest thing is to pretend the question has not been noticed) and yields actual results.

Thus donate to Netbinox (if you don't mind its license has meanwhile been changed to non-viral ones)!

Can I avoid GPL virality?

Yes, you can. In case of the Netbinox project there are two options to do it.

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/>