NetbinoxTutorial

From APIDesign

(Difference between revisions)
Jump to: navigation, search
(→Develop!)
Current revision (07:43, 1 September 2011) (edit) (undo)
(→It is easy to start!)
 
(28 intermediate revisions not shown.)
Line 1: Line 1:
 +
== Before [[NetBeans]] 7.1 and After ==
 +
 +
Prior to [[NetBeans]] 7.1 the [[Netbinox]] was a separate component hosted in the [http://source.apidesign.org/hg/netbinox 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 [[NetbinoxTutorial|easy to start]]! ===
=== It is [[NetbinoxTutorial|easy to start]]! ===
-
Here is a quick tutorial to get you up to the speed using [[Netbinox]]. You can either build the [[GPL]] sources of the [[bridge]] between [[NetBeans]] and [[Equinox]] yourself or download the binaries.
+
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.
-
==== Get the bits! ====
+
To build from [http://source.apidesign.org/hg/netbinox the sources] you need [[JDK]]6:
-
To build from [http://source.apidesign.org/hg/netbinox the sources]:
+
<source lang="bash">
 +
$ hg clone http://source.apidesign.org/hg/netbinox
 +
$ cd netbinox
 +
$ ant
 +
</source>
-
# hg clone http://source.apidesign.org/hg/netbinox
+
This script will download all the necessary binaries, build [[Netbinox]] bits and create an [[netbeans:NBM|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 [http://hudson.apidesign.org/job/netbinox daily builder] or you can even build [[ZIP]] file with whole application:
-
# cd netbinox
+
 
-
# ant
+
<source lang="bash">
 +
$ ant build-zip
 +
</source>
-
This will create a [[ZIP]] file in ''dist'' directory with [[Netbinox]] IDE - e.g. [[NetBeans]] platform and IDE ready to empower [[Equinox]]. Alternatively you can download the binaries directly from the [http://hudson.apidesign.org/job/netbinox daily builder].
 
-
'''Warning''' and TBD: right now '''download the [[ZIP]]''' from the builder!
 
==== Execute! ====
==== Execute! ====
-
Now it is time to start the system. You can do it via ant by running
+
Now it is time to start the system. You can do it via [[Ant]] by running
-
ant run
+
<source lang="bash">
 +
$ ant run
 +
</source>
-
or, you can extract the [[ZIP]] file and start '''bin/netbeans'''. [[NetBeans]] IDE optimized for development against [[Equinox]] is started.
+
This will start the [[NetBeans]] Platform together with [[Equinox]] [[OSGi]] container.
-
==== Setup Development! ====
+
=== Empower [[Mylyn]] ===
-
First thing to do is to create a platform based application. Choose from menu ''File/New Project''. Select NetBeans Modules/NetBeans Platform Application''. Select root node of the created project, invoke pop-up menu and choose ''Properties''. There is a button ''Add Cluster'' in the ''Libraries'' category, we will use it to add [[Eclipse]] as a cluster (e.g. bunch of modules or bundles ready for development).
+
Download our [http://source.apidesign.org/hg/netbinox-mylyn-sample sample application] that uses [[Mylyn]] (written as set of [[OSGi]] bundles) to connect to [[Bugzilla]].
-
First of all you need to ''clusterize'' your [[Eclipse]] installation. Go to command line, change your current directory to root folder of such installation and invoke:
+
<source lang="bash">
 +
$ hg clone http://source.apidesign.org/hg/netbinox-mylyn-sample
 +
</source>
-
{{{
+
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
-
/space/eclipse$ ant -f $netbinox/harness/suite.xml clusterize -Dcluster=`pwd` -Dincludes=plugins/*
+
-
}}}
+
-
Notice that a bunch of [[XML]] configuration files has been created in ''config/Modules'' directory. These help [[Netbinox]] recognize bundles present in each cluster. Now you can return back to the IDE's configuration dialog and invoke ''Add Cluster'' and provide path to your clusterize [[Eclipse]] installation. Once the cluster is provided, finish the dialog.
+
<source lang="xml" snippet="netbinox.mylyn.clusterize"/>
-
==== Develop! ====
+
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:
-
Time to create your first bundle or module! Choose from menu ''File/New Project'' and select [[OSGi]] bundle. New project is created and added into the already existing suite. Choose its ''Properties'' and select ''Libraries'' category. There is a button ''Add Dependency''. Invoke it and choose your favorite [[Eclipse]] bundle.
+
<source lang="bash">
 +
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]
 +
</source>
-
My favourite one is '''org.eclipse.mylyn.bugzilla.core'''. Add it into the list of dependencies of your bundle. Finish the dialog, select package in your project and create a class. Start to code and you can find classes from the bugzilla.core bundle. Refer to them, use them. Small example:
+
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.
-
<source lang="java">
+
==== Listen to ScreenCast ====
-
public class Installer implements BundleActivator {
+
 
-
public void start(BundleContext c) throws Exception {
+
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 [[module system|common ground]] in the following screen cast:
-
System.err.println("before");
+
 
-
try {
+
{{#ev:bliptv|2790848}}
-
org.eclipse.mylyn.internal.bugzilla.core.BugzillaClientFactory.createClient(null);
+
 
-
} catch (NullPointerException ex) {}
+
 
-
System.err.println("after");
+
==== 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:
 +
 
 +
<source lang="xml" snippet="netbinox.mylyn.dependencies"/>
 +
 
 +
And it contains regular [[Swing]] action that can use [[Mylyn]] [[API]]s to connect to some [[Bugzilla]]:
 +
 
 +
<source lang="java" snippet="netbinox.mylyn.bugzilla"/>
 +
 
 +
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:
 +
 
 +
<source lang="bash">
 +
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
</source>
</source>
-
==== Deploy! ====
+
Then one can create an [[OSGi]] activator, remember the context:
 +
 
 +
<source lang="java" snippet="netbinox.mylyn.activator"/>
 +
 
 +
And create another [[Swing]] action to list all the activated [[OSGi]] bundles:
 +
 
 +
<source lang="java" snippet="netbinox.mylyn.listbundles"/>
 +
 
 +
The following picture shows the output of such action demonstrating that [[NetBeans]] and [[Equinox]] really run together:
 +
 
 +
[[Image:Netbinox.png]]
 +
 
 +
=== Join ===
-
Just choose ''Run/Run Main Project'' from the menu and your application is started. The system launches both the traditional [[NetBeans Runtime Container]] as well as [[Equinox]] and both cooperate with each other having their usual environment around themselves (more about that is explained in [[Netigso]] article).
+
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 [http://lists.apidesign.org/mailman/listinfo/netigso mailing list] or share your comments.

Current revision

Contents

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:
See the whole file.

<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:
See the whole file.

<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:
See the whole file.

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:
See the whole file.

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:
See the whole file.

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:

Image:Netbinox.png

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.

Retrieved from "http://wiki.apidesign.org/wiki/NetbinoxTutorial"
Personal tools
buy