Meng Yan (孟岩) @ SUN Personal Opinions Only

Netbeans RCP In Action (2)

How to develop a module using netbeans platform?

I have ever developed a little tool called MP3 Renamer before. Because I have many music files in my laptop, but many of them are called "1.mp3
" , "music.mp3". I build this little tool to parse the tag information from the mp3 files and rename the file name to "Author -- Songname.mp3".

I decide to change the stand alone application to a netbeans module to test the Netbeans RCP. Here I'd like to share my experience with you.

1) What we needed

• JDK 1.4.2 or above (http://java.sun.com)
• Netbeans RCP (http://www.netbeans.info/downloads/download.php?a=b&p=2), you can download the binary version or even the source to build one, all up to you.
• Apache Ant (http://ant.apache.org/)

2) Install the Netbeans RCP

After unzip the netbeans zip file to a directory ("/home/elan/netbeans" in my case), make a user preference directory such as "elan" in the netbeans directory. Then, type "/home/elan/netbeans/platform4/lib/nbexec --userdir /home/elan/elan to test if it works. If it works, congratulations, we have already installed the netbeans RCP and can build our own module base on it.

3) Create MP3 Renamer Module

First, we should build the module working enviroment. Here's the structure of the Mp3 renamer dir:

--build.xml
--manifest.mf
--lib/
--nbproject/
--src/

Source files are all put into "src" and third party library files are put into "lib" directory.

After that, we need to edit the manifest file ("manifest.mf"). The content of mine is :

Manifest-Version: 1.0
OpenIDE-Module: Mp3 Renamer/1
OpenIDE-Module-IDE-Dependencies: IDE/1 > 4.0
OpenIDE-Module-Specification-Version: 1.0
OpenIDE-Module-Layer: com/vvworkshop/shareware/mp3rename/resources/layer.xml
OpenIDE-Module-Localizing-Bundle: com/vvworkshop/shareware/mp3rename/Bundle.properties

The layer file ("com/vvworkshop/shareware/mp3rename/resources/layer.xml") describe the extension point and the Bundle file ("com/vvworkshop/shareware/mp3rename/Bundle.properties") store the localized string of our module.

You can modify the file according to your case.

Ok, let's take a look at the layer file:

<filesystem>
<folder name="Menu">
<folder name="View">
<file name="com-vvworkshop-shareware-mp3rename-Mp3RenamerAction.instance">
</file>
</folder>
</folder>
</filesystem>

It extends the netbeans system menu and will insert our own one into the "View" sub menu. The Action that the menu connected with is "com.vvworkshop.shareware.mp3rename.Mp3RenamerAction". Let's take a look at the source file of this action.

"
public class Mp3RenamerAction extends CallableSystemAction {
// System Component

public Mp3RenamerAction() {
}

public void performAction() {
SiteListComponent.activate();
}

public String getName() {
return NbBundle.getMessage(Mp3RenamerAction.class, "SLC_title");
}

public HelpCtx getHelpCtx() {
return null;
}

protected boolean asynchronous() {
return false;
}
}
"

The most important functions are "performAction" and "getName". Function "getName" will return the menu name, and function "performAction" will provide the real action when the user click the menu. And in the Bundle.properties file, there's one line "SLC_title=MP3 Renamer" , so, the menu name will be called"Mp3 Renamer". "performAction" provides the action, in my case, in this function the MP3 Renamer main panel will dock into the netbeans panel.

Another important file is "build.xml", we can use Ant to compile, archive, and build "nbm" file. The file is a little long, I'd like to abstract some important slice from my ant script:

Some property

"
<property name="nb.home" location="/home/elan/netbeans"/>
<property name="test.user.dir" location="/home/elan/netbeans/elan"/>

<path id="class.path">
<pathelement location="${nb.home}/platform4/core/openide.jar"/>
<pathelement location="${nb.home}/platform4/core/openide-loaders.jar"/>
</path>

<property name="libs" value="${nb.home}/platform4/core/openide.jar;${nb.home}/platform4/core/openide-loaders.jar"/>

<property name="package.dir" value="mp3renamer"/>

<!-- The paths of the clusters to be opened when the platform starts. -->
<!-- Name of our NetBeans cluster. -->
<property name="nbantext.jar" location="lib/nbantext.jar"/>
<property name="cluster.dir" value="mp3renamer"/>
<property name="modules.dir" value="${cluster.dir}/modules"/>
<property name="module.name" value="mp3renamer"/>
<!-- Path to the module XML directory. -->
<property name="modulexml.dir" value="${cluster.dir}/config/Modules"/>

<!-- MakeNBM Ant task needs this. -->
<property name="nb.system.dir" value="config"/>

<path id="cluster.path">
<pathelement location="${nb.home}/${cluster.dir}"/>
</path>
"

How to archive the jar file

besides the archive work, we also need to create the module xml file. And in order to build it, we also need a jar file named as "nbantext.jar", it can be acquired from the NetBeans IDE binary.

"
<target name = "archive" depends = "compile" description = "Build the JAR files" >
<!-- Put everything in ${classes} into a basic archive into $(archive)/MP3Renamer.jar -->
<mkdir dir = "${archive}"/>
<mkdir dir="netbeans/${modules.dir}"/>
<jar destfile= "netbeans/${modules.dir}/${module.name}.jar" manifest="manifest.mf" compress="false">
<fileset dir = "${classes}" excludes="**/*.java"/>
<!--<fileset dir="${source}" excludes="**/*.java" /> -->
</jar>

<mkdir dir="netbeans/${modulexml.dir}"/>
<taskdef name="createmodulexml" classpath="${nbantext.jar}"
classname="org.netbeans.nbbuild.CreateModuleXML"/>
<createmodulexml xmldir="netbeans/${modulexml.dir}">
<enabled dir="netbeans/${cluster.dir}">
<include name="modules/${module.name}.jar"/>
</enabled>
</createmodulexml>
</target>
"

How to create the "nbm" file

"
<target name="nbm" depends="archive"
description="Prepare the module for distribution via Auto Update.">
<taskdef name="makenbm" classpath="${nbantext.jar}"
classname="org.netbeans.nbbuild.MakeNBM"/>
<taskdef name="genlist" classpath="${nbantext.jar}"
classname="org.netbeans.nbbuild.MakeListOfNBM"/>
<!-- Need to generate the update_tracking file for makenbm. -->
<genlist outputfiledir="netbeans/${cluster.dir}"
module="modules/${module.name}.jar">
<fileset dir="netbeans/${cluster.dir}">
<include name="modules/${module.name}.jar"/>
<include name="config/Modules/${module.name}.xml"/>
</fileset>
</genlist>
<makenbm file="${module.name}.nbm" needsrestart="false"
productdir="netbeans/${cluster.dir}"
module="modules/${module.name}.jar"
homepage="http://www.vvworkshop.com"
distribution="http://www.vvworkshop.com"/>
</target>
"

You can just copy this target to your build file and change the propertiy value.

4) Test the Module

So far, after build the nbm file, we can test our module. First, you should use the netbeans update center ("Tools"->"Update Center"->"Install Manually Downloaded Modules") to install the new module.
After install the module, you could click the "View" menu, we can see a sub menu named "Mp3 renamer", after click it, the Mp3 Renamer panel will popup. So, you can see, the netbeans module development is easy, and with the help of module development enviroment in the future version, the development work will be easier. Here, I cannot give you too much detail information because it will be too long, if you are interested in it, you can send email to me and ask for the demo source file.

Enjoy~